@vizzly-testing/honeydiff 0.2.1 → 0.3.0

package/README.md

@@ -16,7 +16,7 @@ Requires Node.js 22+. Pre-built binaries included for macOS (ARM64), Linux (x64/
 
 - **6x faster than odiff** - Processes 230M+ pixels/sec with multi-core parallelization
 - **Smart anti-aliasing** - Filters out rendering artifacts, not actual changes
-- **Accessibility built-in** - WCAG contrast checking and color blindness simulation
+- **Accessibility built-in** - WCAG contrast analysis for catching accessibility violations
 - **Flexible inputs** - Works with file paths or Buffers
 - **Full TypeScript support** - Complete type definitions included
 - **Advanced analytics** - SSIM perceptual scoring, spatial clustering, intensity stats
@@ -257,116 +257,55 @@ let dims = await getDimensions(buffer);
 
 ## Accessibility Features
 
-Built-in accessibility testing to catch WCAG compliance issues and color blindness visibility problems.
+Built-in WCAG color contrast analysis to catch accessibility violations in screenshots and UI designs.
 
-### WCAG Contrast Checking
+### WCAG Contrast Analysis
 
-Validate that visual changes meet WCAG AA/AAA contrast standards.
+Analyze entire images for WCAG color contrast violations - perfect for catching accessibility issues in screenshots and UI designs.
 
 ```javascript
-const result = await compare('baseline.png', 'current.png', {
-  includeClusters: true,
-  includeAccessibilityData: true
+const { analyzeWcagContrast, saveWcagOverlay } = require('@vizzly-testing/honeydiff');
+
+// Analyze a screenshot for accessibility violations
+let analysis = await analyzeWcagContrast('screenshot.png', {
+  edgeThreshold: 60,      // Edge detection sensitivity (0-255)
+  minRegionSize: 50,      // Minimum violation region size (pixels)
+  checkAA: true,          // Check WCAG AA (4.5:1 normal, 3.0:1 large)
+  checkAAA: true          // Check WCAG AAA (7.0:1 normal, 4.5:1 large)
 });
 
-if (result.diffClusters) {
-  result.diffClusters.forEach(cluster => {
-    if (cluster.accessibilityMetadata) {
-      let meta = cluster.accessibilityMetadata;
-
-      console.log(`Contrast ratio: ${meta.contrastRatio.toFixed(2)}:1`);
-      console.log(`Range: ${meta.minContrastRatio.toFixed(2)} - ${meta.maxContrastRatio.toFixed(2)}`);
-
-      // WCAG validation
-      if (meta.minContrastRatio < 4.5) {
-        console.log('⚠️  Below WCAG AA normal text (4.5:1)');
-      }
-      if (meta.minContrastRatio < 3.0) {
-        console.log('⚠️  Below WCAG AA large text (3.0:1)');
-      }
-      if (meta.minContrastRatio >= 7.0) {
-        console.log('✓ Meets WCAG AAA (7.0:1)');
-      }
-    }
-  });
-}
-```
-
-### RGB Channel Analysis
-
-Track which color channels changed - useful for debugging design changes.
-
-```javascript
-const result = await compare('baseline.png', 'current.png', {
-  includeClusters: true,
-  includeAccessibilityData: true
+console.log(`Total edges analyzed: ${analysis.totalEdges}`);
+console.log(`AA normal text pass rate: ${analysis.aaNormalPassPercentage.toFixed(1)}%`);
+console.log(`Found ${analysis.violations.length} violations`);
+
+// Examine violations
+analysis.violations.forEach((violation, i) => {
+  console.log(`\nViolation ${i + 1}:`);
+  console.log(`  Location: (${violation.boundingBox.x}, ${violation.boundingBox.y})`);
+  console.log(`  Contrast ratio: ${violation.contrastRatio.toFixed(2)}:1`);
+  console.log(`  Foreground: rgb(${violation.foregroundColor.slice(0,3).join(', ')})`);
+  console.log(`  Background: rgb(${violation.backgroundColor.slice(0,3).join(', ')})`);
+  console.log(`  Fails AA normal: ${violation.failsAaNormal}`);
+  console.log(`  Fails AAA normal: ${violation.failsAaaNormal}`);
 });
 
-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(`Luminance: baseline=${meta.avgBaselineLuminance.toFixed(3)}, current=${meta.avgCurrentLuminance.toFixed(3)}`);
-    }
-  });
-}
-// Output:
-// RGB diffs: R=45.2, G=12.3, B=8.7
-// Dominant channel: R
-// Luminance: baseline=0.234, current=0.567
-```
-
-### Color Blindness Simulation
-
-Test if visual changes are visible to users with color vision deficiencies.
-
-```javascript
-const result = await compare('baseline.png', 'current.png', {
-  includeClusters: true,
-  checkColorBlindness: true,
-  colorBlindnessThreshold: 30.0  // Sensitivity threshold (0-255)
+// Generate visual overlay showing violations
+await saveWcagOverlay('screenshot.png', analysis, 'violations.png', {
+  highlightColor: [255, 0, 0, 180]  // Semi-transparent red
 });
-
-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, ~1% of population): ${impact.deuteranopiaVisible ? '✓' : '✗'}`);
-      console.log(`Protanopia (red-weak, ~0.5%): ${impact.protanopiaVisible ? '✓' : '✗'}`);
-      console.log(`Tritanopia (blue-yellow, rare): ${impact.tritanopiaVisible ? '✓' : '✗'}`);
-      console.log(`Achromatopsia (grayscale, very rare): ${impact.achromatopsiaVisible ? '✓' : '✗'}`);
-
-      if (impact.visibilityScore < 0.5) {
-        console.log('⚠️  May not be visible to colorblind users');
-      }
-    }
-  });
-}
 ```
 
-**Real-world example:**
-
+**Advanced filtering:**
 ```javascript
