snap_diff-capybara 2.0.0.alpha1 → 2.0.0.beta2

data/lib/snap_diff/config.rb

@@ -1,35 +1,50 @@
 # frozen_string_literal: true
 
-# The MAPPING below references the legacy modules, so they must be loaded
-# first. Requires config_legacy directly (a leaf, see its own header
-# comment), not the capybara_screenshot_diff umbrella -- config.rb is
-# required by both snap_diff.rb and (indirectly) capybara_screenshot_diff.rb,
-# and neither of those may lead back here.
-require "capybara/screenshot/diff/config_legacy"
+require "pathname"
+
+# This file is the LEAF of the config require graph (ADR-008 step 1):
+# config_legacy.rb requires it, so it must never require config_legacy nor
+# anything that leads back to either entry point. The MAPPING below needs
+# the legacy module constants to exist at class-body eval time, so the empty
+# skeleton is predefined here (same technique as legacy_shims.rb);
+# config_legacy.rb reopens these modules and installs the delegating
+# accessors from MAPPING.
+module Capybara
+  module Screenshot
+    module Diff
+    end
+  end
+end
+
+# Referenced by Config#initialize (screenshoter/manager defaults), which
+# runs at the eager Config.new at the bottom of this file, so they must be
+# real, already-loaded classes first. Neither requires back here.
+require "snap_diff/screenshoter"
+require "snap_diff/snap_manager"
 
 module SnapDiff
-  # Flat, additive consolidation of every existing
-  # +Capybara::Screenshot+ / +Capybara::Screenshot::Diff+ +mattr_accessor+
-  # setting behind one object: <tt>SnapDiff.config.<em>attr</em></tt>.
+  # Flat consolidation of every legacy +Capybara::Screenshot+ /
+  # +Capybara::Screenshot::Diff+ setting behind one object:
+  # <tt>SnapDiff.config.<em>attr</em></tt>.
+  #
+  # Storage ownership (ADR-008 step 1, inverted from the original v2
+  # consolidation): Config IS the single storage. The legacy accessors on
+  # +Capybara::Screenshot+ / +Capybara::Screenshot::Diff+ are thin
+  # delegators installed by config_legacy.rb from {MAPPING} -- one storage,
+  # two views, so a write through either surface is visible through the
+  # other structurally, not by synchronization.
   #
-  # Storage ownership: the OLD mattr_accessors remain the single source of
-  # truth. Config holds no state of its own -- every reader/writer defined
-  # from {MAPPING} simply forwards to the existing accessor. This is
-  # deliberate, not just simplest: several of those accessors carry default
-  # logic with observable timing (+fail_if_new+ derives its default from
-  # +ENV["CI"]+, +root+ falls back to +Rails.root+) that Rails' +mattr_accessor+
-  # evaluates once, at class-body-eval time, when +capybara_screenshot_diff.rb+
-  # first loads. Re-implementing that logic here -- even faithfully -- would
-  # mean evaluating it again, at a different moment (Config#new time), which
-  # is exactly the kind of "when defaults are evaluated" divergence the v2
-  # consolidation must not introduce. Delegating sidesteps the question
-  # entirely: Config never evaluates a default, it only ever forwards to
-  # whichever accessor already owns one. Bidirectional consistency (a write
-  # through either the old accessor or Config is visible through the other)
-  # falls out for free, because both paths read and write the exact same
-  # class-variable-backed storage.
+  # Default timing contract (pinned by config_default_timing_test.rb):
+  # every default below is evaluated ONCE, in #initialize, which runs at
+  # require time of this file (the eager +Config.new+ at the bottom) -- the
+  # same load moment the old +mattr_accessor+ default blocks evaluated at.
+  # In particular +fail_if_new+ (from <tt>ENV["CI"]</tt>) and +root+ (from
+  # +Rails.root+ / pwd) must never become lazy read-time defaults, memoized
+  # or not. The one deliberately LIVE value, +default_options[:wait]+, is
+  # not storage at all: it stays a method-body read of
+  # +Capybara.default_max_wait_time+ in +#default_options+.
   class Config
