@vizzly-testing/honeydiff 0.0.2 → 0.0.3

package/README.md

@@ -5,25 +5,9 @@
 [![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)
 
-High-performance image diffing for Node.js - Native bindings to the Honeydiff Rust library.
-
-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
+Fast image diffing for Node.js with native Rust performance (1.1B pixels/sec). Supports anti-aliasing detection, SSIM, clustering, and variable-height screenshots.
+
+**Features:** File paths or Buffers • Async + sync APIs • TypeScript types • Pre-built binaries (macOS/Linux/Windows)
 
 ## Installation
 
@@ -31,25 +15,15 @@ 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)
-
-No Rust toolchain required! The correct binary is automatically loaded for your platform.
+Requires Node.js 22+. Ships with pre-built binaries for macOS (ARM64), Linux (x64/ARM64), and Windows (x64). No Rust toolchain needed.
 
 ## 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 +34,62 @@ 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}`);
 ```
 
-### 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`);
 }
 ```
 
-## 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 +104,79 @@ 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
-});
 
+// 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
-});
 
+// 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)}`);
 }
 ```
 
 ## Performance
 
-Benchmarks on M-series Mac:
-
 | Image Size | Time | Throughput |
 |------------|------|------------|
 | 1920x1080 (Full HD) | ~2ms | 1.1B pixels/sec |
 | 3840x2160 (4K) | ~3ms | 3.0B pixels/sec |
 
-With diff artifact generation: ~30-35ms for Full HD images
-
-## Variable Height Support
-
-Honeydiff can compare images with different heights (same width) - perfect for scrollable screenshots:
-
-```javascript
-const result = await compare('short.png', 'tall.png');
-
-if (result.heightDiff) {
-  console.log(`Height diff: ${result.heightDiff.height1}px vs ${result.heightDiff.height2}px`);
-  console.log(`Extra pixels: ${result.heightDiff.extraPixels}`);
-}
-```
+With artifacts: ~30-35ms for Full HD. Benchmarked on Apple M-series Mac.
 
 ## Building from Source
 
-Only needed if you want to contribute or modify the native code.
-
-**Prerequisites:**
-- Rust toolchain (install from https://rustup.rs)
-- Node.js 22+
+Only needed for contributing or modifying native code. Requires Rust toolchain and Node.js 22+.
 
 ```bash
-# Clone the repository
 git clone https://github.com/vizzly-testing/honeydiff
 cd honeydiff/crates/honeydiff-node
-
-# Install dependencies
-npm install
-
-# Build for your platform
-npm run build
-
-# Run examples
-node examples/basic.js
-```
-
-### Cross-Platform Builds
-
-```bash
-# Build for all supported platforms (requires cross-compilation setup)
-npm run cross-build
+npm install && npm run build
 ```
 
-## Related Projects
-
-- [honeydiff](https://github.com/vizzly-testing/honeydiff) - The core Rust library
-- [Vizzly](https://github.com/vizzly-testing/vizzly) - Visual regression testing platform
-
 ## License
 
-MIT - See [LICENSE](../../LICENSE) for details
+MIT - See [LICENSE](../../LICENSE) for details. Built for [Vizzly](https://github.com/vizzly-testing/vizzly) visual regression testing.

package/package.json

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