@vizzly-testing/honeydiff 0.12.0 → 0.13.0

package/CHANGELOG.md

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

package/README.md

@@ -187,6 +187,9 @@ interface DiffResult {
   diffPercentage: number;
   totalPixels: number;
   diffPixels: number;
+  effectiveDiffPixels: number;
+  effectiveMaskComplete: boolean;
+  maskSemanticsVersion: string;
   aaPixelsIgnored: number;
   aaPercentage: number;
   boundingBox: BoundingBox | null;
@@ -199,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

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) */
@@ -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
 // ============================================================================

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.12.0",
+  "version": "0.13.0",
   "description": "High-performance image diffing for Node.js - Native bindings to Honeydiff Rust library",
   "type": "module",
   "main": "index.js",