-    # config attr name => [owning module, mattr_accessor name].
+    # config attr name => [legacy module, legacy accessor name].
     #
     # The two names differ only for +screenshot_enabled+:
     # +Capybara::Screenshot.enabled+ and +Capybara::Screenshot::Diff.enabled+
@@ -70,9 +85,116 @@ module SnapDiff
       manager: [Capybara::Screenshot::Diff, :manager]
     }.freeze
 
-    MAPPING.each do |name, (mod, mattr)|
-      define_method(name) { mod.public_send(mattr) }
-      define_method(:"#{name}=") { |value| mod.public_send(:"#{mattr}=", value) }
+    attr_accessor(*(MAPPING.keys - [:root]))
+    attr_reader :root
+
+    def initialize
+      # Every mapped setting gets its ivar up front (nil-defaulted ones
+      # included) so the full set always exists -- test_helper's per-test
+      # isolation snapshots/restores config by instance variable, and an
+      # ivar that only appears on first write would escape that snapshot
+      # and leak between tests.
+      MAPPING.each_key { |key| instance_variable_set(:"@#{key}", nil) }
+      # Capybara::Screenshot side.
+      @blur_active_element = true
+      @hide_caret = true
+      # Raw Rails.root (no coercion), matching the old mattr_reader default;
+      # only the writer below coerces.
+      @root = (defined?(Rails) && defined?(Rails.root) && Rails.root) || Pathname(".").expand_path
+      @save_path = "doc/screenshots"
+      @screenshot_format = "png"
+      @capybara_screenshot_options = {}
+      # Capybara::Screenshot::Diff side.
+      @delayed = true
+      @fail_if_new = !ENV["CI"].nil? && !ENV["CI"].empty?
+      @pending_if_new = false
+      @fail_on_difference = true
+      @enabled = true
+      @driver = :auto
+      @screenshoter = SnapDiff::Screenshoter
+      @manager = SnapDiff::SnapManager
+    end
+
+    def root=(path)
+      @root = Pathname(path).expand_path
+    end
+
+    # --- Derived config (ADR-008 step 7b) -------------------------------
+    # Read-only values computed from the storage above. They used to live
+    # on the legacy modules; those now one-line forward here.
+
+    # ex +Capybara::Screenshot.active?+. The two +enabled+ settings are
+    # independent (see {MAPPING}): the Screenshot-side one wins whenever it
+    # was set at all, and only a nil there falls through to the Diff-side
+    # one.
+    def active?
+      screenshot_enabled || (screenshot_enabled.nil? && enabled)
+    end
+
+    # ex +Capybara::Screenshot.screenshot_area+: the save_path, optionally
+    # segmented per OS and per Capybara driver.
+    def screenshot_area
+      parts = [save_path]
+      parts << Os.name if add_os_path
+      parts << Capybara.current_driver.to_s if add_driver_path
+      File.join(*parts)
+    end
+
+    # ex +Capybara::Screenshot.screenshot_area_abs+.
+    def screenshot_area_abs
+      root / screenshot_area
+    end
+
+    # ex +Capybara::Screenshot::Diff.default_options+: the capture/compare
+    # defaults handed to {SnapDiff::Comparison}. Carries the one literal
+    # that is not a stored setting -- the vips tolerance floor.
+    def default_options
+      {
+        area_size_limit: area_size_limit,
+        color_distance_limit: color_distance_limit,
+        driver: driver,
+        screenshot_format: screenshot_format,
+        capybara_screenshot_options: capybara_screenshot_options,
+        perceptual_threshold: perceptual_threshold,
+        shift_distance_limit: shift_distance_limit,
+        skip_area: skip_area,
+        stability_time_limit: stability_time_limit,
+        tolerance: tolerance || ((driver == :vips) ? 0.001 : nil),
+        # Deliberately LIVE (pinned by config_default_timing_test.rb):
+        # read at call time, never frozen into storage.
+        wait: Capybara.default_max_wait_time
+      }
+    end
+  end
+
+  # Instantiated eagerly so the require-time defaults above are evaluated
+  # NOW, at load, not at the first SnapDiff.config call.
+  @config = Config.new
+
+  # The single consolidated settings object -- and the single storage.
+  # See {SnapDiff::Config}.
+  def self.config
+    @config
+  end
+
+  # Installs the old mattr_accessor surface onto the legacy modules,
+  # delegating to the single storage above. mattr_accessor used to define
+  # both singleton and instance accessors (the instance ones are what
+  # `include Capybara::Screenshot::Diff` picks up), so both are installed.
+  # root keeps its historical asymmetry -- readable everywhere, writable
+  # only at module level (it was mattr_reader plus a custom module-level
+  # writer) -- with the Pathname coercion living in Config#root=.
+  #
+  # Generated here rather than in config_legacy.rb (ADR-008 step 7b) for
+  # the same reason legacy_shims.rb generates the legacy constants here:
+  # the generator is code, and the v1 trees must stay alias-only so 3.0 is
+  # a `git rm`. Same technique, same side of the fence.
+  Config::MAPPING.each do |name, (mod, mattr)|
+    [mod, mod.singleton_class].each do |target|
+      target.define_method(mattr) { SnapDiff.config.public_send(name) }
+      next if name == :root && target == mod
+
+      target.define_method(:"#{mattr}=") { |value| SnapDiff.config.public_send(:"#{name}=", value) }
     end
   end
 end

