feat: add perceptual color distance (dE00) support to VipsDriver

New `perceptual: true` option uses CIE dE00 formula for color
comparison instead of raw RGB channel distance. dE00 measures
perceptual color difference — values <2.0 are imperceptible to
human eyes, making it ideal for handling anti-aliasing artifacts.

Usage:
  screenshot 'page', perceptual: true, color_distance_limit: 2.0

Falls back to existing RGB distance when perceptual is not set.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: pftg

README.md

@@ -155,6 +155,37 @@ end
 | Standard Rails apps | 0.0005 | 15 | 1s |
 | Pixel-perfect design tests | 0.0001 | 5 | 1s |
 
+### Perceptual color comparison (VIPS only)
+
+By default, color differences are measured using raw RGB channel distance. This can produce
+false positives from anti-aliasing and sub-pixel font rendering — the same page rendered on
+different OS versions or browsers will have slightly different pixel values at text edges.
+
+The `perceptual_threshold` option uses the CIE dE00 formula instead, which measures color
+difference the way human eyes perceive it. Anti-aliasing artifacts typically score below 2.0
+on the dE00 scale and are automatically ignored.
+
+```ruby
+# Per-screenshot: ignore anti-aliasing, catch real visual changes
+screenshot 'dashboard', perceptual_threshold: 2.0
+
+# Global: apply to all screenshots
+Capybara::Screenshot::Diff.perceptual_threshold = 2.0
+
+# dE00 scale reference:
+#   < 1.0  — not perceptible by human eyes
+#   1-2    — perceptible through close observation (anti-aliasing, font hinting)
+#   2-10   — perceptible at a glance (color shifts, layout changes)
+#   > 10   — clearly different colors
+```
+
+Use `perceptual_threshold` when you see false positives from font rendering differences across
+CI environments, or when `color_distance_limit` with raw RGB requires frequent tuning.
+
+**Note:** `perceptual_threshold` and `color_distance_limit` are independent options on different
+scales. `perceptual_threshold` uses dE00 (0-100+), `color_distance_limit` uses Euclidean RGB
+distance (0-441). Set one or the other, not both.
+
 ### Taking screenshots
 
 Add `screenshot '<my_feature>'` to your tests.  The screenshot will be saved in

docs/simplest_comparator.rb

@@ -19,7 +19,11 @@ class VipsDriver < BaseDriver
           def find_difference_region(comparison)
             new_image, base_image, options = comparison.new_image, comparison.base_image, comparison.options
 
-            diff_mask = self.class.difference_mask(base_image, new_image, options[:color_distance_limit])
+            diff_mask = if options[:perceptual_threshold]
+              self.class.perceptual_difference_mask(base_image, new_image, options[:perceptual_threshold])
+            else
+              self.class.difference_mask(base_image, new_image, options[:color_distance_limit])
+            end
             region = self.class.difference_region_by(diff_mask)
             # TODO: schedule research when we got this case for VIPs
             # region = nil if region && region_covers_entire_image?(region, base_image)
@@ -131,6 +135,27 @@ def difference_mask(base_image, new_image, color_distance = nil)
               color_distance ? result > color_distance : result
             end
 
+            def perceptual_difference_mask(base_image, new_image, threshold = 2.0)
+              base_rgb = (base_image.bands > 3) ? base_image.extract_band(0, n: 3) : base_image
+              new_rgb = (new_image.bands > 3) ? new_image.extract_band(0, n: 3) : new_image
+              base_lab = base_rgb.colourspace(:lab)
+              new_lab = new_rgb.colourspace(:lab)
+              perceptual_diff = begin
+                base_lab.dE00(new_lab)
+              rescue Vips::Error
+                base_lab.dE76(new_lab)
+              end
+              color_diff = perceptual_diff > threshold
+
+              # Compare alpha channel separately to catch transparency changes
+              if base_image.bands > 3 && new_image.bands > 3
+                alpha_diff = (base_image.extract_band(3) - new_image.extract_band(3)).abs > 0
+                color_diff | alpha_diff
+              else
+                color_diff
+              end
+            end
+
             def difference_region_by(diff_mask)
               columns, rows = diff_mask.bandor.project
 

