@vizzly-testing/honeydiff 0.8.1 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.0] - 2026-02-03
+
+## What's Changed
+
+### Added
+- **GMSD (Gradient Magnitude Similarity Deviation)** - New `includeGMSD` option for fast, edge-sensitive perceptual comparison
+  - Returns `gmsdScore` in results (0.0 = identical, higher = more different)
+  - Very fast compared to SSIM, ideal for detecting border/outline changes
+  - Based on Xue et al. 2014 research paper
+  - **Note:** GMSD requires images with identical dimensions. For variable-height comparisons, `gmsdScore` will be `null`
+- **Cluster Merging** - New `clusterMerge` option to consolidate fragmented text regions
+  - Simple API: `clusterMerge: true` enables with sensible defaults
+  - Advanced API: Pass an object with `horizontalDistance`, `yBandTolerance`, `maxHeightRatio`, `maxWidthRatio`
+  - Solves the "59 clusters for one date string" problem by intelligently merging nearby character-level changes into logical text regions
+  - Uses SWT-inspired heuristics (Epshtein et al. 2010) for horizontal-biased text detection
+
+**Full Changelog**: https://github.com/vizzly-testing/honeydiff/compare/v0.9.0...v0.10.0
+
+## [Unreleased]
+
+### Added
+- **GMSD (Gradient Magnitude Similarity Deviation)** - New `includeGMSD` option for fast, edge-sensitive perceptual comparison
+  - Returns `gmsdScore` in results (0.0 = identical, higher = more different)
+  - Very fast compared to SSIM, ideal for detecting border/outline changes
+  - Based on Xue et al. 2014 research paper
+- **Cluster Merging** - New `clusterMerge` option to consolidate fragmented text regions
+  - Simple API: `clusterMerge: true` enables with sensible defaults
+  - Advanced API: Pass an object with `horizontalDistance`, `yBandTolerance`, `maxHeightRatio`, `maxWidthRatio`
+  - Solves the "59 clusters for one date string" problem
+  - Uses SWT-inspired heuristics (Epshtein et al. 2010)
+
+## [0.9.0] - 2026-01-26
+
+## What's Changed
+
+### Added
+- **Diff Fingerprinting API** - New functionality for grouping similar diffs across different image comparisons. This enables batch-approving the same visual change that appears on multiple pages (e.g., header/footer updates).
+  - `computeFingerprintSync()` - Generate a compact fingerprint from a diff result
+  - `fingerprintSimilaritySync()` - Compare two fingerprints with a similarity score (0.0-1.0)
+  - `fingerprintHashSync()` - Get a coarse hash for fast O(1) grouping
+  - `DiffFingerprint` interface with rich metadata:
+    - `zoneMask` - 4x4 spatial grid showing which regions are affected
+    - `clusterCount`, `clusterPositions`, `clusterSizes` - Spatial distribution data
+    - `diffMagnitude` - Bucketed size categories (tiny/small/medium/large/massive)
+    - `avgIntensity`, `avgDensity` - Change characteristics
+    - `hash` - Pre-computed coarse hash for grouping
+
+**Full Changelog**: https://github.com/vizzly-testing/honeydiff/compare/v0.8.1...v0.9.0
+
 ## [0.8.1] - 2026-01-09
 
 ## What's Changed

package/README.md