data/lib/snap_diff/deprecation.rb

@@ -5,12 +5,16 @@ module SnapDiff
   #
   # Internal until the v2 namespace transition; not a public contract.
   #
-  # Warn-once-per-subject deprecation helper. Dormant: nothing in the
-  # current codebase calls this yet -- it exists so the gated v2 shim layer
-  # (ADR-004's +const_missing+-based legacy constant shim and the
-  # mattr_accessor-to-Config method shims) has pre-tested warning
-  # machinery to call into once it lands.
+  # Warn-once-per-subject deprecation engine for the legacy-namespace
+  # shims: snap_diff/legacy_shims routes every +const_missing+ hit on an
+  # old +Capybara::Screenshot::Diff+ / +CapybaraScreenshotDiff+ constant
+  # through {.warn}, so each deprecated name warns exactly once per
+  # process (ADR-004's v2 namespace transition).
   module Deprecation
+    # Everything under lib/ is "the gem"; the first caller frame outside
+    # it is the user code that referenced the deprecated name (same
+    # filtering idea as BacktraceFilter in error_with_filtered_backtrace).
+    GEM_LIB_DIR = File.expand_path("..", __dir__) + File::SEPARATOR
     # Emission channel: Kernel#warn, not a direct +$stderr.puts+.
     #
     # Kernel#warn delegates to +Warning.warn+ (Ruby >= 2.4), so anything
@@ -40,7 +44,7 @@ module SnapDiff
         end
         return unless first_time
 
-        Kernel.warn(message_for(subject, replacement, category))
+        Kernel.warn(message_for(subject, replacement, category, caller_locations(1)))
       end
 
       # @api private
@@ -55,9 +59,23 @@ module SnapDiff
 
       private
 
-      def message_for(subject, replacement, category)
-        "[snap_diff deprecation] `#{subject}` is deprecated (#{category}); " \
+      def message_for(subject, replacement, category, locations)
+        message = "[snap_diff deprecation] `#{subject}` is deprecated (#{category}); " \
           "use `#{replacement}` instead."
+        origin = origin_for(locations)
+        origin ? "#{message} (called from #{origin})" : message
+      end
+
+      # First frame outside the gem's lib dir, formatted "file:line";
+      # nil when every frame is internal (or paths are unavailable).
+      def origin_for(locations)
+        (locations || []).each do |location|
+          path = location.absolute_path || location.path
+          next if path.nil? || path.start_with?(GEM_LIB_DIR)
+
+          return "#{path}:#{location.lineno}"
+        end
+        nil
       end
     end
   end

