snap_diff-capybara 2.0.0.beta1 → 2.0.0.beta2

data/lib/capybara/screenshot/diff/reporters/default.rb

@@ -1,109 +1,7 @@
 # frozen_string_literal: true
 
-require "snap_diff/annotation_service"
-# Defines the Capybara::Screenshot::Diff namespace this file reopens.
+# Forwarder (ADR-008 step 4): the default reporter lives at
+# SnapDiff::Reporters::Default; the old name now resolves lazily via
+# snap_diff/legacy_shims' const_missing, with a deprecation warning.
+require "snap_diff/reporters/default"
 require "snap_diff/legacy_shims"
-
-module Capybara::Screenshot::Diff
-  module Reporters
-    class Default
-      attr_reader :difference
-
-      def initialize(difference)
-        @difference = difference
-        @annotation_service = SnapDiff::AnnotationService.new(difference)
-      end
-
-      def annotated_image_path
-        annotation_service.annotated_image_path
-      end
-
-      def annotated_base_image_path
-        annotation_service.annotated_base_image_path
-      end
-
-      def heatmap_diff_path
-        annotation_service.heatmap_diff_path
-      end
-
-      def generate
-        if difference.equal?
-          # NOTE: Delete previous run runtime files
-          clean_tmp_files
-          return nil
-        end
-
-        if difference.failed? && difference.failed_by[:different_dimensions]
-          return build_error_for_different_dimensions
-        end
-
-        annotate_and_save_images
-        build_error_message
-      end
-
-      def clean_tmp_files
-        annotation_service.clean_tmp_files
-      end
-
-      def annotate_and_save_images
-        annotation_service.annotate_and_save_images
-      end
-
-      def save_annotation_for(image, image_path)
-        annotation_service.save_annotation_for(image, image_path)
-      end
-
-      def annotate_difference(image, region)
-        annotation_service.annotate_difference(image, region)
-      end
-
-      def annotate_skip_areas(image, skip_areas)
-        annotation_service.annotate_skip_areas(image, skip_areas)
-      end
-
-      def save(image, image_path)
-        annotation_service.save(image, image_path)
-      end
-
-      def build_error_for_different_dimensions
-        change_msg = [comparison.base_image, comparison.new_image]
-          .map { |image| driver.dimension(image).join("x") }
-          .join(" => ")
-
-        "Dimensions have changed: #{change_msg}\n#{base_image_path.to_path}\n#{image_path.to_path}"
-      end
-
-      NEW_LINE = "\n"
-
-      def build_error_message
-        [
-          "(#{difference.to_h.to_json})",
-          image_path.to_path,
-          annotated_base_image_path.to_path,
-          annotated_image_path.to_path,
-          heatmap_diff_path.to_path
-        ].join(NEW_LINE)
-      end
-
-      private
-
-      attr_reader :annotation_service
-
-      def base_image_path
-        comparison.base_image_path
-      end
-
-      def image_path
-        comparison.new_image_path
-      end
-
-      def driver
-        @_driver ||= comparison.driver
-      end
-
-      def comparison
-        @_comparison ||= difference.comparison
-      end
-    end
-  end
-end

data/lib/capybara_screenshot_diff/screenshot_assertion.rb

@@ -6,49 +6,37 @@ require "snap_diff/reporting"
 # warnings) via snap_diff/legacy_shims' const_missing since v2 step 6.
 require "snap_diff/legacy_shims"
 
-# CapybaraScreenshotDiff's module methods cover two lifecycles with
-# different scopes, kept separate below:
-#
-# - Session lifecycle: thread-local, per-test. The AssertionRegistry holds
-#   the assertions and screenshot names of the test running on this thread;
-#   `reset` clears it between tests.
-# - Reporter lifecycle: process-global, suite-long. Owned by
-#   SnapDiff::Reporting; the methods here are thin public shims over it.
-#
-# `reset` is the one deliberate bridge between the two: a finished test's
-# assertions are handed to the reporters before the registry is cleared.
+# Since ADR-008 step 6 every method here is a thin forwarder; the canonical
+# homes are SnapDiff (session lifecycle: per-test, `SnapDiff.session` and
+# friends) and SnapDiff::Reporting (reporter lifecycle: process-global,
+# suite-long). Names, arities and object identities are unchanged -- this
+# module stays as the compatibility surface for existing consumers.
 module CapybaraScreenshotDiff
   class << self
     require "forwardable"
     extend Forwardable
 
-    # --- Session lifecycle (thread-local, per-test) ---
+    # --- Session lifecycle (per-test) -> SnapDiff ---
 
     def registry
-      Thread.current[:capybara_screenshot_diff_registry] ||= SnapDiff::AssertionRegistry.new
+      SnapDiff.session
     end
 
     def_delegators :registry, :add_assertion, :assertions, :assertions_present?,
       :failed_assertions, :record_new_screenshot, :new_screenshots,
       :new_screenshots_present?, :screenshot_namer, :verify
 
