@vizzly-testing/honeydiff 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-07-19
+
+### Fixed
+- Prevented AA filtering from hiding thin border and divider recoloring by
+  requiring cross-image raster displacement.
+- Compared rendered RGBA appearance, including opacity changes, while ignoring
+  hidden RGB under full transparency.
+- Kept zero-threshold results and artifact masks consistent for low-alpha RGBA.
+- Kept optional metrics independent from threshold and AA-filtered diff counts.
+- Corrected small-image SSIM/MS-SSIM, GMSD boundaries, and exact artifact masks.
+- Matched the authors' MS-SSIM pyramid, pooling, and direct weight semantics,
+  plus GMSD's exact normalized constant and sample-deviation pooling.
+- Made capped comparisons classify from observed pixel evidence regardless of
+  cluster policy, preventing early exit from reporting false identity.
+- Kept diff pixels and clusters null unless callers request them.
+- Added Node boundary coverage for transparency, evidence privacy, exact RGBA,
+  and metric independence.
+
+**Full Changelog**: https://github.com/vizzly-testing/honeydiff/compare/v0.11.1...v0.12.0
+
 ## [0.11.1] - 2026-06-20
 
 ## What's Changed

package/README.md

@@ -53,8 +53,11 @@ Most image diff packages stop at basic pixel comparison. Honeydiff gives you the
 pieces visual regression systems usually need once screenshots get real:
 
 - CIEDE2000 perceptual color thresholds, with `2.0` as the default.
-- Strict exact matching when you set `threshold: 0`.
+- Zero perceptual tolerance with `threshold: 0`; disable AA and set
+  `minClusterSize: 1` for strict rendered-pixel matching.
 - Conservative anti-aliasing detection for font and sub-pixel rendering noise.
+- RGBA-aware comparison that detects opacity changes and ignores RGB payload
+  hidden behind full transparency.
 - Variable-height screenshot support for full-page comparisons.
 - Diff, mask, and overlay image artifacts for debugging failures.
 - Spatial clusters, intensity stats, SSIM, GMSD, and diff fingerprints.
