@vizzly-testing/honeydiff 0.4.3 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,66 @@ 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.6.0] - 2025-12-10
+
+## What's Changed
+
+### Added
+- **Noise filtering with `minClusterSize` option** - New option to filter out single-pixel rendering variance while catching real visual changes. Defaults to `2` (filters isolated pixels), can be set to `1` for exact matching or `3+` for more permissive detection. Clustering is automatically enabled when `minClusterSize > 1`.
+
+### Changed
+- **`isDifferent` now respects noise filtering** - When `minClusterSize` is set, small clusters below the threshold are filtered out, meaning `isDifferent` may be `false` even when `diffPixels > 0` (those pixels were classified as noise)
+- **`diffPixels` reports raw count** - The raw pixel count is now unaffected by `minClusterSize` filtering, showing all differing pixels including those filtered as noise
+- **Documentation improvements** - Added comprehensive documentation for the `minClusterSize` option in TypeScript types and README, including a behavior table and usage examples
+
+### Fixed
+- Height differences now always count regardless of clustering (structural changes are never filtered as noise)
+
+**Full Changelog**: https://github.com/vizzly-testing/honeydiff/compare/v0.5.0...v0.6.0
+
+## [0.5.0] - 2025-12-04
+
+## What's Changed
+
+### Changed
+
+**⚠️ BREAKING CHANGE: Switched from YIQ to CIEDE2000 for perceptual color comparison**
+
+The image comparison algorithm has been upgraded to use the industry-standard CIEDE2000 (Delta E) metric, providing superior perceptual accuracy compared to the previous YIQ approach.
+
+**API Changes:**
+- **Removed:** `colorThreshold` option (0.0-1.0 scale)
+- **Removed:** `pixelTolerance` option (0-255 scale)
+- **Removed:** `ignoreColors` option
+- **Added:** `threshold` option using CIEDE2000 Delta E units with intuitive perceptual scale:
+  - `0.0` = Exact pixel matching (strictest)
+  - `1.0` = Just Noticeable Difference (JND) - barely perceptible to trained observers
+  - `2.0` = **Recommended default** - ignores sub-pixel rendering variance, catches real differences
+  - `3.0+` = Permissive - high tolerance for rendering variations
+
+**Migration Guide:**
+```typescript
+// Before (v0.4.x)
+const result = await compare('baseline.png', 'current.png', {
+  pixelTolerance: 10,      // ❌ Removed
+  colorThreshold: 0.1,     // ❌ Removed
+  ignoreColors: false      // ❌ Removed
+});
+
+// After (v0.5.0)
+const result = await compare('baseline.png', 'current.png', {
+  threshold: 2.0           // ✅ CIEDE2000 Delta E units (new default)
+});
+```
+
+**Benefits:**
+- More accurate perceptual color difference detection
+- Aligns with CIE standards used in color science
+- Better handling of subtle color variations
+- Improved anti-aliasing detection accuracy
+
+**Full Changelog**: https://github.com/vizzly-testing/honeydiff/compare/v0.4.3...v0.5.0
+
 ## [0.4.3] - 2025-12-01
 
 ## What's Changed

package/README.md

