@vizzly-testing/honeydiff 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.0] - 2026-08-03
+
+### Added
+
+- Added complete, data-only comparison results with reconciled pixel counts, exact retained regions, Delta E summaries, and explicit height-change data.
+- Added `analyze` for SSIM, MS-SSIM, and GMSD across Rust, Node, and the CLI.
+- Added optional diff, mask, and side-by-side artifacts without putting image data in the result.
+
+### Changed
+
+- Replaced metric include flags with four comparison settings: threshold, antialiasing, minimum region size, and height alignment.
+- Node and CLI now return the same nested analysis shape serialized by Rust.
+- Small suppressed regions now use bounded aggregate statistics instead of one object per region.
+- `images_differ` and fingerprints now derive from the same comparison result.
+
+### Removed
+
+- Removed early-exit results, public diff-pixel coordinates, packed mask payloads, and encoded image data from comparison results.
+
+**Full Changelog**: https://github.com/vizzly-testing/honeydiff/compare/v0.15.0...v0.16.0
+
 ## [0.15.0] - 2026-08-03
 
 ### Changed

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stubborn Mule Software, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -25,26 +25,21 @@ x64/ARM64, and Windows x64.
 ## Quick Start
 
 ```js
-import { compare, quickCompare } from '@vizzly-testing/honeydiff';
+import { compare, imagesDiffer } from '@vizzly-testing/honeydiff';
 
-let changed = await quickCompare('baseline.png', 'current.png');
+let options = {
+  threshold: 2,
+  antialiasing: true,
+  minimumRegionPixels: 2,
+  alignHeightChanges: false,
+};
 
-if (changed) {
-  console.log('Visual change detected');
-}
-
-let result = await compare('baseline.png', 'current.png', {
-  threshold: 2.0,
-  includeClusters: true,
-  diffPath: 'artifacts/diff.png',
-  maskPath: 'artifacts/mask.png',
-  overlayPath: 'artifacts/overlay.png',
-  overwrite: true,
-});
+let result = await compare('baseline.png', 'current.png', options);
 
-console.log(result.isDifferent);
-console.log(result.diffPercentage);
-console.log(result.diffClusters);
+console.log(result.different);
+console.log(result.pixels.changed.total);
+console.log(result.difference.regions);
+console.log(await imagesDiffer('baseline.png', 'current.png', options));
 ```
 
 ## Why Honeydiff?
@@ -54,13 +49,13 @@ pieces visual regression systems usually need once screenshots get real:
 
 - CIEDE2000 perceptual color thresholds, with `2.0` as the default.
 - Zero perceptual tolerance with `threshold: 0`; disable AA and set
-  `minClusterSize: 1` for strict rendered-pixel matching.
+  `minimumRegionPixels: 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.
+- Diff, mask, and side-by-side image artifacts for debugging failures.
+- Exact region data, Delta E summaries, SSIM, MS-SSIM, GMSD, and diff fingerprints.
 - WCAG contrast screening and color vision deficiency simulation.
 - Async and sync APIs with TypeScript definitions included.
 
@@ -71,12 +66,10 @@ pieces visual regression systems usually need once screenshots get real:
 ```js
 import { compare } from '@vizzly-testing/honeydiff';
 
-let result = await compare('before.png', 'after.png', {
-  threshold: 2.0,
-});
+let result = await compare('before.png', 'after.png');
 
