@vizzly-testing/honeydiff 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2025-12-11
+
+## What's Changed
+
+### Added
+- **Image Metadata API** - New functions to extract image dimensions, file size, and format without performing comparison
+  - `getImageMetadata(buffer)` / `getImageMetadataSync(buffer)` - Extract metadata from Buffer
+  - `getImageMetadataFromFile(path)` / `getImageMetadataFromFileSync(path)` - Extract metadata from file path
+  - Returns `ImageMetadata` with `width`, `height`, `fileSizeBytes`, and `format` properties
+  - Useful for storage tracking and billing purposes without needing to scan cloud storage buckets
+
+**Full Changelog**: https://github.com/vizzly-testing/honeydiff/compare/v0.6.0...v0.7.0
+
+## [0.6.0] - 2025-12-10
+
+## What's Changed
+
+### Added
+- **Noise filtering with `minClusterSize` option** - New option to filter out single-pixel rendering variance while catching real visual changes. Defaults to `2` (filters isolated pixels), can be set to `1` for exact matching or `3+` for more permissive detection. Clustering is automatically enabled when `minClusterSize > 1`.
+
+### Changed
+- **`isDifferent` now respects noise filtering** - When `minClusterSize` is set, small clusters below the threshold are filtered out, meaning `isDifferent` may be `false` even when `diffPixels > 0` (those pixels were classified as noise)
+- **`diffPixels` reports raw count** - The raw pixel count is now unaffected by `minClusterSize` filtering, showing all differing pixels including those filtered as noise
+- **Documentation improvements** - Added comprehensive documentation for the `minClusterSize` option in TypeScript types and README, including a behavior table and usage examples
+
+### Fixed
+- Height differences now always count regardless of clustering (structural changes are never filtered as noise)
+
+**Full Changelog**: https://github.com/vizzly-testing/honeydiff/compare/v0.5.0...v0.6.0
+
 ## [0.5.0] - 2025-12-04
 
 ## What's Changed

package/README.md