@@ -154,13 +154,14 @@ const result = await compare('baseline.png', 'current.png', {
 console.log('Artifacts saved to ./artifacts/');
 ```
 
-### 5. Spatial Clustering
+### 5. Spatial Clustering & Noise Filtering
 
-Group nearby differences into regions to identify distinct changed areas.
+Group nearby differences into regions and filter out single-pixel noise from rendering variance.
 
 ```javascript
 const result = await compare('img1.png', 'img2.png', {
-  includeClusters: true
+  includeClusters: true,
+  minClusterSize: 2  // Default: filter single isolated pixels as noise
 });
 
 if (result.diffClusters) {
@@ -180,6 +181,13 @@ if (result.diffClusters) {
 //   - Average intensity: 127.3
 ```
 
+**Noise filtering values:**
+| Value | Behavior |
+|-------|----------|
+| 1 | Exact matching - any different pixel counts |
+| 2 | Default - filters single isolated pixels as rendering noise |
+| 3+ | More permissive - only larger clusters detected |
+
 ### 6. Perceptual Similarity (SSIM)
 
 Beyond pixel counting - measure structural similarity from a human perception perspective.
@@ -445,6 +453,7 @@ interface CompareOptions {
   includeDiffPixels?: boolean;          // List all diff pixels (memory intensive, default: false)
   includeClusters?: boolean;            // Spatial clustering (default: false)
   includeSSIM?: boolean;                // SSIM perceptual score (slow, default: false)
+  minClusterSize?: number;              // Filter clusters smaller than this (default: 2)
 
   // Accessibility options
   includeAccessibilityData?: boolean;   // RGB, luminance, WCAG (default: false)
@@ -464,10 +473,10 @@ interface CompareOptions {
 ```typescript
 interface DiffResult {
   // Basic metrics
-  isDifferent: boolean;                 // Are images different?
+  isDifferent: boolean;                 // Are images different? (respects minClusterSize filtering)
   diffPercentage: number;               // 0.0-100.0
   totalPixels: number;
-  diffPixels: number;
+  diffPixels: number;                   // Raw count (unaffected by minClusterSize filtering)
 
   // Anti-aliasing
   aaPixelsIgnored: number;

package/index.d.ts

@@ -61,13 +61,19 @@ export interface DiffCluster {
 }
 
 export interface DiffResult {
-  /** Whether the images are different based on the comparison threshold */
+  /**
+   * Whether the images are different based on the comparison threshold
+   * Note: This respects minClusterSize filtering - small clusters may be filtered as noise
+   */
   isDifferent: boolean;
   /** Percentage of pixels that differ (0.0 - 100.0) */
   diffPercentage: number;
   /** Total number of pixels compared */
   totalPixels: number;
-  /** Number of pixels that differ */
+  /**
+   * Number of pixels that differ (raw count, unaffected by minClusterSize filtering)
+   * Note: This may be > 0 even when isDifferent is false if small clusters were filtered as noise
+   */
   diffPixels: number;
   /** Number of pixels ignored due to anti-aliasing detection */
   aaPixelsIgnored: number;
@@ -93,19 +99,17 @@ export interface DiffResult {
 
 export interface CompareOptions {
   /**
-   * Pixel difference threshold (0-255). Differences below this are ignored.
-   * NOTE: When using YIQ comparison, use colorThreshold instead (0.0-1.0)
-   * @default 0
-   */
-  pixelTolerance?: number;
-
-  /**
-   * Color difference threshold for YIQ comparison (0.0-1.0)
-   * Set to 0.0 to use RGB comparison (default)
-   * Set to 0.1 for odiff-style YIQ comparison
-   * @default 0.0
+   * Perceptual color difference threshold using CIEDE2000 (Delta E units)
+   *
+   * The CIEDE2000 standard provides intuitive, perceptually uniform thresholds:
+   * - 0.0 = Exact pixel matching (strictest)
+   * - 1.0 = Just Noticeable Difference (JND) - barely perceptible to trained observers
+   * - 2.0 = Recommended default - ignores sub-pixel rendering variance, catches real differences
+   * - 3.0+ = Permissive - high tolerance for rendering variations
+   *
+   * @default 2.0
    */
-  colorThreshold?: number;
+  threshold?: number;
 
   /**
    * Enable anti-aliasing detection to ignore AA differences
@@ -113,12 +117,6 @@ export interface CompareOptions {
    */
   antialiasing?: boolean;
 
-  /**
-   * Ignore color differences (compare only structure/brightness)
-   * @default false
-   */
-  ignoreColors?: boolean;
-
   /**
    * Maximum number of differences to detect before stopping
    * @default undefined (unlimited)
@@ -147,6 +145,22 @@ export interface CompareOptions {
    */
   includeSSIM?: boolean;
 
+  /**
+   * Minimum cluster size to count as a real difference
+   *
+   * Clusters smaller than this threshold are filtered out as noise.
+   * This helps ignore run-to-run rendering variance (scattered single pixels)
+   * while still catching real visual changes (grouped pixel differences).
+   *
+   * - 1 = Exact matching - any different pixel counts
+   * - 2 = Default - filters single isolated pixels as noise
+   * - 3+ = More permissive - only larger clusters detected
+   *
+   * When set to a value > 1, clustering is automatically enabled.
+   * @default 2
+   */
+  minClusterSize?: number;
+
   /**
    * Path to save the diff image (highlighted differences)
    * @default undefined
@@ -194,7 +208,7 @@ export type ImageInput = string | Buffer;
  * @example
  * ```typescript
  * const result = await compare('baseline.png', 'current.png', {
- *   pixelTolerance: 10,
+ *   threshold: 2.0,  // CIEDE2000 Delta E (default)
  *   includeSSIM: true
  * });
  *
@@ -238,7 +252,7 @@ export function quickCompare(img1: ImageInput, img2: ImageInput): Promise<boolea
  * @example
  * ```typescript
  * const result = compareSync('baseline.png', 'current.png', {
- *   pixelTolerance: 5,
+ *   threshold: 3.0,  // More lenient threshold
  *   includeClusters: true
  * });
  *

package/package.json

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