@vizzly-testing/honeydiff 0.0.2 → 0.1.0

package/README.md

@@ -2,28 +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)
 
-High-performance image diffing for Node.js - Native bindings to the Honeydiff Rust library.
+Blazingly fast image comparison for Node.js. Perfect for visual regression testing, screenshot
+validation, and detecting visual changes.
 
-Blazing fast image comparison with support for anti-aliasing detection, perceptual similarity (SSIM), spatial clustering, and variable-height screenshots. Perfect for visual regression testing.
-
-## Features
-
-- **🚀 Native Performance** - Rust-powered via Neon bindings (1.1B pixels/sec for Full HD)
-- **📦 Dual Input** - Works with file paths or Buffers
-- **⚡ Async + Sync APIs** - Choose between non-blocking promises or synchronous operations
-- **🎯 Full TypeScript Support** - Complete type definitions included
-- **🔍 Advanced Analysis**:
-  - Anti-aliasing detection
-  - SSIM perceptual similarity scoring
-  - Spatial clustering of diff regions
-  - Intensity statistics (min, max, mean, median, std dev)
-  - Bounding box detection
-- **📸 Variable Height Support** - Compare scrollable screenshots with different heights
-- **🎨 Visual Artifacts** - Generate diff, mask, and overlay images
-- **⚙️ Flexible Options** - Pixel tolerance, color thresholds, custom diff colors
+**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
 
@@ -31,25 +20,18 @@ Blazing fast image comparison with support for anti-aliasing detection, perceptu
 npm install @vizzly-testing/honeydiff
 ```
 
-**Requirements:**
-- Node.js 22+
-
-**Pre-built Binaries:**
-This package ships with pre-built native binaries for:
-- macOS (Apple Silicon arm64)
-- Linux (x64 and arm64)
-- Windows (x64)
+**Requirements:** Node.js 22+
 
-No Rust toolchain required! The correct binary is automatically loaded for your platform.
+Pre-built binaries included for macOS (ARM64), Linux (x64/ARM64), and Windows (x64). No compilation
+required.
 
 ## Quick Start
 
-### JavaScript (Async - Recommended)
-
+**JavaScript**
 ```javascript
 const { compare, quickCompare } = require('@vizzly-testing/honeydiff');
 
-// Quick boolean check
+// Quick check
 if (await quickCompare('baseline.png', 'current.png')) {
   console.log('Visual regression detected!');
 }
@@ -60,112 +42,64 @@ const result = await compare('baseline.png', 'current.png', {
   includeSSIM: true
 });
 
-console.log(`Diff: ${result.diffPercentage.toFixed(2)}%`);
-console.log(`SSIM: ${result.perceptualScore}`);
+console.log(`Diff: ${result.diffPercentage.toFixed(2)}%, SSIM: ${result.perceptualScore}`);
+// Output: Diff: 3.55%, SSIM: 0.9234
 ```
 
-### TypeScript
+**TypeScript**
 
 ```typescript
 import { compare, CompareOptions, DiffResult } from '@vizzly-testing/honeydiff';
 
-const options: CompareOptions = {
+const result: DiffResult = await compare('img1.png', 'img2.png', {
   pixelTolerance: 5,
   includeSSIM: true,
   includeClusters: true
-};
-
-const result: DiffResult = await compare('img1.png', 'img2.png', options);
+});
 
 if (result.diffClusters) {
   console.log(`Found ${result.diffClusters.length} diff regions`);
 }