@@ -188,10 +188,39 @@ if (result.diffClusters) {
 | 2 | Default - filters single isolated pixels as rendering noise |
 | 3+ | More permissive - only larger clusters detected |
 
-### 6. Perceptual Similarity (SSIM)
+**Cluster Merging for Text Regions:**
+
+Text changes often fragment into many small clusters (one per character). Enable cluster merging to consolidate them into logical regions:
+
+```javascript
+// Simple: enable with sensible defaults
+const result = await compare('img1.png', 'img2.png', {
+  includeClusters: true,
+  clusterMerge: true  // Merge nearby clusters (great for text)
+});
+
+// Advanced: tune the merging behavior
+const result = await compare('img1.png', 'img2.png', {
+  includeClusters: true,
+  clusterMerge: {
+    horizontalDistance: 15,  // Max gap between clusters to merge (pixels)
+    yBandTolerance: 5,       // Vertical tolerance for "same line"
+    maxHeightRatio: 2.0,     // Prevent merging very different sized clusters
+    maxWidthRatio: 3.0
+  }
+});
+
+// Before: "2024-01-01" detected as 59 clusters (one per character/gap)
+// After:  "2024-01-01" detected as 1-2 logical regions
+```
+
+Uses SWT-inspired heuristics from text detection research (Epshtein et al. 2010).
+
+### 6. Perceptual Similarity (SSIM & GMSD)
 
 Beyond pixel counting - measure structural similarity from a human perception perspective.
 
+**SSIM (Structural Similarity Index)** - Overall perceptual similarity:
 ```javascript
 const result = await compare('img1.png', 'img2.png', {
   includeSSIM: true  // Note: Can be slow on large images
@@ -200,13 +229,33 @@ const result = await compare('img1.png', 'img2.png', {
 if (result.perceptualScore !== null) {
   console.log(`SSIM: ${result.perceptualScore.toFixed(3)}`);
   // Output: SSIM: 0.923 (0.0 = different, 1.0 = identical)
+}
+```
+
+**GMSD (Gradient Magnitude Similarity Deviation)** - Fast edge-sensitive metric:
+```javascript
+const result = await compare('img1.png', 'img2.png', {
+  includeGMSD: true  // Very fast, great for detecting structural changes
+});
+
+if (result.gmsdScore !== null) {
+  console.log(`GMSD: ${result.gmsdScore.toFixed(4)}`);
+  // Output: GMSD: 0.0234 (0.0 = identical, higher = more different)
 
-  if (result.perceptualScore > 0.95) {
-    console.log('Images are perceptually very similar');
+  if (result.gmsdScore < 0.05) {
+    console.log('Edges are very similar');
   }
 }
 ```
 
+GMSD is ideal for catching:
+- Border thickness changes
+- Font weight shifts
+- Icon updates
+- Any edge/outline regressions
+
+**Reference:** Xue et al. 2014 - "Gradient Magnitude Similarity Deviation: A Highly Efficient Perceptual Image Quality Index"
+
 ### 7. Tolerance & Color Spaces
 
 **RGB Mode (default)** - Exact matching with pixel tolerance:
@@ -285,6 +334,69 @@ let metadata = await getImageMetadataFromFile('screenshot.png');
 console.log(`${metadata.width}x${metadata.height}, ${metadata.fileSizeBytes} bytes`);
 ```
 
+### 11. Diff Fingerprinting
+
+Group similar diffs across comparisons with fingerprinting. Perfect for batch-approving the same visual change that appears on multiple pages (e.g., header/footer updates).
+
+```javascript
+const { compare, computeFingerprintSync, fingerprintSimilaritySync, fingerprintHashSync } = require('@vizzly-testing/honeydiff');
+
+// Compare images with clustering enabled
+let result = await compare('baseline.png', 'current.png', {
+  includeClusters: true
+});
+
+// Compute fingerprint
+let fingerprint = computeFingerprintSync(result, 1920, 1080);
+
+if (fingerprint) {
+  console.log(`Hash: ${fingerprint.hash}`);
+  console.log(`Zones affected: ${fingerprint.zoneMask.toString(2).padStart(16, '0')}`);
+  console.log(`Cluster count: ${fingerprint.clusterCount}`);
+  console.log(`Magnitude: ${fingerprint.diffMagnitude}`);
+}
+```
+
+**Grouping similar diffs:**
+```javascript
+// Group diffs by hash for batch approval
+let groups = new Map();
+
+for (let comparison of comparisons) {
+  let fp = computeFingerprintSync(comparison.result, width, height);
+  if (fp) {
+    let hash = fingerprintHashSync(fp);
+    if (!groups.has(hash)) groups.set(hash, []);
+    groups.get(hash).push(comparison);
+  }
+}
+
+// Find groups with multiple similar diffs
+for (let [hash, items] of groups) {
+  if (items.length > 1) {
+    console.log(`Found ${items.length} similar diffs with hash ${hash}`);
+  }
+}
+```
+
+**Similarity scoring:**
+```javascript
+// Compare two fingerprints (0.0 = different, 1.0 = identical)
+let similarity = fingerprintSimilaritySync(fp1, fp2);
+
+if (similarity > 0.8) {
+  console.log('These diffs are likely the same visual change');
+}
+```
+
+**Fingerprint properties:**
+- `clusterCount` - Number of distinct change regions
+- `clusterPositions` - Normalized positions (0.0-1.0)
+- `clusterSizes` - Relative sizes (area ratio)
+- `zoneMask` - 4x4 grid (16 zones) showing affected regions
+- `diffMagnitude` - Bucketed size: `tiny`, `small`, `medium`, `large`, `massive`
+- `hash` - Pre-computed coarse hash for fast grouping
+
 ## Accessibility Features
 
 Built-in WCAG color contrast analysis and color blindness simulation to catch accessibility violations in screenshots and UI designs.
@@ -470,6 +582,20 @@ Synchronous metadata retrieval from buffer.
 
 Synchronous metadata retrieval from file.
 
+### Diff Fingerprint Functions (Sync only)
+
+**`computeFingerprintSync(diffResult, width, height): DiffFingerprint | null`**
+
+Compute a fingerprint from a diff result. Requires `includeClusters: true` in compare options. Returns null if no clusters.
+
+**`fingerprintSimilaritySync(fp1, fp2): number`**
+
+Compare two fingerprints. Returns 0.0 (different) to 1.0 (identical).
+
+**`fingerprintHashSync(fingerprint): string`**
+
+Get coarse hash for fast grouping. Returns 16-char hex string.
+
 ### Input Types
 
 All functions accept:
@@ -481,22 +607,22 @@ All functions accept:
 ```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)
+  threshold?: number;                   // CIEDE2000 Delta E threshold (default: 2.0)
   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)
+  includeGMSD?: boolean;                // GMSD edge similarity (fast, default: false)
   minClusterSize?: number;              // Filter clusters smaller than this (default: 2)
-
-  // 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)
+  clusterMerge?: boolean | {            // Merge nearby clusters (default: false)
+    horizontalDistance?: number;        // Max horizontal gap to merge (default: 15)
+    yBandTolerance?: number;            // Vertical "same line" tolerance (default: 5)
+    maxHeightRatio?: number;            // Max height ratio to merge (default: 2.0)
+    maxWidthRatio?: number;             // Max width ratio to merge (default: 3.0)
+  };
 
   // Output options
   diffPath?: string;                    // Save diff image path
