@vizzly-testing/honeydiff 0.13.1 → 0.14.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-07-24
+
+### Added
+- Added opt-in, versioned `diffMaskEvidence` with a native analysis
+  identity, bitmap dimensions, completeness, and exact 8-connected component
+  facts derived from the retained pixels used by mask artifacts.
+
+### Changed
+- Named retained mask facts consistently around Honeydiff's diff-mask artifact:
+  `diffMaskPixels`, `diffMaskComplete`, `diffMaskEvidence`, and
+  `includeDiffMaskEvidence`.
+- Diff-mask artifact generation reuses requested native evidence instead
+  of repeating the comparison to recover filtered coordinates.
+
+**Full Changelog**: https://github.com/vizzly-testing/honeydiff/compare/v0.13.1...v0.14.0
+
 ## [0.13.1] - 2026-07-23
 
 ### Changed
@@ -18,14 +34,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.13.0] - 2026-07-23
 
 ### Added
-- Exposed `effectiveDiffPixels`, `effectiveMaskComplete`,
-  `maskSemanticsVersion`, and the installed package `version` for auditable
-  mask consumers.
+- Exposed retained mask pixel count, completeness, semantics version, 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
+- Kept requested pixel and cluster diagnostics from changing the diff mask
   or variable-height classification.
 
 **Full Changelog**: https://github.com/vizzly-testing/honeydiff/compare/v0.12.0...v0.13.0

package/README.md

@@ -121,6 +121,25 @@ for (let cluster of result.diffClusters ?? []) {
 }
 ```
 
+### Persist Authoritative Mask Evidence
+
+Use diff-mask evidence when another system needs durable spatial facts
+without decoding the generated PNG:
+
+```js
+let result = await compare('baseline.png', 'current.png', {
+  includeDiffMaskEvidence: true,
+  maskPath: 'artifacts/mask.png',
+});
+
+console.log(result.diffMaskEvidence?.analysisContractHash);
+console.log(result.diffMaskEvidence?.components);
+```
+
+The components are exact 8-connected groups of retained mask pixels. They are
+separate from `diffClusters`, whose optional merge heuristics are intended for
+diagnostic presentation.
+
 ### Add Perceptual Metrics
 
 ```js
@@ -170,6 +189,7 @@ await saveColorBlindnessSimulation(
 | `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. |
+| `includeDiffMaskEvidence` | `false` | Return authoritative diff-mask identity, dimensions, and exact components. |
 | `minClusterSize` | `2` | Filter tiny isolated clusters as noise. |
 | `clusterMerge` | disabled | Merge nearby clusters into logical text-like regions. |
 | `includeSSIM` | `false` | Calculate structural similarity. More expensive on large images. |
@@ -187,9 +207,10 @@ interface DiffResult {
   diffPercentage: number;
   totalPixels: number;
   diffPixels: number;
-  effectiveDiffPixels: number;
-  effectiveMaskComplete: boolean;
+  diffMaskPixels: number;
+  diffMaskComplete: boolean;
   maskSemanticsVersion: string;
+  diffMaskEvidence: DiffMaskEvidence | null;
   aaPixelsIgnored: number;
   aaPercentage: number;
   boundingBox: BoundingBox | null;
@@ -203,11 +224,14 @@ interface DiffResult {
 ```
 
 `diffPixels` is the raw post-threshold/anti-aliasing count.
-`effectiveDiffPixels` is the retained count represented by the binary mask after
+`diffMaskPixels` 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;
+count. If `diffMaskComplete` 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.
+`diffMaskEvidence` is returned only when `includeDiffMaskEvidence` is enabled. Its
+native analysis hash covers every normalized option that can change retained
+pixels, and its component pixel counts sum to `diffMaskPixels`.
 
 The package also exports `version` from its installed manifest and
 `maskSemanticsVersion` from the native comparison engine.

package/index.d.ts

@@ -60,6 +60,36 @@ export interface DiffCluster {
   boundingBox: BoundingBox;
 }
 
+export interface DiffMaskComponent {
+  /** Number of retained pixels in this exact 8-connected component */
+  pixelCount: number;
+  /** Bitmap-pixel bounds around the component */
+  boundingBox: BoundingBox;
+}
+
+export interface DiffMaskEvidence {
+  /** Version of this evidence result shape */
+  contractVersion: string;
+  /** Native identity of normalized options that can change retained pixels */
+  analysisContractHash: string;
+  /** Version of Honeydiff's retained-pixel semantics */
+  semanticsVersion: string;
+  /** Version of the connected-component semantics */
+  componentSemanticsVersion: string;
+  /** Bitmap coordinate-space version */
+  coordinateSpaceVersion: string;
+  /** Diff-mask width in bitmap pixels */
+  width: number;
+  /** Diff-mask height in bitmap pixels */
+  height: number;
+  /** Number of retained pixels represented by the mask */
+  pixelCount: number;
+  /** False when maxDiffs stopped the comparison early */
+  complete: boolean;
+  /** Deterministically ordered exact connected components */
+  components: DiffMaskComponent[];
+}
+
 export interface DiffResult {
   /**
    * Whether the images are different based on the comparison threshold
@@ -75,12 +105,14 @@ 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;
+  /** Number of retained pixels represented by the diff mask */
+  diffMaskPixels: 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 */
+  diffMaskComplete: boolean;
+  /** Version of the pixel-retention semantics used by the diff mask */
   maskSemanticsVersion: string;
+  /** Authoritative diff-mask evidence (null unless includeDiffMaskEvidence is enabled) */
+  diffMaskEvidence: DiffMaskEvidence | null;
   /** Number of pixels ignored due to anti-aliasing detection */
   aaPixelsIgnored: number;
   /** Percentage of pixels ignored as anti-aliasing (0.0 - 100.0) */
@@ -108,7 +140,7 @@ export interface DiffResult {
 /** Installed @vizzly-testing/honeydiff package version */
 export const version: string;
 
-/** Native effective-mask semantics implemented by this package */
+/** Native diff-mask semantics implemented by this package */
 export const maskSemanticsVersion: string;
 
 // ============================================================================
@@ -209,6 +241,13 @@ export interface CompareOptions {
    */
   includeClusters?: boolean;
 
+  /**
+   * Include authoritative diff-mask dimensions, identity, and exact
+   * connected-component facts.
+   * @default false
+   */
+  includeDiffMaskEvidence?: boolean;
+
   /**
    * Calculate SSIM (Structural Similarity Index) perceptual score
    * This metric measures the source images independently of threshold and AA

package/package.json

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