@vizzly-testing/honeydiff 0.0.2

package/README.md

@@ -0,0 +1,327 @@
+# @vizzly-testing/honeydiff
+
+[![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)
+
+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
+
+## Installation
+
+```bash
+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.
+
+## Quick Start
+
+### JavaScript (Async - Recommended)
+
+```javascript
+const { compare, quickCompare } = require('@vizzly-testing/honeydiff');
+
+// Quick boolean check
+if (await quickCompare('baseline.png', 'current.png')) {
+  console.log('Visual regression detected!');
+}
+
+// Detailed comparison
+const result = await compare('baseline.png', 'current.png', {
+  pixelTolerance: 10,
+  includeSSIM: true
+});
+
+console.log(`Diff: ${result.diffPercentage.toFixed(2)}%`);
+console.log(`SSIM: ${result.perceptualScore}`);
+```
+
+### TypeScript
+
+```typescript
+import { compare, CompareOptions, DiffResult } from '@vizzly-testing/honeydiff';
+
+const options: CompareOptions = {
+  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'
+});
+```
+
+#### `quickCompare(img1, img2): Promise<boolean>`
+
+Quick async comparison returning only a boolean.
+
+**Returns:** `Promise<boolean>` - `true` if different, `false` if identical
+
+### Sync API
+
+#### `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
+
+```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;
+}
+```
+
+## Result Object
+
+```typescript
+interface DiffResult {
+  isDifferent: boolean;
+  diffPercentage: number;
+  totalPixels: number;
+  diffPixels: number;
+  aaPixelsIgnored: number;
+  aaPercentage: number;
+  boundingBox: BoundingBox | null;
+  heightDiff: HeightDiff | null;
+  diffPixelsList: DiffPixel[] | null;
+  diffClusters: DiffCluster[] | null;
+  intensityStats: IntensityStats | null;
+  perceptualScore: number | null; // SSIM 0.0-1.0
+}
+```
+
+## Usage Examples
+
+### With 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
+});
+```
+
+### Generate Diff Images
+
+```javascript
+const result = await compare('baseline.png', 'current.png', {
+  diffPath: './output/diff.png',
+  maskPath: './output/mask.png',
+  overlayPath: './output/overlay.png',
+  overwrite: true
+});
+
+console.log(`Diff images saved with ${result.diffPercentage}% difference`);
+```
+
+### Spatial Clustering
+
+```javascript
+const result = await compare('img1.png', 'img2.png', {
+  includeClusters: true
+});
+
+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}`);
+  });
+}
+```
+
+### Perceptual Similarity (SSIM)
+
+```javascript
+const result = await compare('img1.png', 'img2.png', {
+  includeSSIM: true
+});
+
+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');
+  }
+}
+```
+
+### Intensity Statistics
+
+```javascript
+const result = await compare('img1.png', 'img2.png', {
+  includeDiffPixels: true // Enables 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)}`);
+}
+```
+
+## 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}`);
+}
+```
+
+## 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+
+
+```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
+```
+
+## 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

package/index.d.ts

@@ -0,0 +1,276 @@
+/**
+ * TypeScript definitions for @vizzly-testing/honeydiff
+ * High-performance image diffing for Node.js
+ */
+
+// ============================================================================
+// Core Types
+// ============================================================================
+
+export interface BoundingBox {
+  /** X coordinate of top-left corner */
+  x: number;
+  /** Y coordinate of top-left corner */
+  y: number;
+  /** Width of the bounding box */
+  width: number;
+  /** Height of the bounding box */
+  height: number;
+}
+
+export interface HeightDiff {
+  /** Height of the first image in pixels */
+  height1: number;
+  /** Height of the second image in pixels */
+  height2: number;
+  /** Number of extra pixels due to height difference */
+  extraPixels: number;
+}
+
+export interface DiffPixel {
+  /** X coordinate of the differing pixel */
+  x: number;
+  /** Y coordinate of the differing pixel */
+  y: number;
+  /** Intensity of the difference (0-255, higher = more different) */
+  intensity: number;
+}
+
+export interface IntensityStats {
+  /** Maximum difference intensity observed (0-255) */
+  max: number;
+  /** Minimum difference intensity observed (0-255) */
+  min: number;
+  /** Mean (average) difference intensity */
+  mean: number;
+  /** Median difference intensity */
+  median: number;
+  /** Standard deviation of difference intensities */
+  stdDev: number;
+}
+
+export interface DiffCluster {
+  /** Number of pixels in this cluster */
+  pixelCount: number;
+  /** Center of mass [x, y] coordinates */
+  centerOfMass: [number, number];
+  /** Average intensity of differences in this cluster */
+  avgIntensity: number;
+  /** Bounding box containing this cluster */
+  boundingBox: BoundingBox;
+}
+
+export interface DiffResult {
+  /** Whether the images are different based on the comparison threshold */
+  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 */
+  diffPixels: number;
+  /** Number of pixels ignored due to anti-aliasing detection */
+  aaPixelsIgnored: number;
+  /** Percentage of pixels ignored as anti-aliasing (0.0 - 100.0) */
+  aaPercentage: number;
+  /** Bounding box containing all differences (null if identical) */
+  boundingBox: BoundingBox | null;
+  /** Height difference information (null if same height) */
+  heightDiff: HeightDiff | null;
+  /** List of differing pixels with positions and intensities (null unless includeDiffPixels is enabled) */
+  diffPixelsList: DiffPixel[] | null;
+  /** Clustered groups of connected differing pixels (null unless includeClusters is enabled) */
+  diffClusters: DiffCluster[] | null;
+  /** Statistical metrics about difference intensities (null unless includeDiffPixels is enabled) */
+  intensityStats: IntensityStats | null;
+  /** SSIM (Structural Similarity Index) perceptual score 0.0-1.0 (null unless includeSSIM is enabled) */
+  perceptualScore: number | null;
+}
+
+// ============================================================================
+// Options
+// ============================================================================
+
+export interface CompareOptions {
+  /**
+   * Pixel difference threshold (0-255). Differences below this are ignored.
+   * NOTE: When using YIQ comparison, use colorThreshold instead (0.0-1.0)
+   * @default 0
+   */
+  pixelTolerance?: number;
+
+  /**
+   * Color difference threshold for YIQ comparison (0.0-1.0)
+   * Set to 0.0 to use RGB comparison (default)
+   * Set to 0.1 for odiff-style YIQ comparison
+   * @default 0.0
+   */
+  colorThreshold?: number;
+
+  /**
+   * Enable anti-aliasing detection to ignore AA differences
+   * @default true
+   */
+  antialiasing?: boolean;
+
+  /**
+   * Ignore color differences (compare only structure/brightness)
+   * @default false
+   */
+  ignoreColors?: boolean;
+
+  /**
+   * Maximum number of differences to detect before stopping
+   * @default undefined (unlimited)
+   */
+  maxDiffs?: number;
+
+  /**
+   * Include list of differing pixels with positions and intensities
+   * WARNING: This can use significant memory for images with many differences
+   * @default false
+   */
+  includeDiffPixels?: boolean;
+
+  /**
+   * Include clustered groups of connected differing pixels
+   * Automatically enables includeDiffPixels if not already enabled
+   * Clusters are sorted by size (largest first)
+   * @default false
+   */
+  includeClusters?: boolean;
+
+  /**
+   * Calculate SSIM (Structural Similarity Index) perceptual score
+   * WARNING: SSIM can be computationally expensive on large images
+   * @default false
+   */
+  includeSSIM?: boolean;
+
+  /**
+   * Path to save the diff image (highlighted differences)
+   * @default undefined
+   */
+  diffPath?: string;
+
+  /**
+   * Path to save the mask image (binary diff mask)
+   * @default undefined
+   */
+  maskPath?: string;
+
+  /**
+   * Path to save the overlay image (side-by-side comparison)
+   * @default undefined
+   */
+  overlayPath?: string;
+
+  /**
+   * Whether to overwrite existing output files
+   * @default false
+   */
+  overwrite?: boolean;
+}
+
+// ============================================================================
+// Input Types
+// ============================================================================
+
+/** Image input can be a file path or a Buffer containing image data */
+export type ImageInput = string | Buffer;
+
+// ============================================================================
+// API Functions
+// ============================================================================
+
+/**
+ * Compare two images asynchronously (recommended)
+ *
+ * @param img1 - First image (file path or Buffer)
+ * @param img2 - Second image (file path or Buffer)
+ * @param options - Comparison options
+ * @returns Promise resolving to detailed diff results
+ *
+ * @example
+ * ```typescript
+ * const result = await compare('baseline.png', 'current.png', {
+ *   pixelTolerance: 10,
+ *   includeSSIM: true
+ * });
+ *
+ * console.log(`Diff: ${result.diffPercentage.toFixed(2)}%`);
+ * console.log(`SSIM: ${result.perceptualScore}`);
+ * ```
+ */
+export function compare(
+  img1: ImageInput,
+  img2: ImageInput,
+  options?: CompareOptions
+): Promise<DiffResult>;
+
+/**
+ * Quick asynchronous comparison (returns only boolean)
+ *
+ * @param img1 - First image (file path or Buffer)
+ * @param img2 - Second image (file path or Buffer)
+ * @returns Promise resolving to true if different, false if identical
+ *
+ * @example
+ * ```typescript
+ * if (await quickCompare('baseline.png', 'current.png')) {
+ *   console.log('Visual regression detected!');
+ * }
+ * ```
+ */
+export function quickCompare(
+  img1: ImageInput,
+  img2: ImageInput
+): Promise<boolean>;
+
+/**
+ * Compare two images synchronously (blocks event loop)
+ *
+ * Use this only when you need blocking behavior.
+ * For most cases, prefer the async compare() function.
+ *
+ * @param img1 - First image (file path or Buffer)
+ * @param img2 - Second image (file path or Buffer)
+ * @param options - Comparison options
+ * @returns Detailed diff results
+ *
+ * @example
+ * ```typescript
+ * const result = compareSync('baseline.png', 'current.png', {
+ *   pixelTolerance: 5,
+ *   includeClusters: true
+ * });
+ *
+ * if (result.diffClusters) {
+ *   console.log(`Found ${result.diffClusters.length} diff regions`);
+ * }
+ * ```
+ */
+export function compareSync(
+  img1: ImageInput,
+  img2: ImageInput,
+  options?: CompareOptions
+): DiffResult;
+
+/**
+ * Quick synchronous comparison (returns only boolean, blocks event loop)
+ *
+ * @param img1 - First image (file path or Buffer)
+ * @param img2 - Second image (file path or Buffer)
+ * @returns true if different, false if identical
+ *
+ * @example
+ * ```typescript
+ * if (quickCompareSync('baseline.png', 'current.png')) {
+ *   console.log('Images differ');
+ * }
+ * ```
+ */
+export function quickCompareSync(
+  img1: ImageInput,
+  img2: ImageInput
+): boolean;

package/index.js

@@ -0,0 +1,24 @@
+/**
+ * @vizzly-testing/honeydiff - Native Node.js bindings for Honeydiff
+ */
+
+let addon;
+
+try {
+  // Load the platform-specific native addon
+  addon = require('./load-platform.js');
+} catch (e) {
+  throw new Error(
+    '@vizzly-testing/honeydiff failed to load native binary.\n' +
+    'Platform: ' + process.platform + ' ' + process.arch + '\n' +
+    'Original error: ' + e.message
+  );
+}
+
+// Export all functions from the native addon
+module.exports = {
+  compare: addon.compare,
+  quickCompare: addon.quickCompare,
+  compareSync: addon.compareSync,
+  quickCompareSync: addon.quickCompareSync,
+};

package/load-platform.js

@@ -0,0 +1,25 @@
+const os = require('os');
+const path = require('path');
+
+function getPlatformBinary() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  let target;
+  if (platform === 'darwin' && arch === 'arm64') {
+    target = 'aarch64-apple-darwin';
+  } else if (platform === 'linux' && arch === 'x64') {
+    target = 'x86_64-unknown-linux-gnu';
+  } else if (platform === 'linux' && arch === 'arm64') {
+    target = 'aarch64-unknown-linux-gnu';
+  } else if (platform === 'win32' && arch === 'x64') {
+    target = 'x86_64-pc-windows-msvc';
+  } else {
+    throw new Error(`Unsupported platform: ${platform} ${arch}. Supported: macOS ARM64, Linux x64/ARM64, Windows x64`);
+  }
+
+  const binaryPath = path.join(__dirname, 'platforms', `index-${target}.node`);
+  return require(binaryPath);
+}
+
+module.exports = getPlatformBinary();

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@vizzly-testing/honeydiff",
+  "version": "0.0.2",
+  "description": "High-performance image diffing for Node.js - Native bindings to Honeydiff Rust library",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "neon": {
+    "targets": [
+      "x86_64-pc-windows-msvc",
+      "aarch64-apple-darwin",
+      "x86_64-unknown-linux-gnu",
+      "aarch64-unknown-linux-gnu"
+    ]
+  },
+  "scripts": {
+    "build": "cargo build --release",
+    "build-debug": "cargo build",
+    "test": "node examples/basic.js",
+    "clean": "cargo clean && rm -f index.node"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vizzly-testing/honeydiff.git",
+    "directory": "crates/honeydiff-node"
+  },
+  "keywords": [
+    "image",
+    "diff",
+    "comparison",
+    "visual-regression",
+    "testing",
+    "screenshot",
+    "rust",
+    "neon",
+    "native"
+  ],
+  "author": "Robert DeLuca",
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "index.node",
+    "README.md",
+    "index.js",
+    "index.d.ts",
+    "load-platform.js",
+    "platforms/*.node",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}