+    # Written out rather than def_delegators so the arities stay 0 (a
+    # Forwardable-generated method takes *args, **kwargs, &block).
     def reset
-      notify_reporters(registry.assertions)
-      registry.reset
+      SnapDiff.reset
     end
 
-    # Message to skip the test with when a new screenshot has no baseline yet
-    # and `pending_if_new` is enabled. Adapters call this after verifying
-    # screenshots, and skip the test with the returned message when present.
-    #
-    # @return [String, nil] the pending message, or nil when there is nothing to report
     def pending_screenshots_message
-      return unless ::Capybara::Screenshot::Diff.pending_if_new && new_screenshots_present?
-
-      "No baseline for: #{new_screenshots.join(", ")}. Commit the captured screenshots to record them."
+      SnapDiff.pending_screenshots_message
     end
 
-    # --- Reporter lifecycle (process-global, suite-long) ---
+    # --- Reporter lifecycle (process-global, suite-long) -> SnapDiff::Reporting ---
 
     def reporters
       SnapDiff::Reporting.reporters

data/lib/capybara_screenshot_diff.rb

@@ -22,19 +22,25 @@ require "capybara/screenshot/diff/screenshot_matcher"
 require "capybara/screenshot/diff/reporters/default"
 
 require "capybara_screenshot_diff/error_with_filtered_backtrace"
+require "snap_diff/errors"
 
 module CapybaraScreenshotDiff
   # RED_RGBA / ORANGE_RGBA moved to SnapDiff (snap_diff/annotation_service)
   # so the bare "snap_diff" entry gets them too; the old names resolve via
   # snap_diff/legacy_shims with a deprecation warning.
 
-  class CapybaraScreenshotDiffError < SnapDiff::ErrorWithFilteredBacktrace; end
+  # ADR-008 step 2: the error classes moved to SnapDiff (snap_diff/errors).
+  # These are EAGER same-object aliases -- deliberately not const_missing
+  # shims -- so rescue-by-old-name and defined?/const_defined? feature
+  # detection keep working exactly as before (const_defined? never
+  # triggers const_missing).
+  CapybaraScreenshotDiffError = SnapDiff::Error
 
-  class ExpectationNotMet < CapybaraScreenshotDiffError; end
+  ExpectationNotMet = SnapDiff::ExpectationNotMet
 
-  class UnstableImage < CapybaraScreenshotDiffError; end
+  UnstableImage = SnapDiff::UnstableImage
 
-  class WindowSizeMismatchError < SnapDiff::ErrorWithFilteredBacktrace; end
+  WindowSizeMismatchError = SnapDiff::WindowSizeMismatchError
 end
 
 require "capybara_screenshot_diff/dsl"

data/lib/snap_diff/area_calculator.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-# Region has not moved yet (ADR-004 v2 scoping: it's already unnamespaced,
-# no v2.0 move needed).
-require "capybara/screenshot/diff/region"
+require "snap_diff/region"
 
 module SnapDiff
   class AreaCalculator

data/lib/snap_diff/browser_helpers.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-# Region has not moved yet (ADR-004 v2 scoping: it's already unnamespaced,
-# no v2.0 move needed) so this is an absolute require, not require_relative.
-require "capybara/screenshot/diff/region"
+require "snap_diff/region"
 
 module SnapDiff
   module BrowserHelpers

data/lib/snap_diff/capture/viewport.rb

@@ -9,24 +9,23 @@ module SnapDiff
     # Called exactly once per capture, before the screenshoter runs and outside
     # any stability retry loop. Today it only validates the window size
     # (raise-only, never resizes) — the same guard ScreenshotMatcher carried
-    # inline before. v3 hangs scroll-position preservation and element-anchored
-    # capture off this seam via the +anchor+ parameter without touching callers.
+    # inline before. When v3 adds scroll preservation / element-anchored
+    # capture it designs its own parameters here; adding an optional kwarg
+    # later is non-breaking, so none is reserved up front.
     module Viewport
       module_function
 
       # @param expected_window_size [Array(Integer, Integer), nil] the configured window size
-      # @param anchor [Object, nil] reserved for v3 (scroll preservation /
-      #   element-anchored capture); accepted but unused today.
-      # @raise [CapybaraScreenshotDiff::WindowSizeMismatchError] if the browser
+      # @raise [SnapDiff::WindowSizeMismatchError] if the browser
       #   window does not match the expected size.
-      def prepare!(expected_window_size, anchor: nil)
+      def prepare!(expected_window_size)
         return unless BrowserHelpers.window_size_is_wrong?(expected_window_size)
 
         current_size = BrowserHelpers.selenium? ?
           BrowserHelpers.session.driver.browser.manage.window.size.to_s :
           "unknown"
 