+// Output: Found 3 diff regions
 ```
 
-## API Reference
-
-### Async API (Recommended)
-
-#### `compare(img1, img2, options?): Promise<DiffResult>`
-
-Compare two images asynchronously. Non-blocking operation.
-
-**Parameters:**
-- `img1`: `string | Buffer` - First image (file path or Buffer)
-- `img2`: `string | Buffer` - Second image (file path or Buffer)
-- `options`: `CompareOptions` (optional) - Comparison configuration
-
-**Returns:** `Promise<DiffResult>` - Detailed diff results
-
-**Example:**
-```javascript
-const result = await compare('baseline.png', 'current.png', {
-  pixelTolerance: 10,
-  antialiasing: true,
-  includeSSIM: true,
-  diffPath: '/tmp/diff.png'
-});
-```
+## API
 
-#### `quickCompare(img1, img2): Promise<boolean>`
+**Async (recommended)**
+- `compare(img1, img2, options?): Promise<DiffResult>` - Full comparison
+- `quickCompare(img1, img2): Promise<boolean>` - Quick check
 
-Quick async comparison returning only a boolean.
+**Sync (blocks event loop)**
+- `compareSync(img1, img2, options?): DiffResult`
+- `quickCompareSync(img1, img2): boolean`
 
-**Returns:** `Promise<boolean>` - `true` if different, `false` if identical
+Inputs: `string` (file path) or `Buffer`
 
-### Sync API
+## Options & Results
 
-#### `compareSync(img1, img2, options?): DiffResult`
-
-Synchronous comparison (blocks event loop). Use only when necessary.
-
-#### `quickCompareSync(img1, img2): boolean`
-
-Synchronous quick comparison returning a boolean.
-
-## Options
+<details>
+<summary><strong>CompareOptions</strong></summary>
 
 ```typescript
 interface CompareOptions {
-  /** Pixel tolerance 0-255 (default: 0) */
-  pixelTolerance?: number;
-
-  /** YIQ color threshold 0.0-1.0 (default: 0.0 = RGB mode) */
-  colorThreshold?: number;
-
-  /** Enable anti-aliasing detection (default: true) */
-  antialiasing?: boolean;
-
-  /** Ignore colors, compare brightness only (default: false) */
-  ignoreColors?: boolean;
-
-  /** Max differences to find before stopping (default: unlimited) */
-  maxDiffs?: number;
-
-  /** Include detailed pixel list (default: false) */
-  includeDiffPixels?: boolean;
-
-  /** Include spatial clusters (default: false) */
-  includeClusters?: boolean;
-
-  /** Calculate SSIM score (default: false) */
-  includeSSIM?: boolean;
-
-  /** Path to save diff image */
-  diffPath?: string;
-
-  /** Path to save binary mask */
-  maskPath?: string;
-
-  /** Path to save side-by-side overlay */
-  overlayPath?: string;
-
-  /** Overwrite existing files (default: false) */
-  overwrite?: boolean;
+  pixelTolerance?: number;        // 0-255 (default: 0)
+  colorThreshold?: number;        // 0.0-1.0 for YIQ mode (default: 0.0 = RGB)
+  antialiasing?: boolean;         // Enable AA detection (default: true)
+  ignoreColors?: boolean;         // Brightness only (default: false)
+  maxDiffs?: number;              // Stop after N diffs (default: unlimited)
+  includeDiffPixels?: boolean;    // Detailed pixel list (default: false)
+  includeClusters?: boolean;      // Spatial clusters (default: false)
+  includeSSIM?: boolean;          // SSIM score (default: false)
+  diffPath?: string;              // Save diff image
+  maskPath?: string;              // Save mask image
+  overlayPath?: string;           // Save overlay image
+  overwrite?: boolean;            // Overwrite files (default: false)
 }
 ```
+</details>
 
-## Result Object
+<details>
+<summary><strong>DiffResult</strong></summary>
 
 ```typescript
 interface DiffResult {
@@ -180,148 +114,172 @@ interface DiffResult {
   diffPixelsList: DiffPixel[] | null;
   diffClusters: DiffCluster[] | null;
   intensityStats: IntensityStats | null;
-  perceptualScore: number | null; // SSIM 0.0-1.0
+  perceptualScore: number | null;  // SSIM 0.0-1.0
 }
 ```
+</details>
 
-## Usage Examples
-
-### With Buffers
+## Examples
 
+**Buffers**
 ```javascript
 const fs = require('fs');
 const { compare } = require('@vizzly-testing/honeydiff');
 
-const img1 = fs.readFileSync('image1.png');
-const img2 = fs.readFileSync('image2.png');
-
-const result = await compare(img1, img2, {
-  pixelTolerance: 5
-});
+let img1 = fs.readFileSync('image1.png');
+let img2 = fs.readFileSync('image2.png');
+let result = await compare(img1, img2, { pixelTolerance: 5 });
 ```
 
-### Generate Diff Images
+**Diff Images**
 
 ```javascript
-const result = await compare('baseline.png', 'current.png', {
-  diffPath: './output/diff.png',
-  maskPath: './output/mask.png',
-  overlayPath: './output/overlay.png',
+let result = await compare('baseline.png', 'current.png', {
+  diffPath: './diff.png',
+  maskPath: './mask.png',
+  overlayPath: './overlay.png',
   overwrite: true
 });
-
-console.log(`Diff images saved with ${result.diffPercentage}% difference`);
 ```
 
-### Spatial Clustering
-
+**Clustering & Metrics**
 ```javascript
-const result = await compare('img1.png', 'img2.png', {
-  includeClusters: true
+let result = await compare('img1.png', 'img2.png', {
+  includeClusters: true,
+  includeSSIM: true,
+  includeDiffPixels: true
 });
 
+// Spatial clusters
 if (result.diffClusters) {
-  result.diffClusters.forEach((cluster, i) => {
-    console.log(`Cluster ${i + 1}:`);
-    console.log(`  Pixels: ${cluster.pixelCount}`);
-    console.log(`  Center: (${cluster.centerOfMass[0]}, ${cluster.centerOfMass[1]})`);
-    console.log(`  Bounds: ${cluster.boundingBox.width}x${cluster.boundingBox.height}`);
+  result.diffClusters.forEach((c, i) => {
+    console.log(`Region ${i + 1}: ${c.pixelCount} pixels at (${c.centerOfMass[0]}, ${c.centerOfMass[1]})`);
   });
 }
-```
-
-### Perceptual Similarity (SSIM)
-
-```javascript
-const result = await compare('img1.png', 'img2.png', {
-  includeSSIM: true
-});
+// 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) {
-  if (result.perceptualScore > 0.95) {
-    console.log('Perceptually very similar');
-  } else if (result.perceptualScore > 0.80) {
-    console.log('Somewhat similar');
-  } else {
-    console.log('Perceptually different');
-  }
+  console.log(`SSIM: ${result.perceptualScore.toFixed(3)}`);
 }
-```
-
-### Intensity Statistics
-
-```javascript
-const result = await compare('img1.png', 'img2.png', {
-  includeDiffPixels: true // Enables intensity stats
-});
+// Output: SSIM: 0.923
 
+// Intensity stats
 if (result.intensityStats) {
-  console.log(`Intensity 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)}`);
+  console.log(`Range: ${result.intensityStats.min}-${result.intensityStats.max}, Mean: ${result.intensityStats.mean.toFixed(1)}`);
 }
+// Output: Range: 12-255, Mean: 87.3
 ```
 
-## Performance
+**Complete Result Example**
+```javascript
+let result = await compare('baseline.png', 'current.png', {
+  pixelTolerance: 10,
+  includeClusters: true
+});
 
-Benchmarks on M-series Mac:
+console.log(JSON.stringify(result, null, 2));
+```
 
-| Image Size | Time | Throughput |
-|------------|------|------------|
-| 1920x1080 (Full HD) | ~2ms | 1.1B pixels/sec |
-| 3840x2160 (4K) | ~3ms | 3.0B pixels/sec |
+<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>
+```
 
-With diff artifact generation: ~30-35ms for Full HD images
+## Use Cases
 
-## Variable Height Support
+- **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
 
-Honeydiff can compare images with different heights (same width) - perfect for scrollable screenshots:
+## Performance
 
-```javascript
-const result = await compare('short.png', 'tall.png');
+Tested on real-world tall screenshots (750 x 24,162 pixels = 18.3M pixels):
 
-if (result.heightDiff) {
-  console.log(`Height diff: ${result.heightDiff.height1}px vs ${result.heightDiff.height2}px`);
-  console.log(`Extra pixels: ${result.heightDiff.extraPixels}`);
-}
-```
+| 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 if you want to contribute or modify the native code.
+*Benchmarked on Apple M-series Mac.*
 
-**Prerequisites:**
-- Rust toolchain (install from https://rustup.rs)
-- Node.js 22+
+## Advanced Features
 
-```bash
-# Clone the repository
-git clone https://github.com/vizzly-testing/honeydiff
-cd honeydiff/crates/honeydiff-node
+**Variable Height Screenshots**
+Compare scrollable content with different heights. Overlapping regions are compared pixel-by-pixel,
+extra rows counted as differences.
 
-# Install dependencies
-npm install
+**Color Spaces**
+- RGB mode (default): Exact matching, fastest performance
+- YIQ mode: Perceptual matching weighted for human vision
 
-# Build for your platform
-npm run build
+**Spatial Clustering**
+Group nearby differences into regions using 8-connectivity clustering. Useful for identifying distinct changed areas.
 
-# Run examples
-node examples/basic.js
-```
+**SSIM Scoring**
+Structural Similarity Index (0.0-1.0) provides perceptual similarity measurement beyond pixel differences.
 
-### Cross-Platform Builds
+## Troubleshooting
 
-```bash
-# Build for all supported platforms (requires cross-compilation setup)
-npm run cross-build
-```
+**Module not found errors**
+Ensure you're on Node.js 22+ and your platform is supported (macOS ARM64, Linux x64/ARM64, Windows x64).
 
-## Related Projects
+**Large memory usage with `includeDiffPixels`**
+This option stores every different pixel's position and intensity. Disable for large images with many differences.
 
-- [honeydiff](https://github.com/vizzly-testing/honeydiff) - The core Rust library
-- [Vizzly](https://github.com/vizzly-testing/vizzly) - Visual regression testing platform
+**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
+MIT License
+
+Built with native Rust for maximum performance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/honeydiff",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "High-performance image diffing for Node.js - Native bindings to Honeydiff Rust library",
   "main": "index.js",
   "types": "index.d.ts",
@@ -45,6 +45,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": {