@@ -162,9 +165,9 @@ await saveColorBlindnessSimulation(
 
 | Option | Default | Notes |
 | --- | --- | --- |
-| `threshold` | `2.0` | CIEDE2000 Delta E threshold. Use `0` for exact matching. |
+| `threshold` | `2.0` | CIEDE2000 Delta E threshold. Use `0` for zero perceptual tolerance. |
 | `antialiasing` | `true` | Ignore likely anti-aliased pixels. |
-| `maxDiffs` | unlimited | Stop after a maximum number of differing pixels. |
+| `maxDiffs` | unlimited | Stop after a maximum number of differing pixels. Capped results classify from the pixels observed before early exit, without cluster filtering. |
 | `includeDiffPixels` | `false` | Return individual differing pixel positions and intensities. |
 | `includeClusters` | `false` | Return connected regions of visual change. |
 | `minClusterSize` | `2` | Filter tiny isolated clusters as noise. |
@@ -204,7 +207,7 @@ Honeydiff uses CIEDE2000 Delta E for perceptual color difference.
 
 | Threshold | Meaning |
 | --- | --- |
-| `0` | Exact pixel matching. |
+| `0` | No Delta E tolerance; AA and cluster filtering still apply if enabled. |
 | `1` | Barely noticeable color changes. |
 | `2` | Recommended default for UI screenshots. |
 | `3+` | More tolerant of rendering differences. |
@@ -213,7 +216,7 @@ The default is intentionally practical for browser and app screenshots: it
 filters tiny rendering variance while still catching meaningful UI changes.
 
 The cited algorithms and standards are listed in the repo's
-[References](../../docs/REFERENCES.md), including CIEDE2000, SSIM, MS-SSIM,
+[References](https://github.com/vizzly-testing/honeydiff/blob/main/docs/REFERENCES.md), including CIEDE2000, SSIM, MS-SSIM,
 GMSD, Brettel CVD simulation, sRGB, and WCAG contrast math.
 
 ## Performance
@@ -222,12 +225,12 @@ Current local benchmark snapshots:
 
 | Scenario | Result |
 | --- | ---: |
-| Full HD default comparison | ~31.6ms |
-| Full HD strict threshold with AA | ~103ms |
-| Identical image fast path | ~0.34ms |
-| 4K default comparison | ~131ms |
-| Tall screenshot default comparison | ~192ms |
-| Tall screenshot exact/no-AA comparison | ~4.1ms |
+| Vizzly screenshot default comparison | ~2.81ms |
+| Vizzly screenshot strict/no-AA comparison | ~2.18ms |
+| Tall screenshot default comparison | ~147ms |
+| Tall screenshot strict/no-AA comparison | ~4.34ms |
+| 1080p isolated SSIM | ~14.7ms |
+| 1080p isolated GMSD | ~10.9ms |
 
 See [benchmarks/BENCHMARK_RESULTS.md](https://github.com/vizzly-testing/honeydiff/blob/main/benchmarks/BENCHMARK_RESULTS.md)
 for the current benchmark notes.

package/index.d.ts

@@ -89,7 +89,7 @@ export interface DiffResult {
   diffClusters: DiffCluster[] | null;
   /** Statistical metrics about difference intensities (null unless includeDiffPixels is enabled) */
   intensityStats: IntensityStats | null;
-  /** SSIM (Structural Similarity Index) perceptual score 0.0-1.0 (null unless includeSSIM is enabled) */
+  /** SSIM score, approximately -1.0 to 1.0 (null unless includeSSIM is enabled) */
   perceptualScore: number | null;
   /**
    * GMSD (Gradient Magnitude Similarity Deviation) score (null unless includeGMSD is enabled)
@@ -157,7 +157,7 @@ export interface CompareOptions {
    * Perceptual color difference threshold using CIEDE2000 (Delta E units)
    *
    * The CIEDE2000 standard provides intuitive, perceptually uniform thresholds:
-   * - 0.0 = Exact pixel matching (strictest)
+   * - 0.0 = No Delta E tolerance; AA and cluster filtering remain independent
    * - 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
@@ -168,12 +168,17 @@ export interface CompareOptions {
 
   /**
    * Enable anti-aliasing detection to ignore AA differences
+   *
+   * Suppression requires a luminance ramp plus strict cross-image evidence that
+   * raster coverage moved to a neighboring pixel. Stable edge recolors remain differences.
    * @default true
    */
   antialiasing?: boolean;
 
   /**
    * Maximum number of differences to detect before stopping
+   * Capped comparisons classify from observed pixel evidence because early
+   * exit cannot determine whether a complete cluster meets minClusterSize.
    * @default undefined (unlimited)
    */
   maxDiffs?: number;
@@ -194,7 +199,10 @@ export interface CompareOptions {
 
   /**
    * Calculate SSIM (Structural Similarity Index) perceptual score
-   * WARNING: SSIM can be computationally expensive on large images
+   * This metric measures the source images independently of threshold and AA
+   * filtering. Transparent inputs are evaluated over black and white mattes,
+   * keeping the more conservative score.
+   * WARNING: SSIM can use substantial memory on large images.
    * @default false
    */
   includeSSIM?: boolean;
@@ -205,6 +213,8 @@ export interface CompareOptions {
    * GMSD is very fast and highly sensitive to edge/structural changes.
    * Useful for detecting border thickness changes, font weight shifts,
    * and icon updates.
+   * A score of 0 does not prove image identity; uniform changes can have no
+   * spatial variation in gradient degradation.
    *
    * **Note:** For variable-height comparisons, GMSD is calculated on the
    * overlapping region shared by both images.
@@ -223,9 +233,9 @@ export interface CompareOptions {
    * 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
+   * - 1 = Any surviving diff pixel counts
    * - 2 = Default - filters single isolated pixels as noise
-   * - 3+ = More permissive - only larger clusters detected
+   * - 3+ = More aggressive noise filtering
    *
    * When set to a value > 1, clustering is automatically enabled.
    * @default 2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/honeydiff",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "High-performance image diffing for Node.js - Native bindings to Honeydiff Rust library",
   "type": "module",
   "main": "index.js",
@@ -59,6 +59,7 @@
   "devDependencies": {
     "@biomejs/biome": "2.3.8",
     "@types/node": "^24.10.1",
+    "pngjs": "^7.0.0",
     "typescript": "^5.9.3"
   },
   "bugs": {