@vizzly-testing/honeydiff 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.18.0] - 2026-11-11
+
+### Added
+
+- You know when one small tweak to a shared nav or footer shows up as a diff in every single
+  screenshot? Honeydiff can now spot those repeats for you. Pass `changeBlocks: true` to `compare`
+  and you'll get `difference.changeBlocks` back.
+
+  Each block groups nearby changed regions into what a person would call one change, then gives it
+  a `signature` based on its pixels instead of where it sits on the page. So the same change gets the
+  same signature on a short page, a tall page, or below a banner that pushed everything down. Group
+  by signature and you can review a repeated change once instead of fifty times.
+
+  Matching is exact on purpose. Two blocks only share a signature when every pixel in them is the
+  same, because a fuzzy match can't tell a one-letter edit apart from text that moved half a pixel.
+  The same edit on a different background, or right next to another change, gets its own signature.
+
+  It's off by default, since hashing a big changed area takes real time on full-page diffs. On a real
+  build with 148 changed screenshots it added about 4%, and leaving it off costs nothing at all.
+
+**Full Changelog**: https://github.com/vizzly-testing/honeydiff/compare/v0.17.0...v0.18.0
+
 ## [0.17.0] - 2026-09-06
 
 ### Added

package/README.md

@@ -56,6 +56,8 @@ pieces visual regression systems usually need once screenshots get real:
 - Variable-height screenshot support for full-page comparisons.
 - Diff, mask, and side-by-side image artifacts for debugging failures.
 - Exact region data, Delta E summaries, SSIM, MS-SSIM, GMSD, and diff fingerprints.
+- Change blocks that identify each change by its pixels, so the same change matches across
+  screenshots at any position and page height.
 - WCAG contrast screening and color vision deficiency simulation.
 - Async and sync APIs with TypeScript definitions included.
 
@@ -150,6 +152,28 @@ configureThreads(4);
 Repeating the same value is safe. Changing it after Honeydiff work starts
 throws instead of silently creating an oversubscribed pool.
 
+### Find The Same Change Across Screenshots
+
+```js
+let result = await compare('baseline.png', 'current.png', {
+  alignHeightChanges: true,
+  changeBlocks: true,
+});
+
+for (let block of result.difference.changeBlocks) {
+  console.log(block.signature, block.bounds);
+}
+```
+
+A block is a group of regions within 16px of each other, which is usually what a person would call
+one change. Two blocks with the same `signature` have byte-identical baseline and current pixels in
+their whole rectangle, wherever they sit on the page and however tall the page is. Group by
+signature to review a repeated change once.
+
+Matching is exact on purpose. The same edit on a different background, at a fractional position, or
+next to another change within the gap gets a different signature. Only compare signatures whose
+`cb1:` version prefix matches.
+
 ### Align One Added Or Removed Block
 
 ```js
@@ -198,8 +222,10 @@ await saveColorBlindnessSimulation(
 | `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. |
+| `changeBlocks` | `false` | Merge nearby regions into blocks identified by their pixels. |
 
-There are no include flags. `compare` always returns its complete data.
+`compare` always returns its complete data. `changeBlocks` is the one opt-in, because hashing a
+large changed area adds real time to a full-page diff.
 
 ## Result Shape
 

package/index.d.ts

@@ -77,6 +77,16 @@ export interface DiffRegion {
   appearance: DeltaESummary | null;
 }
 
+export interface ChangeBlock {
+  /** Canvas-coordinate rectangle containing the merged regions. */
+  bounds: BoundingBox;
+  /**
+   * Exact identity of every baseline and current pixel in `bounds`, independent of position.
+   * Only compare signatures whose version prefix matches.
+   */
+  signature: string;
+}
+
 export interface DiffAnalysis {
   different: boolean;
   settings: {
@@ -96,6 +106,8 @@ export interface DiffAnalysis {
     spatial: SpatialSummary | null;
     appearance: DeltaESummary | null;
     regions: DiffRegion[];
+    /** Present when the `changeBlocks` option is set. */
+    changeBlocks: ChangeBlock[] | null;
   };
   heightChange: {
     direction: 'added' | 'removed';
@@ -131,6 +143,8 @@ export interface CompareOptions {
   minimumRegionPixels?: number;
   /** Detect and align one unambiguous inserted or removed row block. Default: false. */
   alignHeightChanges?: boolean;
+  /** Merge nearby regions into blocks identified by their pixels. Default: false. */
+  changeBlocks?: boolean;
 }
 
 export interface ArtifactOutput {

package/package.json

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