@vizzly-testing/honeydiff 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.1] - 2026-03-11
+
+## What's Changed
+
+### Fixed
+- Variable-height image comparisons now correctly return diff clusters for the height-difference region. Previously, when a baseline and current screenshot had different heights, `diffClusters` was empty even though `isDifferent` was `true` and `diffPixels` was non-zero — meaning callers had no bounding box to highlight. A synthetic cluster covering the full-width region at the height boundary is now included in `diffClusters`.
+
+**Full Changelog**: https://github.com/vizzly-testing/honeydiff/compare/v0.10.0...v0.10.1
+
+## [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

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:
@@ -558,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
@@ -606,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/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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/honeydiff",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "High-performance image diffing for Node.js - Native bindings to Honeydiff Rust library",
   "type": "module",
   "main": "index.js",