@vizzly-testing/honeydiff 0.1.0 → 0.2.0

package/README.md

@@ -10,6 +10,7 @@ validation, and detecting visual changes.
 **Why Honeydiff?**
 - **Fast:** Native performance processing 230M+ pixels/sec
 - **Smart:** Intelligent anti-aliasing detection filters rendering artifacts
+- **Accessible:** Built-in WCAG contrast checking and color blindness simulation
 - **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
@@ -68,10 +69,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`
 
@@ -90,6 +93,9 @@ interface CompareOptions {
   includeDiffPixels?: boolean;    // Detailed pixel list (default: false)
   includeClusters?: boolean;      // Spatial clusters (default: false)
   includeSSIM?: boolean;          // SSIM score (default: false)
+  includeAccessibilityData?: boolean;  // RGB, luminance, WCAG (default: false)
+  checkColorBlindness?: boolean;  // Color blindness simulation (default: false)
+  colorBlindnessThreshold?: number;  // Visibility threshold 0-255 (default: 30)
   diffPath?: string;              // Save diff image
   maskPath?: string;              // Save mask image
   overlayPath?: string;           // Save overlay image
@@ -121,6 +127,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');
@@ -174,6 +198,53 @@ if (result.intensityStats) {
 // Output: Range: 12-255, Mean: 87.3
 ```
 