@@ -154,13 +154,14 @@ const result = await compare('baseline.png', 'current.png', {
 console.log('Artifacts saved to ./artifacts/');
 ```
 
-### 5. Spatial Clustering
+### 5. Spatial Clustering & Noise Filtering
 
-Group nearby differences into regions to identify distinct changed areas.
+Group nearby differences into regions and filter out single-pixel noise from rendering variance.
 
 ```javascript
 const result = await compare('img1.png', 'img2.png', {
-  includeClusters: true
+  includeClusters: true,
+  minClusterSize: 2  // Default: filter single isolated pixels as noise
 });
 
 if (result.diffClusters) {
@@ -180,6 +181,13 @@ if (result.diffClusters) {
 //   - Average intensity: 127.3
 ```
 
+**Noise filtering values:**
+| Value | Behavior |
+|-------|----------|
+| 1 | Exact matching - any different pixel counts |
+| 2 | Default - filters single isolated pixels as rendering noise |
+| 3+ | More permissive - only larger clusters detected |
+
 ### 6. Perceptual Similarity (SSIM)
 
 Beyond pixel counting - measure structural similarity from a human perception perspective.
@@ -255,6 +263,28 @@ let buffer = fs.readFileSync('image.png');
 let dims = await getDimensions(buffer);
 ```
 
+### 10. Image Metadata
+
+Get image dimensions, file size, and format detection - useful for storage tracking and billing.
+
+```javascript
+const { getImageMetadata, getImageMetadataFromFile } = require('@vizzly-testing/honeydiff');
+
+// From buffer
+let buffer = fs.readFileSync('screenshot.png');
+let metadata = await getImageMetadata(buffer);
+console.log(`Image: ${metadata.width}x${metadata.height}`);
+console.log(`Size: ${metadata.fileSizeBytes} bytes`);
+console.log(`Format: ${metadata.format}`);
+// Output: Image: 1920x1080
+//         Size: 245760 bytes
+//         Format: png
+
+// From file (gets accurate file size from disk)
+let metadata = await getImageMetadataFromFile('screenshot.png');
+console.log(`${metadata.width}x${metadata.height}, ${metadata.fileSizeBytes} bytes`);
+```
+
 ## Accessibility Features
 
 Built-in WCAG color contrast analysis and color blindness simulation to catch accessibility violations in screenshots and UI designs.
@@ -410,6 +440,14 @@ Fast boolean check - returns true if different, false if identical.
 
 Get image dimensions without loading full image data.
 
+**`getImageMetadata(buffer): Promise<ImageMetadata>`**
+
+Get image metadata (dimensions, file size, format) from a buffer.
+
+**`getImageMetadataFromFile(path): Promise<ImageMetadata>`**
+
+Get image metadata from a file path. File size is read from disk for accuracy.
+
 ### Sync Functions (Blocks Event Loop)
 
 **`compareSync(img1, img2, options?): DiffResult`**
@@ -424,6 +462,14 @@ Synchronous boolean check.
 
 Synchronous dimension retrieval.
 
+**`getImageMetadataSync(buffer): ImageMetadata`**
+
+Synchronous metadata retrieval from buffer.
+
+**`getImageMetadataFromFileSync(path): ImageMetadata`**
+
+Synchronous metadata retrieval from file.
+
 ### Input Types
 
 All functions accept:
@@ -445,6 +491,7 @@ interface CompareOptions {
   includeDiffPixels?: boolean;          // List all diff pixels (memory intensive, default: false)
   includeClusters?: boolean;            // Spatial clustering (default: false)
   includeSSIM?: boolean;                // SSIM perceptual score (slow, default: false)
+  minClusterSize?: number;              // Filter clusters smaller than this (default: 2)
 
   // Accessibility options
   includeAccessibilityData?: boolean;   // RGB, luminance, WCAG (default: false)
@@ -464,10 +511,10 @@ interface CompareOptions {
 ```typescript
 interface DiffResult {
   // Basic metrics
-  isDifferent: boolean;                 // Are images different?
+  isDifferent: boolean;                 // Are images different? (respects minClusterSize filtering)
   diffPercentage: number;               // 0.0-100.0
   totalPixels: number;
-  diffPixels: number;
+  diffPixels: number;                   // Raw count (unaffected by minClusterSize filtering)
 
   // Anti-aliasing
   aaPixelsIgnored: number;

package/index.d.ts

@@ -61,13 +61,19 @@ export interface DiffCluster {
 }
 
 export interface DiffResult {
-  /** Whether the images are different based on the comparison threshold */
+  /**
+   * Whether the images are different based on the comparison threshold
+   * Note: This respects minClusterSize filtering - small clusters may be filtered as noise
+   */
   isDifferent: boolean;
   /** Percentage of pixels that differ (0.0 - 100.0) */
   diffPercentage: number;
   /** Total number of pixels compared */
   totalPixels: number;
-  /** Number of pixels that differ */
+  /**
+   * Number of pixels that differ (raw count, unaffected by minClusterSize filtering)
+   * Note: This may be > 0 even when isDifferent is false if small clusters were filtered as noise
+   */
   diffPixels: number;
   /** Number of pixels ignored due to anti-aliasing detection */
   aaPixelsIgnored: number;
@@ -139,6 +145,22 @@ export interface CompareOptions {
    */
   includeSSIM?: boolean;
 
+  /**
+   * Minimum cluster size to count as a real difference
+   *
+   * Clusters smaller than this threshold are filtered out as noise.
+   * 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
+   * - 2 = Default - filters single isolated pixels as noise
+   * - 3+ = More permissive - only larger clusters detected
+   *
+   * When set to a value > 1, clustering is automatically enabled.
+   * @default 2
+   */
+  minClusterSize?: number;
+
   /**
    * Path to save the diff image (highlighted differences)
    * @default undefined
@@ -272,6 +294,17 @@ export interface ImageDimensions {
   height: number;
 }
 
+export interface ImageMetadata {
+  /** Image width in pixels */
+  width: number;
+  /** Image height in pixels */
+  height: number;
+  /** Size of the image data in bytes */
+  fileSizeBytes: number;
+  /** Detected image format (e.g., "png", "jpeg", "webp") or null if unknown */
+  format: string | null;
+}
+
 /**
  * Get image dimensions asynchronously (recommended)
  *
@@ -308,6 +341,87 @@ export function getDimensions(img: ImageInput): Promise<ImageDimensions>;
  */
 export function getDimensionsSync(img: ImageInput): ImageDimensions;
 
+// ============================================================================
+// Image Metadata API
+// ============================================================================
+
+/**
+ * Get image metadata asynchronously (recommended)
+ *
+ * Retrieves image dimensions, file size, and format detection.
+ * Useful for storage tracking and billing purposes.
+ *
+ * @param img - Image Buffer
+ * @returns Promise resolving to ImageMetadata
+ *
+ * @example
+ * ```typescript
+ * const buffer = fs.readFileSync('screenshot.png');
+ * const metadata = await getImageMetadata(buffer);
+ * console.log(`Image: ${metadata.width}x${metadata.height}`);
+ * console.log(`Size: ${metadata.fileSizeBytes} bytes`);
+ * console.log(`Format: ${metadata.format}`);
+ * // Output: Image: 1920x1080
+ * //         Size: 245760 bytes
+ * //         Format: png
+ * ```
+ */
+export function getImageMetadata(img: Buffer): Promise<ImageMetadata>;
+
+/**
+ * Get image metadata synchronously (blocks event loop)
+ *
+ * Retrieves image dimensions, file size, and format detection.
+ * Use this only when you need blocking behavior.
+ *
+ * @param img - Image Buffer
+ * @returns ImageMetadata
+ *
+ * @example
+ * ```typescript
+ * const buffer = fs.readFileSync('screenshot.png');
+ * const metadata = getImageMetadataSync(buffer);
+ * console.log(`${metadata.width}x${metadata.height}, ${metadata.fileSizeBytes} bytes`);
+ * ```
+ */
+export function getImageMetadataSync(img: Buffer): ImageMetadata;
+
+/**
+ * Get image metadata from file asynchronously (recommended)
+ *
+ * Retrieves image dimensions, file size (from disk), and format detection.
+ * The file size is read from filesystem metadata for accuracy.
+ *
+ * @param path - Path to the image file
+ * @returns Promise resolving to ImageMetadata
+ *
+ * @example
+ * ```typescript
+ * const metadata = await getImageMetadataFromFile('screenshot.png');
+ * console.log(`Image: ${metadata.width}x${metadata.height}`);
+ * console.log(`Size: ${metadata.fileSizeBytes} bytes`);
+ * console.log(`Format: ${metadata.format}`);
+ * ```
+ */
+export function getImageMetadataFromFile(path: string): Promise<ImageMetadata>;
+
+/**
+ * Get image metadata from file synchronously (blocks event loop)
+ *
+ * Retrieves image dimensions, file size (from disk), and format detection.
+ * Use this only when you need blocking behavior.
+ *
+ * @param path - Path to the image file
+ * @returns ImageMetadata
+ *
+ * @example
+ * ```typescript
+ * const metadata = getImageMetadataFromFileSync('screenshot.png');
+ * console.log(`${metadata.width}x${metadata.height}, ${metadata.fileSizeBytes} bytes`);
+ * ```
+ */
+export function getImageMetadataFromFileSync(path: string): ImageMetadata;
+
 // ============================================================================
 // WCAG Accessibility API
 // ============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/honeydiff",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "High-performance image diffing for Node.js - Native bindings to Honeydiff Rust library",
   "type": "module",
   "main": "index.js",
@@ -69,6 +69,18 @@
     "load-platform.cjs",
     "platforms/*.node",
     "README.md",
+    "CHANGELOG.md",
+    "index.js",
+    "index.d.ts",
+    "load-platform.cjs",
+    "platforms/*.node",
+    "README.md",
+    "CHANGELOG.md",
+    "index.js",
+    "index.d.ts",
+    "load-platform.cjs",
+    "platforms/*.node",
+    "README.md",
     "CHANGELOG.md"
   ],
   "engines": {