capybara-screenshot-diff 1.15.0 → 2.0.0.alpha1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e22999718673e3e7cec926c524deedb3e3d0ead26e7c8350b777f5a453f02ad6
-  data.tar.gz: 1c10e980fb7787a493c763ddc3ee8f1a7ada5180af7277e389b24761a359f68d
+  metadata.gz: 183664107a9aaffa1f5e89fb5c4ba3b74e798d856ed22d3256a3d3b03e528231
+  data.tar.gz: b2a226430eaeab196e297efc9c476eb4cf0d192334d1503ba29f330fb9bd81ed
 SHA512:
-  metadata.gz: 6a3328839042af4d915150aba0c135d52f99074b9c31a69bdf9f6ff7e2b5a4c2c352b94f767ed9ec24f517c232257d1111bce1db3f019a668b8b4ba5314b09b1
-  data.tar.gz: 30c9cabdbabf2823c7fe77b4b825f7d59d0e3a8b49d373544eabb3ad171bee58d9ca8e57c6555b93254e7f04d0aa04075dd84839f4623151ae818efdd020845d
+  metadata.gz: fda1cec9f451076ee8260b3f9d3777b1c384e6ba5ca7119a08b265cb5fec23ffe6c7315e6f97feb3c2199ab9dcf99d827eda54e3cd0857c671e270016af61af3
+  data.tar.gz: 2651d17eaceca6a6b8f5c94136e8e221639ec5cf70d70d9178d9d30a630f5014e5eb240ace31233a45a456cf3918d0e70b324c998e2b4ab3531bac7d7d21ffe0

data/CHANGELOG.md