-test('button color change is accessible', async () => {
-  let result = await compare('button-baseline.png', 'button-hover.png', {
-    includeClusters: true,
-    checkColorBlindness: true
-  });
-
-  // Ensure button hover is visible to colorblind users
-  let lowestVisibility = Math.min(
-    ...result.diffClusters.map(c =>
-      c.accessibilityMetadata?.colorBlindnessImpact?.visibilityScore ?? 1
-    )
-  );
-
-  expect(lowestVisibility).toBeGreaterThan(0.7);
+let analysis = await analyzeWcagContrast('screenshot.png', {
+  edgeThreshold: 80,           // Higher = fewer false positives
+  minRegionSize: 100,          // Ignore tiny regions
+  maxContrastThreshold: 3.5,   // Only flag severe violations
+  checkAA: true,
+  checkAAA: false
 });
+
+console.log(`AA pass rate: ${analysis.aaNormalPassPercentage.toFixed(1)}%`);
 ```
 
 ## Complete API Reference

package/index.d.ts

@@ -49,42 +49,6 @@ 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;
@@ -94,8 +58,6 @@ 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 {
@@ -208,28 +170,6 @@ 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;
 }
 
 // ============================================================================
@@ -381,3 +321,264 @@ export function getDimensions(img: ImageInput): Promise<ImageDimensions>;
  * ```
  */
 export function getDimensionsSync(img: ImageInput): ImageDimensions;
+
+// ============================================================================
+// WCAG Accessibility API
+// ============================================================================
+
+/**
+ * Options for WCAG color contrast analysis
+ */
+export interface WcagOptions {
+  /**
+   * Edge detection threshold (0-255)
+   * Differences below this threshold are not considered edges
+   * @default 60
+   */
+  edgeThreshold?: number;
+
+  /**
+   * Minimum region size (in pixels)
+   * Regions smaller than this are filtered out to reduce noise
+   * @default 50
+   */
+  minRegionSize?: number;
+
+  /**
+   * Maximum contrast threshold
+   * Regions with contrast above this are excluded (gradient filtering)
+   * @default 3.5
+   */
+  maxContrastThreshold?: number;
+
+  /**
+   * Check WCAG AA compliance (4.5:1 for normal text, 3.0:1 for large text)
+   * @default true
+   */
+  checkAA?: boolean;
+
+  /**
+   * Check WCAG AAA compliance (7.0:1 for normal text, 4.5:1 for large text)
+   * @default false
+   */
+  checkAAA?: boolean;
+}
+
+/**
+ * A single WCAG color contrast violation region
+ */
+export interface ContrastViolation {
+  /** Bounding box containing this violation region */
+  boundingBox: BoundingBox;
+
+  /** List of pixel coordinates [x, y] in this violation */
+  pixels: [number, number][];
+
+  /** Center of mass [x, y] of the violation region */
+  centerOfMass: [number, number];
+
+  /** Number of pixels in this violation */
+  pixelCount: number;
+
+  /** Foreground color [r, g, b, a] (0-255) */
+  foregroundColor: [number, number, number, number];
+
+  /** Background color [r, g, b, a] (0-255) */
+  backgroundColor: [number, number, number, number];
+
+  /** Foreground relative luminance (0.0-1.0, sRGB) */
+  foregroundLuminance: number;
+
+  /** Background relative luminance (0.0-1.0, sRGB) */
+  backgroundLuminance: number;
+
+  /** Average contrast ratio for this region (1.0-21.0) */
+  contrastRatio: number;
+
+  /** Minimum contrast ratio in this region (worst case) */
+  minContrastRatio: number;
+
+  /** Maximum contrast ratio in this region (best case) */
+  maxContrastRatio: number;
+
+  /** Whether this region fails WCAG AA for normal text (< 4.5:1) */
+  failsAaNormal: boolean;
+
+  /** Whether this region fails WCAG AA for large text (< 3.0:1) */
+  failsAaLarge: boolean;
+
+  /** Whether this region fails WCAG AAA for normal text (< 7.0:1) */
+  failsAaaNormal: boolean;
+
+  /** Whether this region fails WCAG AAA for large text (< 4.5:1) */
+  failsAaaLarge: boolean;
+}
+
+/**
+ * Complete WCAG accessibility analysis result
+ */
+export interface WcagAnalysis {
+  /** Total number of edges analyzed */
+  totalEdges: number;
+
+  /** Number of edges passing WCAG AA for normal text */
+  aaNormalPass: number;
+
+  /** Number of edges passing WCAG AA for large text */
+  aaLargePass: number;
+
+  /** Number of edges passing WCAG AAA for normal text */
+  aaaNormalPass: number;
+
+  /** Number of edges passing WCAG AAA for large text */
+  aaaLargePass: number;
+
+  /** List of contrast violations found */
+  violations: ContrastViolation[];
+
+  /** Percentage of edges passing WCAG AA for normal text (0.0-100.0) */
+  aaNormalPassPercentage: number;
+
+  /** Percentage of edges passing WCAG AA for large text (0.0-100.0) */
+  aaLargePassPercentage: number;
+
+  /** Percentage of edges passing WCAG AAA for normal text (0.0-100.0) */
+  aaaNormalPassPercentage: number;
+
+  /** Percentage of edges passing WCAG AAA for large text (0.0-100.0) */
+  aaaLargePassPercentage: number;
+}
+
+/**
+ * Analyze WCAG color contrast accessibility asynchronously (recommended)
+ *
+ * Detects text/content edges in an image and checks if they meet WCAG contrast requirements.
+ * This is useful for catching accessibility issues in screenshots and UI designs.
+ *
+ * @param img - Image to analyze (file path or Buffer)
+ * @param options - WCAG analysis options
+ * @returns Promise resolving to detailed accessibility analysis
+ *
+ * @example
+ * ```typescript
+ * const analysis = await analyzeWcagContrast('screenshot.png', {
+ *   edgeThreshold: 60,
+ *   checkAA: true,
+ *   checkAAA: true
+ * });
+ *
+ * console.log(`Total edges: ${analysis.totalEdges}`);
+ * console.log(`AA pass rate: ${analysis.aaNormalPassPercentage.toFixed(1)}%`);
+ * console.log(`Found ${analysis.violations.length} violations`);
+ *
+ * for (let violation of analysis.violations.slice(0, 5)) {
+ *   console.log(`Region at (${violation.boundingBox.x}, ${violation.boundingBox.y})`);
+ *   console.log(`  Contrast: ${violation.contrastRatio.toFixed(2)}:1`);
+ *   console.log(`  Fails AA: ${violation.failsAaNormal}`);
+ * }
+ * ```
+ */
+export function analyzeWcagContrast(
+  img: ImageInput,
+  options?: WcagOptions
+): Promise<WcagAnalysis>;
+
+/**
+ * Analyze WCAG color contrast accessibility synchronously (blocks event loop)
+ *
+ * Use this only when you need blocking behavior.
+ * For most cases, prefer the async analyzeWcagContrast() function.
+ *
+ * @param img - Image to analyze (file path or Buffer)
+ * @param options - WCAG analysis options
+ * @returns Detailed accessibility analysis
+ *
+ * @example
+ * ```typescript
+ * const analysis = analyzeWcagContrastSync('screenshot.png', {
+ *   minRegionSize: 50
+ * });
+ *
+ * if (analysis.violations.length > 0) {
+ *   console.log('Accessibility issues found!');
+ * }
+ * ```
+ */
+export function analyzeWcagContrastSync(
+  img: ImageInput,
+  options?: WcagOptions
+): WcagAnalysis;
+
+/**
+ * Options for saving WCAG overlay images
+ */
+export interface WcagOutputOptions {
+  /**
+   * Highlight color for violations [r, g, b, a] (0-255)
+   * @default [255, 0, 0, 180] (semi-transparent red)
+   */
+  highlightColor?: [number, number, number, number];
+
+  /**
+   * Whether to overwrite existing output file
+   * @default false
+   */
+  overwrite?: boolean;
+}
+
+/**
+ * Save WCAG violation overlay image asynchronously (recommended)
+ *
+ * Generates an image with contrast violations highlighted in red (or custom color).
+ * Useful for visual debugging of accessibility issues.
+ *
+ * @param img - Original image (file path or Buffer)
+ * @param analysis - WCAG analysis result from analyzeWcagContrast()
+ * @param outputPath - Path to save the overlay image
+ * @param options - Output options
+ * @returns Promise that resolves when the file is saved
+ *
+ * @example
+ * ```typescript
+ * const analysis = await analyzeWcagContrast('screenshot.png');
+ *
+ * await saveWcagOverlay(
+ *   'screenshot.png',
+ *   analysis,
+ *   'violations-overlay.png',
+ *   { highlightColor: [255, 0, 0, 180] }
+ * );
+ *
+ * console.log('Overlay saved to violations-overlay.png');
+ * ```
+ */
+export function saveWcagOverlay(
+  img: ImageInput,
+  analysis: WcagAnalysis,
+  outputPath: string,
+  options?: WcagOutputOptions
+): Promise<void>;
+
+/**
+ * Save WCAG violation overlay image synchronously (blocks event loop)
+ *
+ * Use this only when you need blocking behavior.
+ * For most cases, prefer the async saveWcagOverlay() function.
+ *
+ * @param img - Original image (file path or Buffer)
+ * @param analysis - WCAG analysis result from analyzeWcagContrastSync()
+ * @param outputPath - Path to save the overlay image
+ * @param options - Output options
+ *
+ * @example
+ * ```typescript
+ * const analysis = analyzeWcagContrastSync('screenshot.png');
+ * saveWcagOverlaySync('screenshot.png', analysis, 'violations.png');
+ * ```
+ */
+export function saveWcagOverlaySync(
+  img: ImageInput,
+  analysis: WcagAnalysis,
+  outputPath: string,
+  options?: WcagOutputOptions
+): void;

package/package.json

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