@vizzly-testing/honeydiff 0.0.3 → 0.1.1

package/README.md

@@ -2,12 +2,17 @@
 
 [![npm version](https://img.shields.io/npm/v/@vizzly-testing/honeydiff.svg)](https://www.npmjs.com/package/@vizzly-testing/honeydiff)
 [![npm downloads](https://img.shields.io/npm/dm/@vizzly-testing/honeydiff.svg)](https://www.npmjs.com/package/@vizzly-testing/honeydiff)
-[![CI](https://github.com/vizzly-testing/honeydiff/workflows/Node.js%20Bindings/badge.svg)](https://github.com/vizzly-testing/honeydiff/actions)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/vizzly-testing/honeydiff/blob/main/LICENSE)
 
-Fast image diffing for Node.js with native Rust performance (1.1B pixels/sec). Supports anti-aliasing detection, SSIM, clustering, and variable-height screenshots.
+Blazingly fast image comparison for Node.js. Perfect for visual regression testing, screenshot
+validation, and detecting visual changes.
 
-**Features:** File paths or Buffers • Async + sync APIs • TypeScript types • Pre-built binaries (macOS/Linux/Windows)
+**Why Honeydiff?**
+- **Fast:** Native performance processing 230M+ pixels/sec
+- **Smart:** Intelligent anti-aliasing detection filters rendering artifacts
+- **Flexible:** File paths or Buffers, async or sync APIs
+- **Complete:** TypeScript types, pre-built binaries for all platforms
+- **Advanced:** SSIM perceptual scoring, spatial clustering, variable-height screenshots
 
 ## Installation
 
@@ -15,7 +20,10 @@ Fast image diffing for Node.js with native Rust performance (1.1B pixels/sec). S
 npm install @vizzly-testing/honeydiff
 ```
 
-Requires Node.js 22+. Ships with pre-built binaries for macOS (ARM64), Linux (x64/ARM64), and Windows (x64). No Rust toolchain needed.
+**Requirements:** Node.js 22+
+
+Pre-built binaries included for macOS (ARM64), Linux (x64/ARM64), and Windows (x64). No compilation
+required.
 
 ## Quick Start
 
@@ -35,6 +43,7 @@ const result = await compare('baseline.png', 'current.png', {
 });
 
 console.log(`Diff: ${result.diffPercentage.toFixed(2)}%, SSIM: ${result.perceptualScore}`);
+// Output: Diff: 3.55%, SSIM: 0.9234
 ```
 
 **TypeScript**
@@ -51,6 +60,7 @@ const result: DiffResult = await compare('img1.png', 'img2.png', {
 if (result.diffClusters) {
   console.log(`Found ${result.diffClusters.length} diff regions`);
 }
+// Output: Found 3 diff regions
 ```
 
 ## API
@@ -58,10 +68,12 @@ if (result.diffClusters) {
 **Async (recommended)**
 - `compare(img1, img2, options?): Promise<DiffResult>` - Full comparison
 - `quickCompare(img1, img2): Promise<boolean>` - Quick check
+- `getDimensions(img): Promise<{ width: number, height: number }>` - Get image dimensions
 
 **Sync (blocks event loop)**
 - `compareSync(img1, img2, options?): DiffResult`
 - `quickCompareSync(img1, img2): boolean`
+- `getDimensionsSync(img): { width: number, height: number }` - Get image dimensions
 
 Inputs: `string` (file path) or `Buffer`
 
@@ -111,6 +123,24 @@ interface DiffResult {
 
 ## Examples
 
+**Get Image Dimensions**
+```javascript
+const { getDimensions, getDimensionsSync } = require('@vizzly-testing/honeydiff');
+
+// Async
+let dims = await getDimensions('screenshot.png');
+console.log(`Image is ${dims.width}x${dims.height} pixels`);
+// Output: Image is 1920x1080 pixels
+
+// Sync
+let dims = getDimensionsSync('screenshot.png');
+console.log(`Image is ${dims.width}x${dims.height} pixels`);
+
+// Works with buffers too
+let buffer = fs.readFileSync('image.png');
+let dims = await getDimensions(buffer);
+```
+
 **Buffers**
 ```javascript
 const fs = require('fs');
@@ -146,37 +176,130 @@ if (result.diffClusters) {
     console.log(`Region ${i + 1}: ${c.pixelCount} pixels at (${c.centerOfMass[0]}, ${c.centerOfMass[1]})`);
   });
 }
+// Output:
+// Region 1: 12450 pixels at (245, 189)
+// Region 2: 3891 pixels at (672, 401)
+// Region 3: 1023 pixels at (1156, 823)
 
 // SSIM score
 if (result.perceptualScore !== null) {
   console.log(`SSIM: ${result.perceptualScore.toFixed(3)}`);
 }
+// Output: SSIM: 0.923
 
 // Intensity stats
 if (result.intensityStats) {
   console.log(`Range: ${result.intensityStats.min}-${result.intensityStats.max}, Mean: ${result.intensityStats.mean.toFixed(1)}`);
 }
+// Output: Range: 12-255, Mean: 87.3
+```
+
+**Complete Result Example**
+```javascript
+let result = await compare('baseline.png', 'current.png', {
+  pixelTolerance: 10,
+  includeClusters: true
+});
+
+console.log(JSON.stringify(result, null, 2));
+```
+
+<details>
+<summary>Example output (click to expand)</summary>
+
+```json
+{
+  "isDifferent": true,
+  "diffPercentage": 3.55,
+  "totalPixels": 18309000,
+  "diffPixels": 650086,
+  "aaPixelsIgnored": 1952904,
+  "aaPercentage": 10.67,
+  "boundingBox": {
+    "x": 124,
+    "y": 89,
+    "width": 1456,
+    "height": 2301
+  },
+  "heightDiff": {
+    "height1": 24162,
+    "height2": 24412,
+    "extraPixels": 187500
+  },
+  "diffPixelsList": null,
+  "diffClusters": [
+    {
+      "pixelCount": 12450,
+      "centerOfMass": [245, 189]
+    },
+    {
+      "pixelCount": 3891,
+      "centerOfMass": [672, 401]
+    }
+  ],
+  "intensityStats": {
+    "min": 12,
+    "max": 255,
+    "mean": 87.3,
+    "median": 76,
+    "stdDev": 45.2
+  },
+  "perceptualScore": null
+}
 ```
+</details>
+```
+
+## Use Cases
+
+- **Visual Regression Testing:** Detect unintended UI changes in your test suite
+- **Screenshot Validation:** Compare generated screenshots against baselines
+- **Design QA:** Validate UI implementations match designs
+- **Cross-browser Testing:** Detect rendering differences across browsers
+- **Scrollable Content:** Compare full-page screenshots with variable heights
 
 ## Performance
 
-| Image Size | Time | Throughput |
-|------------|------|------------|
-| 1920x1080 (Full HD) | ~2ms | 1.1B pixels/sec |
-| 3840x2160 (4K) | ~3ms | 3.0B pixels/sec |
+Tested on real-world tall screenshots (750 x 24,162 pixels = 18.3M pixels):
 
-With artifacts: ~30-35ms for Full HD. Benchmarked on Apple M-series Mac.
+| Operation | Time | Throughput |
+|-----------|------|------------|
+| Basic comparison | ~79ms | 231.8M pixels/sec |
+| With artifacts (diff/mask/overlay) | ~432ms | 42.4M pixels/sec |
 
-## Building from Source
+**6x faster than odiff** on large screenshots with excellent multi-core parallelization.
 
-Only needed for contributing or modifying native code. Requires Rust toolchain and Node.js 22+.
+*Benchmarked on Apple M-series Mac.*
 
-```bash
-git clone https://github.com/vizzly-testing/honeydiff
-cd honeydiff/crates/honeydiff-node
-npm install && npm run build
-```
+## Advanced Features
+
+**Variable Height Screenshots**
+Compare scrollable content with different heights. Overlapping regions are compared pixel-by-pixel,
+extra rows counted as differences.
+
+**Color Spaces**
+- RGB mode (default): Exact matching, fastest performance
+- YIQ mode: Perceptual matching weighted for human vision
+
+**Spatial Clustering**
+Group nearby differences into regions using 8-connectivity clustering. Useful for identifying distinct changed areas.
+
+**SSIM Scoring**
+Structural Similarity Index (0.0-1.0) provides perceptual similarity measurement beyond pixel differences.
+
+## Troubleshooting
+
+**Module not found errors**
+Ensure you're on Node.js 22+ and your platform is supported (macOS ARM64, Linux x64/ARM64, Windows x64).
+
+**Large memory usage with `includeDiffPixels`**
+This option stores every different pixel's position and intensity. Disable for large images with many differences.
+
+**Slow performance with `includeSSIM`**
+SSIM calculation is O(width × height × window²). Only enable when perceptual scoring is needed.
 
 ## License
 
-MIT - See [LICENSE](../../LICENSE) for details. Built for [Vizzly](https://github.com/vizzly-testing/vizzly) visual regression testing.
+MIT License
+
+Built with native Rust for maximum performance.

package/index.d.ts

@@ -274,3 +274,50 @@ export function quickCompareSync(
   img1: ImageInput,
   img2: ImageInput
 ): boolean;
+
+// ============================================================================
+// Dimensions API
+// ============================================================================
+
+export interface ImageDimensions {
+  /** Image width in pixels */
+  width: number;
+  /** Image height in pixels */
+  height: number;
+}
+
+/**
+ * Get image dimensions asynchronously (recommended)
+ *
+ * Fast utility to retrieve image width and height without loading the full image data.
+ * Useful for pre-flight checks before comparison.
+ *
+ * @param img - Image (file path or Buffer)
+ * @returns Promise resolving to { width, height } in pixels
+ *
+ * @example
+ * ```typescript
+ * const dims = await getDimensions('screenshot.png');
+ * console.log(`Image is ${dims.width}x${dims.height} pixels`);
+ * // Output: Image is 1920x1080 pixels
+ * ```
+ */
+export function getDimensions(img: ImageInput): Promise<ImageDimensions>;
+
+/**
+ * Get image dimensions synchronously (blocks event loop)
+ *
+ * Fast utility to retrieve image width and height without loading the full image data.
+ * Use this only when you need blocking behavior.
+ *
+ * @param img - Image (file path or Buffer)
+ * @returns { width, height } in pixels
+ *
+ * @example
+ * ```typescript
+ * const dims = getDimensionsSync('screenshot.png');
+ * console.log(`Image is ${dims.width}x${dims.height} pixels`);
+ * // Output: Image is 1920x1080 pixels
+ * ```
+ */
+export function getDimensionsSync(img: ImageInput): ImageDimensions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/honeydiff",
-  "version": "0.0.3",
+  "version": "0.1.1",
   "description": "High-performance image diffing for Node.js - Native bindings to Honeydiff Rust library",
   "main": "index.js",
   "types": "index.d.ts",
@@ -50,6 +50,16 @@
     "index.d.ts",
     "load-platform.js",
     "platforms/*.node",
+    "README.md",
+    "index.js",
+    "index.d.ts",
+    "load-platform.js",
+    "platforms/*.node",
+    "README.md",
+    "index.js",
+    "index.d.ts",
+    "load-platform.js",
+    "platforms/*.node",
     "README.md"
   ],
   "engines": {