data/lib/snap_diff/drivers.rb

@@ -10,5 +10,25 @@ module SnapDiff
 
       Utils.find_driver_class_for(driver_option).new
     end
+
+    # Canonical driver-class cache (ADR-008 step 5b, ex
+    # Capybara::Screenshot::Diff::LOADED_DRIVERS): driver name => driver
+    # class, filled lazily by Utils.find_driver_class_for. Mutated in
+    # place -- including by user registration through the legacy constant,
+    # which legacy_shims pins as an EAGER same-object alias of this hash
+    # (a lazy copy would silently drop such registrations).
+    def self.loaded
+      @loaded ||= {}
+    end
+
+    # Canonical read API for the detected-drivers list. The value itself
+    # stays on Capybara::Screenshot::Diff::AVAILABLE_DRIVERS (assigned in
+    # config_legacy.rb at load time, exactly when detection historically
+    # ran); this reads it live rather than caching, because that constant
+    # is the published stubbing point (image_compare_test stubs it to []
+    # to exercise the no-drivers error path).
+    def self.available
+      Capybara::Screenshot::Diff::AVAILABLE_DRIVERS
+    end
   end
 end

data/lib/snap_diff/dsl.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 # No require of "capybara_screenshot_diff" here: every Capybara::Screenshot
-# / CapybaraScreenshotDiff reference below is inside a method body, resolved
-# lazily at call time, not at this file's own load time -- so this unit has
-# no eager dependency on the umbrella entry point, and requiring it here
-# would create a require cycle back to capybara_screenshot_diff.rb (which
-# requires this file's old-path forwarder).
+# reference below is inside a method body, resolved lazily at call time, not
+# at this file's own load time -- so this unit has no eager dependency on
+# the umbrella entry point, and requiring it here would create a require
+# cycle back to capybara_screenshot_diff.rb (which requires this file's
+# old-path forwarder).
 # DSL includes Capybara::DSL directly below, so it needs the base gem
 # loaded regardless of what pulled this file in.
 require "capybara/dsl"
@@ -59,14 +59,14 @@ module SnapDiff
     # @option options [Numeric] :area_size_limit Maximum allowed difference area size in pixels.
     # @option options [Symbol] :driver (:auto) The image processing driver to use (:auto, :chunky_png, :vips).
     # @return [Boolean] True if the screenshot was successfully captured and processed.
-    # @raise [CapybaraScreenshotDiff::ExpectationNotMet] If comparison fails and immediate validation is enabled.
-    # @raise [CapybaraScreenshotDiff::UnstableImage] If the image comparison is unstable.
-    # @raise [CapybaraScreenshotDiff::WindowSizeMismatchError] If the window size doesn't match expectations.
+    # @raise [SnapDiff::ExpectationNotMet] If comparison fails and immediate validation is enabled.
+    # @raise [SnapDiff::UnstableImage] If the image comparison is unstable.
+    # @raise [SnapDiff::WindowSizeMismatchError] If the window size doesn't match expectations.
     def assert_matches_screenshot(name, skip_stack_frames: 0, **options)
       return false unless Capybara::Screenshot.active?
 
       # Get the full name with section and group information
-      full_name = CapybaraScreenshotDiff.screenshot_namer.full_name(name)
+      full_name = SnapDiff.session.screenshot_namer.full_name(name)
 
       # Build the screenshot assertion
       assertion = build_screenshot_assertion(full_name, options, skip_stack_frames: skip_stack_frames + 1)
@@ -77,7 +77,7 @@ module SnapDiff
       delayed = options.fetch(:delayed, Capybara::Screenshot::Diff.delayed)
 
       if delayed
-        CapybaraScreenshotDiff.add_assertion(assertion)
+        SnapDiff.session.add_assertion(assertion)
       else
         assertion.validate!
       end