+**Accessibility Features**
+
+```javascript
+// WCAG contrast checking and RGB analysis
+let result = await compare('baseline.png', 'current.png', {
+  includeClusters: true,
+  includeAccessibilityData: true
+});
+
+if (result.diffClusters) {
+  result.diffClusters.forEach(cluster => {
+    if (cluster.accessibilityMetadata) {
+      let meta = cluster.accessibilityMetadata;
+      console.log(`RGB diffs: R=${meta.avgRDiff}, G=${meta.avgGDiff}, B=${meta.avgBDiff}`);
+      console.log(`Dominant channel: ${meta.dominantChannel}`);
+      console.log(`WCAG contrast: ${meta.contrastRatio.toFixed(2)}:1`);
+
+      if (meta.contrastRatio < 4.5) {
+        console.log('⚠️  Below WCAG AA threshold');
+      }
+    }
+  });
+}
+
+// Color blindness simulation
+let result = await compare('baseline.png', 'current.png', {
+  includeClusters: true,
+  checkColorBlindness: true
+});
+
+if (result.diffClusters) {
+  result.diffClusters.forEach(cluster => {
+    if (cluster.accessibilityMetadata?.colorBlindnessImpact) {
+      let impact = cluster.accessibilityMetadata.colorBlindnessImpact;
+      console.log(`Visibility score: ${(impact.visibilityScore * 100).toFixed(0)}%`);
+      console.log(`Deuteranopia (red-green): ${impact.deuteranopiaVisible ? '✓' : '✗'}`);
+      console.log(`Protanopia (red-weak): ${impact.protanopiaVisible ? '✓' : '✗'}`);
+      console.log(`Tritanopia (blue-yellow): ${impact.tritanopiaVisible ? '✓' : '✗'}`);
+
+      if (impact.visibilityScore < 0.5) {
+        console.log('⚠️  May not be visible to colorblind users');
+      }
+    }
+  });
+}
+```
+
 **Complete Result Example**
 ```javascript
 let result = await compare('baseline.png', 'current.png', {
@@ -234,6 +305,7 @@ console.log(JSON.stringify(result, null, 2));
 
 - **Visual Regression Testing:** Detect unintended UI changes in your test suite
 - **Screenshot Validation:** Compare generated screenshots against baselines
+- **Accessibility Testing:** Validate WCAG contrast ratios and color blindness visibility
 - **Design QA:** Validate UI implementations match designs
 - **Cross-browser Testing:** Detect rendering differences across browsers
 - **Scrollable Content:** Compare full-page screenshots with variable heights
@@ -253,6 +325,13 @@ Tested on real-world tall screenshots (750 x 24,162 pixels = 18.3M pixels):
 
 ## Advanced Features
 
+**Accessibility Testing**
+- **RGB Channel Analysis:** Track which color channels changed (R/G/B)
+- **Luminance Tracking:** Measure perceived brightness using sRGB relative luminance
+- **WCAG Contrast Ratios:** Validate contrast meets AA (4.5:1) and AAA (7:1) standards
+- **Color Blindness Simulation:** Test visibility for deuteranopia, protanopia, tritanopia, and achromatopsia
+- **Visibility Scoring:** 0-100% score indicating how visible changes are to colorblind users
+
 **Variable Height Screenshots**
 Compare scrollable content with different heights. Overlapping regions are compared pixel-by-pixel,
 extra rows counted as differences.

package/index.d.ts

@@ -49,6 +49,42 @@ export interface IntensityStats {
   stdDev: number;
 }
 
+export interface ColorBlindnessImpact {
+  /** Whether the difference is visible to people with deuteranopia (red-green color blindness) */
+  deuteranopiaVisible: boolean;
+  /** Whether the difference is visible to people with protanopia (red-weak color blindness) */
+  protanopiaVisible: boolean;
+  /** Whether the difference is visible to people with tritanopia (blue-yellow color blindness) */
+  tritanopiaVisible: boolean;
+  /** Whether the difference is visible to people with achromatopsia (complete color blindness) */
+  achromatopsiaVisible: boolean;
+  /** Overall visibility score (0.0-1.0, higher = more visible) */
+  visibilityScore: number;
+}
+
+export interface AccessibilityMetadata {
+  /** Average difference in red channel (0-255) */
+  avgRDiff: number;
+  /** Average difference in green channel (0-255) */
+  avgGDiff: number;
+  /** Average difference in blue channel (0-255) */
+  avgBDiff: number;
+  /** Dominant color channel ('R', 'G', or 'B') */
+  dominantChannel: string;
+  /** Average relative luminance of baseline pixels (0.0-1.0, sRGB) */
+  avgBaselineLuminance: number;
+  /** Average relative luminance of current pixels (0.0-1.0, sRGB) */
+  avgCurrentLuminance: number;
+  /** WCAG contrast ratio between average colors (1.0-21.0, values below 4.5 may fail WCAG AA) */
+  contrastRatio: number;
+  /** Minimum WCAG contrast ratio in this cluster (worst case) */
+  minContrastRatio: number;
+  /** Maximum WCAG contrast ratio in this cluster (best case) */
+  maxContrastRatio: number;
+  /** Color blindness visibility analysis (null unless checkColorBlindness is enabled) */
+  colorBlindnessImpact: ColorBlindnessImpact | null;
+}
+
 export interface DiffCluster {
   /** Number of pixels in this cluster */
   pixelCount: number;
@@ -58,6 +94,8 @@ export interface DiffCluster {
   avgIntensity: number;
   /** Bounding box containing this cluster */
   boundingBox: BoundingBox;
+  /** Accessibility metadata (null unless includeAccessibilityData is enabled) */
+  accessibilityMetadata: AccessibilityMetadata | null;
 }
 
 export interface DiffResult {
@@ -170,6 +208,28 @@ export interface CompareOptions {
    * @default false
    */
   overwrite?: boolean;
+
+  /**
+   * Include accessibility metadata (RGB channels, luminance, WCAG contrast)
+   * When enabled, each cluster will include detailed color and brightness analysis
+   * @default false
+   */
+  includeAccessibilityData?: boolean;
+
+  /**
+   * Check if differences are visible to color blind users
+   * Automatically enables includeAccessibilityData if not already enabled
+   * Tests visibility for deuteranopia, protanopia, tritanopia, and achromatopsia
+   * @default false
+   */
+  checkColorBlindness?: boolean;
+
+  /**
+   * Threshold for color blindness visibility detection (0-255)
+   * Differences below this threshold after color blindness simulation are considered invisible
+   * @default 30.0
+   */
+  colorBlindnessThreshold?: number;
 }
 
 // ============================================================================
@@ -274,3 +334,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.1.0",
+  "version": "0.2.0",
   "description": "High-performance image diffing for Node.js - Native bindings to Honeydiff Rust library",
   "main": "index.js",
   "types": "index.d.ts",
@@ -55,6 +55,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": {