@vizzly-testing/honeydiff 0.11.1 → 0.13.0

package/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-07-23
+
+### Added
+- Exposed `effectiveDiffPixels`, `effectiveMaskComplete`,
+  `maskSemanticsVersion`, and the installed package `version` for auditable
+  mask consumers.
+
+### Fixed
+- Kept binary mask alpha opaque even when a transparent display diff color is
+  requested.
+- Kept requested pixel and cluster diagnostics from changing the effective mask
+  or variable-height classification.
+
+**Full Changelog**: https://github.com/vizzly-testing/honeydiff/compare/v0.12.0...v0.13.0
+
+## [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. |
@@ -184,6 +187,9 @@ interface DiffResult {
   diffPercentage: number;
   totalPixels: number;
   diffPixels: number;
+  effectiveDiffPixels: number;
+  effectiveMaskComplete: boolean;
+  maskSemanticsVersion: string;
   aaPixelsIgnored: number;
   aaPercentage: number;
   boundingBox: BoundingBox | null;
@@ -196,6 +202,16 @@ interface DiffResult {
 }
 ```
 
+`diffPixels` is the raw post-threshold/anti-aliasing count.
+`effectiveDiffPixels` is the retained count represented by the binary mask after
+`minClusterSize` filtering. It always matches the mask's nontransparent pixel
+count. If `effectiveMaskComplete` is `false`, `maxDiffs` stopped the scan early;
+the partial mask is useful for diagnostics but not complete spatial proof.
+Requesting `diffPixelsList` or `diffClusters` never changes that retained result.
+
+The package also exports `version` from its installed manifest and
+`maskSemanticsVersion` from the native comparison engine.
+
 See [index.d.ts](./index.d.ts) for the full API surface.
 
 ## Thresholds
@@ -204,7 +220,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 +229,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 +238,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

@@ -75,6 +75,12 @@ export interface DiffResult {
    * Note: This may be > 0 even when isDifferent is false if small clusters were filtered as noise
    */
   diffPixels: number;
+  /** Number of retained pixels represented by the effective diff mask */
+  effectiveDiffPixels: number;
+  /** False when maxDiffs stopped the scan before the full image was evaluated */
+  effectiveMaskComplete: boolean;
+  /** Version of the pixel-retention semantics used by the effective mask */
+  maskSemanticsVersion: string;
   /** Number of pixels ignored due to anti-aliasing detection */
   aaPixelsIgnored: number;
   /** Percentage of pixels ignored as anti-aliasing (0.0 - 100.0) */
@@ -89,7 +95,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)
@@ -99,6 +105,12 @@ export interface DiffResult {
   gmsdScore: number | null;
 }
 
+/** Installed @vizzly-testing/honeydiff package version */
+export const version: string;
+
+/** Native effective-mask semantics implemented by this package */
+export const maskSemanticsVersion: string;
+
 // ============================================================================
 // Options
 // ============================================================================
@@ -157,7 +169,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 +180,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 +211,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 +225,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 +245,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/index.js

@@ -2,7 +2,7 @@
  * @vizzly-testing/honeydiff - Native Node.js bindings for Honeydiff
  */
 
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -11,6 +11,7 @@ const require = createRequire(import.meta.url);
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 let addon;
+let packageMetadata = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
 
 // Try to load the native addon:
 // 1. First try load-platform.cjs (exists in published npm package with multi-platform binaries)
@@ -41,6 +42,8 @@ export const compareSync = addon.compareSync;
 export const quickCompareSync = addon.quickCompareSync;
 export const getDimensions = addon.getDimensions;
 export const getDimensionsSync = addon.getDimensionsSync;
+export const maskSemanticsVersion = addon.maskSemanticsVersion;
+export const version = packageMetadata.version;
 
 // Image Metadata API
 export const getImageMetadata = addon.getImageMetadata;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/honeydiff",
-  "version": "0.11.1",
+  "version": "0.13.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": {