@@ -5,6 +5,65 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v2.0.0.alpha1] - 2026-08-22
+
+**Opt-in experiment prerelease.** RubyGems never installs prereleases by default
+resolution — to try it: `gem "capybara-screenshot-diff", "2.0.0.alpha1"`. The
+final 2.0.0 ships only after adopter feedback on this train; please report
+anything surprising on [#166](https://github.com/snap-diff/snap_diff-capybara/issues/166).
+
+### Changed
+- **`SnapDiff` is the canonical namespace.** The implementation lives in
+  `lib/snap_diff/`; every legacy constant (`Capybara::Screenshot::Diff::*`,
+  `CapybaraScreenshotDiff::*`) still resolves to the *same object* and keeps
+  working ([#208](https://github.com/snap-diff/snap_diff-capybara/pull/208),
+  [#209](https://github.com/snap-diff/snap_diff-capybara/pull/209),
+  [#210](https://github.com/snap-diff/snap_diff-capybara/pull/210)):
+  `ImageCompare` → `SnapDiff::Comparison`, `Difference` →
+  `SnapDiff::ComparisonResult`, `Drivers::BaseDriver` → `SnapDiff::Driver` (mixin).
+- **Legacy constants warn on first use** — once per constant per process, naming
+  the replacement ([#218](https://github.com/snap-diff/snap_diff-capybara/pull/218)).
+  Silence with `SnapDiff.silence_deprecations = true` or
+  `SNAP_DIFF_SILENCE_DEPRECATIONS=1`. A few constants stay silent by design
+  (`Os`, `DSL`, `VERSION`, driver leaf classes — see `lib/snap_diff/legacy_shims.rb`).
+
+### Fixed
+- Annotation color constants resolve under the bare `require "snap_diff"` entry;
+  previously a differing comparison raised `NameError` there
+  ([#219](https://github.com/snap-diff/snap_diff-capybara/pull/219))
+
+### Known caveats (deliberate, alpha)
+- `defined?(...)` / `const_defined?` on lazily-shimmed legacy names returns
+  false/nil — feature detection like `defined?(Capybara::Screenshot::Diff::Drivers::VipsDriver)`
+  must move to the `SnapDiff::` name. Rescuing legacy error classes is unaffected
+  (they remain eagerly defined).
+- Reopening `module Capybara::Screenshot::Diff::Drivers` (historical custom-driver
+  monkey-patch pattern) defines a fresh module that shadows the shim; define custom
+  drivers under `SnapDiff::Drivers` instead.
+
+### Internal
+- Core simplification, behavior-preserving (the "5.5-lite" pass): pure
+  capture/comparison option partition ([#212](https://github.com/snap-diff/snap_diff-capybara/pull/212)),
+  stability failure as data ([#213](https://github.com/snap-diff/snap_diff-capybara/pull/213)),
+  explicit `ScreenshotAssertion#archive_baseline!` + `#inspect` on
+  assertion/result ([#214](https://github.com/snap-diff/snap_diff-capybara/pull/214)),
+  `SnapDiff::Capture::Viewport` seam with the future `anchor:` hook
+  ([#215](https://github.com/snap-diff/snap_diff-capybara/pull/215)), reporter vs
+  session lifecycle separation ([#216](https://github.com/snap-diff/snap_diff-capybara/pull/216)),
+  all behind a guard-test net ([#211](https://github.com/snap-diff/snap_diff-capybara/pull/211))
+
+---
+
+## [v1.15.1] - 2026-08-22
+
+### Fixed
+- **`VipsDriver#resize_image_to` resizes to the requested dimensions** — the vips driver passed a target aspect ratio where libvips expects a scale factor, so retina-halving on macOS/Selenium could enlarge screenshots (2560×1600 → 4096×2560) and save wrongly-sized baselines; now scales width and height independently via `resize(scale, vscale:)` ([#205](https://github.com/snap-diff/snap_diff-capybara/pull/205))
+
+### Internal
+- Driver contract tests pinning the shared ChunkyPNG/Vips driver seam (method surface, load/compare behavior, option handling) — the net that caught the resize bug ([#204](https://github.com/snap-diff/snap_diff-capybara/pull/204))
+
+---
+
 ## [v1.15.0] - 2026-08-22
 
 ### Added

data/docs/RELEASE_PREP.md

@@ -1,23 +1,23 @@
-# Release Preparation — v1.15.0
+# Release Preparation — v1.15.1
 
 ## Summary
 
-Additive `SnapDiff::Config`, two failure-masking fixes in the `pending_if_new`
-teardown paths, a `BacktraceFilter` boundary fix, and an internal hygiene pass.
+HIGH-severity VipsDriver resize fix (retina halving could enlarge screenshots
+and corrupt baselines) plus the driver contract tests that caught it.
 
 ## Release Checklist
 
 ### Pre-Release
 
-- [x] Update version to `1.15.0`
-- [x] Run tests: `bundle exec rake test:unit` (267 runs, 0 failures)
+- [x] Update version to `1.15.1`
+- [x] Run tests: `bundle exec rake test:unit` (376 runs, 0 failures)
 - [x] Update CHANGELOG.md
 
 ### Release (One Click)
 
 1. Push to GitHub
 2. Go to [Actions → Release](https://github.com/snap-diff/snap_diff-capybara/actions/workflows/release.yml)
-3. Click **Run workflow**, enter `1.15.0`
+3. Click **Run workflow**, enter `1.15.1`
 4. Workflow will: test → tag → publish to RubyGems → create GitHub Release
 
 ### Post-Release

data/docs/thread_safety.md

@@ -95,3 +95,18 @@ Do not:
 - Paths are unique per screenshot name and counter
 - `FileUtils.mv` is atomic on most file systems
 - Directory creation uses `mkpath`
+
+## Load-time thread safety
+
+Runtime state is thread-local (above), but *loading* the gem is a separate
+concern. The require graph is deliberately acyclic: `lib/snap_diff/*` units
+depend only on the legacy-config leaf
+(`capybara/screenshot/diff/config_legacy`) and specific sibling units, the
+umbrella files depend on the units, and nothing requires back up the chain.
+
+Eager mutual requires between entry points are forbidden, even guarded ones:
+per-thread "loading" flags cannot serialize Ruby's process-global per-file
+require locks, so two threads requiring opposite entry points first can
+deadlock (lock-order inversion — observed deterministically before this
+design). If two files ever need each other, extract the shared piece into a
+leaf both can require instead.

data/lib/capybara/screenshot/diff/annotation_service.rb

@@ -1,79 +1,7 @@
 # frozen_string_literal: true
 
-module Capybara::Screenshot::Diff
-  # Draws diff/skip-area rectangles and the heatmap overlay for a Difference,
-  # and saves the resulting images to their `.diff.*` / `.heatmap.diff.*` paths.
-  #
-  # Extracted from Reporters::Default (ADR-004 PR 7) so the reporter only
-  # builds error messages; this class owns all image annotation work.
-  class AnnotationService
-    attr_reader :annotated_image_path, :annotated_base_image_path, :heatmap_diff_path
-
-    def initialize(difference)
-      @difference = difference
-
-      comparison = difference.comparison
-      ext = comparison.new_image_path.extname.delete_prefix(".")
-      screenshot_format = comparison.options[:screenshot_format] || (ext unless ext.empty?) || "png"
-      @annotated_image_path = comparison.new_image_path.sub_ext(".diff.#{screenshot_format}")
-      @annotated_base_image_path = comparison.base_image_path.sub_ext(".diff.#{screenshot_format}")
-      @heatmap_diff_path = comparison.new_image_path.sub_ext(".heatmap.diff.#{screenshot_format}")
-    end
-
-    def clean_tmp_files
-      annotated_base_image_path.unlink if annotated_base_image_path.exist?
-      annotated_image_path.unlink if annotated_image_path.exist?
-      heatmap_diff_path.unlink if heatmap_diff_path.exist?
-    end
-
-    def annotate_and_save_images
-      save_annotation_for(new_image, annotated_image_path)
-      save_annotation_for(base_image, annotated_base_image_path)
-      save_heatmap_diff if difference.diff_mask
-    end
-
-    def save_annotation_for(image, image_path)
-      image = annotate_difference(image, difference.region)
-      image = annotate_skip_areas(image, difference.comparison.skip_area) if difference.comparison.skip_area
-
-      save(image, image_path.to_path)
-    end
-
-    def annotate_difference(image, region)
-      driver.draw_rectangles([image], region, CapybaraScreenshotDiff::RED_RGBA, offset: 1).first
-    end
-
-    def annotate_skip_areas(image, skip_areas)
-      skip_areas.reduce(image) do |memo, region|
-        driver.draw_rectangles([memo], region, CapybaraScreenshotDiff::ORANGE_RGBA).first
-      end
-    end
-
-    def save(image, image_path)
-      driver.save_image_to(image, image_path.to_s)
-    end
-
-    private
-
-    attr_reader :difference
-
-    def save_heatmap_diff
-      merged_image = driver.merge(new_image, base_image)
-      highlighted_mask = driver.highlight_mask(difference.diff_mask, merged_image, color: CapybaraScreenshotDiff::RED_RGBA)
-
-      save(highlighted_mask, heatmap_diff_path.to_path)
-    end
-
-    def base_image
-      difference.comparison.base_image
-    end
-
-    def new_image
-      difference.comparison.new_image
-    end
-
-    def driver
-      @_driver ||= difference.comparison.driver
-    end
-  end
-end
+# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Diff::AnnotationService
+# now resolves lazily via snap_diff/legacy_shims' const_missing, with a
+# deprecation warning pointing at SnapDiff::AnnotationService.
+require "snap_diff/annotation_service"
+require "snap_diff/legacy_shims"

data/lib/capybara/screenshot/diff/area_calculator.rb

@@ -1,56 +1,7 @@
 # frozen_string_literal: true
 
-module Capybara
-  module Screenshot
-    module Diff
-      class AreaCalculator
-        def initialize(crop_coordinates, skip_area)
-          @crop_coordinates = crop_coordinates
-          @skip_area = skip_area
-        end
-
-        def calculate_crop
-          return @_calculated_crop if defined?(@_calculated_crop)
-          return @_calculated_crop = nil unless @crop_coordinates
-
-          # TODO: Move out from this class, this should be done on before screenshot and should not depend on Browser
-          @crop_coordinates = BrowserHelpers.bounds_for_css(@crop_coordinates).first if @crop_coordinates.is_a?(String)
-          @_calculated_crop = Region.from_edge_coordinates(*@crop_coordinates)
-        end
-
-        # Cast skip areas params into Region
-        # and if there is crop then makes absolute coordinates to eb relative to crop top left corner
-        def calculate_skip_area
-          return nil unless @skip_area
-
-          crop_region = calculate_crop
-          skip_area = Array(@skip_area)
-
-          css_selectors, coords_list = skip_area.compact.partition { |region| region.is_a? String }
-          regions, coords_list = coords_list.partition { |region| region.is_a? Region }
-
-          regions.concat(build_regions_for(BrowserHelpers.bounds_for_css(*css_selectors))) unless css_selectors.empty?
-          regions.concat(build_regions_for(coords_list.flatten.each_slice(4))) unless coords_list.empty?
-
-          regions.compact!
-
-          if crop_region
-            regions
-              .map! { |region| crop_region.find_relative_intersect(region) }
-              .filter! { |region| region&.present? }
-          end
-
-          regions
-        end
-
-        private
-
-        def build_regions_for(coordinates)
-          coordinates
-            .map { |entry| Region.from_edge_coordinates(*entry) }
-            .tap { |region| region.compact! }
-        end
-      end
-    end
-  end
-end
+# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Diff::AreaCalculator
+# now resolves lazily via snap_diff/legacy_shims' const_missing, with a
+# deprecation warning pointing at SnapDiff::AreaCalculator.
+require "snap_diff/area_calculator"
+require "snap_diff/legacy_shims"

data/lib/capybara/screenshot/diff/browser_helpers.rb

@@ -1,121 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "region"
-
-module Capybara
-  module Screenshot
-    module BrowserHelpers
-      def self.resize_window_if_needed
-        if ::Capybara::Screenshot.respond_to?(:window_size) && ::Capybara::Screenshot.window_size
-          resize_to(::Capybara::Screenshot.window_size)
-        end
-      end
-
-      def self.resize_to(window_size)
-        if session.driver.respond_to?(:resize)
-          session.driver.resize(*window_size)
-        elsif BrowserHelpers.selenium?
-          session.driver.browser.manage.window.resize_to(*window_size)
-        end
-      end
-
-      def self.selenium?
-        current_capybara_driver_class <= Capybara::Selenium::Driver
-      end
-
-      def self.window_size_is_wrong?(expected_window_size = nil)
-        selenium? && expected_window_size &&
-          session.driver.browser.manage.window.size != ::Selenium::WebDriver::Dimension.new(*expected_window_size)
-      end
-
-      def self.bounds_for_css(*css_selectors)
-        css_selectors.reduce([]) do |regions, selector|
-          regions.concat(all_visible_regions_for(selector))
-        end
-      end
-
-      IMAGE_WAIT_SCRIPT = <<~JS
-        function pending_image() {
-          const images = document.images
-          for (var i = 0; i < images.length; i++) {
-            if (!images[i].complete && images[i].loading !== "lazy") {
-                return images[i].src
-            }
-          }
-          return false
-        }(window)
-      JS
-
-      HIDE_CARET_SCRIPT = <<~JS
-        if (!document.getElementById('csdHideCaretStyle')) {
-          let style = document.createElement('style');
-          style.setAttribute('id', 'csdHideCaretStyle');
-          document.head.appendChild(style);
-          let styleSheet = style.sheet;
-          styleSheet.insertRule("* { caret-color: transparent !important; }", 0);
-        }
-      JS
-
-      def self.hide_caret
-        session.execute_script(HIDE_CARET_SCRIPT)
-      end
-
-      DISABLE_ANIMATIONS_SCRIPT = <<~JS
-        if (!document.getElementById('csdDisableAnimationsStyle')) {
-          let style = document.createElement('style');
-          style.setAttribute('id', 'csdDisableAnimationsStyle');
-          style.textContent = '*, *::before, *::after { animation-duration: 0s !important; animation-delay: 0s !important; transition-duration: 0s !important; transition-delay: 0s !important; }';
-          document.head.appendChild(style);
-        }
-      JS
-
-      def self.disable_animations
-        session.execute_script(DISABLE_ANIMATIONS_SCRIPT)
-      end
-
-      FIND_ACTIVE_ELEMENT_SCRIPT = <<~JS
-        function activeElement(){
-          const ae = document.activeElement; 
-          if (ae.nodeName === "INPUT" || ae.nodeName === "TEXTAREA") { 
-            ae.blur();      
-            return ae;
-          }
-          return null;
-        }(window);
-      JS
-
-      def self.blur_from_focused_element
-        session.evaluate_script(FIND_ACTIVE_ELEMENT_SCRIPT)
-      end
-
-      GET_BOUNDING_CLIENT_RECT_SCRIPT = <<~JS
-        [
-          this.getBoundingClientRect().left,
-          this.getBoundingClientRect().top,
-          this.getBoundingClientRect().right,
-          this.getBoundingClientRect().bottom
-        ]
-      JS
-
-      def self.all_visible_regions_for(selector)
-        BrowserHelpers.session.all(selector, visible: true).map { |el| region_for(el) }
-      end
-
-      def self.region_for(element)
-        element.evaluate_script(GET_BOUNDING_CLIENT_RECT_SCRIPT).map { |point| point.negative? ? 0 : point.ceil.to_i }
-      end
-
-      def self.session
-        Capybara.current_session
-      end
-
-      def self.pending_image_to_load
-        BrowserHelpers.session.evaluate_script(IMAGE_WAIT_SCRIPT)
-      end
-
-      def self.current_capybara_driver_class
-        session.driver.class
-      end
-    end
-  end
-end
+# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::BrowserHelpers now
+# resolves lazily via snap_diff/legacy_shims' const_missing, with a
+# deprecation warning pointing at SnapDiff::BrowserHelpers.
+require "snap_diff/browser_helpers"
+require "snap_diff/legacy_shims"

data/lib/capybara/screenshot/diff/config_legacy.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# Legacy Capybara::Screenshot / Capybara::Screenshot::Diff mattr_accessor
+# config module, extracted out of capybara_screenshot_diff.rb so it is a
+# leaf: it can be required by both capybara_screenshot_diff.rb (the old
+# umbrella entry point) and snap_diff.rb (the canonical entry point)
+# without either of *those* requiring the other back.
+#
+# Why this file has to exist at all: several lib/snap_diff/* units
+# (Screenshoter, SnapManager, Utils) are referenced here at class-body
+# eval time (mattr_accessor default blocks, AVAILABLE_DRIVERS) rather
+# than at call time, so they must be real, already-loaded classes before
+# this module body runs. Since v2 step 6 they are pulled in and referenced
+# under their canonical SnapDiff names: the old-name aliases are lazy
+# const_missing shims that emit deprecation warnings, and the gem's own
+# code must stay warning-free. Everything else this module references
+# (Os, Comparison) is referenced only inside method bodies, resolved
+# lazily at call time by whichever entry point loaded them.
+require "snap_diff/screenshoter"
+require "snap_diff/snap_manager"
+require "snap_diff/utils"
+
+module Capybara
+  module Screenshot
+    mattr_accessor :add_driver_path
+    mattr_accessor :add_os_path
+    mattr_accessor(:blur_active_element) { true }
+    mattr_accessor :enabled
+    mattr_accessor(:hide_caret) { true }
+    mattr_accessor :disable_animations
+    mattr_reader(:root) { (defined?(Rails) && defined?(Rails.root) && Rails.root) || Pathname(".").expand_path }
+    mattr_accessor :stability_time_limit
+    mattr_accessor :window_size
+    mattr_accessor(:save_path) { "doc/screenshots" }
+    mattr_accessor(:use_lfs)
+    mattr_accessor(:screenshot_format) { "png" }
+    mattr_accessor(:capybara_screenshot_options) { {} }
+
+    class << self
+      def root=(path)
+        @@root = Pathname(path).expand_path
+      end
+
+      def active?
+        enabled || (enabled.nil? && Diff.enabled)
+      end
+
+      def screenshot_area
+        parts = [Screenshot.save_path]
+        parts << SnapDiff::Os.name if Screenshot.add_os_path
+        parts << Capybara.current_driver.to_s if Screenshot.add_driver_path
+        File.join(*parts)
+      end
+
+      def screenshot_area_abs
+        root / screenshot_area
+      end
+    end
+
+    # Module to track screenshot changes
+    module Diff
+      mattr_accessor(:delayed) { true }
+      mattr_accessor :area_size_limit
+      mattr_accessor(:fail_if_new) { !ENV["CI"].nil? && !ENV["CI"].empty? }
+      mattr_accessor(:pending_if_new) { false }
+      mattr_accessor(:fail_on_difference) { true }
+      mattr_accessor :color_distance_limit
+      mattr_accessor(:enabled) { true }
+      mattr_accessor :shift_distance_limit
+      mattr_accessor :skip_area
+      mattr_accessor(:driver) { :auto }
+      mattr_accessor :tolerance
+      mattr_accessor :perceptual_threshold
+
+      mattr_accessor(:screenshoter) { SnapDiff::Screenshoter }
+      mattr_accessor(:manager) { SnapDiff::SnapManager }
+
+      AVAILABLE_DRIVERS = SnapDiff::Utils.detect_available_drivers.freeze
+
+      # Configure screenshot and diff settings in one block.
+      #
+      #   Capybara::Screenshot::Diff.configure do |screenshot, diff|
+      #     screenshot.window_size = [1280, 1024]
+      #     screenshot.stability_time_limit = 1
+      #     diff.driver = :vips
+      #     diff.tolerance = 0.0005
+      #   end
+      def self.configure
+        yield Screenshot, self
+      end
+
+      def self.compare(baseline_path, current_path, **options)
+        SnapDiff::Comparison.new(current_path, baseline_path, default_options.merge(options))
+      end
+
+      def self.default_options
+        {
+          area_size_limit: area_size_limit,
+          color_distance_limit: color_distance_limit,
+          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,
+          tolerance: tolerance || ((driver == :vips) ? 0.001 : nil),
+          wait: Capybara.default_max_wait_time
+        }
+      end
+    end
+  end
+end

data/lib/capybara/screenshot/diff/cucumber.rb

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
 
-require "capybara_screenshot_diff/cucumber"
+require "snap_diff/integrations/cucumber"

data/lib/capybara/screenshot/diff/difference.rb

@@ -1,104 +1,8 @@
 # frozen_string_literal: true
 
-require "json"
-
-module Capybara
-  module Screenshot
-    module Diff
-      # Represents a difference between two images
-      #
-      # This value object encapsulates the result of an image comparison operation.
-      # It follows the Single Responsibility Principle by focusing solely on representing
-      # the difference state, including:
-      # - Whether images are different or equal
-      # - Why they differ (dimensions, pixels, etc.)
-      # - The specific region of difference
-      # - Whether differences are tolerable based on configured thresholds
-      #
-      # As part of the layered comparison architecture, this class represents the final
-      # output of the comparison process, containing all data needed for reporting.
-      # Represents a difference between two images
-      class Difference < Struct.new(:region, :meta, :comparison, :failed_by, :base_image_path, :image_path, keyword_init: nil)
-        def self.build_null(comparison, base_image_path, new_image_path, failed_by = nil)
-          Difference.new(
-            nil,
-            {difference_level: nil, max_color_distance: 0},
-            comparison,
-            failed_by,
-            base_image_path,
-            new_image_path
-          ).freeze
-        end
-
-        def different?
-          failed? || !(blank? || tolerable?)
-        end
-
-        def equal?
-          !different?
-        end
-
-        def failed?
-          !!failed_by
-        end
-
-        def options
-          comparison.options
-        end
-
-        def tolerance
-          options[:tolerance]
-        end
-
-        def skip_area
-          comparison.skip_area
-        end
-
-        def area_size_limit
-          options[:area_size_limit]
-        end
-
-        def blank?
-          region.nil? || region_area_size.zero?
-        end
-
-        def region_area_size
-          @region_area_size ||= region&.size || 0
-        end
-
-        def ratio
-          meta[:difference_level]
-        end
-
-        def to_h
-          {area_size: region_area_size, region: coordinates}.merge!(meta)
-        end
-
-        def coordinates
-          region&.to_edge_coordinates
-        end
-
-        def inspect
-          to_h.to_json
-        end
-
-        def tolerable?
-          !!((area_size_limit && area_size_limit >= region_area_size) || (tolerance && tolerance >= ratio))
-        end
-
-        # Path accessors for backward compatibility
-        def new_image_path
-          image_path || comparison&.new_image_path
-        end
-
-        def original_image_path
-          base_image_path || comparison&.base_image_path
-        end
-
-        def diff_mask
-          meta[:diff_mask]
-        end
-      end
-    end
-  end
-end
+# Forwarder (ADR-004 v2 step 6): the comparison-result value object lives at
+# SnapDiff::ComparisonResult (ex-Difference); the old name now resolves
+# lazily via snap_diff/legacy_shims' const_missing, with a deprecation
+# warning.
+require "snap_diff/comparison_result"
+require "snap_diff/legacy_shims"

data/lib/capybara/screenshot/diff/drivers/base_driver.rb

@@ -1,41 +1,9 @@
 # frozen_string_literal: true
 
-require "capybara/screenshot/diff/difference"
-
-module Capybara
-  module Screenshot
-    module Diff
-      # Compare two images and determine if they are equal, different, or within some comparison
-      # range considering color values and difference area size.
-      module Drivers
-        class BaseDriver
-          PNG_EXTENSION = ".png"
-
-          def same_dimension?(comparison)
-            dimension(comparison.base_image) == dimension(comparison.new_image)
-          end
-
-          def height_for(image)
-            image.height
-          end
-
-          def width_for(image)
-            image.width
-          end
-
-          def image_area_size(image)
-            width_for(image) * height_for(image)
-          end
-
-          def dimension(image)
-            [width_for(image), height_for(image)]
-          end
-
-          def supports?(feature)
-            respond_to?(feature)
-          end
-        end
-      end
-    end
-  end
-end
+# BaseDriver was dissolved into the SnapDiff::Driver mixin (ADR-004 v2
+# step 4); since step 6 the old name resolves lazily via
+# snap_diff/legacy_shims' const_missing, with a deprecation warning.
+# Note it is now a module -- `class MyDriver < BaseDriver` becomes
+# `include SnapDiff::Driver`.
+require "snap_diff/driver"
+require "snap_diff/legacy_shims"