-if (result.isDifferent) {
-  console.log(`${result.diffPercentage.toFixed(2)}% of pixels changed`);
+if (result.different) {
+  console.log(`${result.pixels.changed.total} pixels changed`);
 }
 ```
 
@@ -97,61 +90,44 @@ let result = await compare(baseline, current);
 ```js
 import { compare } from '@vizzly-testing/honeydiff';
 
-let result = await compare('baseline.png', 'current.png', {
-  diffPath: 'artifacts/diff.png',
-  maskPath: 'artifacts/mask.png',
-  overlayPath: 'artifacts/overlay.png',
-  overwrite: true,
-});
+let result = await compare(
+  'baseline.png',
+  'current.png',
+  {},
+  {
+    diffPath: 'artifacts/diff.png',
+    maskPath: 'artifacts/mask.png',
+    sideBySidePath: 'artifacts/side-by-side.png',
+    overwrite: true,
+  }
+);
 ```
 
-### Group Differences Into Regions
+Artifact settings are a separate fourth argument. Honeydiff writes the files
+from the same comparison state but doesn't put image data in the result.
+
+### Inspect Changed Regions
 
 ```js
 import { compare } from '@vizzly-testing/honeydiff';
 
-let result = await compare('baseline.png', 'current.png', {
-  includeClusters: true,
-  minClusterSize: 2,
-  clusterMerge: true,
-});
+let result = await compare('baseline.png', 'current.png');
 
-for (let cluster of result.diffClusters ?? []) {
-  console.log(cluster.pixelCount, cluster.boundingBox);
+for (let region of result.difference.regions) {
+  console.log(region.pixels, region.bounds, region.deltaE);
 }
 ```
 
-### 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
-import { compare } from '@vizzly-testing/honeydiff';
+import { analyze } from '@vizzly-testing/honeydiff';
 
-let result = await compare('baseline.png', 'current.png', {
-  includeSSIM: true,
-  includeGMSD: true,
-});
+let result = await analyze('baseline.png', 'current.png');
 
-console.log(result.perceptualScore);
-console.log(result.gmsdScore);
+console.log(result.perception.ssim);
+console.log(result.perception.msSsim);
+console.log(result.perception.gmsd);
 ```
 
 ### Align One Added Or Removed Block
@@ -159,17 +135,14 @@ console.log(result.gmsdScore);
 ```js
 let result = await compare('baseline.png', 'current.png', {
   alignHeightChanges: true,
-  maskPath: 'artifacts/mask.png',
 });
 ```
 
 This opt-in handles one exact added or removed block of rows, such as a banner,
-while keeping separate changes below it visible. Ambiguous matches,
-bottom-only growth, and comparisons using `maxDiffs` use the normal comparison.
-It does not handle multiple blocks, partial-width movement, or fuzzy matching.
-An accepted comparison temporarily uses one additional RGBA frame. SSIM and
-GMSD compare the unaligned overlapping portions, and the side-by-side overlay
-uses the original images.
+while keeping separate changes below it visible. Ambiguous matches and
+bottom-only growth use the normal comparison. It does not handle multiple
+blocks, partial-width movement, or fuzzy matching. `analyze` applies the same
+accepted row mapping before it calculates perceptual scores.
 
 ### Screenshot Contrast
 
@@ -201,60 +174,26 @@ await saveColorBlindnessSimulation(
 
 | Option | Default | Notes |
 | --- | --- | --- |
-| `threshold` | `2.0` | CIEDE2000 Delta E threshold. Use `0` for zero perceptual tolerance. |
-| `antialiasing` | `true` | Ignore likely anti-aliased pixels. |
-| `alignHeightChanges` | `false` | Align one conservatively detected added or removed block of rows. |
-| `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. |
-| `includeGMSD` | `false` | Calculate fast edge-sensitive structural difference. |
-| `diffPath` | unset | Save a highlighted diff image. |
-| `maskPath` | unset | Save a binary diff mask. |
-| `overlayPath` | unset | Save an overlay comparison image. |
-| `overwrite` | `false` | Replace existing artifact files. |
+| `threshold` | `2` | CIEDE2000 tolerance. Use `0` for zero perceptual tolerance. |
+| `antialiasing` | `true` | Suppress conservative raster-coverage movement. |
+| `minimumRegionPixels` | `2` | Suppress smaller 8-connected visual regions. |
+| `alignHeightChanges` | `false` | Align one unambiguous inserted or removed row block. |
 
-## Result Shape
+There are no include flags. `compare` always returns its complete data.
 
-```ts
-interface DiffResult {
-  isDifferent: boolean;
-  diffPercentage: number;
-  totalPixels: number;
-  diffPixels: number;
-  diffMaskPixels: number;
-  diffMaskComplete: boolean;
-  maskSemanticsVersion: string;
-  diffMaskEvidence: DiffMaskEvidence | null;
-  aaPixelsIgnored: number;
-  aaPercentage: number;
-  boundingBox: BoundingBox | null;
-  heightDiff: HeightDiff | null;
-  diffPixelsList: DiffPixel[] | null;
-  diffClusters: DiffCluster[] | null;
-  intensityStats: IntensityStats | null;
-  perceptualScore: number | null;
-  gmsdScore: number | null;
-}
-```
+## Result Shape
 
-`diffPixels` is the raw post-threshold/anti-aliasing count.
-`diffMaskPixels` is the retained count represented by the binary mask after
-`minClusterSize` filtering. It always matches the mask's nontransparent pixel
-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 result separates every pixel into rendered-equal, suppressed, visual-change,
+or structural-change populations. Those counts always add up to `pixels.total`.
 
-The package also exports `version` from its installed manifest and
-`maskSemanticsVersion` from the native comparison engine.
+`difference.regions` contains exact maximal 8-connected retained regions with
+bounds, centroid, density, perimeter, visual/structural composition, and real
+Delta E statistics where visual samples exist. `heightChange` explains added or
+removed rows and whether alignment was applied.
 
-See [index.d.ts](./index.d.ts) for the full API surface.
+The result is JSON-native data. It never contains a `Buffer`, base64 image,
+packed mask, bitmap-sized array, or per-pixel coordinate list. See
+[`index.d.ts`](./index.d.ts) for the complete shape.
 
 ## Thresholds
 
@@ -294,6 +233,8 @@ for the current benchmark notes.
 
 ```js
 import {
+  analyze,
+  analyzeSync,
   analyzeWcagAllCvd,
   analyzeWcagContrast,
   analyzeWcagForCvd,
@@ -309,8 +250,8 @@ import {
   getImageMetadataFromFile,
   getImageMetadataFromFileSync,
   getImageMetadataSync,
-  quickCompare,
-  quickCompareSync,
+  imagesDiffer,
+  imagesDifferSync,
   saveAllColorBlindnessSimulations,
   saveColorBlindnessSimulation,
   saveWcagOverlay,

package/examples/basic.js

@@ -1,81 +1,21 @@
-/**
- * Basic usage example for @vizzly-testing/honeydiff
- */
+import { analyze, compare, imagesDiffer } from '../index.js';
 
-import * as honeydiff from '../index.js';
-
-let baseline = '../../tests/fixtures/screenshots/vizzly-baseline.png';
-let current = '../../tests/fixtures/screenshots/vizzly-with-diff.png';
-
-async function main() {
-  console.log('Honeydiff Node.js examples\n');
-
-  console.log('1. Quick comparison');
-  let isDifferent = await honeydiff.quickCompare(baseline, current);
-  console.log(`  Result: ${isDifferent ? 'DIFFERENT' : 'IDENTICAL'}\n`);
-
-  console.log('2. Detailed comparison');
-  let result = await honeydiff.compare(baseline, current, {
-    threshold: 0,
-    antialiasing: true,
-    includeSSIM: true,
-    includeGMSD: true,
-    includeClusters: true,
-    includeDiffPixels: true,
-    minClusterSize: 1,
-  });
-
-  console.log(`  Diff percentage: ${result.diffPercentage.toFixed(2)}%`);
-  console.log(`  Different pixels: ${result.diffPixels} / ${result.totalPixels}`);
-  console.log(`  AA pixels ignored: ${result.aaPixelsIgnored}`);
-
-  if (result.perceptualScore !== null) {
-    console.log(`  SSIM score: ${result.perceptualScore.toFixed(4)}`);
-  }
-
-  if (result.gmsdScore !== null) {
-    console.log(`  GMSD score: ${result.gmsdScore.toFixed(4)}`);
-  }
-
-  if (result.boundingBox) {
-    console.log(
-      `  Bounding box: (${result.boundingBox.x}, ${result.boundingBox.y}) ${result.boundingBox.width}x${result.boundingBox.height}`
-    );
-  }
-
-  if (result.diffClusters && result.diffClusters.length > 0) {
-    console.log(`  Found ${result.diffClusters.length} diff clusters`);
-    for (let [index, cluster] of result.diffClusters.slice(0, 3).entries()) {
-      console.log(
-        `    Cluster ${index + 1}: ${cluster.pixelCount} pixels at (${cluster.centerOfMass[0].toFixed(0)}, ${cluster.centerOfMass[1].toFixed(0)})`
-      );
-    }
-  }
-
-  console.log('\n3. Synchronous comparison');
-  let syncResult = honeydiff.compareSync(baseline, current, {
-    threshold: 2,
-    includeClusters: true,
-  });
-  console.log(`  Diff percentage: ${syncResult.diffPercentage.toFixed(2)}%`);
-
-  console.log('\n4. Image dimensions');
-  let dimensions = await honeydiff.getDimensions(baseline);
-  console.log(`  Dimensions: ${dimensions.width}x${dimensions.height}`);
-
-  console.log('\n5. Diff artifacts');
-  let artifactResult = await honeydiff.compare(baseline, current, {
-    threshold: 0,
-    diffPath: '/tmp/honeydiff-diff.png',
-    maskPath: '/tmp/honeydiff-mask.png',
-    overlayPath: '/tmp/honeydiff-side-by-side.png',
-    overwrite: true,
-  });
-  console.log(`  Artifact diff percentage: ${artifactResult.diffPercentage.toFixed(2)}%`);
-  console.log('  Artifacts saved to /tmp/honeydiff-*.png');
+let baseline = process.argv[2];
+let current = process.argv[3];
+if (!baseline || !current) {
+  throw new Error('Usage: node examples/basic.js <baseline.png> <current.png>');
 }
-
-main().catch((err) => {
-  console.error('Error:', err);
-  process.exit(1);
-});
+let options = { threshold: 2, antialiasing: true, minimumRegionPixels: 2 };
+let result = await compare(baseline, current, options);
+
+console.log(`Different: ${result.different}`);
+console.log(`Changed: ${result.pixels.changed.total} / ${result.pixels.total}`);
+console.log(`Regions: ${result.difference.regions.length}`);
+console.log(
+  `Boolean agrees: ${(await imagesDiffer(baseline, current, options)) === result.different}`
+);
+
+let detailed = await analyze(baseline, current, options);
+console.log(`SSIM: ${detailed.perception.ssim.toFixed(4)}`);
+console.log(`MS-SSIM: ${detailed.perception.msSsim.toFixed(4)}`);
+console.log(`GMSD: ${detailed.perception.gmsd.toFixed(4)}`);

package/examples/buffers.js

@@ -1,40 +1,9 @@
-/**
- * Example: Using Buffers instead of file paths
- */
-
 import fs from 'node:fs';
-import * as honeydiff from '../index.js';
-
-async function main() {
-  console.log('Buffer Example\n');
-
-  // Load images as buffers
-  let img1Buffer = fs.readFileSync('../../tests/fixtures/screenshots/vizzly-baseline.png');
-  let img2Buffer = fs.readFileSync('../../tests/fixtures/screenshots/vizzly-with-diff.png');
-
-  console.log(`Loaded buffers: ${img1Buffer.length} and ${img2Buffer.length} bytes\n`);
-
-  // Compare using buffers
-  let result = await honeydiff.compare(img1Buffer, img2Buffer, {
-    threshold: 0,
-    includeSSIM: true,
-  });
-
-  console.log('Comparison result:');
-  console.log(`  Different: ${result.isDifferent}`);
-  console.log(`  Diff percentage: ${result.diffPercentage.toFixed(2)}%`);
-  console.log(`  SSIM: ${result.perceptualScore?.toFixed(4) || 'N/A'}`);
+import { compare } from '../index.js';
 
-  // Mixed: buffer + file path
-  console.log('\nMixed comparison (buffer + file path):');
-  let mixedResult = await honeydiff.compare(
-    img1Buffer,
-    '../../tests/fixtures/screenshots/vizzly-with-diff.png'
-  );
-  console.log(`  Diff percentage: ${mixedResult.diffPercentage.toFixed(2)}%`);
-}
+let baseline = fs.readFileSync(process.argv[2] ?? 'baseline.png');
+let current = fs.readFileSync(process.argv[3] ?? 'current.png');
+let result = await compare(baseline, current);
 
-main().catch((err) => {
-  console.error('Error:', err);
-  process.exit(1);
-});
+console.log(`Different: ${result.different}`);
+console.log(`Changed fraction: ${result.difference.fraction}`);

package/examples/typescript.ts

@@ -1,78 +1,25 @@
-/**
- * TypeScript example with full type safety
- */
-
-import { type CompareOptions, compare, type DiffResult, quickCompare } from '../index';
-
-async function main(): Promise<void> {
-  console.log('TypeScript Example\n');
-
-  // Quick comparison
-  let isDifferent: boolean = await quickCompare(
-    '../../tests/fixtures/screenshots/vizzly-baseline.png',
-    '../../tests/fixtures/screenshots/vizzly-with-diff.png'
-  );
-  console.log(`Quick result: ${isDifferent ? 'DIFFERENT' : 'IDENTICAL'}\n`);
-
-  // Detailed comparison with full typing
-  let options: CompareOptions = {
-    threshold: 2,
-    antialiasing: true,
-    includeSSIM: true,
-    includeClusters: true,
-    includeDiffPixels: false,
-  };
-
-  let result: DiffResult = await compare(
-    '../../tests/fixtures/screenshots/vizzly-baseline.png',
-    '../../tests/fixtures/screenshots/vizzly-with-diff.png',
-    options
-  );
-
-  console.log('Detailed results:');
-  console.log(`  Diff: ${result.diffPercentage.toFixed(2)}%`);
-  console.log(`  Different pixels: ${result.diffPixels} / ${result.totalPixels}`);
-
-  // Type-safe access to optional fields
-  if (result.perceptualScore !== null) {
-    let ssim: number = result.perceptualScore;
-    console.log(`  SSIM: ${ssim.toFixed(4)}`);
-
-    if (ssim > 0.95) {
-      console.log('  → Perceptually very similar');
-    } else if (ssim > 0.8) {
-      console.log('  → Somewhat similar');
-    } else {
-      console.log('  → Perceptually different');
-    }
-  }
-
-  if (result.boundingBox) {
-    console.log(
-      `  Changes in region: (${result.boundingBox.x}, ${result.boundingBox.y}) ${result.boundingBox.width}x${result.boundingBox.height}`
-    );
-  }
-
-  if (result.diffClusters && result.diffClusters.length > 0) {
-    console.log(`\nFound ${result.diffClusters.length} separate diff regions:`);
-    result.diffClusters.slice(0, 5).forEach((cluster, i) => {
-      let [cx, cy] = cluster.centerOfMass;
-      console.log(
-        `  ${i + 1}. ${cluster.pixelCount} pixels at (${cx.toFixed(0)}, ${cy.toFixed(0)})`
-      );
-    });
-  }
-
-  if (result.intensityStats) {
-    console.log('\nIntensity statistics:');
-    console.log(`  Range: ${result.intensityStats.min} - ${result.intensityStats.max}`);
-    console.log(`  Mean: ${result.intensityStats.mean.toFixed(1)}`);
-    console.log(`  Median: ${result.intensityStats.median}`);
-    console.log(`  Std Dev: ${result.intensityStats.stdDev.toFixed(1)}`);
-  }
-}
-
-main().catch((err: Error) => {
-  console.error('Error:', err.message);
-  process.exit(1);
-});
+import {
+  analyze,
+  type CompareOptions,
+  compare,
+  computeFingerprintSync,
+  type DiffAnalysis,
+  imagesDiffer,
+} from '../index.js';
+
+let options: CompareOptions = {
+  threshold: 2,
+  antialiasing: true,
+  minimumRegionPixels: 2,
+};
+let result: DiffAnalysis = await compare('baseline.png', 'current.png', options);
+
+console.log(`${result.pixels.changed.total} changed pixels`);
+console.log(`${result.difference.regions.length} exact regions`);
+console.log(
+  `boolean agrees: ${(await imagesDiffer('baseline.png', 'current.png', options)) === result.different}`
+);
+console.log(`fingerprint: ${computeFingerprintSync(result)?.hash ?? 'identical'}`);
+
+let detailed = await analyze('baseline.png', 'current.png', options);
+console.log(`SSIM ${detailed.perception.ssim}, MS-SSIM ${detailed.perception.msSsim}`);