feat: add Diff.compare for standalone image comparison

Browser-independent API for comparing any two images:

  result = Capybara::Screenshot::Diff.compare("a.png", "b.png")
  result.quick_equal?  # byte-identical?
  result.different?    # visually different?

Supports all existing options (driver, tolerance, perceptual_threshold).
Based on real usage from corsis/pet which uses the gem for PDF regression.

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

Author: pftg

README.md

@@ -155,6 +155,23 @@ end
 | Standard Rails apps | 0.0005 | 15 | 1s |
 | Pixel-perfect design tests | 0.0001 | 5 | 1s |
 
+### Standalone image comparison
+
+Compare any two images without Capybara or a browser — useful for PDF regression, generated images, or CI artifact validation:
+
+```ruby
+result = Capybara::Screenshot::Diff.compare("baseline.png", "current.png")
+result.quick_equal?  # => true if byte-identical
+result.different?    # => true if visually different (respects tolerance)
+
+# With options
+result = Capybara::Screenshot::Diff.compare("baseline.pdf.png", "current.pdf.png",
+  driver: :vips,
+  tolerance: 0.001,
+  perceptual_threshold: 2.0
+)
+```
+
 ### Perceptual color comparison (VIPS only)
 
 By default, color differences are measured using raw RGB channel distance. This can produce

lib/capybara_screenshot_diff.rb

@@ -90,6 +90,10 @@ def self.configure
         yield Screenshot, self
       end
 
+      def self.compare(baseline_path, current_path, **options)
+        ImageCompare.new(current_path, baseline_path, default_options.merge(options))
+      end
+
       def self.default_options
         {
           area_size_limit: area_size_limit,

test/unit/compare_api_test.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+module Capybara
+  module Screenshot
+    module Diff
+      class CompareApiTest < ActiveSupport::TestCase
+        test ".compare returns ImageCompare instance" do
+          result = Diff.compare(
+            TEST_IMAGES_DIR / "a.png",
+            TEST_IMAGES_DIR / "a.png"
+          )
+          assert_kind_of ImageCompare, result
+        end
+
+        test ".compare detects identical images" do
+          result = Diff.compare(
+            TEST_IMAGES_DIR / "a.png",
+            TEST_IMAGES_DIR / "a.png"
+          )
+          assert result.quick_equal?
+          assert_not result.different?
+        end
+
+        test ".compare detects different images" do
+          result = Diff.compare(
+            TEST_IMAGES_DIR / "a.png",
+            TEST_IMAGES_DIR / "b.png"
+          )
+          assert_not result.quick_equal?
+          assert result.different?
+        end
+
+        test ".compare accepts driver option" do
+          skip "VIPS not present" unless defined?(Vips)
+
+          result = Diff.compare(
+            TEST_IMAGES_DIR / "a.png",
+            TEST_IMAGES_DIR / "a.png",
+            driver: :vips
+          )
+          assert result.quick_equal?
+        end
+
+        test ".compare accepts tolerance options" do
+          skip "VIPS not present" unless defined?(Vips)
+
+          result = Diff.compare(
+            TEST_IMAGES_DIR / "a.png",
+            TEST_IMAGES_DIR / "b.png",
+            driver: :vips,
+            tolerance: 1.0
+          )
+          assert_not result.different?
+        end
+      end
+    end
+  end
+end