@@ -104,7 +104,7 @@ module SnapDiff
     def capture_screenshot(name, **options)
       return false unless Capybara::Screenshot.active?
 
-      full_name = CapybaraScreenshotDiff.screenshot_namer.full_name(name)
+      full_name = SnapDiff.session.screenshot_namer.full_name(name)
       SnapDiff::ScreenshotMatcher.new(full_name, options).capture
 
       true
@@ -137,7 +137,7 @@ module SnapDiff
     end
 
     def screenshot_namer
-      CapybaraScreenshotDiff.screenshot_namer
+      SnapDiff.session.screenshot_namer
     end
   end
 end

data/lib/snap_diff/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "snap_diff/error_with_filtered_backtrace"
+
+# ADR-008 step 2: the gem's error classes live under SnapDiff. The old
+# CapybaraScreenshotDiff names (capybara_screenshot_diff.rb) are EAGER
+# same-object aliases of these classes -- deliberately not const_missing
+# shims, because rescue clauses and defined?/const_defined? feature
+# detection in adopter code must keep behaving exactly as before
+# (const_defined? never triggers const_missing).
+module SnapDiff
+  class Error < ErrorWithFilteredBacktrace; end
+
+  class ExpectationNotMet < Error; end
+
+  class UnstableImage < Error; end
+
+  class WindowSizeMismatchError < ErrorWithFilteredBacktrace; end
+end

data/lib/snap_diff/integrations/cucumber.rb

@@ -2,7 +2,8 @@
 
 # See the matching comment in integrations/minitest.rb.
 require_relative "../dsl"
-require "capybara_screenshot_diff/screenshot_assertion"
+require "snap_diff/screenshot_assertion"
+require "snap_diff/reporting"
 
 World(::SnapDiff::DSL)
 
@@ -12,11 +13,11 @@ Before do
 end
 
 After do |scenario|
-  if !scenario.failed? && (msg = CapybaraScreenshotDiff.pending_screenshots_message)
+  if !scenario.failed? && (msg = SnapDiff.pending_screenshots_message)
     skip_this_scenario(msg)
   end
 ensure
-  CapybaraScreenshotDiff.reset
+  SnapDiff.reset
 end
 
-AfterAll { CapybaraScreenshotDiff.finalize_reporters! }
+AfterAll { SnapDiff::Reporting.finalize! }

data/lib/snap_diff/integrations/minitest.rb

@@ -2,12 +2,11 @@
 
 require "minitest"
 require_relative "../dsl"
-# The CapybaraScreenshotDiff.verify/.reset/.pending_screenshots_message/
-# .finalize_reporters! calls below need the registry singleton machinery,
-# which lives in the *old* capybara_screenshot_diff/screenshot_assertion.rb
-# file (deliberately not moved -- see that file's own comment) and is no
-# longer pulled in transitively by requiring dsl.rb alone.
-require "capybara_screenshot_diff/screenshot_assertion"
+# SnapDiff.session/.reset/.pending_screenshots_message live in
+# snap_diff/screenshot_assertion, SnapDiff::Reporting.finalize! in
+# snap_diff/reporting -- neither is pulled in by requiring dsl.rb alone.
+require "snap_diff/screenshot_assertion"
+require "snap_diff/reporting"
 
 used_deprecated_entrypoint = caller.any? do |path|
   path.include?("capybara-screenshot-diff.rb") || path.include?("capybara/screenshot/diff.rb")
@@ -29,7 +28,7 @@ module SnapDiff
         self.assertions += 1
 
         super(*args, skip_stack_frames: skip_stack_frames + 1, **opts)
-      rescue ::CapybaraScreenshotDiff::ExpectationNotMet => e
+      rescue ::SnapDiff::ExpectationNotMet => e
         raise ::Minitest::Assertion, e.message
       end
 
@@ -40,18 +39,18 @@ module SnapDiff
 
       def before_teardown
         super