@@ -529,7 +655,8 @@ interface DiffResult {
   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
+  perceptualScore: number | null;       // SSIM 0.0-1.0, null unless includeSSIM enabled
+  gmsdScore: number | null;             // GMSD 0.0+, null unless includeGMSD enabled
 }
 ```
 

package/examples/basic.js

@@ -0,0 +1,316 @@
+/**
+ * Basic usage example for @honeydiff/node
+ */
+
+import * as honeydiff from '../index.js';
+
+async function main() {
+  console.log('Honeydiff Node.js Examples\n');
+
+  // Example 1: Quick async comparison
+  console.log('1. Quick comparison:');
+  let isDifferent = await honeydiff.quickCompare(
+    '../../tests/fixtures/screenshots/vizzly-baseline.png',
+    '../../tests/fixtures/screenshots/vizzly-with-diff.png'
+  );
+  console.log(`  Result: ${isDifferent ? 'DIFFERENT' : 'IDENTICAL'}\n`);
+
+  // Example 2: Detailed async comparison
+  console.log('2. Detailed comparison with options:');
+  let result = await honeydiff.compare(
+    '../../tests/fixtures/screenshots/vizzly-baseline.png',
+    '../../tests/fixtures/screenshots/vizzly-with-diff.png',
+    {
+      pixelTolerance: 0,
+      antialiasing: true,
+      includeSSIM: true,
+      includeClusters: true,
+    }
+  );
+
+  console.log(`  Diff percentage: ${result.diffPercentage.toFixed(2)}%`);
+  console.log(`  Different pixels: ${result.diffPixels} / ${result.totalPixels}`);
+  console.log(`  AA pixels ignored: ${result.aaPixelsIgnored}`);
+
+  if (result.perceptualScore !== null) {
+    console.log(`  SSIM score: ${result.perceptualScore.toFixed(4)}`);
+  }
+
+  if (result.boundingBox) {
+    console.log(
+      `  Bounding box: (${result.boundingBox.x}, ${result.boundingBox.y}) ${result.boundingBox.width}x${result.boundingBox.height}`
+    );
+  }
+
+  if (result.diffClusters && result.diffClusters.length > 0) {
+    console.log(`  Found ${result.diffClusters.length} diff clusters`);
+    result.diffClusters.slice(0, 3).forEach((cluster, i) => {
+      console.log(
+        `    Cluster ${i + 1}: ${cluster.pixelCount} pixels at (${cluster.centerOfMass[0].toFixed(0)}, ${cluster.centerOfMass[1].toFixed(0)})`
+      );
+    });
+  }
+
+  if (result.intensityStats) {
+    console.log(`  Intensity stats:`);
+    console.log(`    Range: ${result.intensityStats.min}-${result.intensityStats.max}`);
+    console.log(
+      `    Mean: ${result.intensityStats.mean.toFixed(1)}, Median: ${result.intensityStats.median}`
+    );
+  }
+
+  console.log();
+
+  // Example 3: Synchronous comparison (for when you need blocking behavior)
+  console.log('3. Synchronous comparison:');
+  let syncResult = honeydiff.compareSync(
+    '../../tests/fixtures/screenshots/vizzly-baseline.png',
+    '../../tests/fixtures/screenshots/vizzly-with-diff.png',
+    { pixelTolerance: 10 }
+  );
+  console.log(`  Diff percentage: ${syncResult.diffPercentage.toFixed(2)}%`);
+  console.log();
+
+  // Example 4: Get image dimensions
+  console.log('4. Get image dimensions:');
+  let dimensions = await honeydiff.getDimensions(
+    '../../tests/fixtures/screenshots/vizzly-baseline.png'
+  );
+  console.log(`  Dimensions: ${dimensions.width}x${dimensions.height} pixels`);
+  console.log();
+
+  // Example 5: Get dimensions synchronously
+  console.log('5. Get dimensions (sync):');
+  let syncDimensions = honeydiff.getDimensionsSync(
+    '../../tests/fixtures/screenshots/vizzly-with-diff.png'
+  );
+  console.log(`  Dimensions: ${syncDimensions.width}x${syncDimensions.height} pixels`);
+  console.log();
+
+  // Example 6: Generate diff artifacts
+  console.log('6. Generate diff artifacts:');
+  let artifactResult = await honeydiff.compare(
+    '../../tests/fixtures/screenshots/vizzly-baseline.png',
+    '../../tests/fixtures/screenshots/vizzly-with-diff.png',
+    {
+      diffPath: '/tmp/honeydiff-diff.png',
+      maskPath: '/tmp/honeydiff-mask.png',
+      overlayPath: '/tmp/honeydiff-overlay.png',
+      overwrite: true,
+    }
+  );
+  console.log(`  Diff percentage: ${artifactResult.diffPercentage.toFixed(2)}%`);
+  console.log(`  Artifacts saved to /tmp/honeydiff-*.png`);
+  console.log();
+
+  // Example 7: Accessibility metadata tests
+  console.log('7. Accessibility metadata (RGB + luminance + WCAG):');
+  let accessibilityResult = await honeydiff.compare(
+    '../../tests/fixtures/screenshots/vizzly-baseline.png',
+    '../../tests/fixtures/screenshots/vizzly-with-diff.png',
+    {
+      includeClusters: true,
+      includeAccessibilityData: true,
+    }
+  );
+
+  // Validate accessibility data is present
+  if (!accessibilityResult.diffClusters || accessibilityResult.diffClusters.length === 0) {
+    throw new Error('Test failed: Expected diff clusters to be present');
+  }
+
+  let firstCluster = accessibilityResult.diffClusters[0];
+  if (!firstCluster.accessibilityMetadata) {
+    throw new Error('Test failed: Expected accessibilityMetadata to be present');
+  }
+
+  let meta = firstCluster.accessibilityMetadata;
+
+  // Validate RGB channel differences
+  if (typeof meta.avgRDiff !== 'number' || meta.avgRDiff < 0) {
+    throw new Error('Test failed: avgRDiff should be a non-negative number');
+  }
+  if (typeof meta.avgGDiff !== 'number' || meta.avgGDiff < 0) {
+    throw new Error('Test failed: avgGDiff should be a non-negative number');
+  }
+  if (typeof meta.avgBDiff !== 'number' || meta.avgBDiff < 0) {
+    throw new Error('Test failed: avgBDiff should be a non-negative number');
+  }
+
+  // Validate dominant channel
+  if (!['R', 'G', 'B'].includes(meta.dominantChannel)) {
+    throw new Error(
+      `Test failed: dominantChannel should be R, G, or B, got ${meta.dominantChannel}`
+    );
+  }
+
+  // Validate luminance values (0.0-1.0 range)
+  if (meta.avgBaselineLuminance < 0 || meta.avgBaselineLuminance > 1) {
+    throw new Error('Test failed: avgBaselineLuminance should be between 0 and 1');
+  }
+  if (meta.avgCurrentLuminance < 0 || meta.avgCurrentLuminance > 1) {
+    throw new Error('Test failed: avgCurrentLuminance should be between 0 and 1');
+  }
+
+  // Validate contrast ratios (1.0-21.0 range)
+  if (meta.contrastRatio < 1 || meta.contrastRatio > 21) {
+    throw new Error('Test failed: contrastRatio should be between 1 and 21');
+  }
+  if (meta.minContrastRatio < 1 || meta.minContrastRatio > 21) {
+    throw new Error('Test failed: minContrastRatio should be between 1 and 21');
+  }
+  if (meta.maxContrastRatio < 1 || meta.maxContrastRatio > 21) {
+    throw new Error('Test failed: maxContrastRatio should be between 1 and 21');
+  }
+  if (meta.minContrastRatio > meta.maxContrastRatio) {
+    throw new Error('Test failed: minContrastRatio should be <= maxContrastRatio');
+  }
+
+  // Validate colorBlindnessImpact is null when not requested
+  if (meta.colorBlindnessImpact !== null) {
+    throw new Error(
+      'Test failed: colorBlindnessImpact should be null when checkColorBlindness is not enabled'
+    );
+  }
+
+  console.log(
+    `  RGB diffs: R=${meta.avgRDiff.toFixed(1)}, G=${meta.avgGDiff.toFixed(1)}, B=${meta.avgBDiff.toFixed(1)}`
+  );
+  console.log(`  Dominant channel: ${meta.dominantChannel}`);
+  console.log(
+    `  Luminance: baseline=${meta.avgBaselineLuminance.toFixed(3)}, current=${meta.avgCurrentLuminance.toFixed(3)}`
+  );
+  console.log(
+    `  WCAG contrast: ${meta.contrastRatio.toFixed(2)}:1 (range: ${meta.minContrastRatio.toFixed(2)}-${meta.maxContrastRatio.toFixed(2)})`
+  );
+  console.log('  All accessibility metadata tests passed!');
+  console.log();
+
+  // Example 8: Color blindness checking tests
+  console.log('8. Color blindness checking:');
+  let cbResult = await honeydiff.compare(
+    '../../tests/fixtures/screenshots/vizzly-baseline.png',
+    '../../tests/fixtures/screenshots/vizzly-with-diff.png',
+    {
+      includeClusters: true,
+      checkColorBlindness: true,
+      colorBlindnessThreshold: 30.0,
+    }
+  );
+
+  // Validate clusters and accessibility data
+  if (!cbResult.diffClusters || cbResult.diffClusters.length === 0) {
+    throw new Error('Test failed: Expected diff clusters to be present');
+  }
+
+  let cbCluster = cbResult.diffClusters[0];
+  if (!cbCluster.accessibilityMetadata) {
+    throw new Error(
+      'Test failed: Expected accessibilityMetadata to be present when checkColorBlindness is enabled'
+    );
+  }
+
+  let cbMeta = cbCluster.accessibilityMetadata;
+
+  // Validate colorBlindnessImpact is present
+  if (!cbMeta.colorBlindnessImpact) {
+    throw new Error(
+      'Test failed: Expected colorBlindnessImpact to be present when checkColorBlindness is enabled'
+    );
+  }
+
+  let impact = cbMeta.colorBlindnessImpact;
+
+  // Validate boolean flags
+  if (typeof impact.deuteranopiaVisible !== 'boolean') {
+    throw new Error('Test failed: deuteranopiaVisible should be a boolean');
+  }
+  if (typeof impact.protanopiaVisible !== 'boolean') {
+    throw new Error('Test failed: protanopiaVisible should be a boolean');
+  }
+  if (typeof impact.tritanopiaVisible !== 'boolean') {
+    throw new Error('Test failed: tritanopiaVisible should be a boolean');
+  }
+  if (typeof impact.achromatopsiaVisible !== 'boolean') {
+    throw new Error('Test failed: achromatopsiaVisible should be a boolean');
+  }
+
+  // Validate visibility score (0.0-1.0 range)
+  if (impact.visibilityScore < 0 || impact.visibilityScore > 1) {
+    throw new Error('Test failed: visibilityScore should be between 0 and 1');
+  }
+
+  console.log(`  Visibility score: ${(impact.visibilityScore * 100).toFixed(0)}%`);
+  console.log(`  Deuteranopia visible: ${impact.deuteranopiaVisible}`);
+  console.log(`  Protanopia visible: ${impact.protanopiaVisible}`);
+  console.log(`  Tritanopia visible: ${impact.tritanopiaVisible}`);
+  console.log(`  Achromatopsia visible: ${impact.achromatopsiaVisible}`);
+  console.log('  All color blindness tests passed!');
+  console.log();
+
+  // Example 9: Test checkColorBlindness automatically enables includeAccessibilityData
+  console.log('9. Auto-enable test (checkColorBlindness enables includeAccessibilityData):');
+  let autoEnableResult = await honeydiff.compare(
+    '../../tests/fixtures/screenshots/vizzly-baseline.png',
+    '../../tests/fixtures/screenshots/vizzly-with-diff.png',
+    {
+      includeClusters: true,
+      checkColorBlindness: true,
+      // Note: NOT explicitly setting includeAccessibilityData
+    }
+  );
+
+  if (!autoEnableResult.diffClusters || autoEnableResult.diffClusters.length === 0) {
+    throw new Error('Test failed: Expected diff clusters to be present');
+  }
+
+  let autoCluster = autoEnableResult.diffClusters[0];
+  if (!autoCluster.accessibilityMetadata) {
+    throw new Error(
+      'Test failed: checkColorBlindness should automatically enable accessibilityMetadata'
+    );
+  }
+
+  // Should have both accessibility data and color blindness impact
+  if (!autoCluster.accessibilityMetadata.colorBlindnessImpact) {
+    throw new Error(
+      'Test failed: Expected colorBlindnessImpact when checkColorBlindness is enabled'
+    );
+  }
+
+  console.log('  Accessibility metadata auto-enabled: Yes');
+  console.log('  Color blindness data present: Yes');
+  console.log('  Auto-enable test passed!');
+  console.log();
+
+  // Example 10: Test accessibility data is null when not requested
+  console.log('10. Null handling test (accessibility data absent when not requested):');
+  let noAccessibilityResult = await honeydiff.compare(
+    '../../tests/fixtures/screenshots/vizzly-baseline.png',
+    '../../tests/fixtures/screenshots/vizzly-with-diff.png',
+    {
+      includeClusters: true,
+      // Note: NOT setting includeAccessibilityData or checkColorBlindness
+    }
+  );
+
+  if (!noAccessibilityResult.diffClusters || noAccessibilityResult.diffClusters.length === 0) {
+    throw new Error('Test failed: Expected diff clusters to be present');
+  }
+
+  let noAccessCluster = noAccessibilityResult.diffClusters[0];
+  if (noAccessCluster.accessibilityMetadata !== null) {
+    throw new Error('Test failed: accessibilityMetadata should be null when not requested');
+  }
+
+  console.log('  Accessibility metadata: null (as expected)');
+  console.log('  Null handling test passed!');
+  console.log();
+
+  console.log('=== All accessibility binding tests passed! ===\n');
+}
+
+main().catch((err) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/examples/buffers.js

@@ -0,0 +1,40 @@
+/**
+ * Example: Using Buffers instead of file paths
+ */
+
+import fs from 'node:fs';
+import * as honeydiff from '../index.js';
+
+async function main() {
+  console.log('Buffer Example\n');
+
+  // Load images as buffers
+  let img1Buffer = fs.readFileSync('../../tests/fixtures/screenshots/vizzly-baseline.png');
+  let img2Buffer = fs.readFileSync('../../tests/fixtures/screenshots/vizzly-with-diff.png');
+
+  console.log(`Loaded buffers: ${img1Buffer.length} and ${img2Buffer.length} bytes\n`);
+
+  // Compare using buffers
+  let result = await honeydiff.compare(img1Buffer, img2Buffer, {
+    pixelTolerance: 0,
+    includeSSIM: true,
+  });
+
+  console.log('Comparison result:');
+  console.log(`  Different: ${result.isDifferent}`);
+  console.log(`  Diff percentage: ${result.diffPercentage.toFixed(2)}%`);
+  console.log(`  SSIM: ${result.perceptualScore?.toFixed(4) || 'N/A'}`);
+
+  // Mixed: buffer + file path
+  console.log('\nMixed comparison (buffer + file path):');
+  let mixedResult = await honeydiff.compare(
+    img1Buffer,
+    '../../tests/fixtures/screenshots/vizzly-with-diff.png'
+  );
+  console.log(`  Diff percentage: ${mixedResult.diffPercentage.toFixed(2)}%`);
+}
+
+main().catch((err) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/examples/color-blindness.js

@@ -0,0 +1,211 @@
+/**
+ * Color Vision Deficiency (CVD) Simulation Example
+ *
+ * Demonstrates how to simulate color blindness for images and run
+ * accessibility analysis to ensure your UI works for all users.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  analyzeWcagAllCvd,
+  analyzeWcagForCvd,
+  getColorBlindnessTypes,
+  saveAllColorBlindnessSimulations,
+  saveColorBlindnessSimulation,
+  simulateColorBlindness,
+} from '../index.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function main() {
+  console.log('=== Color Vision Deficiency (CVD) Simulation Demo ===\n');
+
+  let testImage = path.join(__dirname, '../../../tests/fixtures/screenshots/vizzly-baseline.png');
+
+  // Example 1: Get information about CVD types
+  console.log('1. Available color blindness types:\n');
+  let types = getColorBlindnessTypes();
+  for (let cvd of types) {
+    console.log(`   ${cvd.name} (${cvd.type})`);
+    console.log(`     ${cvd.description}`);
+    console.log(`     Affects: ${cvd.prevalence}\n`);
+  }
+
+  // Example 2: Simulate a single CVD type and get buffer
+  console.log('2. Simulating deuteranopia (red-green color blindness)...');
+  try {
+    let simulatedBuffer = await simulateColorBlindness(testImage, 'deuteranopia');
+    console.log(`   Generated ${simulatedBuffer.length} bytes of simulated image data`);
+
+    // Save the buffer if you want
+    let outputPath = path.join(__dirname, '../cvd-deuteranopia.png');
+    fs.writeFileSync(outputPath, simulatedBuffer);
+    console.log(`   Saved to: ${outputPath}\n`);
+  } catch (error) {
+    console.error('   Error:', error.message, '\n');
+  }
+
+  // Example 3: Save CVD simulation directly to file
+  console.log('3. Saving protanopia simulation to file...');
+  try {
+    let outputPath = path.join(__dirname, '../cvd-protanopia.png');
+    await saveColorBlindnessSimulation(testImage, 'protanopia', outputPath);
+    console.log(`   Saved to: ${outputPath}\n`);
+  } catch (error) {
+    console.error('   Error:', error.message, '\n');
+  }
+
+  // Example 4: Generate all CVD simulations at once
+  console.log('4. Generating all CVD simulations...');
+  try {
+    let outputPrefix = path.join(__dirname, '../cvd-all');
+    await saveAllColorBlindnessSimulations(testImage, outputPrefix, 'png');
+    console.log('   Created files:');
+    console.log(`   - ${outputPrefix}_protanopia.png`);
+    console.log(`   - ${outputPrefix}_deuteranopia.png`);
+    console.log(`   - ${outputPrefix}_tritanopia.png`);
+    console.log(`   - ${outputPrefix}_achromatopsia.png\n`);
+  } catch (error) {
+    console.error('   Error:', error.message, '\n');
+  }
+
+  // Example 5: WCAG analysis for a specific CVD type
+  console.log('5. Analyzing WCAG contrast for deuteranopia users...');
+  try {
+    let analysis = await analyzeWcagForCvd(testImage, 'deuteranopia', {
+      checkAA: true,
+      checkAAA: false,
+      edgeThreshold: 60,
+    });
+
+    console.log(`   Total edges analyzed: ${analysis.totalEdges}`);
+    console.log(`   AA normal text pass rate: ${analysis.aaNormalPassPercentage.toFixed(1)}%`);
+    console.log(`   Violations found: ${analysis.violations.length}`);
+
+    if (analysis.violations.length > 0) {
+      console.log('\n   Top 3 violations:');
+      for (let i = 0; i < Math.min(3, analysis.violations.length); i++) {
+        let v = analysis.violations[i];
+        console.log(`   ${i + 1}. Location: (${v.boundingBox.x}, ${v.boundingBox.y})`);
+        console.log(`      Contrast: ${v.contrastRatio.toFixed(2)}:1`);
+        console.log(`      Pixels affected: ${v.pixelCount}`);
+      }
+    }
+    console.log();
+  } catch (error) {
+    console.error('   Error:', error.message, '\n');
+  }
+
+  // Example 6: Comprehensive CVD accessibility report
+  console.log('6. Running comprehensive CVD accessibility analysis...');
+  try {
+    let report = await analyzeWcagAllCvd(testImage, {
+      checkAA: true,
+      checkAAA: true,
+    });
+
+    console.log('\n   Accessibility Report:');
+    console.log('   ─────────────────────────────────────────────');
+    console.log(
+      `   Normal Vision:  ${report.normalVision.violations.length} violations ` +
+        `(${report.normalVision.aaNormalPassPercentage.toFixed(1)}% pass)`
+    );
+    console.log(
+      `   Protanopia:     ${report.protanopia.violations.length} violations ` +
+        `(${report.protanopia.aaNormalPassPercentage.toFixed(1)}% pass)`
+    );
+    console.log(
+      `   Deuteranopia:   ${report.deuteranopia.violations.length} violations ` +
+        `(${report.deuteranopia.aaNormalPassPercentage.toFixed(1)}% pass)`
+    );
+    console.log(
+      `   Tritanopia:     ${report.tritanopia.violations.length} violations ` +
+        `(${report.tritanopia.aaNormalPassPercentage.toFixed(1)}% pass)`
+    );
+    console.log('   ─────────────────────────────────────────────');
+    console.log(`   Total violations: ${report.totalViolations}`);
+    console.log(`   CVD-only violations: ~${report.cvdOnlyViolationCount}`);
+    console.log(`   Has any violations: ${report.hasAnyViolations}`);
+    console.log();
+  } catch (error) {
+    console.error('   Error:', error.message, '\n');
+  }
+
+  // Example 7: Using short aliases
+  console.log('7. Using short CVD type aliases...');
+  try {
+    // These are equivalent:
+    // 'protanopia' === 'protan'
+    // 'deuteranopia' === 'deutan'
+    // 'tritanopia' === 'tritan'
+    // 'achromatopsia' === 'achroma' === 'monochromacy'
+
+    let outputPath = path.join(__dirname, '../cvd-tritan.png');
+    await saveColorBlindnessSimulation(testImage, 'tritan', outputPath);
+    console.log(`   Saved tritanopia simulation using "tritan" alias`);
+    console.log(`   Output: ${outputPath}\n`);
+  } catch (error) {
+    console.error('   Error:', error.message, '\n');
+  }
+
+  // Example 8: Test integration example
+  console.log('8. Example test integration (pseudocode):');
+  console.log(`
+   // In your visual regression tests:
+   test('UI colors work for colorblind users', async () => {
+     let screenshot = await page.screenshot();
+
+     // Check accessibility for all CVD types
+     let report = await analyzeWcagAllCvd(screenshot, { checkAA: true });
+
+     // Assert no violations
+     expect(report.hasAnyViolations).toBe(false);
+
+     // Or check specific CVD types
+     expect(report.deuteranopia.violations.length).toBe(0);
+   });
+
+   test('chart is readable for protanopia users', async () => {
+     let chart = await page.screenshot({ element: '[data-testid="chart"]' });
+
+     // Simulate and compare
+     let simulated = await simulateColorBlindness(chart, 'protanopia');
+
+     // Verify distinguishability
+     let diff = await compare(chart, simulated);
+
+     // Some difference is expected, but important info should remain visible
+     let analysis = await analyzeWcagForCvd(chart, 'protanopia');
+     expect(analysis.aaNormalPassPercentage).toBeGreaterThan(90);
+   });
+  `);
+
+  // Cleanup generated files
+  console.log('9. Cleaning up generated files...');
+  let filesToClean = [
+    path.join(__dirname, '../cvd-deuteranopia.png'),
+    path.join(__dirname, '../cvd-protanopia.png'),
+    path.join(__dirname, '../cvd-tritan.png'),
+    path.join(__dirname, '../cvd-all_protanopia.png'),
+    path.join(__dirname, '../cvd-all_deuteranopia.png'),
+    path.join(__dirname, '../cvd-all_tritanopia.png'),
+    path.join(__dirname, '../cvd-all_achromatopsia.png'),
+  ];
+
+  for (let file of filesToClean) {
+    try {
+      if (fs.existsSync(file)) {
+        fs.unlinkSync(file);
+      }
+    } catch {
+      // ignore cleanup errors
+    }
+  }
+  console.log('   Cleaned up generated files.\n');
+
+  console.log('=== Demo Complete ===');
+}
+
+main().catch(console.error);

package/examples/typescript.ts

@@ -0,0 +1,78 @@
+/**
+ * TypeScript example with full type safety
+ */
+
+import { type CompareOptions, compare, type DiffResult, quickCompare } from '../index';
+
+async function main(): Promise<void> {
+  console.log('TypeScript Example\n');
+
+  // Quick comparison
+  let isDifferent: boolean = await quickCompare(
+    '../../tests/fixtures/screenshots/vizzly-baseline.png',
+    '../../tests/fixtures/screenshots/vizzly-with-diff.png'
+  );
+  console.log(`Quick result: ${isDifferent ? 'DIFFERENT' : 'IDENTICAL'}\n`);
+
+  // Detailed comparison with full typing
+  let options: CompareOptions = {
+    pixelTolerance: 5,
+    antialiasing: true,
+    includeSSIM: true,
+    includeClusters: true,
+    includeDiffPixels: false,
+  };
+
+  let result: DiffResult = await compare(
+    '../../tests/fixtures/screenshots/vizzly-baseline.png',
+    '../../tests/fixtures/screenshots/vizzly-with-diff.png',
+    options
+  );
+
+  console.log('Detailed results:');
+  console.log(`  Diff: ${result.diffPercentage.toFixed(2)}%`);
+  console.log(`  Different pixels: ${result.diffPixels} / ${result.totalPixels}`);
+
+  // Type-safe access to optional fields
+  if (result.perceptualScore !== null) {
+    let ssim: number = result.perceptualScore;
+    console.log(`  SSIM: ${ssim.toFixed(4)}`);
+
+    if (ssim > 0.95) {
+      console.log('  → Perceptually very similar');
+    } else if (ssim > 0.8) {
+      console.log('  → Somewhat similar');
+    } else {
+      console.log('  → Perceptually different');
+    }
+  }
+
+  if (result.boundingBox) {
+    console.log(
+      `  Changes in region: (${result.boundingBox.x}, ${result.boundingBox.y}) ${result.boundingBox.width}x${result.boundingBox.height}`
+    );
+  }
+
+  if (result.diffClusters && result.diffClusters.length > 0) {
+    console.log(`\nFound ${result.diffClusters.length} separate diff regions:`);
+    result.diffClusters.slice(0, 5).forEach((cluster, i) => {
+      let [cx, cy] = cluster.centerOfMass;
+      console.log(
+        `  ${i + 1}. ${cluster.pixelCount} pixels at (${cx.toFixed(0)}, ${cy.toFixed(0)})`
+      );
+    });
+  }
+
+  if (result.intensityStats) {
+    console.log('\nIntensity statistics:');
+    console.log(`  Range: ${result.intensityStats.min} - ${result.intensityStats.max}`);
+    console.log(`  Mean: ${result.intensityStats.mean.toFixed(1)}`);
+    console.log(`  Median: ${result.intensityStats.median}`);
+    console.log(`  Std Dev: ${result.intensityStats.stdDev.toFixed(1)}`);
+  }
+}
+
+main().catch((err: Error) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/examples/wcag.js

@@ -0,0 +1,159 @@
+/**
+ * WCAG Accessibility Testing Example
+ *
+ * Demonstrates how to analyze images for WCAG color contrast violations
+ * and generate visual overlays showing problematic regions.
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { analyzeWcagContrast, saveWcagOverlay } from '../index.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function main() {
+  console.log('=== WCAG Accessibility Testing Demo ===\n');
+
+  // Example 1: Basic WCAG analysis
+  console.log('1. Running basic WCAG AA analysis...');
+  try {
+    let analysis = await analyzeWcagContrast(
+      path.join(__dirname, '../../../tests/fixtures/screenshots/vizzly-baseline.png'),
+      {
+        edgeThreshold: 60,
+        minRegionSize: 50,
+        checkAA: true,
+        checkAAA: false,
+      }
+    );
+
+    console.log(`   Total edges detected: ${analysis.totalEdges}`);
+    console.log(`   AA normal text pass rate: ${analysis.aaNormalPassPercentage.toFixed(1)}%`);
+    console.log(`   AA large text pass rate: ${analysis.aaLargePassPercentage.toFixed(1)}%`);
+    console.log(`   Violations found: ${analysis.violations.length}\n`);
+
+    if (analysis.violations.length > 0) {
+      console.log('   Top 5 violations by size:');
+      for (let i = 0; i < Math.min(5, analysis.violations.length); i++) {
+        let violation = analysis.violations[i];
+        console.log(
+          `   ${i + 1}. Region at (${violation.boundingBox.x}, ${violation.boundingBox.y})`
+        );
+        console.log(`      Contrast ratio: ${violation.contrastRatio.toFixed(2)}:1`);
+        console.log(`      Pixels affected: ${violation.pixelCount}`);
+        console.log(
+          `      Fails AA normal: ${violation.failsAaNormal}, Fails AA large: ${violation.failsAaLarge}`
+        );
+      }
+      console.log();
+    }
+  } catch (error) {
+    console.error('   Error:', error.message);
+  }
+
+  // Example 2: WCAG AAA analysis (stricter)
+  console.log('2. Running strict WCAG AAA analysis...');
+  try {
+    let analysis = await analyzeWcagContrast(
+      path.join(__dirname, '../../../tests/fixtures/screenshots/vizzly-baseline.png'),
+      {
+        edgeThreshold: 60,
+        minRegionSize: 50,
+        checkAA: true,
+        checkAAA: true,
+      }
+    );
+
+    console.log(`   Total edges detected: ${analysis.totalEdges}`);
+    console.log(`   AAA normal text pass rate: ${analysis.aaaNormalPassPercentage.toFixed(1)}%`);
+    console.log(`   AAA large text pass rate: ${analysis.aaaLargePassPercentage.toFixed(1)}%`);
+    console.log(`   AAA violations found: ${analysis.violations.length}\n`);
+  } catch (error) {
+    console.error('   Error:', error.message);
+  }
+
+  // Example 3: Generate visual overlay
+  console.log('3. Generating visual overlay...');
+  try {
+    let analysis = await analyzeWcagContrast(
+      path.join(__dirname, '../../../tests/fixtures/screenshots/vizzly-baseline.png'),
+      {
+        checkAA: true,
+        checkAAA: false,
+      }
+    );
+
+    let outputPath = path.join(__dirname, '../wcag-violations.png');
+
+    await saveWcagOverlay(
+      path.join(__dirname, '../../../tests/fixtures/screenshots/vizzly-baseline.png'),
+      analysis,
+      outputPath,
+      {
+        highlightColor: [255, 0, 0, 180], // Semi-transparent red
+      }
+    );
+
+    console.log(`   ✓ Overlay saved to: ${outputPath}\n`);
+  } catch (error) {
+    console.error('   Error:', error.message);
+  }
+
+  // Example 4: Synchronous API (for simple scripts)
+  console.log('4. Using synchronous API...');
+  try {
+    const { analyzeWcagContrastSync } = require('../index.js');
+
+    let analysis = analyzeWcagContrastSync(
+      path.join(__dirname, '../../../tests/fixtures/screenshots/vizzly-baseline.png'),
+      {
+        edgeThreshold: 80, // More lenient threshold
+        minRegionSize: 100, // Larger regions only
+      }
+    );
+
+    console.log(`   Total edges: ${analysis.totalEdges}`);
+    console.log(`   Violations: ${analysis.violations.length}`);
+    console.log(`   Pass rate: ${analysis.aaNormalPassPercentage.toFixed(1)}%\n`);
+  } catch (error) {
+    console.error('   Error:', error.message);
+  }
+
+  // Example 5: Detailed violation analysis
+  console.log('5. Analyzing violation details...');
+  try {
+    let analysis = await analyzeWcagContrast(
+      path.join(__dirname, '../../../tests/fixtures/screenshots/vizzly-baseline.png')
+    );
+
+    if (analysis.violations.length > 0) {
+      let violation = analysis.violations[0];
+
+      console.log('   First violation details:');
+      console.log(`   - Location: (${violation.boundingBox.x}, ${violation.boundingBox.y})`);
+      console.log(`   - Size: ${violation.boundingBox.width}x${violation.boundingBox.height}`);
+      console.log(
+        `   - Center: (${violation.centerOfMass[0].toFixed(1)}, ${violation.centerOfMass[1].toFixed(1)})`
+      );
+      console.log(`   - Foreground color: rgba(${violation.foregroundColor.join(', ')})`);
+      console.log(`   - Background color: rgba(${violation.backgroundColor.join(', ')})`);
+      console.log(`   - Foreground luminance: ${violation.foregroundLuminance.toFixed(3)}`);
+      console.log(`   - Background luminance: ${violation.backgroundLuminance.toFixed(3)}`);
+      console.log(
+        `   - Contrast ratio: ${violation.contrastRatio.toFixed(2)}:1 (${violation.minContrastRatio.toFixed(2)} - ${violation.maxContrastRatio.toFixed(2)})`
+      );
+      console.log(`   - Pixel count: ${violation.pixelCount}`);
+      console.log('   - WCAG Status:');
+      console.log(`     AA Normal (4.5:1): ${violation.failsAaNormal ? '❌ FAIL' : '✓ PASS'}`);
+      console.log(`     AA Large (3.0:1): ${violation.failsAaLarge ? '❌ FAIL' : '✓ PASS'}`);
+      console.log(`     AAA Normal (7.0:1): ${violation.failsAaaNormal ? '❌ FAIL' : '✓ PASS'}`);
+      console.log(`     AAA Large (4.5:1): ${violation.failsAaaLarge ? '❌ FAIL' : '✓ PASS'}`);
+    }
+  } catch (error) {
+    console.error('   Error:', error.message);
+  }
+
+  console.log('\n=== Demo Complete ===');
+}
+
+main().catch(console.error);

package/index.d.ts

@@ -91,12 +91,67 @@ export interface DiffResult {
   intensityStats: IntensityStats | null;
   /** SSIM (Structural Similarity Index) perceptual score 0.0-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;
 }
 
 // ============================================================================
 // 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;
+
+  /**
+   * 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;
+
+  /**
+   * 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;
+
+  /**
+   * Maximum width ratio between clusters to allow merging
+   *
+   * Additional SWT-inspired heuristic to prevent merging dissimilar
+   * regions.
+   * @default 3.0
+   */
+  maxWidthRatio?: number;
+}
+
 export interface CompareOptions {
   /**
    * Perceptual color difference threshold using CIEDE2000 (Delta E units)
@@ -145,6 +200,23 @@ export interface CompareOptions {
    */
   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.
+   *
+   * **Note:** GMSD requires images with identical dimensions. For variable-height
+   * comparisons, `gmsdScore` will be `null`. Use SSIM for variable-height 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
    *
@@ -161,6 +233,28 @@ export interface CompareOptions {
    */
   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
@@ -1049,3 +1143,131 @@ export function analyzeWcagAllCvdSync(img: ImageInput, options?: WcagOptions): C
  * ```
  */
 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.
+   */
+  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 fingerprintHashSync(fingerprint: DiffFingerprint): string;

package/index.js

@@ -66,3 +66,8 @@ export const analyzeWcagForCvdSync = addon.analyzeWcagForCvdSync;
 export const analyzeWcagAllCvd = addon.analyzeWcagAllCvd;
 export const analyzeWcagAllCvdSync = addon.analyzeWcagAllCvdSync;
 export const getColorBlindnessTypes = addon.getColorBlindnessTypes;
+
+// Diff Fingerprint API
+export const computeFingerprintSync = addon.computeFingerprintSync;
+export const fingerprintSimilaritySync = addon.fingerprintSimilaritySync;
+export const fingerprintHashSync = addon.fingerprintHashSync;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/honeydiff",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "High-performance image diffing for Node.js - Native bindings to Honeydiff Rust library",
   "type": "module",
   "main": "index.js",
@@ -48,6 +48,7 @@
     "index.d.ts",
     "load-platform.cjs",
     "platforms/*.node",
+    "examples/",
     "README.md",
     "CHANGELOG.md"
   ],