@vizzly-testing/honeydiff 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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

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;
@@ -139,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/honeydiff",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "High-performance image diffing for Node.js - Native bindings to Honeydiff Rust library",
   "type": "module",
   "main": "index.js",
@@ -69,6 +69,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": {