-        CapybaraScreenshotDiff.verify
+        SnapDiff.session.verify
 
         # Computed here (before teardown/reset), but the actual `skip` is
         # deferred to `after_teardown` so a real error raised by the user's
         # `teardown` isn't masked by a pending skip recorded before it ran.
-        @capybara_screenshot_diff_pending_message = CapybaraScreenshotDiff.pending_screenshots_message
-      rescue CapybaraScreenshotDiff::ExpectationNotMet => e
+        @capybara_screenshot_diff_pending_message = SnapDiff.pending_screenshots_message
+      rescue SnapDiff::ExpectationNotMet => e
         assertion = ::Minitest::Assertion.new(e)
         assertion.set_backtrace(e.backtrace)
         failures << assertion
       ensure
-        CapybaraScreenshotDiff.reset
+        SnapDiff.reset
       end
 
       def after_teardown
@@ -67,4 +66,4 @@ module SnapDiff
   end
 end
 
-::Minitest.after_run { CapybaraScreenshotDiff.finalize_reporters! } if ::Minitest.respond_to?(:after_run)
+::Minitest.after_run { SnapDiff::Reporting.finalize! } if ::Minitest.respond_to?(:after_run)

data/lib/snap_diff/integrations/rspec.rb

@@ -3,7 +3,8 @@
 require "rspec/core"
 require_relative "../dsl"
 # See the matching comment in integrations/minitest.rb.
-require "capybara_screenshot_diff/screenshot_assertion"
+require "snap_diff/screenshot_assertion"
+require "snap_diff/reporting"
 
 RSpec::Matchers.define :match_screenshot do |name, **options|
   description { "match screenshot '#{name}'" }
@@ -45,7 +46,7 @@ RSpec.configure do |config|
   config.append_after do |example|
     if self.class.include?(SnapDiff::DSL)
       begin
-        CapybaraScreenshotDiff.verify
+        SnapDiff.session.verify
 
         # Never mask a real failure with a pending marker. Kept as
         # defense-in-depth: `append_after` observes failures from plain
@@ -53,16 +54,16 @@ RSpec.configure do |config|
         # so a user `append_after` registered after this gem still runs
         # later than us — RSpec has no "run absolutely last" construct.
         # Mitigation for such consumers: require this gem last.
-        if example.exception.nil? && (msg = CapybaraScreenshotDiff.pending_screenshots_message)
+        if example.exception.nil? && (msg = SnapDiff.pending_screenshots_message)
           skip(msg)
         end
-      rescue CapybaraScreenshotDiff::ExpectationNotMet => e
+      rescue SnapDiff::ExpectationNotMet => e
         raise RSpec::Expectations::ExpectationNotMetError.new(e.message).tap { |ex| ex.set_backtrace(e.backtrace) }
       ensure
-        CapybaraScreenshotDiff.reset
+        SnapDiff.reset
       end
     end
   end
 
-  config.after(:suite) { CapybaraScreenshotDiff.finalize_reporters! }
+  config.after(:suite) { SnapDiff::Reporting.finalize! }
 end

data/lib/snap_diff/legacy_shims.rb

@@ -24,6 +24,14 @@ require "snap_diff/drivers"
 #   shared SnapDiff::Drivers module (the Drivers alias is same-object by
 #   contract), so const_missing can never fire for the leaf names;
 #   resolving them through the old path still warns for ...::Drivers.
+# - Diff::LOADED_DRIVERS: user code registers custom drivers by mutating
+#   this hash in place, so it must be the exact same object as the
+#   canonical SnapDiff::Drivers.loaded -- a lazy warn-once shim could not
+#   keep a mutable alias, and warning on a supported registration surface
+#   would be noise. Assigned eagerly below.
+# - Diff::AVAILABLE_DRIVERS: stays a real constant defined by
+#   config_legacy.rb (detection runs at that load moment);
+#   SnapDiff::Drivers.available is the canonical reader.
 module SnapDiff
   # @api private
   module LegacyShims
@@ -47,6 +55,11 @@ end
 module Capybara
   module Screenshot
     module Diff
