@vizzly-testing/honeydiff 0.10.3 → 0.11.0

package/examples/color-blindness.js

@@ -1,8 +1,8 @@
 /**
  * Color Vision Deficiency (CVD) Simulation Example
  *
- * Demonstrates how to simulate color blindness for images and run
- * accessibility analysis to ensure your UI works for all users.
+ * Demonstrates how to simulate color blindness for images and screen
+ * detected color boundaries with WCAG color-pair thresholds.
  */
 
 import fs from 'node:fs';
@@ -71,8 +71,8 @@ async function main() {
     console.error('   Error:', error.message, '\n');
   }
 
-  // Example 5: WCAG analysis for a specific CVD type
-  console.log('5. Analyzing WCAG contrast for deuteranopia users...');
+  // Example 5: WCAG threshold screening for a specific CVD type
+  console.log('5. Screening WCAG contrast thresholds for deuteranopia users...');
   try {
     let analysis = await analyzeWcagForCvd(testImage, 'deuteranopia', {
       checkAA: true,
@@ -82,10 +82,10 @@ async function main() {
 
     console.log(`   Total edges analyzed: ${analysis.totalEdges}`);
     console.log(`   AA normal text pass rate: ${analysis.aaNormalPassPercentage.toFixed(1)}%`);
-    console.log(`   Violations found: ${analysis.violations.length}`);
+    console.log(`   Warnings found: ${analysis.violations.length}`);
 
     if (analysis.violations.length > 0) {
-      console.log('\n   Top 3 violations:');
+      console.log('\n   Top 3 warnings:');
       for (let i = 0; i < Math.min(3, analysis.violations.length); i++) {
         let v = analysis.violations[i];
         console.log(`   ${i + 1}. Location: (${v.boundingBox.x}, ${v.boundingBox.y})`);
@@ -98,36 +98,36 @@ async function main() {
     console.error('   Error:', error.message, '\n');
   }
 
-  // Example 6: Comprehensive CVD accessibility report
-  console.log('6. Running comprehensive CVD accessibility analysis...');
+  // Example 6: Comprehensive CVD contrast report
+  console.log('6. Running comprehensive CVD contrast screening...');
   try {
     let report = await analyzeWcagAllCvd(testImage, {
       checkAA: true,
       checkAAA: true,
     });
 
-    console.log('\n   Accessibility Report:');
+    console.log('\n   Contrast Screening Report:');
     console.log('   ─────────────────────────────────────────────');
     console.log(
-      `   Normal Vision:  ${report.normalVision.violations.length} violations ` +
+      `   Normal Vision:  ${report.normalVision.violations.length} warnings ` +
         `(${report.normalVision.aaNormalPassPercentage.toFixed(1)}% pass)`
     );
     console.log(
-      `   Protanopia:     ${report.protanopia.violations.length} violations ` +
+      `   Protanopia:     ${report.protanopia.violations.length} warnings ` +
         `(${report.protanopia.aaNormalPassPercentage.toFixed(1)}% pass)`
     );
     console.log(
-      `   Deuteranopia:   ${report.deuteranopia.violations.length} violations ` +
+      `   Deuteranopia:   ${report.deuteranopia.violations.length} warnings ` +
         `(${report.deuteranopia.aaNormalPassPercentage.toFixed(1)}% pass)`
     );
     console.log(
-      `   Tritanopia:     ${report.tritanopia.violations.length} violations ` +
+      `   Tritanopia:     ${report.tritanopia.violations.length} warnings ` +
         `(${report.tritanopia.aaNormalPassPercentage.toFixed(1)}% pass)`
     );
     console.log('   ─────────────────────────────────────────────');
-    console.log(`   Total violations: ${report.totalViolations}`);
-    console.log(`   CVD-only violations: ~${report.cvdOnlyViolationCount}`);
-    console.log(`   Has any violations: ${report.hasAnyViolations}`);
+    console.log(`   Total warnings: ${report.totalViolations}`);
+    console.log(`   CVD-only warnings: ~${report.cvdOnlyViolationCount}`);
+    console.log(`   Has any warnings: ${report.hasAnyViolations}`);
     console.log();
   } catch (error) {
     console.error('   Error:', error.message, '\n');
@@ -157,10 +157,10 @@ async function main() {
    test('UI colors work for colorblind users', async () => {
      let screenshot = await page.screenshot();
 
-     // Check accessibility for all CVD types
+     // Screen contrast for all CVD types
      let report = await analyzeWcagAllCvd(screenshot, { checkAA: true });
 
-     // Assert no violations
+     // Assert no warnings
      expect(report.hasAnyViolations).toBe(false);
 
      // Or check specific CVD types

package/examples/wcag.js

@@ -1,8 +1,8 @@
 /**
- * WCAG Accessibility Testing Example
+ * Screenshot Contrast Screening Example
  *
- * Demonstrates how to analyze images for WCAG color contrast violations
- * and generate visual overlays showing problematic regions.
+ * Demonstrates how to screen screenshots with WCAG color-pair thresholds
+ * and generate visual overlays showing regions worth reviewing.
  */
 
 import path from 'node:path';
@@ -12,10 +12,10 @@ import { analyzeWcagContrast, analyzeWcagContrastSync, saveWcagOverlay } from '.
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 async function main() {
-  console.log('=== WCAG Accessibility Testing Demo ===\n');
+  console.log('=== Screenshot Contrast Screening Demo ===\n');
 
-  // Example 1: Basic WCAG analysis
-  console.log('1. Running basic WCAG AA analysis...');
+  // Example 1: Basic contrast screening
+  console.log('1. Running basic WCAG AA color-pair screening...');
   try {
     let analysis = await analyzeWcagContrast(
       path.join(__dirname, '../../../tests/fixtures/screenshots/vizzly-baseline.png'),
@@ -30,10 +30,10 @@ async function main() {
     console.log(`   Total edges detected: ${analysis.totalEdges}`);
     console.log(`   AA normal text pass rate: ${analysis.aaNormalPassPercentage.toFixed(1)}%`);
     console.log(`   AA large text pass rate: ${analysis.aaLargePassPercentage.toFixed(1)}%`);
-    console.log(`   Violations found: ${analysis.violations.length}\n`);
+    console.log(`   Warnings found: ${analysis.violations.length}\n`);
 
     if (analysis.violations.length > 0) {
-      console.log('   Top 5 violations by size:');
+      console.log('   Top 5 warnings by size:');
       for (let i = 0; i < Math.min(5, analysis.violations.length); i++) {
         let violation = analysis.violations[i];
         console.log(
@@ -51,8 +51,8 @@ async function main() {
     console.error('   Error:', error.message);
   }
 
-  // Example 2: WCAG AAA analysis (stricter)
-  console.log('2. Running strict WCAG AAA analysis...');
+  // Example 2: WCAG AAA threshold screening (stricter)
+  console.log('2. Running strict WCAG AAA color-pair screening...');
   try {
     let analysis = await analyzeWcagContrast(
       path.join(__dirname, '../../../tests/fixtures/screenshots/vizzly-baseline.png'),
@@ -67,7 +67,7 @@ async function main() {
     console.log(`   Total edges detected: ${analysis.totalEdges}`);
     console.log(`   AAA normal text pass rate: ${analysis.aaaNormalPassPercentage.toFixed(1)}%`);
     console.log(`   AAA large text pass rate: ${analysis.aaaLargePassPercentage.toFixed(1)}%`);
-    console.log(`   AAA violations found: ${analysis.violations.length}\n`);
+    console.log(`   AAA warnings found: ${analysis.violations.length}\n`);
   } catch (error) {
     console.error('   Error:', error.message);
   }
@@ -83,7 +83,7 @@ async function main() {
       }
     );
 
-    let outputPath = path.join(__dirname, '../wcag-violations.png');
+    let outputPath = path.join(__dirname, '../wcag-warnings.png');
 
     await saveWcagOverlay(
       path.join(__dirname, '../../../tests/fixtures/screenshots/vizzly-baseline.png'),
@@ -111,14 +111,14 @@ async function main() {
     );
 
     console.log(`   Total edges: ${analysis.totalEdges}`);
-    console.log(`   Violations: ${analysis.violations.length}`);
+    console.log(`   Warnings: ${analysis.violations.length}`);
     console.log(`   Pass rate: ${analysis.aaNormalPassPercentage.toFixed(1)}%\n`);
   } catch (error) {
     console.error('   Error:', error.message);
   }
 
-  // Example 5: Detailed violation analysis
-  console.log('5. Analyzing violation details...');
+  // Example 5: Detailed warning analysis
+  console.log('5. Analyzing warning details...');
   try {
     let analysis = await analyzeWcagContrast(
       path.join(__dirname, '../../../tests/fixtures/screenshots/vizzly-baseline.png')
@@ -127,7 +127,7 @@ async function main() {
     if (analysis.violations.length > 0) {
       let violation = analysis.violations[0];
 
-      console.log('   First violation details:');
+      console.log('   First warning details:');
       console.log(`   - Location: (${violation.boundingBox.x}, ${violation.boundingBox.y})`);
       console.log(`   - Size: ${violation.boundingBox.width}x${violation.boundingBox.height}`);
       console.log(
@@ -141,7 +141,7 @@ async function main() {
         `   - Contrast ratio: ${violation.contrastRatio.toFixed(2)}:1 (${violation.minContrastRatio.toFixed(2)} - ${violation.maxContrastRatio.toFixed(2)})`
       );
       console.log(`   - Pixel count: ${violation.pixelCount}`);
-      console.log('   - WCAG Status:');
+      console.log('   - Detected threshold status:');
       console.log(`     AA Normal (4.5:1): ${violation.failsAaNormal ? '❌ FAIL' : '✓ PASS'}`);
       console.log(`     AA Large (3.0:1): ${violation.failsAaLarge ? '❌ FAIL' : '✓ PASS'}`);
       console.log(`     AAA Normal (7.0:1): ${violation.failsAaaNormal ? '❌ FAIL' : '✓ PASS'}`);

package/index.d.ts

@@ -206,8 +206,8 @@ export interface CompareOptions {
    * Useful for detecting border thickness changes, font weight shifts,
    * and icon updates.
    *
-   * **Note:** GMSD requires images with identical dimensions. For variable-height
-   * comparisons, `gmsdScore` will be `null`. Use SSIM for variable-height images.
+   * **Note:** For variable-height comparisons, GMSD is calculated on the
+   * overlapping region shared by both images.
    *
    * Reference: Xue et al. 2014 - "Gradient Magnitude Similarity Deviation:
    * A Highly Efficient Perceptual Image Quality Index"
@@ -541,11 +541,11 @@ export function getImageMetadataFromFile(path: string): Promise<ImageMetadata>;
 export function getImageMetadataFromFileSync(path: string): ImageMetadata;
 
 // ============================================================================
-// WCAG Accessibility API
+// Screenshot Contrast Screening API
 // ============================================================================
 
 /**
- * Options for WCAG color contrast analysis
+ * Options for screenshot contrast screening with WCAG color-pair math.
  */
 export interface WcagOptions {
   /**
@@ -564,38 +564,39 @@ export interface WcagOptions {
 
   /**
    * Maximum contrast threshold
-   * Regions with contrast above this are excluded (gradient filtering)
-   * @default 3.5
+   * Set above 0 to exclude regions with contrast above this ratio. 0 reports
+   * all detected failures.
+   * @default 0
    */
   maxContrastThreshold?: number;
 
   /**
-   * Check WCAG AA compliance (4.5:1 for normal text, 3.0:1 for large text)
+   * Check WCAG AA color-pair thresholds (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)
+   * Check WCAG AAA color-pair thresholds (7.0:1 for normal text, 4.5:1 for large text)
    * @default false
    */
   checkAAA?: boolean;
 }
 
 /**
- * A single WCAG color contrast violation region
+ * A single screenshot contrast warning region.
  */
 export interface ContrastViolation {
-  /** Bounding box containing this violation region */
+  /** Bounding box containing this warning region */
   boundingBox: BoundingBox;
 
-  /** List of pixel coordinates [x, y] in this violation */
+  /** List of pixel coordinates [x, y] in this warning region */
   pixels: [number, number][];
 
-  /** Center of mass [x, y] of the violation region */
+  /** Center of mass [x, y] of the warning region */
   centerOfMass: [number, number];
 
-  /** Number of pixels in this violation */
+  /** Number of pixels in this warning region */
   pixelCount: number;
 
   /** Foreground color [r, g, b, a] (0-255) */
@@ -633,7 +634,7 @@ export interface ContrastViolation {
 }
 
 /**
- * Complete WCAG accessibility analysis result
+ * Complete screenshot contrast screening result.
  */
 export interface WcagAnalysis {
   /** Total number of edges analyzed */
@@ -651,7 +652,7 @@ export interface WcagAnalysis {
   /** Number of edges passing WCAG AAA for large text */
   aaaLargePass: number;
 
-  /** List of contrast violations found */
+  /** List of contrast warning regions found */
   violations: ContrastViolation[];
 
   /** Percentage of edges passing WCAG AA for normal text (0.0-100.0) */
@@ -668,14 +669,16 @@ export interface WcagAnalysis {
 }
 
 /**
- * Analyze WCAG color contrast accessibility asynchronously (recommended)
+ * Screen screenshot contrast warnings 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.
+ * Detects color boundaries in an image and measures each color pair with the
+ * WCAG contrast formula. Treat results as screening warnings, not full WCAG
+ * conformance, because screenshots do not expose text size, boldness, DOM
+ * foreground/background, compositing, or semantic roles.
  *
  * @param img - Image to analyze (file path or Buffer)
- * @param options - WCAG analysis options
- * @returns Promise resolving to detailed accessibility analysis
+ * @param options - Screenshot contrast screening options
+ * @returns Promise resolving to detailed screenshot contrast screening result
  *
  * @example
  * ```typescript
@@ -699,14 +702,14 @@ export interface WcagAnalysis {
 export function analyzeWcagContrast(img: ImageInput, options?: WcagOptions): Promise<WcagAnalysis>;
 
 /**
- * Analyze WCAG color contrast accessibility synchronously (blocks event loop)
+ * Screen screenshot contrast warnings 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
+ * @param options - Screenshot contrast screening options
+ * @returns Detailed screenshot contrast screening result
  *
  * @example
  * ```typescript
@@ -745,7 +748,7 @@ export interface WcagOutputOptions {
  * Useful for visual debugging of accessibility issues.
  *
  * @param img - Original image (file path or Buffer)
- * @param analysis - WCAG analysis result from analyzeWcagContrast()
+ * @param analysis - Screenshot contrast screening result from analyzeWcagContrast()
  * @param outputPath - Path to save the overlay image
  * @param options - Output options
  * @returns Promise that resolves when the file is saved
@@ -778,7 +781,7 @@ export function saveWcagOverlay(
  * For most cases, prefer the async saveWcagOverlay() function.
  *
  * @param img - Original image (file path or Buffer)
- * @param analysis - WCAG analysis result from analyzeWcagContrastSync()
+ * @param analysis - Screenshot contrast screening result from analyzeWcagContrastSync()
  * @param outputPath - Path to save the overlay image
  * @param options - Output options
  *
@@ -835,22 +838,22 @@ export interface ColorBlindnessTypeInfo {
 }
 
 /**
- * Comprehensive WCAG analysis report for all color vision deficiency types.
+ * Comprehensive screenshot contrast screening report for all color vision deficiency types.
  *
- * Contains WCAG contrast analysis for normal vision and all three main types
+ * Contains contrast screening 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 */
+  /** Contrast screening for normal (typical) color vision */
   normalVision: WcagAnalysis;
 
-  /** WCAG analysis simulating protanopia (red-blind) */
+  /** Contrast screening simulating protanopia (red-blind) */
   protanopia: WcagAnalysis;
 
-  /** WCAG analysis simulating deuteranopia (green-blind) */
+  /** Contrast screening simulating deuteranopia (green-blind) */
   deuteranopia: WcagAnalysis;
 
-  /** WCAG analysis simulating tritanopia (blue-blind) */
+  /** Contrast screening simulating tritanopia (blue-blind) */
   tritanopia: WcagAnalysis;
 
   /** Whether any CVD type has violations */
@@ -870,8 +873,8 @@ export interface CvdWcagReport {
  * 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.
+ * specified type of color vision deficiency. Complete dichromacy uses the
+ * piecewise Brettel, Viénot & Mollon 1997 LMS projection model.
  *
  * @param img - Image to transform (file path or Buffer)
  * @param cvdType - Type of color blindness to simulate
@@ -1010,16 +1013,17 @@ export function saveAllColorBlindnessSimulationsSync(
 ): void;
 
 /**
- * Analyze WCAG contrast for a specific color blindness type asynchronously (recommended)
+ * Screen 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.
+ * deficiency, then runs screenshot contrast screening with WCAG color-pair
+ * math. This finds detected color-pair warnings that only appear for
+ * colorblind users.
  *
  * @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
+ * @param options - Screenshot contrast screening options
+ * @returns Promise resolving to screening results for the simulated image
  *
  * @example
  * ```typescript
@@ -1042,14 +1046,14 @@ export function analyzeWcagForCvd(
 ): Promise<WcagAnalysis>;
 
 /**
- * Analyze WCAG contrast for a specific color blindness type synchronously (blocks event loop)
+ * Screen 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
+ * @param options - Screenshot contrast screening options
+ * @returns Screening results for the simulated image
  *
  * @example
  * ```typescript
@@ -1064,15 +1068,14 @@ export function analyzeWcagForCvdSync(
 ): WcagAnalysis;
 
 /**
- * Analyze WCAG contrast for all CVD types asynchronously (recommended)
+ * Screen 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.
+ * Runs screenshot contrast screening for normal vision and all three main
+ * types of dichromatic color blindness.
  *
  * @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
+ * @param options - Screenshot contrast screening options (same options used for all analyses)
+ * @returns Promise resolving to a report containing screening results for each vision type
  *
  * @example
  * ```typescript
@@ -1081,11 +1084,11 @@ export function analyzeWcagForCvdSync(
  *   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}`);
+ * console.log('Contrast Screening Report:');
+ * console.log(`Normal vision warnings: ${report.normalVision.violations.length}`);
+ * console.log(`Protanopia warnings: ${report.protanopia.violations.length}`);
+ * console.log(`Deuteranopia warnings: ${report.deuteranopia.violations.length}`);
+ * console.log(`Tritanopia warnings: ${report.tritanopia.violations.length}`);
  *
  * if (report.hasAnyViolations) {
  *   console.log(`\nTotal issues found: ${report.totalViolations}`);
@@ -1096,20 +1099,20 @@ export function analyzeWcagForCvdSync(
 export function analyzeWcagAllCvd(img: ImageInput, options?: WcagOptions): Promise<CvdWcagReport>;
 
 /**
- * Analyze WCAG contrast for all CVD types synchronously (blocks event loop)
+ * Screen 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
+ * @param options - Screenshot contrast screening options
+ * @returns Report containing screening results for each vision type
  *
  * @example
  * ```typescript
  * const report = analyzeWcagAllCvdSync('ui.png');
  *
  * if (report.hasAnyViolations) {
- *   console.log('Accessibility issues detected!');
+ *   console.log('Contrast warnings detected!');
  * }
  * ```
  */

package/index.js

@@ -48,7 +48,7 @@ export const getImageMetadataSync = addon.getImageMetadataSync;
 export const getImageMetadataFromFile = addon.getImageMetadataFromFile;
 export const getImageMetadataFromFileSync = addon.getImageMetadataFromFileSync;
 
-// WCAG Accessibility API
+// Screenshot Contrast Screening API
 export const analyzeWcagContrast = addon.analyzeWcagContrast;
 export const analyzeWcagContrastSync = addon.analyzeWcagContrastSync;
 export const saveWcagOverlay = addon.saveWcagOverlay;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/honeydiff",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "description": "High-performance image diffing for Node.js - Native bindings to Honeydiff Rust library",
   "type": "module",
   "main": "index.js",
@@ -48,6 +48,7 @@
     "index.d.ts",
     "load-platform.cjs",
     "platforms/*.node",
+    "assets/",
     "examples/",
     "README.md",
     "CHANGELOG.md"