@vizzly-testing/honeydiff 0.3.1 → 0.4.0

package/README.md

@@ -257,7 +257,7 @@ let dims = await getDimensions(buffer);
 
 ## Accessibility Features
 
-Built-in WCAG color contrast analysis to catch accessibility violations in screenshots and UI designs.
+Built-in WCAG color contrast analysis and color blindness simulation to catch accessibility violations in screenshots and UI designs.
 
 ### WCAG Contrast Analysis
 
@@ -308,6 +308,92 @@ let analysis = await analyzeWcagContrast('screenshot.png', {
 console.log(`AA pass rate: ${analysis.aaNormalPassPercentage.toFixed(1)}%`);
 ```
 
+### Color Blindness Simulation
+
+Simulate how your UI appears to users with color vision deficiencies. Uses the scientifically accurate Brettel, Viénot & Mollon 1997 algorithm.
+
+**Supported CVD types:**
+- `protanopia` - Red-blind (~1% of males)
+- `deuteranopia` - Green-blind (~1% of males, most common)
+- `tritanopia` - Blue-blind (~0.003% of population)
+- `achromatopsia` - Complete color blindness (grayscale only)
+
+```javascript
+const {
+  simulateColorBlindness,
+  saveColorBlindnessSimulation,
+  saveAllColorBlindnessSimulations,
+  getColorBlindnessTypes
+} = require('@vizzly-testing/honeydiff');
+
+// Get CVD type information
+let types = getColorBlindnessTypes();
+types.forEach(cvd => {
+  console.log(`${cvd.name}: ${cvd.description} (${cvd.prevalence})`);
+});
+
+// Simulate and get buffer (useful for in-memory operations)
+let simulated = await simulateColorBlindness('chart.png', 'deuteranopia');
+fs.writeFileSync('chart-deuteranopia.png', simulated);
+
+// Or save directly to file
+await saveColorBlindnessSimulation('ui.png', 'protanopia', 'ui-protanopia.png');
+
+// Generate all simulations at once
+// Creates: dashboard_protanopia.png, dashboard_deuteranopia.png,
+//          dashboard_tritanopia.png, dashboard_achromatopsia.png
+await saveAllColorBlindnessSimulations('dashboard.png', 'dashboard', 'png');
+```
+
+### CVD-Aware WCAG Analysis
+
+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');
+
+// Analyze for a specific CVD type
+let analysis = await analyzeWcagForCvd('ui.png', 'deuteranopia', {
+  checkAA: true,
+  checkAAA: false
+});
+
+if (analysis.violations.length > 0) {
+  console.log(`Found ${analysis.violations.length} contrast issues for red-green colorblind users`);
+}
+
+// Comprehensive report for all CVD types
+let report = await analyzeWcagAllCvd('dashboard.png', {
+  checkAA: true,
+  checkAAA: true
+});
+
+console.log('Accessibility Report:');
+console.log(`Normal vision:  ${report.normalVision.violations.length} violations`);
+console.log(`Protanopia:     ${report.protanopia.violations.length} violations`);
+console.log(`Deuteranopia:   ${report.deuteranopia.violations.length} violations`);
+console.log(`Tritanopia:     ${report.tritanopia.violations.length} violations`);
+console.log(`Total: ${report.totalViolations} violations`);
+console.log(`CVD-only issues: ~${report.cvdOnlyViolationCount}`);
+
+if (report.hasAnyViolations) {
+  console.log('Accessibility issues detected!');
+}
+```
+
+**Test integration:**
+```javascript
+test('UI colors work for colorblind users', async () => {
+  let screenshot = await page.screenshot();
+
+  // Comprehensive CVD accessibility check
+  let report = await analyzeWcagAllCvd(screenshot, { checkAA: true });
+
+  expect(report.hasAnyViolations).toBe(false);
+  expect(report.deuteranopia.aaNormalPassPercentage).toBeGreaterThan(95);
+});
+```
+
 ## Complete API Reference
 
 ### Async Functions (Recommended)
@@ -507,10 +593,11 @@ if (result.diffPercentage > 5.0) {
 ## Examples
 
 See [examples/](./examples/) directory:
-- [basic.js](./examples/basic.js) - Core features and accessibility
+- [basic.js](./examples/basic.js) - Core features and comparison options
 - [buffers.js](./examples/buffers.js) - Working with in-memory images
 - [typescript.ts](./examples/typescript.ts) - TypeScript integration
-- [accessibility.js](./examples/accessibility.js) - WCAG and color blindness
+- [wcag.js](./examples/wcag.js) - WCAG contrast analysis
+- [color-blindness.js](./examples/color-blindness.js) - CVD simulation and accessibility
 
 ## License
 

package/index.d.ts

@@ -222,10 +222,7 @@ export function compare(
  * }
  * ```
  */
-export function quickCompare(
-  img1: ImageInput,
-  img2: ImageInput
-): Promise<boolean>;
+export function quickCompare(img1: ImageInput, img2: ImageInput): Promise<boolean>;
 
 /**
  * Compare two images synchronously (blocks event loop)
@@ -270,10 +267,7 @@ export function compareSync(
  * }
  * ```
  */
-export function quickCompareSync(
-  img1: ImageInput,
-  img2: ImageInput
-): boolean;
+export function quickCompareSync(img1: ImageInput, img2: ImageInput): boolean;
 
 // ============================================================================
 // Dimensions API
@@ -478,10 +472,7 @@ export interface WcagAnalysis {
  * }
  * ```
  */
-export function analyzeWcagContrast(
-  img: ImageInput,
-  options?: WcagOptions
-): Promise<WcagAnalysis>;
+export function analyzeWcagContrast(img: ImageInput, options?: WcagOptions): Promise<WcagAnalysis>;
 
 /**
  * Analyze WCAG color contrast accessibility synchronously (blocks event loop)
@@ -504,10 +495,7 @@ export function analyzeWcagContrast(
  * }
  * ```
  */
-export function analyzeWcagContrastSync(
-  img: ImageInput,
-  options?: WcagOptions
-): WcagAnalysis;
+export function analyzeWcagContrastSync(img: ImageInput, options?: WcagOptions): WcagAnalysis;
 
 /**
  * Options for saving WCAG overlay images
@@ -582,3 +570,353 @@ export function saveWcagOverlaySync(
   outputPath: string,
   options?: WcagOutputOptions
 ): void;
+
+// ============================================================================
+// Color Vision Deficiency (CVD) Simulation API
+// ============================================================================
+
+/**
+ * Types of color vision deficiency (color blindness) that can be simulated.
+ *
+ * - `protanopia` - Red-blind (~1% of males). Reds appear dark/muddy, red-green confusion.
+ * - `deuteranopia` - Green-blind (~1% of males, most common). Greens shift toward red/brown.
+ * - `tritanopia` - Blue-blind (~0.003% of population). Blues appear greenish, yellow-purple confusion.
+ * - `achromatopsia` - Complete color blindness (very rare). Only luminance is perceived.
+ *
+ * Short aliases are also accepted: `protan`, `deutan`, `tritan`, `achroma`, `monochromacy`
+ */
+export type ColorBlindnessType =
+  | 'protanopia'
+  | 'deuteranopia'
+  | 'tritanopia'
+  | 'achromatopsia'
+  | 'protan'
+  | 'deutan'
+  | 'tritan'
+  | 'achroma'
+  | 'monochromacy';
+
+/**
+ * Information about a color blindness type
+ */
+export interface ColorBlindnessTypeInfo {
+  /** The canonical type identifier (e.g., "protanopia") */
+  type: string;
+  /** Human-readable name (e.g., "Protanopia") */
+  name: string;
+  /** Description of what colors are affected */
+  description: string;
+  /** Approximate prevalence in the population */
+  prevalence: string;
+}
+
+/**
+ * Comprehensive WCAG analysis report for all color vision deficiency types.
+ *
+ * Contains WCAG contrast analysis for normal vision and all three main types
+ * of dichromatic color blindness (protanopia, deuteranopia, tritanopia).
+ */
+export interface CvdWcagReport {
+  /** WCAG analysis for normal (typical) color vision */
+  normalVision: WcagAnalysis;
+
+  /** WCAG analysis simulating protanopia (red-blind) */
+  protanopia: WcagAnalysis;
+
+  /** WCAG analysis simulating deuteranopia (green-blind) */
+  deuteranopia: WcagAnalysis;
+
+  /** WCAG analysis simulating tritanopia (blue-blind) */
+  tritanopia: WcagAnalysis;
+
+  /** Whether any CVD type has violations */
+  hasAnyViolations: boolean;
+
+  /** Total number of violations across all CVD types */
+  totalViolations: number;
+
+  /**
+   * Estimated count of violations unique to colorblind users.
+   * These are violations present in CVD analysis but not in normal vision.
+   */
+  cvdOnlyViolationCount: number;
+}
+
+/**
+ * Simulate color blindness for an image asynchronously (recommended)
+ *
+ * Transforms the input image to show how it appears to someone with the
+ * specified type of color vision deficiency. Uses the Brettel, Viénot & Mollon
+ * 1997 algorithm, which is considered the gold standard for CVD simulation.
+ *
+ * @param img - Image to transform (file path or Buffer)
+ * @param cvdType - Type of color blindness to simulate
+ * @returns Promise resolving to a Buffer containing the simulated PNG image
+ *
+ * @example
+ * ```typescript
+ * import { simulateColorBlindness } from '@vizzly-testing/honeydiff';
+ * import fs from 'fs';
+ *
+ * // Simulate how an image appears to someone with red-green color blindness
+ * const simulated = await simulateColorBlindness('chart.png', 'deuteranopia');
+ *
+ * // Save the result
+ * fs.writeFileSync('chart-deuteranopia.png', simulated);
+ *
+ * // Or use directly with image comparison
+ * const result = await compare('chart.png', simulated);
+ * ```
+ */
+export function simulateColorBlindness(
+  img: ImageInput,
+  cvdType: ColorBlindnessType
+): Promise<Buffer>;
+
+/**
+ * Simulate color blindness for an image synchronously (blocks event loop)
+ *
+ * Use this only when you need blocking behavior.
+ * For most cases, prefer the async simulateColorBlindness() function.
+ *
+ * @param img - Image to transform (file path or Buffer)
+ * @param cvdType - Type of color blindness to simulate
+ * @returns Buffer containing the simulated PNG image
+ *
+ * @example
+ * ```typescript
+ * const simulated = simulateColorBlindnessSync('button.png', 'protanopia');
+ * fs.writeFileSync('button-protanopia.png', simulated);
+ * ```
+ */
+export function simulateColorBlindnessSync(img: ImageInput, cvdType: ColorBlindnessType): Buffer;
+
+/**
+ * Simulate and save color blindness image to file asynchronously (recommended)
+ *
+ * Convenience function that simulates CVD and saves the output in one step.
+ *
+ * @param img - Image to transform (file path or Buffer)
+ * @param cvdType - Type of color blindness to simulate
+ * @param outputPath - Path where the simulated image should be saved
+ * @returns Promise that resolves when the file is saved
+ *
+ * @example
+ * ```typescript
+ * // Save a single simulation
+ * await saveColorBlindnessSimulation('ui.png', 'deuteranopia', 'ui-deutan.png');
+ *
+ * // Generate simulations for all types you care about
+ * for (const type of ['protanopia', 'deuteranopia', 'tritanopia']) {
+ *   await saveColorBlindnessSimulation('ui.png', type, `ui-${type}.png`);
+ * }
+ * ```
+ */
+export function saveColorBlindnessSimulation(
+  img: ImageInput,
+  cvdType: ColorBlindnessType,
+  outputPath: string
+): Promise<void>;
+
+/**
+ * Simulate and save color blindness image to file synchronously (blocks event loop)
+ *
+ * Use this only when you need blocking behavior.
+ *
+ * @param img - Image to transform (file path or Buffer)
+ * @param cvdType - Type of color blindness to simulate
+ * @param outputPath - Path where the simulated image should be saved
+ *
+ * @example
+ * ```typescript
+ * saveColorBlindnessSimulationSync('chart.png', 'tritanopia', 'chart-tritan.png');
+ * ```
+ */
+export function saveColorBlindnessSimulationSync(
+  img: ImageInput,
+  cvdType: ColorBlindnessType,
+  outputPath: string
+): void;
+
+/**
+ * Generate and save all CVD simulations to files asynchronously (recommended)
+ *
+ * Generates simulated images for all CVD types (protanopia, deuteranopia,
+ * tritanopia, achromatopsia), saving each with a suffix indicating the type.
+ *
+ * @param img - Image to transform (file path or Buffer)
+ * @param outputPrefix - Base path for output files (without extension)
+ * @param extension - File extension to use (default: "png")
+ * @returns Promise that resolves when all files are saved
+ *
+ * @example
+ * ```typescript
+ * // Creates: dashboard_protanopia.png, dashboard_deuteranopia.png,
+ * //          dashboard_tritanopia.png, dashboard_achromatopsia.png
+ * await saveAllColorBlindnessSimulations('dashboard.png', 'dashboard', 'png');
+ *
+ * // With different extension
+ * await saveAllColorBlindnessSimulations('ui.png', './artifacts/ui', 'jpg');
+ * ```
+ */
+export function saveAllColorBlindnessSimulations(
+  img: ImageInput,
+  outputPrefix: string,
+  extension?: string
+): Promise<void>;
+
+/**
+ * Generate and save all CVD simulations to files synchronously (blocks event loop)
+ *
+ * Use this only when you need blocking behavior.
+ *
+ * @param img - Image to transform (file path or Buffer)
+ * @param outputPrefix - Base path for output files (without extension)
+ * @param extension - File extension to use (default: "png")
+ *
+ * @example
+ * ```typescript
+ * saveAllColorBlindnessSimulationsSync('button.png', 'button');
+ * ```
+ */
+export function saveAllColorBlindnessSimulationsSync(
+  img: ImageInput,
+  outputPrefix: string,
+  extension?: string
+): void;
+
+/**
+ * Analyze WCAG contrast for a specific color blindness type asynchronously (recommended)
+ *
+ * Simulates the image as seen by someone with the specified color vision
+ * deficiency, then runs WCAG contrast analysis. This finds contrast violations
+ * that only appear for colorblind users - critical for inclusive design.
+ *
+ * @param img - Image to analyze (file path or Buffer)
+ * @param cvdType - Type of color blindness to simulate
+ * @param options - WCAG analysis options
+ * @returns Promise resolving to WCAG analysis results for the simulated image
+ *
+ * @example
+ * ```typescript
+ * // Check if colors are distinguishable for deuteranopia users
+ * const analysis = await analyzeWcagForCvd('ui.png', 'deuteranopia', {
+ *   checkAA: true,
+ *   checkAAA: false
+ * });
+ *
+ * if (analysis.violations.length > 0) {
+ *   console.log(`Found ${analysis.violations.length} contrast issues`);
+ *   console.log('for users with red-green color blindness');
+ * }
+ * ```
+ */
+export function analyzeWcagForCvd(
+  img: ImageInput,
+  cvdType: ColorBlindnessType,
+  options?: WcagOptions
+): Promise<WcagAnalysis>;
+
+/**
+ * Analyze WCAG contrast for a specific color blindness type synchronously (blocks event loop)
+ *
+ * Use this only when you need blocking behavior.
+ *
+ * @param img - Image to analyze (file path or Buffer)
+ * @param cvdType - Type of color blindness to simulate
+ * @param options - WCAG analysis options
+ * @returns WCAG analysis results for the simulated image
+ *
+ * @example
+ * ```typescript
+ * const analysis = analyzeWcagForCvdSync('chart.png', 'protanopia');
+ * console.log(`Pass rate: ${analysis.aaNormalPassPercentage.toFixed(1)}%`);
+ * ```
+ */
+export function analyzeWcagForCvdSync(
+  img: ImageInput,
+  cvdType: ColorBlindnessType,
+  options?: WcagOptions
+): WcagAnalysis;
+
+/**
+ * Analyze WCAG contrast for all CVD types asynchronously (recommended)
+ *
+ * Runs WCAG contrast analysis for normal vision and all three main types of
+ * dichromatic color blindness. This provides a comprehensive accessibility
+ * report covering the majority of color vision deficiencies.
+ *
+ * @param img - Image to analyze (file path or Buffer)
+ * @param options - WCAG analysis options (same options used for all analyses)
+ * @returns Promise resolving to a report containing WCAG analysis for each vision type
+ *
+ * @example
+ * ```typescript
+ * const report = await analyzeWcagAllCvd('dashboard.png', {
+ *   checkAA: true,
+ *   checkAAA: true
+ * });
+ *
+ * console.log('Accessibility Report:');
+ * console.log(`Normal vision violations: ${report.normalVision.violations.length}`);
+ * console.log(`Protanopia violations: ${report.protanopia.violations.length}`);
+ * console.log(`Deuteranopia violations: ${report.deuteranopia.violations.length}`);
+ * console.log(`Tritanopia violations: ${report.tritanopia.violations.length}`);
+ *
+ * if (report.hasAnyViolations) {
+ *   console.log(`\nTotal issues found: ${report.totalViolations}`);
+ *   console.log(`Issues only affecting colorblind users: ~${report.cvdOnlyViolationCount}`);
+ * }
+ * ```
+ */
+export function analyzeWcagAllCvd(img: ImageInput, options?: WcagOptions): Promise<CvdWcagReport>;
+
+/**
+ * Analyze WCAG contrast for all CVD types synchronously (blocks event loop)
+ *
+ * Use this only when you need blocking behavior.
+ *
+ * @param img - Image to analyze (file path or Buffer)
+ * @param options - WCAG analysis options
+ * @returns Report containing WCAG analysis for each vision type
+ *
+ * @example
+ * ```typescript
+ * const report = analyzeWcagAllCvdSync('ui.png');
+ *
+ * if (report.hasAnyViolations) {
+ *   console.log('Accessibility issues detected!');
+ * }
+ * ```
+ */
+export function analyzeWcagAllCvdSync(img: ImageInput, options?: WcagOptions): CvdWcagReport;
+
+/**
+ * Get metadata about all supported color blindness types
+ *
+ * Returns information about each CVD type including name, description,
+ * and prevalence. Useful for building UI selectors or generating reports.
+ *
+ * @returns Array of color blindness type information
+ *
+ * @example
+ * ```typescript
+ * const types = getColorBlindnessTypes();
+ *
+ * for (const cvd of types) {
+ *   console.log(`${cvd.name} (${cvd.type})`);
+ *   console.log(`  ${cvd.description}`);
+ *   console.log(`  Affects: ${cvd.prevalence}`);
+ * }
+ *
+ * // Output:
+ * // Protanopia (protanopia)
+ * //   Red-blind: reds appear dark, red-green confusion
+ * //   Affects: ~1% of males
+ * // Deuteranopia (deuteranopia)
+ * //   Green-blind: greens shift to brown, red-green confusion
+ * //   Affects: ~1% of males
+ * // ...
+ * ```
+ */
+export function getColorBlindnessTypes(): ColorBlindnessTypeInfo[];

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@vizzly-testing/honeydiff",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "High-performance image diffing for Node.js - Native bindings to Honeydiff Rust library",
+  "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
   "neon": {
@@ -15,7 +16,14 @@
   "scripts": {
     "build": "cargo build --release",
     "build-debug": "cargo build",
-    "test": "node examples/basic.js",
+    "test": "node --test --experimental-strip-types tests/*.test.ts",
+    "test:types": "tsc --noEmit",
+    "test:examples": "node examples/basic.js",
+    "check": "biome check .",
+    "check:fix": "biome check --write .",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
     "clean": "cargo clean && rm -f index.node"
   },
   "repository": {
@@ -40,39 +48,6 @@
     "index.js",
     "index.d.ts",
     "index.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",
-    "index.js",
-    "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",
-    "index.js",
-    "index.d.ts",
-    "load-platform.js",
-    "platforms/*.node",
-    "README.md",
-    "index.js",
-    "index.d.ts",
     "load-platform.js",
     "platforms/*.node",
     "README.md",
@@ -84,5 +59,10 @@
   ],
   "engines": {
     "node": ">=22.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.8",
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3"
   }
 }