@vizzly-testing/honeydiff 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.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/index.d.ts

@@ -93,19 +93,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
+   * 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
    */
-  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
-   */
-  colorThreshold?: number;
+  threshold?: number;
 
   /**
    * Enable anti-aliasing detection to ignore AA differences
@@ -113,12 +111,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)
@@ -194,7 +186,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 +230,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.5.0",
   "description": "High-performance image diffing for Node.js - Native bindings to Honeydiff Rust library",
   "type": "module",
   "main": "index.js",
@@ -63,6 +63,12 @@
     "load-platform.cjs",
     "platforms/*.node",
     "README.md",
+    "CHANGELOG.md",
+    "index.js",
+    "index.d.ts",
+    "load-platform.cjs",
+    "platforms/*.node",
+    "README.md",
     "CHANGELOG.md"
   ],
   "engines": {