+      # EAGER same-object alias of the canonical driver cache (see header).
+      LOADED_DRIVERS = SnapDiff::Drivers.loaded
+
+      module Reporters
+      end
     end
   end
 end
@@ -71,9 +84,14 @@ SnapDiff::LegacyShims.install(Capybara::Screenshot::Diff, "Capybara::Screenshot:
   ScreenshotMatcher: "SnapDiff::ScreenshotMatcher",
   Drivers: "SnapDiff::Drivers",
   ImageCompare: "SnapDiff::Comparison",
+  Comparison: "SnapDiff::Comparison::Images",
   Difference: "SnapDiff::ComparisonResult"
 }.freeze)
 
+SnapDiff::LegacyShims.install(Capybara::Screenshot::Diff::Reporters, "Capybara::Screenshot::Diff::Reporters", {
+  Default: "SnapDiff::Reporters::Default"
+}.freeze)
+
 SnapDiff::LegacyShims.install(CapybaraScreenshotDiff, "CapybaraScreenshotDiff", {
   RED_RGBA: "SnapDiff::RED_RGBA",
   ORANGE_RGBA: "SnapDiff::ORANGE_RGBA",

data/lib/snap_diff/region.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module SnapDiff
+  class Region
+    attr_accessor :x, :y, :width, :height
+
+    def initialize(x, y, width, height)
+      @x, @y, @width, @height = x, y, width, height
+    end
+
+    def self.from_edge_coordinates(left, top, right, bottom)
+      return nil unless left && top && right && bottom
+      return nil if right < left || bottom < top
+
+      Region.new(left, top, right - left, bottom - top)
+    end
+
+    def to_edge_coordinates
+      [left, top, right, bottom]
+    end
+
+    def to_top_left_corner_coordinates
+      [x, y, width, height]
+    end
+
+    def top
+      y
+    end
+
+    def bottom
+      y + height
+    end
+
+    def left
+      x
+    end
+
+    def right
+      x + width
+    end
+
+    def size
+      return 0 if width < 0 || height < 0
+
+      result = width * height
+      result.zero? ? 1 : result
+    end
+
+    def to_a
+      [@x, @y, @width, @height]
+    end
+
+    def find_intersect_with(region)
+      return nil unless intersect?(region)
+
+      new_left = [x, region.x].max
+      new_top = [y, region.y].max
+
+      Region.new(new_left, new_top, [right, region.right].min - new_left, [bottom, region.bottom].min - new_top)
+    end
+
+    def intersect?(region)
+      left <= region.right && right >= region.left && top <= region.bottom && bottom >= region.top
+    end
+
+    def move_by(right_by, down_by)
+      Region.new(x + right_by, y + down_by, width, height)
+    end
+
+    def find_relative_intersect(region)
+      intersect = find_intersect_with(region)
+      return nil unless intersect
+
+      intersect.move_by(-x, -y)
+    end
+
+    def cover?(x, y)
+      x.between?(left, right) && y.between?(top, bottom)
+    end
+
+    def empty?
+      width.zero? || height.zero?
+    end
+
+    def blank?
+      empty?
+    end
+
+    def present?
+      !empty?
+    end
+
+    def inspect
+      "Region(x: #{x}, y: #{y}, width: #{width}, height: #{height})"
+    end
+
+    # need to add this method to make it work with assert_equal
+    def ==(other)
+      case other
+      when Region
+        x == other.x && y == other.y && width == other.width && height == other.height
+      when Array
+        to_a == other
+      else
+        false
+      end
+    end
+  end
+end
+
+# Compatibility alias -- EAGER and same-object on purpose, mirroring the
+# ADR-008 step 2 rationale: user configs construct skip_area entries with
+# top-level `Region.new(...)` and SnapDiff internals check
+# `is_a?(SnapDiff::Region)`, so both names must be the exact same class;
+# and `defined?(Region)` feature detection must be truthy as soon as this
+# file loads (a lazy const_missing shim would return nil there).
+Region = SnapDiff::Region