@vizzly-testing/honeydiff 0.10.1 → 0.10.3

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.10.3] - 2026-05-19
+
+## What's Changed
+
+- ⚡ Speed up image comparison hot paths (#31)
+- 🛠️ Resume current npm release
+
+**Full Changelog**: https://github.com/vizzly-testing/honeydiff/compare/v0.10.2...v0.10.3
+
+## [0.10.2] - 2026-05-19
+
+## What's Changed
+
+- 🛠️ Remove release npm self-upgrade (#30)
+- 🛠️ Harden release workflows (#29)
+- 🧪 Give coverage tests more time (#28)
+- 🛡️ Harden honeydiff production contracts (#27)
+- 🐛 Fix honeydiff-core clippy warnings
+- 🧪 Add diff contract test suite
+
+**Full Changelog**: https://github.com/vizzly-testing/honeydiff/compare/v0.10.1...v0.10.2
+
 ## [0.10.1] - 2026-03-11
 
 ## What's Changed

package/README.md

@@ -28,7 +28,7 @@ Built for production visual regression testing at scale.
 ### Basic Comparison
 
 ```javascript
-const { compare, quickCompare } = require('@vizzly-testing/honeydiff');
+import { compare, quickCompare } from '@vizzly-testing/honeydiff';
 
 // Quick boolean check - are these images different?
 if (await quickCompare('baseline.png', 'current.png')) {
@@ -37,7 +37,7 @@ if (await quickCompare('baseline.png', 'current.png')) {
 
 // Detailed comparison with tolerance
 const result = await compare('baseline.png', 'current.png', {
-  pixelTolerance: 10,  // Ignore tiny differences
+  threshold: 10,  // Ignore tiny differences
   includeSSIM: true    // Perceptual similarity score
 });
 
@@ -52,7 +52,7 @@ console.log(`SSIM: ${result.perceptualScore}`);
 import { compare, CompareOptions, DiffResult } from '@vizzly-testing/honeydiff';
 
 const options: CompareOptions = {
-  pixelTolerance: 5,
+  threshold: 5,
   includeSSIM: true,
   includeClusters: true
 };
@@ -79,14 +79,14 @@ test('homepage should match baseline', async () => {
 
 **Playwright**
 ```javascript
-const { compare } = require('@vizzly-testing/honeydiff');
+import { compare } from '@vizzly-testing/honeydiff';
 
 test('button hover state', async () => {
   await page.hover('[data-testid="submit-button"]');
   let screenshot = await page.screenshot();
 
   let result = await compare('baseline.png', screenshot, {
-    pixelTolerance: 10,
+    threshold: 10,
     diffPath: './artifacts/diff.png'
   });
 
@@ -256,26 +256,22 @@ GMSD is ideal for catching:
 
 **Reference:** Xue et al. 2014 - "Gradient Magnitude Similarity Deviation: A Highly Efficient Perceptual Image Quality Index"
 
-### 7. Tolerance & Color Spaces
+### 7. Thresholds
 
-**RGB Mode (default)** - Exact matching with pixel tolerance:
-```javascript
-const result = await compare('img1.png', 'img2.png', {
-  pixelTolerance: 10  // Ignore differences below threshold (0-255)
-});
-```
+Honeydiff uses CIEDE2000 Delta E thresholds for perceptual color difference:
 
-**YIQ Mode** - Perceptual color matching weighted for human vision:
 ```javascript
 const result = await compare('img1.png', 'img2.png', {
-  colorThreshold: 0.1  // YIQ mode (odiff-compatible)
+  threshold: 2.0  // Default: ignores tiny perceptual variance
 });
 ```
 
-**Brightness-only Mode** - Ignore color, compare structure:
+Use exact mode when every changed pixel should count:
+
 ```javascript
 const result = await compare('img1.png', 'img2.png', {
-  ignoreColors: true  // Compare brightness/luminance only
+  threshold: 0,
+  minClusterSize: 1
 });
 ```
 
@@ -283,13 +279,15 @@ const result = await compare('img1.png', 'img2.png', {
 
 Work with in-memory images from screenshots or API responses.
 
+For large screenshots, prefer file paths when possible. Buffer inputs are copied into the native worker before async processing begins, so path inputs put less pressure on the Node.js event loop and heap.
+
 ```javascript
-const fs = require('fs');
+import fs from 'node:fs';
 
 // Compare buffers directly
 let img1 = fs.readFileSync('image1.png');
 let img2 = fs.readFileSync('image2.png');
-let result = await compare(img1, img2, { pixelTolerance: 5 });
+let result = await compare(img1, img2, { threshold: 5 });
 
 // Mix paths and buffers
 let screenshot = await page.screenshot();  // Returns Buffer
@@ -301,7 +299,7 @@ let result = await compare('baseline.png', screenshot);
 Fast utility to get image dimensions without loading full image data.
 
 ```javascript
-const { getDimensions } = require('@vizzly-testing/honeydiff');
+import { getDimensions } from '@vizzly-testing/honeydiff';
 
 let dims = await getDimensions('screenshot.png');
 console.log(`Image is ${dims.width}x${dims.height} pixels`);
@@ -317,7 +315,7 @@ let dims = await getDimensions(buffer);
 Get image dimensions, file size, and format detection - useful for storage tracking and billing.
 
 ```javascript
-const { getImageMetadata, getImageMetadataFromFile } = require('@vizzly-testing/honeydiff');
+import { getImageMetadata, getImageMetadataFromFile } from '@vizzly-testing/honeydiff';
 
 // From buffer
 let buffer = fs.readFileSync('screenshot.png');
@@ -339,7 +337,12 @@ console.log(`${metadata.width}x${metadata.height}, ${metadata.fileSizeBytes} byt
 Group similar diffs across comparisons with fingerprinting. Perfect for batch-approving the same visual change that appears on multiple pages (e.g., header/footer updates).
 
 ```javascript
-const { compare, computeFingerprintSync, fingerprintSimilaritySync, fingerprintHashSync } = require('@vizzly-testing/honeydiff');
+import {
+  compare,
+  computeFingerprintSync,
+  fingerprintSimilaritySync,
+  fingerprintHashSync
+} from '@vizzly-testing/honeydiff';
 
 // Compare images with clustering enabled
 let result = await compare('baseline.png', 'current.png', {
@@ -406,7 +409,7 @@ Built-in WCAG color contrast analysis and color blindness simulation to catch ac
 Analyze entire images for WCAG color contrast violations - perfect for catching accessibility issues in screenshots and UI designs.
 
 ```javascript
-const { analyzeWcagContrast, saveWcagOverlay } = require('@vizzly-testing/honeydiff');
+import { analyzeWcagContrast, saveWcagOverlay } from '@vizzly-testing/honeydiff';
 
 // Analyze a screenshot for accessibility violations
 let analysis = await analyzeWcagContrast('screenshot.png', {
@@ -461,12 +464,12 @@ Simulate how your UI appears to users with color vision deficiencies. Uses the s
 - `achromatopsia` - Complete color blindness (grayscale only)
 
 ```javascript
-const {
+import {
   simulateColorBlindness,
   saveColorBlindnessSimulation,
   saveAllColorBlindnessSimulations,
   getColorBlindnessTypes
-} = require('@vizzly-testing/honeydiff');
+} from '@vizzly-testing/honeydiff';
 
 // Get CVD type information
 let types = getColorBlindnessTypes();
@@ -492,7 +495,7 @@ await saveAllColorBlindnessSimulations('dashboard.png', 'dashboard', 'png');
 Analyze contrast accessibility specifically for colorblind users. This catches issues that only appear when colors are perceived differently.
 
 ```javascript
-const { analyzeWcagForCvd, analyzeWcagAllCvd } = require('@vizzly-testing/honeydiff');
+import { analyzeWcagForCvd, analyzeWcagAllCvd } from '@vizzly-testing/honeydiff';
 
 // Analyze for a specific CVD type
 let analysis = await analyzeWcagForCvd('ui.png', 'deuteranopia', {
@@ -668,9 +671,8 @@ Benchmarked on 18.3M pixel screenshots (750 x 24,162 px):
 
 | Operation | Time | Throughput |
 |-----------|------|------------|
-| Basic RGB comparison | ~79ms | 231.8M pixels/sec |
+| Basic CIEDE2000 comparison | ~79ms | 231.8M pixels/sec |
 | With anti-aliasing | ~88ms | 208M pixels/sec |
-| YIQ color space | ~89ms | 206M pixels/sec |
 | With artifacts (diff/mask/overlay) | ~432ms | 42.4M pixels/sec |
 
 **vs odiff:** 6.0x faster (79ms vs 474ms)
@@ -684,11 +686,11 @@ Multi-core parallelization: 215-309% CPU utilization across cores.
 ### CI/CD Integration
 
 ```javascript
-const { compare } = require('@vizzly-testing/honeydiff');
+import { compare } from '@vizzly-testing/honeydiff';
 
 async function visualRegressionTest() {
   let result = await compare('baseline.png', 'current.png', {
-    pixelTolerance: 10,
+    threshold: 10,
     maxDiffs: 1000,  // Early exit for fast failure
     diffPath: process.env.CI ? './artifacts/diff.png' : undefined
   });
@@ -721,7 +723,7 @@ if (await quickCompare('baseline.png', 'current.png')) {
 
 ```javascript
 const result = await compare('baseline.png', 'current.png', {
-  pixelTolerance: 10
+  threshold: 10
 });
 
 if (result.diffPercentage > 5.0) {
@@ -753,7 +755,7 @@ if (result.diffPercentage > 5.0) {
 
 **Anti-aliasing too aggressive**
 - Set `antialiasing: false` for stricter pixel matching
-- Adjust `pixelTolerance` instead for controlled flexibility
+- Adjust `threshold` instead for controlled flexibility
 
 ## Use Cases
 

package/examples/basic.js

@@ -1,32 +1,29 @@
 /**
- * Basic usage example for @honeydiff/node
+ * Basic usage example for @vizzly-testing/honeydiff
  */
 
 import * as honeydiff from '../index.js';
 
+let baseline = '../../tests/fixtures/screenshots/vizzly-baseline.png';
+let current = '../../tests/fixtures/screenshots/vizzly-with-diff.png';
+
 async function main() {
-  console.log('Honeydiff Node.js Examples\n');
+  console.log('Honeydiff Node.js examples\n');
 
-  // Example 1: Quick async comparison
-  console.log('1. Quick comparison:');
-  let isDifferent = await honeydiff.quickCompare(
-    '../../tests/fixtures/screenshots/vizzly-baseline.png',
-    '../../tests/fixtures/screenshots/vizzly-with-diff.png'
-  );
+  console.log('1. Quick comparison');
+  let isDifferent = await honeydiff.quickCompare(baseline, current);
   console.log(`  Result: ${isDifferent ? 'DIFFERENT' : 'IDENTICAL'}\n`);
 
-  // Example 2: Detailed async comparison
-  console.log('2. Detailed comparison with options:');
-  let result = await honeydiff.compare(
-    '../../tests/fixtures/screenshots/vizzly-baseline.png',
-    '../../tests/fixtures/screenshots/vizzly-with-diff.png',
-    {
-      pixelTolerance: 0,
-      antialiasing: true,
-      includeSSIM: true,
-      includeClusters: true,
-    }
-  );
+  console.log('2. Detailed comparison');
+  let result = await honeydiff.compare(baseline, current, {
+    threshold: 0,
+    antialiasing: true,
+    includeSSIM: true,
+    includeGMSD: true,
+    includeClusters: true,
+    includeDiffPixels: true,
+    minClusterSize: 1,
+  });
 
   console.log(`  Diff percentage: ${result.diffPercentage.toFixed(2)}%`);
   console.log(`  Different pixels: ${result.diffPixels} / ${result.totalPixels}`);
@@ -36,6 +33,10 @@ async function main() {
     console.log(`  SSIM score: ${result.perceptualScore.toFixed(4)}`);
   }
 
+  if (result.gmsdScore !== null) {
+    console.log(`  GMSD score: ${result.gmsdScore.toFixed(4)}`);
+  }
+
   if (result.boundingBox) {
     console.log(
       `  Bounding box: (${result.boundingBox.x}, ${result.boundingBox.y}) ${result.boundingBox.width}x${result.boundingBox.height}`
@@ -44,270 +45,34 @@ async function main() {
 
   if (result.diffClusters && result.diffClusters.length > 0) {
     console.log(`  Found ${result.diffClusters.length} diff clusters`);
-    result.diffClusters.slice(0, 3).forEach((cluster, i) => {
+    for (let [index, cluster] of result.diffClusters.slice(0, 3).entries()) {
       console.log(
-        `    Cluster ${i + 1}: ${cluster.pixelCount} pixels at (${cluster.centerOfMass[0].toFixed(0)}, ${cluster.centerOfMass[1].toFixed(0)})`
+        `    Cluster ${index + 1}: ${cluster.pixelCount} pixels at (${cluster.centerOfMass[0].toFixed(0)}, ${cluster.centerOfMass[1].toFixed(0)})`
       );
-    });
-  }
-
-  if (result.intensityStats) {
-    console.log(`  Intensity stats:`);
-    console.log(`    Range: ${result.intensityStats.min}-${result.intensityStats.max}`);
-    console.log(
-      `    Mean: ${result.intensityStats.mean.toFixed(1)}, Median: ${result.intensityStats.median}`
-    );
-  }
-
-  console.log();
-
-  // Example 3: Synchronous comparison (for when you need blocking behavior)
-  console.log('3. Synchronous comparison:');
-  let syncResult = honeydiff.compareSync(
-    '../../tests/fixtures/screenshots/vizzly-baseline.png',
-    '../../tests/fixtures/screenshots/vizzly-with-diff.png',
-    { pixelTolerance: 10 }
-  );
-  console.log(`  Diff percentage: ${syncResult.diffPercentage.toFixed(2)}%`);
-  console.log();
-
-  // Example 4: Get image dimensions
-  console.log('4. Get image dimensions:');
-  let dimensions = await honeydiff.getDimensions(
-    '../../tests/fixtures/screenshots/vizzly-baseline.png'
-  );
-  console.log(`  Dimensions: ${dimensions.width}x${dimensions.height} pixels`);
-  console.log();
-
-  // Example 5: Get dimensions synchronously
-  console.log('5. Get dimensions (sync):');
-  let syncDimensions = honeydiff.getDimensionsSync(
-    '../../tests/fixtures/screenshots/vizzly-with-diff.png'
-  );
-  console.log(`  Dimensions: ${syncDimensions.width}x${syncDimensions.height} pixels`);
-  console.log();
-
-  // Example 6: Generate diff artifacts
-  console.log('6. Generate diff artifacts:');
-  let artifactResult = await honeydiff.compare(
-    '../../tests/fixtures/screenshots/vizzly-baseline.png',
-    '../../tests/fixtures/screenshots/vizzly-with-diff.png',
-    {
-      diffPath: '/tmp/honeydiff-diff.png',
-      maskPath: '/tmp/honeydiff-mask.png',
-      overlayPath: '/tmp/honeydiff-overlay.png',
-      overwrite: true,
-    }
-  );
-  console.log(`  Diff percentage: ${artifactResult.diffPercentage.toFixed(2)}%`);
-  console.log(`  Artifacts saved to /tmp/honeydiff-*.png`);
-  console.log();
-
-  // Example 7: Accessibility metadata tests
-  console.log('7. Accessibility metadata (RGB + luminance + WCAG):');
-  let accessibilityResult = await honeydiff.compare(
-    '../../tests/fixtures/screenshots/vizzly-baseline.png',
-    '../../tests/fixtures/screenshots/vizzly-with-diff.png',
-    {
-      includeClusters: true,
-      includeAccessibilityData: true,
-    }
-  );
-
-  // Validate accessibility data is present
-  if (!accessibilityResult.diffClusters || accessibilityResult.diffClusters.length === 0) {
-    throw new Error('Test failed: Expected diff clusters to be present');
-  }
-
-  let firstCluster = accessibilityResult.diffClusters[0];
-  if (!firstCluster.accessibilityMetadata) {
-    throw new Error('Test failed: Expected accessibilityMetadata to be present');
-  }
-
-  let meta = firstCluster.accessibilityMetadata;
-
-  // Validate RGB channel differences
-  if (typeof meta.avgRDiff !== 'number' || meta.avgRDiff < 0) {
-    throw new Error('Test failed: avgRDiff should be a non-negative number');
-  }
-  if (typeof meta.avgGDiff !== 'number' || meta.avgGDiff < 0) {
-    throw new Error('Test failed: avgGDiff should be a non-negative number');
-  }
-  if (typeof meta.avgBDiff !== 'number' || meta.avgBDiff < 0) {
-    throw new Error('Test failed: avgBDiff should be a non-negative number');
-  }
-
-  // Validate dominant channel
-  if (!['R', 'G', 'B'].includes(meta.dominantChannel)) {
-    throw new Error(
-      `Test failed: dominantChannel should be R, G, or B, got ${meta.dominantChannel}`
-    );
-  }
-
-  // Validate luminance values (0.0-1.0 range)
-  if (meta.avgBaselineLuminance < 0 || meta.avgBaselineLuminance > 1) {
-    throw new Error('Test failed: avgBaselineLuminance should be between 0 and 1');
-  }
-  if (meta.avgCurrentLuminance < 0 || meta.avgCurrentLuminance > 1) {
-    throw new Error('Test failed: avgCurrentLuminance should be between 0 and 1');
-  }
-
-  // Validate contrast ratios (1.0-21.0 range)
-  if (meta.contrastRatio < 1 || meta.contrastRatio > 21) {
-    throw new Error('Test failed: contrastRatio should be between 1 and 21');
-  }
-  if (meta.minContrastRatio < 1 || meta.minContrastRatio > 21) {
-    throw new Error('Test failed: minContrastRatio should be between 1 and 21');
-  }
-  if (meta.maxContrastRatio < 1 || meta.maxContrastRatio > 21) {
-    throw new Error('Test failed: maxContrastRatio should be between 1 and 21');
-  }
-  if (meta.minContrastRatio > meta.maxContrastRatio) {
-    throw new Error('Test failed: minContrastRatio should be <= maxContrastRatio');
-  }
-
-  // Validate colorBlindnessImpact is null when not requested
-  if (meta.colorBlindnessImpact !== null) {
-    throw new Error(
-      'Test failed: colorBlindnessImpact should be null when checkColorBlindness is not enabled'
-    );
-  }
-
-  console.log(
-    `  RGB diffs: R=${meta.avgRDiff.toFixed(1)}, G=${meta.avgGDiff.toFixed(1)}, B=${meta.avgBDiff.toFixed(1)}`
-  );
-  console.log(`  Dominant channel: ${meta.dominantChannel}`);
-  console.log(
-    `  Luminance: baseline=${meta.avgBaselineLuminance.toFixed(3)}, current=${meta.avgCurrentLuminance.toFixed(3)}`
-  );
-  console.log(
-    `  WCAG contrast: ${meta.contrastRatio.toFixed(2)}:1 (range: ${meta.minContrastRatio.toFixed(2)}-${meta.maxContrastRatio.toFixed(2)})`
-  );
-  console.log('  All accessibility metadata tests passed!');
-  console.log();
-
-  // Example 8: Color blindness checking tests
-  console.log('8. Color blindness checking:');
-  let cbResult = await honeydiff.compare(
-    '../../tests/fixtures/screenshots/vizzly-baseline.png',
-    '../../tests/fixtures/screenshots/vizzly-with-diff.png',
-    {
-      includeClusters: true,
-      checkColorBlindness: true,
-      colorBlindnessThreshold: 30.0,
     }
-  );
-
-  // Validate clusters and accessibility data
-  if (!cbResult.diffClusters || cbResult.diffClusters.length === 0) {
-    throw new Error('Test failed: Expected diff clusters to be present');
-  }
-
-  let cbCluster = cbResult.diffClusters[0];
-  if (!cbCluster.accessibilityMetadata) {
-    throw new Error(
-      'Test failed: Expected accessibilityMetadata to be present when checkColorBlindness is enabled'
-    );
-  }
-
-  let cbMeta = cbCluster.accessibilityMetadata;
-
-  // Validate colorBlindnessImpact is present
-  if (!cbMeta.colorBlindnessImpact) {
-    throw new Error(
-      'Test failed: Expected colorBlindnessImpact to be present when checkColorBlindness is enabled'
-    );
-  }
-
-  let impact = cbMeta.colorBlindnessImpact;
-
-  // Validate boolean flags
-  if (typeof impact.deuteranopiaVisible !== 'boolean') {
-    throw new Error('Test failed: deuteranopiaVisible should be a boolean');
-  }
-  if (typeof impact.protanopiaVisible !== 'boolean') {
-    throw new Error('Test failed: protanopiaVisible should be a boolean');
-  }
-  if (typeof impact.tritanopiaVisible !== 'boolean') {
-    throw new Error('Test failed: tritanopiaVisible should be a boolean');
-  }
-  if (typeof impact.achromatopsiaVisible !== 'boolean') {
-    throw new Error('Test failed: achromatopsiaVisible should be a boolean');
-  }
-
-  // Validate visibility score (0.0-1.0 range)
-  if (impact.visibilityScore < 0 || impact.visibilityScore > 1) {
-    throw new Error('Test failed: visibilityScore should be between 0 and 1');
   }
 
-  console.log(`  Visibility score: ${(impact.visibilityScore * 100).toFixed(0)}%`);
-  console.log(`  Deuteranopia visible: ${impact.deuteranopiaVisible}`);
-  console.log(`  Protanopia visible: ${impact.protanopiaVisible}`);
-  console.log(`  Tritanopia visible: ${impact.tritanopiaVisible}`);
-  console.log(`  Achromatopsia visible: ${impact.achromatopsiaVisible}`);
-  console.log('  All color blindness tests passed!');
-  console.log();
-
-  // Example 9: Test checkColorBlindness automatically enables includeAccessibilityData
-  console.log('9. Auto-enable test (checkColorBlindness enables includeAccessibilityData):');
-  let autoEnableResult = await honeydiff.compare(
-    '../../tests/fixtures/screenshots/vizzly-baseline.png',
-    '../../tests/fixtures/screenshots/vizzly-with-diff.png',
-    {
-      includeClusters: true,
-      checkColorBlindness: true,
-      // Note: NOT explicitly setting includeAccessibilityData
-    }
-  );
-
-  if (!autoEnableResult.diffClusters || autoEnableResult.diffClusters.length === 0) {
-    throw new Error('Test failed: Expected diff clusters to be present');
-  }
-
-  let autoCluster = autoEnableResult.diffClusters[0];
-  if (!autoCluster.accessibilityMetadata) {
-    throw new Error(
-      'Test failed: checkColorBlindness should automatically enable accessibilityMetadata'
-    );
-  }
-
-  // Should have both accessibility data and color blindness impact
-  if (!autoCluster.accessibilityMetadata.colorBlindnessImpact) {
-    throw new Error(
-      'Test failed: Expected colorBlindnessImpact when checkColorBlindness is enabled'
-    );
-  }
-
-  console.log('  Accessibility metadata auto-enabled: Yes');
-  console.log('  Color blindness data present: Yes');
-  console.log('  Auto-enable test passed!');
-  console.log();
-
-  // Example 10: Test accessibility data is null when not requested
-  console.log('10. Null handling test (accessibility data absent when not requested):');
-  let noAccessibilityResult = await honeydiff.compare(
-    '../../tests/fixtures/screenshots/vizzly-baseline.png',
-    '../../tests/fixtures/screenshots/vizzly-with-diff.png',
-    {
-      includeClusters: true,
-      // Note: NOT setting includeAccessibilityData or checkColorBlindness
-    }
-  );
-
-  if (!noAccessibilityResult.diffClusters || noAccessibilityResult.diffClusters.length === 0) {
-    throw new Error('Test failed: Expected diff clusters to be present');
-  }
-
-  let noAccessCluster = noAccessibilityResult.diffClusters[0];
-  if (noAccessCluster.accessibilityMetadata !== null) {
-    throw new Error('Test failed: accessibilityMetadata should be null when not requested');
-  }
-
-  console.log('  Accessibility metadata: null (as expected)');
-  console.log('  Null handling test passed!');
-  console.log();
+  console.log('\n3. Synchronous comparison');
+  let syncResult = honeydiff.compareSync(baseline, current, {
+    threshold: 2,
+    includeClusters: true,
+  });
+  console.log(`  Diff percentage: ${syncResult.diffPercentage.toFixed(2)}%`);
 
-  console.log('=== All accessibility binding tests passed! ===\n');
+  console.log('\n4. Image dimensions');
+  let dimensions = await honeydiff.getDimensions(baseline);
+  console.log(`  Dimensions: ${dimensions.width}x${dimensions.height}`);
+
+  console.log('\n5. Diff artifacts');
+  let artifactResult = await honeydiff.compare(baseline, current, {
+    threshold: 0,
+    diffPath: '/tmp/honeydiff-diff.png',
+    maskPath: '/tmp/honeydiff-mask.png',
+    overlayPath: '/tmp/honeydiff-side-by-side.png',
+    overwrite: true,
+  });
+  console.log(`  Artifact diff percentage: ${artifactResult.diffPercentage.toFixed(2)}%`);
+  console.log('  Artifacts saved to /tmp/honeydiff-*.png');
 }
 
 main().catch((err) => {

package/examples/buffers.js

@@ -16,7 +16,7 @@ async function main() {
 
   // Compare using buffers
   let result = await honeydiff.compare(img1Buffer, img2Buffer, {
-    pixelTolerance: 0,
+    threshold: 0,
     includeSSIM: true,
   });
 

package/examples/typescript.ts

@@ -16,7 +16,7 @@ async function main(): Promise<void> {
 
   // Detailed comparison with full typing
   let options: CompareOptions = {
-    pixelTolerance: 5,
+    threshold: 2,
     antialiasing: true,
     includeSSIM: true,
     includeClusters: true,

package/examples/wcag.js

@@ -7,7 +7,7 @@
 
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { analyzeWcagContrast, saveWcagOverlay } from '../index.js';
+import { analyzeWcagContrast, analyzeWcagContrastSync, saveWcagOverlay } from '../index.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -102,8 +102,6 @@ async function main() {
   // Example 4: Synchronous API (for simple scripts)
   console.log('4. Using synchronous API...');
   try {
-    const { analyzeWcagContrastSync } = require('../index.js');
-
     let analysis = analyzeWcagContrastSync(
       path.join(__dirname, '../../../tests/fixtures/screenshots/vizzly-baseline.png'),
       {

package/index.d.ts

@@ -187,7 +187,6 @@ export interface CompareOptions {
 
   /**
    * Include clustered groups of connected differing pixels
-   * Automatically enables includeDiffPixels if not already enabled
    * Clusters are sorted by size (largest first)
    * @default false
    */
@@ -316,6 +315,8 @@ export type ImageInput = string | Buffer;
 
 /**
  * Compare two images asynchronously (recommended)
+ * For large screenshots, prefer file path inputs. Buffer inputs are copied
+ * before native worker processing begins.
  *
  * @param img1 - First image (file path or Buffer)
  * @param img2 - Second image (file path or Buffer)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/honeydiff",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "description": "High-performance image diffing for Node.js - Native bindings to Honeydiff Rust library",
   "type": "module",
   "main": "index.js",
@@ -28,7 +28,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/vizzly-testing/honeydiff"
+    "url": "https://github.com/vizzly-testing/r-honeydiff"
   },
   "keywords": [
     "image",