lib/capybara/screenshot/diff/drivers/vips_driver.rb

@@ -71,6 +71,7 @@ module Diff
       mattr_accessor :skip_area
       mattr_accessor(:driver) { :auto }
       mattr_accessor :tolerance
+      mattr_accessor :perceptual_threshold
 
       mattr_accessor(:screenshoter) { Screenshoter }
       mattr_accessor(:manager) { CapybaraScreenshotDiff::SnapManager }
@@ -96,6 +97,7 @@ def self.default_options
           driver: driver,
           screenshot_format: Screenshot.screenshot_format,
           capybara_screenshot_options: Screenshot.capybara_screenshot_options,
+          perceptual_threshold: perceptual_threshold,
           shift_distance_limit: shift_distance_limit,
           skip_area: skip_area,
           stability_time_limit: Screenshot.stability_time_limit,

lib/capybara_screenshot_diff.rb

@@ -148,6 +148,16 @@ class VipsDriverTest < ActiveSupport::TestCase
             assert comp.different?
           end
 
+          test "#different? uses perceptual_threshold when set" do
+            comp = make_comparison(:a, :b, perceptual_threshold: 2.0)
+            assert comp.different?
+          end
+
+          test "#different? with perceptual_threshold returns equal for identical images" do
+            comp = make_comparison(:a, :a, perceptual_threshold: 2.0)
+            assert_not comp.different?
+          end
+
           # Test Interface Contracts
 
           test "#from_file successfully loads an image from the specified path" do
@@ -205,6 +215,56 @@ class VipsDriverClassMethodsTest < ActiveSupport::TestCase
             assert_equal 8, VipsDriver.difference_area(old_image, new_image, color_distance: 10)
           end
 
+          test "VipsDriver.perceptual_difference_mask returns nil region for identical images" do
+            old_image = Vips::Image.new_from_file("#{TEST_IMAGES_DIR}/a.png")
+            same_image = Vips::Image.new_from_file("#{TEST_IMAGES_DIR}/a.png")
+
+            diff_mask = VipsDriver.perceptual_difference_mask(old_image, same_image)
+            region = VipsDriver.difference_region_by(diff_mask)
+
+            assert_nil region
+          end
+
+          test "VipsDriver.perceptual_difference_mask detects differences between images" do
+            old_image = Vips::Image.new_from_file("#{TEST_IMAGES_DIR}/a.png")
+            new_image = Vips::Image.new_from_file("#{TEST_IMAGES_DIR}/b.png")
+
+            diff_mask = VipsDriver.perceptual_difference_mask(old_image, new_image, 2.0)
+            region = VipsDriver.difference_region_by(diff_mask)
+
+            assert_not_nil region
+          end
+
+          test "VipsDriver.perceptual_difference_mask detects alpha channel differences" do
+            old_image = Vips::Image.new_from_file("#{TEST_IMAGES_DIR}/a.png")
+            # Make a copy with different alpha
+            transparent = old_image.extract_band(0, n: 3).bandjoin(128)
+
+            diff_mask = VipsDriver.perceptual_difference_mask(old_image, transparent)
+            region = VipsDriver.difference_region_by(diff_mask)
+
+            assert_not_nil region, "Should detect alpha channel difference"
+          end
+
+          test "VipsDriver.perceptual_difference_mask respects threshold" do
+            old_image = Vips::Image.new_from_file("#{TEST_IMAGES_DIR}/a.png")
+            new_image = Vips::Image.new_from_file("#{TEST_IMAGES_DIR}/b.png")
+
+            # High threshold — fewer differences detected
+            high_mask = VipsDriver.perceptual_difference_mask(old_image, new_image, 50.0)
+            high_region = VipsDriver.difference_region_by(high_mask)
+
+            # Low threshold — more differences detected
+            low_mask = VipsDriver.perceptual_difference_mask(old_image, new_image, 2.0)
+            low_region = VipsDriver.difference_region_by(low_mask)
+
+            assert_not_nil low_region
+            # High threshold region should be smaller or nil compared to low threshold
+            if high_region
+              assert high_region.size <= low_region.size
+            end
+          end
+
           private
 
           def difference(old_image, new_image, color_distance: nil)