-        raise CapybaraScreenshotDiff::WindowSizeMismatchError.new(<<~ERROR.chomp, caller)
+        raise SnapDiff::WindowSizeMismatchError.new(<<~ERROR.chomp, caller)
           Window size mismatch detected!
           Expected: #{expected_window_size.inspect}
           Actual: #{current_size}

data/lib/snap_diff/comparison.rb

@@ -6,28 +6,7 @@ require "fileutils"
 require "snap_diff/comparison_result"
 require "snap_diff/drivers"
 require "snap_diff/image_preprocessor"
-require "capybara/screenshot/diff/reporters/default"
-
-# The internal images-holder struct and the driver cache keep their legacy
-# Capybara::Screenshot::Diff homes for now: SnapDiff::Comparison is the
-# comparison class below (ex-ImageCompare), so the struct cannot take the
-# same name. Its SnapDiff home arrives only when it is folded into
-# Comparison as a nested value (v2 design section 2) -- renaming it here
-# would exceed step 5's two approved renames.
-module Capybara
-  module Screenshot
-    module Diff
-      LOADED_DRIVERS = {}
-
-      # Holds the two images (and their paths/options/driver) being compared.
-      class Comparison < Struct.new(:new_image, :base_image, :options, :driver, :new_image_path, :base_image_path)
-        def skip_area
-          options[:skip_area]
-        end
-      end
-    end
-  end
-end
+require "snap_diff/reporters/default"
 
 module SnapDiff
   # Handles comparison of two images with a focus on performance and accuracy.
@@ -53,6 +32,14 @@ module SnapDiff
   # - Only performing expensive operations when absolutely necessary
   # - Maintaining high accuracy for complex comparisons
   class Comparison
+    # Holds the two images (and their paths/options/driver) being compared
+    # (ADR-008 step 5: ex-Capybara::Screenshot::Diff::Comparison struct).
+    Images = Struct.new(:new_image, :base_image, :options, :driver, :new_image_path, :base_image_path) do
+      def skip_area
+        options[:skip_area]
+      end
+    end
+
     TOLERABLE_OPTIONS = [:tolerance, :color_distance_limit, :shift_distance_limit, :area_size_limit].freeze
 
     attr_reader :driver, :driver_options
@@ -136,7 +123,7 @@ module SnapDiff
 
     def load_images_and_build_comparison(base_path, new_path, options)
       base_img, new_img = driver.load_images(base_path, new_path)
-      Capybara::Screenshot::Diff::Comparison.new(new_img, base_img, options, driver, new_path, base_path)
+      Images.new(new_img, base_img, options, driver, new_path, base_path)
     end
 
     def image_preprocessor
@@ -155,7 +142,7 @@ module SnapDiff
 
     # Analyzes the comparison and determines if images are different.
     #
-    # @param comparison [Capybara::Screenshot::Diff::Comparison] The comparison object containing images to analyze.
+    # @param comparison [Comparison::Images] The comparison object containing images to analyze.
     # @param quick_mode [Boolean] When true, performs minimal checks and returns early.
     #   In quick mode, returns [is_equal, difference] where:
     #   - is_equal is true if images are considered equal
@@ -195,7 +182,7 @@ module SnapDiff
 
     def build_reporter
       current_difference = difference || build_null_difference
-      Capybara::Screenshot::Diff::Reporters::Default.new(current_difference)
+      Reporters::Default.new(current_difference)
     end
 
     # Loads and preprocesses images for detailed comparison.
@@ -203,7 +190,7 @@ module SnapDiff
     # This method is responsible for:
     # 1. Loading both images using the configured driver
     # 2. Applying any necessary preprocessing (cropping, normalization)
-    # 3. Creating a Capybara::Screenshot::Diff::Comparison object that holds the image data
+    # 3. Creating a Comparison::Images object that holds the image data
     #
     # @param base_path [String,Pathname] Path to the baseline/reference image
     # @param new_path [String,Pathname] Path to the new/candidate image
@@ -211,7 +198,7 @@ module SnapDiff
     #   - :crop [Array<Integer>] Optional crop area [x, y, width, height]
     #   - :skip_area [Array<Array>] Areas to exclude from comparison
     #   - :tolerance [Numeric] Color tolerance threshold
-    # @return [Capybara::Screenshot::Diff::Comparison] Prepared comparison object ready for analysis
+    # @return [Comparison::Images] Prepared comparison object ready for analysis
     # @raise [ArgumentError] If image files are invalid or unreadable
     def load_comparison(base_path, new_path, options)
       comparison = load_images_and_build_comparison(base_path, new_path, options)
@@ -219,7 +206,7 @@ module SnapDiff
     end
 
     def build_null_difference(failed_by = nil)
-      comparison = Capybara::Screenshot::Diff::Comparison.new(nil, nil, driver_options, driver, image_path, base_image_path).freeze
+      comparison = Images.new(nil, nil, driver_options, driver, image_path, base_image_path).freeze
       ComparisonResult.build_null(comparison, base_image_path, image_path, failed_by)
     end
 

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