snap_diff-capybara 2.0.0.beta2 → 2.0.0.beta4

data/lib/snap_diff/screenshot_matcher.rb

@@ -1,27 +1,45 @@
 # frozen_string_literal: true
 
-require "capybara_screenshot_diff/snap_manager"
+require "snap_diff/removal"
+require "snap_diff/snap_manager"
 require_relative "screenshoter"
 require_relative "stable_screenshoter"
 require_relative "browser_helpers"
 require_relative "capture/viewport"
 require_relative "vcs"
 require_relative "area_calculator"
+require_relative "reporting"
 
 module SnapDiff
   class ScreenshotMatcher
-    attr_reader :screenshot_full_name, :driver_options, :screenshot_format
+    attr_reader :screenshot_full_name, :driver_options, :screenshot_format, :record_mode
 
     def initialize(screenshot_full_name, options = {})
       @screenshot_full_name = screenshot_full_name
-      @driver_options = Capybara::Screenshot::Diff.default_options.merge(options)
+      # BEFORE the merge below -- see SnapDiff.compare. Afterwards `:driver`
+      # is present for every caller and proves nothing.
+      Removal.warn_once(:driver_setting, Removal::DRIVER_REMOVED) if options.key?(:driver)
+      @driver_options = SnapDiff.config.default_options.merge(options)
+
+      # `record:` is a workflow mode, not a capture or comparison option, so
+      # it is carved out here rather than added to Comparison::KNOWN_OPTIONS
+      # -- a key that hash accepts and nothing downstream reads is the
+      # silent no-op ADR-010 forbids. Deleted before anything else touches
+      # the hash, so no later split has to know about it.
+      @record_mode = resolve_record_mode(@driver_options.delete(:record))
 
       @screenshot_format = @driver_options[:screenshot_format]
       @snapshot = SnapDiff::SnapManager.snapshot(screenshot_full_name, @screenshot_format)
     end
 
     def build_screenshot_assertion(skip_stack_frames: 0)
-      Capture::Viewport.prepare!(Capybara::Screenshot.window_size)
+      # Here rather than in #initialize, so it covers exactly the path where
+      # `:all` means anything. #capture never compares against a baseline, so
+      # the mode has nothing to say about it and refusing there would be a
+      # failure invented out of a setting that changes nothing.
+      refuse_bulk_record_under_ci! if record_mode == :all
+
+      Capture::Viewport.prepare!(SnapDiff.config.window_size)
       prepare_screenshot_options
       check_base_screenshot
 
@@ -29,10 +47,14 @@ module SnapDiff
 
       capture_screenshot(capture_options, comparison_options)
 
+      # AFTER the capture, so the path the message tells the user to
+      # `git add` is one that exists by the time they read it (#260).
+      fail_if_new_screenshot
+
       # Pre-computation: No need to compare without base screenshot
       # NOTE: Consider to return PreValid Assertion Value Object with hard coded valid result
       unless need_to_compare?
-        SnapDiff.session.record_new_screenshot(screenshot_full_name)
+        record_uncompared_screenshot
         return
       end
 
@@ -41,7 +63,7 @@ module SnapDiff
 
     # Captures a screenshot without comparing it to a baseline.
     def capture
-      Capture::Viewport.prepare!(Capybara::Screenshot.window_size)
+      Capture::Viewport.prepare!(SnapDiff.config.window_size)
       prepare_screenshot_options
 
       capture_options, comparison_options = extract_capture_and_comparison_options(driver_options)
@@ -52,10 +74,53 @@ module SnapDiff
 
     private
 
+    # The per-screenshot option outranks the configured mode, which in turn
+    # outranks `fail_if_new` (SnapDiff::Config#record). One resolution, so
+    # both routes to a mode agree about everything downstream.
+    def resolve_record_mode(per_screenshot)
+      SnapDiff::Config.validate_record_mode!(per_screenshot) || SnapDiff.config.record
+    end
+
+    # `:all` accepts every rendering as correct -- that is the feature. On
+    # CI there is nobody to review the result and the re-recorded files go
+    # away with the box, so a mode left in a committed config file buys a
+    # build that compares nothing and passes, forever. That is precisely how
+    # Percy goes green on a job that lost its token; refuse it rather than
+    # shipping our own version.
+    #
+    # A CI job that must record NEW baselines does not need `:all` at all:
+    # `record: :once` records them and still compares everything that has a
+    # baseline (docs/ci-integration.md).
+    def refuse_bulk_record_under_ci!
+      return if ENV["CI"].to_s.empty?
+
+      raise SnapDiff::ExpectationNotMet.new(<<~ERROR.chomp, caller)
+        `record: :all` re-records every baseline WITHOUT comparing, so it refuses to run under CI (ENV["CI"] is set).
+        Nothing would be verified and the recorded screenshots would be discarded with the runner.
+        Re-record locally, review the result, and commit the screenshots.
+        To let a CI job record screenshots that have no baseline yet: SnapDiff.config.record = :once
+      ERROR
+    end
+
+    # No `record_mode != :all` clause here on purpose: mutation testing
+    # showed one guards nothing. #check_base_screenshot already leaves `:all`
+    # with no base file at all, so this reads false for it either way, and a
+    # second condition that cannot fire is a second thing to keep true.
     def need_to_compare?
       @snapshot.base_path.exist?
     end
 
+    # `:all` re-records, so nothing was compared and nothing is "new" in the
+    # missing-baseline sense. Reported through its own channel, which counts
+    # only the screenshots that really went down this path.
+    def record_uncompared_screenshot
+      if record_mode == :all
+        SnapDiff::Reporting.record_rerecorded_baseline(screenshot_full_name)
+      else
+        SnapDiff.session.record_new_screenshot(screenshot_full_name)
+      end
+    end
+
     def prepare_screenshot_options
       area_calculator = AreaCalculator.new(driver_options.delete(:crop), driver_options[:skip_area])
 
@@ -64,23 +129,65 @@ module SnapDiff
       driver_options[:driver] = SnapDiff::Drivers.for(driver_options[:driver])
     end
 
+    # The git checkout that drives #need_to_compare?, plus the half of the
+    # no-baseline reporting that MUST run before the capture: it is the only
+    # moment at which `@snapshot.path` still tells us whether the user had a
+    # PNG sitting there already -- the case that confuses people most.
     def check_base_screenshot
+      # `:all` does not ask git for a baseline -- there is nothing to
+      # compare against. A `.base.<fmt>` left by an earlier failing run
+      # would otherwise sit beside the re-recorded screenshot and land in
+      # the user's `git add`.
+      return discard_base_screenshot if record_mode == :all
+
       @snapshot.checkout_base_screenshot
+      return if @snapshot.base_path.exist?
+      # fail_if_new_screenshot raises after the capture and says the same
+      # thing with the fix attached; two messages for one missing baseline
+      # is one too many.
+      return if record_mode == :none
 
-      if Capybara::Screenshot::Diff.fail_if_new && !@snapshot.base_path.exist?
-        raise SnapDiff::ExpectationNotMet.new(<<~ERROR.chomp, caller)
-          No existing screenshot found for #{@snapshot.base_path}!
-          To record baselines: RECORD_SCREENSHOTS=1 bundle exec rake test
-          To allow new screenshots: Capybara::Screenshot::Diff.fail_if_new = false
-        ERROR
-      end
+      warn_no_committed_baseline
+    end
+
+    def discard_base_screenshot
+      @snapshot.base_path.delete if @snapshot.base_path.exist?
+    end
+
+    # Runs AFTER the capture, so `@snapshot.path` names a file that is
+    # really there and `git add` on it is a command the user can run on this
+    # very test run (#260). Before, the raise came first and the screenshot
+    # was never written -- the instruction was unfollowable in CI, the one
+    # place fail_if_new is on by default.
+    def fail_if_new_screenshot
+      return if @snapshot.base_path.exist?
+      return unless record_mode == :none
+
+      raise SnapDiff::ExpectationNotMet.new(<<~ERROR.chomp, caller)
+        No existing screenshot found for #{@snapshot.path}!
+        To record it: `git add #{@snapshot.path}` and commit -- baselines are read from git.
+        To allow new screenshots: SnapDiff.config.record = :once (was: SnapDiff.config.fail_if_new = false)
+      ERROR
+    end
+
+    # `fail_if_new` defaults to false off CI, deliberately: a new screenshot
+    # must not break a local run. The cost is that nothing is compared and
+    # the test passes whatever the page looks like, while the capture
+    # overwrites the file on disk -- a green run that proves nothing. Say so
+    # once per screenshot, and name what to do about it.
+    def warn_no_committed_baseline
+      return unless SnapDiff::Reporting.record_missing_baseline(screenshot_full_name)
+
+      already_there = @snapshot.path.exist? ? " (the file already there is not a baseline until it is committed)" : ""
+      warn "[snap_diff] No committed baseline for #{@snapshot.path}#{already_there} -- nothing was compared. " \
+        "Commit it to enable comparison."
     end
 
     def capture_screenshot(capture_options, comparison_options)
       screenshoter = if capture_options[:stability_time_limit]
         StableScreenshoter.new(capture_options, comparison_options)
       else
-        Capybara::Screenshot::Diff.screenshoter.new(capture_options, comparison_options)
+        SnapDiff.config.screenshoter.new(capture_options, comparison_options)
       end
       screenshoter.take_comparison_screenshot(@snapshot)
     end

data/lib/snap_diff/screenshot_namer.rb

@@ -11,15 +11,10 @@ module SnapDiff
   class ScreenshotNamer
     attr_reader :section, :group
 
-    def initialize(screenshot_area = nil)
+    def initialize
       @section = nil
       @group = nil
       @counter = nil
-      @screenshot_area = screenshot_area
-    end
-
-    def screenshot_area
-      @screenshot_area ||= Capybara::Screenshot.screenshot_area
     end
 
     # Sets the current section for screenshots.
@@ -50,13 +45,6 @@ module SnapDiff
       File.join(*directory_parts.push(name.to_s))
     end
 
-    # Builds the full path for a screenshot file, including section and group directories.
-    # @param base_name [String] The base name for the screenshot.
-    # @return [String] The absolute path for the screenshot file.
-    def full_name_with_path(base_name)
-      File.join(screenshot_area, full_name(base_name))
-    end
-
     # Returns the directory parts (section and group) for constructing paths.
     # @return [Array<String>] An array of directory names.
     def directory_parts
@@ -66,12 +54,6 @@ module SnapDiff
       parts
     end
 
-    # Calculates the directory path for the current section and group.
-    # @return [String] The full path to the directory.
-    def current_group_directory
-      File.join(*([screenshot_area] + directory_parts))
-    end
-
     private
 
     def reset_group_counter

data/lib/snap_diff/screenshoter.rb

@@ -51,9 +51,7 @@ module SnapDiff
       screenshot_image = driver.from_file(stored_path)
 
       # TODO(uwe): Remove when chromedriver takes right size screenshots
-      # TODO: Adds tests when this case is true
       screenshot_image = resize_if_needed(screenshot_image) if selenium_with_retina_screen?
-      # ODOT
 
       screenshot_image = driver.crop(crop, screenshot_image) if crop
 
@@ -71,10 +69,10 @@ module SnapDiff
     def prepare_page_for_screenshot(timeout:)
       wait_images_loaded(timeout: timeout) if timeout
 
-      blurred_input = BrowserHelpers.blur_from_focused_element if Capybara::Screenshot.blur_active_element
+      blurred_input = BrowserHelpers.blur_from_focused_element if SnapDiff.config.blur_active_element
 
-      BrowserHelpers.hide_caret if Capybara::Screenshot.hide_caret
-      BrowserHelpers.disable_animations if Capybara::Screenshot.disable_animations
+      BrowserHelpers.hide_caret if SnapDiff.config.hide_caret
+      BrowserHelpers.disable_animations if SnapDiff.config.disable_animations
 
       blurred_input
     end
@@ -113,7 +111,7 @@ module SnapDiff
     end
 
     def resize_if_needed(saved_image)
-      expected_image_width = Capybara::Screenshot.window_size[0]
+      expected_image_width = SnapDiff.config.window_size[0]
       return saved_image if driver.width_for(saved_image) < expected_image_width * 2
 
       notice_how_to_avoid_this
@@ -123,7 +121,7 @@ module SnapDiff
     end
 
     def selenium_with_retina_screen?
-      Os::ON_MAC && BrowserHelpers.selenium? && Capybara::Screenshot.window_size
+      Os::ON_MAC && BrowserHelpers.selenium? && SnapDiff.config.window_size
     end
   end
 end

data/lib/snap_diff/snap.rb

@@ -20,8 +20,13 @@ module SnapDiff
       cleanup_attempts!
     end
 
+    # Records the successful checkout on the session, so that a LATER
+    # "there is no baseline" reading can be told apart from "there never
+    # was one". Only the second is a legitimate state (#217).
     def checkout_base_screenshot
-      @manager.checkout_file(path, base_path)
+      @manager.checkout_file(path, base_path).tap do |checked_out|
+        SnapDiff.session.record_baseline_checkout(full_name) if checked_out
+      end
     end
 
     def path_for(version = :actual)

data/lib/snap_diff/snap_manager.rb

@@ -55,7 +55,6 @@ module SnapDiff
       path ? path.dirname.mkpath : root.mkpath
     end
 
-    # TODO: rename to delete!
     def cleanup!
       snapshots.each do |snapshot|
         cleanup_attempts!(snapshot)
@@ -111,8 +110,8 @@ module SnapDiff
     # test/fixtures/app/doc/screenshots/ that VCS rollback just restored.
     # Do not reorder those teardowns without revisiting this.
     def self.instance
-      manager_class = Capybara::Screenshot::Diff.manager
-      root = Pathname.new(Capybara::Screenshot.screenshot_area_abs)
+      manager_class = SnapDiff.config.manager
+      root = Pathname.new(SnapDiff.config.screenshot_area_abs)
 
       current = Thread.current[:snap_diff_manager]
       unless current&.instance_of?(manager_class) && current.root == root

data/lib/snap_diff/stable_screenshoter.rb

@@ -12,7 +12,7 @@ module SnapDiff
     # `:stability_time_limit` and `:wait` in capture options and ensures that `:stability_time_limit` is less than or equal to `:wait`.
     #
     # @param capture_options [Hash] The options for capturing screenshots, must include `:stability_time_limit` and `:wait`.
-    # @param comparison_options [Hash] The options for comparing screenshots, defaults to `{}`. Same signature as {Capybara::Screenshot::Screenshoter#initialize}.
+    # @param comparison_options [Hash] The options for comparing screenshots, defaults to `{}`. Same signature as {SnapDiff::Screenshoter#initialize}.
     # @raise [ArgumentError] If `:wait` or `:stability_time_limit` are not provided, or if `:stability_time_limit` is greater than `:wait`.
     def initialize(capture_options, comparison_options = {})
       @stability_time_limit, @wait = capture_options.fetch_values(*STABILITY_OPTIONS)
@@ -23,7 +23,7 @@ module SnapDiff
 
       @comparison_options = comparison_options
 
-      @screenshoter = Capybara::Screenshot::Diff.screenshoter.new(capture_options.except(:stability_time_limit), @comparison_options)
+      @screenshoter = SnapDiff.config.screenshoter.new(capture_options.except(:stability_time_limit), @comparison_options)
     end
 
     # Takes a comparison screenshot ensuring page stability

data/lib/snap_diff/static.rb

@@ -6,6 +6,6 @@ require_relative "integrations/minitest"
 module SnapDiff
   def self.serve(directory, root: Dir.pwd)
     Capybara.app = Rack::Files.new(directory)
-    Capybara::Screenshot.root = root
+    SnapDiff.config.root = root
   end
 end

data/lib/snap_diff/utils.rb

@@ -1,30 +1,48 @@
 # frozen_string_literal: true
 
 require "snap_diff/drivers"
+require "snap_diff/removal"
 
 module SnapDiff
   module Utils
+    # THE selection funnel. Every surface that picks a driver ends up here --
+    # `driver: :chunky_png` per comparison, `SnapDiff.config.driver =`, the
+    # legacy `Diff.driver =` (a delegator onto the same storage), and `:auto`
+    # -- so this is the one place the chunky_png removal has to be announced
+    # from. Warned before the registry lookup, not inside it: the cache is a
+    # `||=`, so a hook there would fire only for the first comparison of a
+    # process that happened to miss.
+    CHUNKY_PNG_REMOVED =
+      "The chunky_png driver is REMOVED in 2.1, when libvips (the `ruby-vips` gem) becomes " \
+      "required. Install ruby-vips and drop `driver: :chunky_png`. See docs/drivers.md."
+
+    # The case that matters most: nobody asked for this driver, so the
+    # warning has to say why they are on it.
+    CHUNKY_PNG_AUTO_REMOVED =
+      "`driver: :auto` selected chunky_png because libvips is not available in this process. " \
+      "The chunky_png driver is REMOVED in 2.1, when libvips (the `ruby-vips` gem) becomes " \
+      "required -- install it now, or this setup stops comparing on 2.1. See docs/drivers.md."
+
+    # Detection itself lives on Drivers now (its canonical home -- so that
+    # `require "snap_diff/drivers"` standalone can answer .available); this
+    # keeps the documented Utils name working. One-way: Drivers never calls
+    # back here at load time, so requiring either file first is safe.
     def self.detect_available_drivers
-      result = []
-      begin
-        result << :vips if defined?(Vips) || require("vips")
-      rescue LoadError
-        # vips not present
-        Object.send(:remove_const, :Vips) if defined?(Vips)
-      end
-      begin
-        result << :chunky_png if defined?(ChunkyPNG) || require("chunky_png")
-      rescue LoadError
-        # chunky_png not present
-        Object.send(:remove_const, :ChunkyPNG) if defined?(ChunkyPNG)
-      end
-      result
+      Drivers.detect_available
     end
 
     def self.find_driver_class_for(driver)
-      driver = Drivers.available.first if driver == :auto
+      if driver == :auto
+        # Drivers::AVAILABLE_DRIVERS, not Drivers.available: same value and
+        # the same stubbing point, without the gem tripping .available's own
+        # removal warning on every comparison.
+        driver = Drivers::AVAILABLE_DRIVERS.first
+        Removal.warn_once(:chunky_png_auto, CHUNKY_PNG_AUTO_REMOVED) if driver == :chunky_png
+      elsif driver == :chunky_png
+        Removal.warn_once(:chunky_png, CHUNKY_PNG_REMOVED)
+      end
 
-      Drivers.loaded[driver] ||=
+      Drivers.registry[driver] ||=
         case driver
         when :chunky_png
           require "snap_diff/drivers/chunky_png_driver"
@@ -33,7 +51,7 @@ module SnapDiff
           require "snap_diff/drivers/vips_driver"
           SnapDiff::Drivers::VipsDriver
         else
-          fail "Wrong adapter #{driver.inspect}. Available adapters: #{Drivers.available.inspect}"
+          fail "Wrong adapter #{driver.inspect}. Available adapters: #{Drivers::AVAILABLE_DRIVERS.inspect}"
         end
     end
   end

data/lib/snap_diff/vcs.rb

@@ -5,23 +5,32 @@ require_relative "os"
 
 module SnapDiff
   module Vcs
+    # `-C <dir>` sets the working directory, but GIT_DIR/GIT_WORK_TREE OVERRIDE
+    # it -- so a suite launched from a git hook (which exports both) reads the
+    # WRONG repository. Every baseline lookup then fails, and because
+    # `fail_if_new` is false locally, screenshots are recorded as new and the
+    # tests PASS. Scrubbing them makes `-C` mean what this code already assumes.
+    GIT_ENV = {"GIT_DIR" => nil, "GIT_WORK_TREE" => nil, "GIT_INDEX_FILE" => nil}.freeze
+
+    @git_roots = {}
+    @git_roots_lock = Mutex.new
+
     def self.checkout_vcs(root, screenshot_path, checkout_path)
       root_path = root.to_s
-      git_root, _, status = Open3.capture3("git", "-C", root_path, "rev-parse", "--show-toplevel")
-      return false unless status.success?
+      git_root = git_root_for(root_path)
+      return false unless git_root
 
-      git_root = git_root.chomp
       vcs_file_path = Pathname.new(screenshot_path).expand_path.relative_path_from(Pathname.new(git_root)).to_s
 
-      if Capybara::Screenshot.use_lfs
+      if SnapDiff.config.use_lfs
         tmp_path = "#{checkout_path}.tmp"
-        success = system("git", "-C", root_path, "show", "HEAD:#{vcs_file_path}", out: tmp_path, err: File::NULL)
+        success = system(GIT_ENV, "git", "-C", root_path, "show", "HEAD:#{vcs_file_path}", out: tmp_path, err: File::NULL)
         if success
-          system("git", "-C", root_path, "lfs", "smudge", in: tmp_path, out: checkout_path.to_s, err: File::NULL)
+          system(GIT_ENV, "git", "-C", root_path, "lfs", "smudge", in: tmp_path, out: checkout_path.to_s, err: File::NULL)
         end
         File.delete(tmp_path) if File.exist?(tmp_path)
       else
-        success = system("git", "-C", root_path, "show", "HEAD:#{vcs_file_path}", out: checkout_path.to_s, err: File::NULL)
+        success = system(GIT_ENV, "git", "-C", root_path, "show", "HEAD:#{vcs_file_path}", out: checkout_path.to_s, err: File::NULL)
       end
 
       unless success
@@ -31,5 +40,29 @@ module SnapDiff
 
       true
     end
+
+    # `git rev-parse --show-toplevel` costs a process spawn (~6ms) and used to
+    # run once per screenshot -- 200 screenshots, 200 spawns, all answering the
+    # same question. The repository a directory belongs to does not change
+    # while the suite runs, so remember it per directory. `false` (not a repo)
+    # is remembered too: that is the every-assertion answer for anyone whose
+    # screenshots live outside a git checkout.
+    #
+    # Synchronized because the lookup itself is what must not be duplicated:
+    # MRI releases the GVL for the whole of `Open3.capture3`, so eight threads
+    # asking about one root all miss `key?` before any of them writes -- eight
+    # spawns, the exact cost this cache exists to remove. Threads are the
+    # default parallel mode on JRuby, which has no GVL to make the Hash write
+    # safe either. Holding the lock across the spawn is deliberate: callers
+    # almost always share one root, so the other threads wait once and then
+    # read the cache, which is the outcome we want.
+    def self.git_root_for(root_path)
+      @git_roots_lock.synchronize do
+        next @git_roots[root_path] if @git_roots.key?(root_path)
+
+        git_root, _, status = Open3.capture3(GIT_ENV, "git", "-C", root_path, "rev-parse", "--show-toplevel")
+        @git_roots[root_path] = status.success? && git_root.chomp
+      end
+    end
   end
 end

data/lib/snap_diff/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SnapDiff
-  VERSION = "2.0.0.beta2"
+  VERSION = "2.0.0.beta4"
 end

data/lib/snap_diff-capybara.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Bundler.require entry point for `gem "snap_diff-capybara"`: Bundler
+# requires the gem's own name, and its dash->slash fallback ("snap_diff/
+# capybara") misses too, so without this file a Rails user gets a silent
+# no-op and a confusing NameError later. The sibling
+# capybara-screenshot-diff.rb is the same door under the v1 gem name and
+# forwards here.
+#
+# Everything below therefore loads for EVERY consumer, RSpec and Cucumber
+# users included, so nothing outside the gem's declared runtime dependencies
+# may be hard-required. minitest is not one of them -- the gemspec declares
+# capybara only -- and requiring it here killed an RSpec-only bundle at boot
+# with `cannot load such file -- minitest`, from a gem that ships a
+# first-class RSpec integration.
+#
+# So: load the gem, then feature-detect minitest. Present is the documented
+# zero-require Rails path and still activates the assertions. Absent gets a
+# line saying so -- a gem that loads and then does nothing, silently, is its
+# own bug report.
+# This IS the canonical door, and it loads the v1 umbrella below -- so claim
+# the process before that require, or every canonical user is told to
+# migrate off an API they never touched.
+require "snap_diff/deprecation"
+SnapDiff::Deprecation.canonical_entry_point!
+
+require "capybara_screenshot_diff"
+
+begin
+  require "minitest"
+rescue LoadError
+  warn "[snap_diff] minitest is not in this bundle, so `Bundler.require` activated no test-framework " \
+    "integration. Require the one you use -- `require \"snap_diff/integrations/rspec\"` or " \
+    "`require \"snap_diff/integrations/cucumber\"` -- and set `require: false` on the gem in your " \
+    "Gemfile to silence this. See docs/framework-setup.md."
+end
+
+require "capybara_screenshot_diff/minitest" if defined?(::Minitest)

data/lib/snap_diff.rb

@@ -6,8 +6,14 @@
 # undetectable. Refuse that setup at the entry point. Local dev from
 # source loads neither spec, so the guard fires only when both are
 # genuinely installed as gems.
+#
+# snap_diff/errors is pulled in first (two dependency-free files) so
+# DualInstallError can sit under SnapDiff::Error like every other error the
+# gem raises -- docs/snapdiff.md promises Error is the catch-all.
+require "snap_diff/errors"
+
 module SnapDiff
-  DualInstallError = Class.new(StandardError)
+  DualInstallError = Class.new(Error)
 
   # @api private
   def self.assert_single_gem!(loaded_specs = Gem.loaded_specs)
@@ -21,59 +27,54 @@ module SnapDiff
 end
 SnapDiff.assert_single_gem!
 
-# None of these requires ever leads back to this file: config_legacy sits
-# just above the snap_diff/config leaf (see both headers -- since ADR-008
-# step 1 the storage leaf is snap_diff/config, which config_legacy
-# requires), the image_compare forwarder pulls in
-# snap_diff/comparison plus the legacy const_missing shims, and
-# "capybara/dsl" is the base gem. That keeps this file's require graph
-# acyclic -- it never requires "capybara_screenshot_diff" back, unlike the
-# old autoload-based wiring this replaced. The forwarder path (not
-# "snap_diff/comparison" directly) is deliberate: it installs
-# snap_diff/legacy_shims, so the old Capybara::Screenshot::Diff constants
-# stay resolvable (now with deprecation warnings) even in processes that
-# only ever require "snap_diff".
+# This lean entry must never load the umbrella "capybara_screenshot_diff"
+# -- snap_diff_test.rb's "bare require never loads the umbrella" guard
+# enforces it -- so nothing required below may reach back here. None of
+# these requires reaches into lib/capybara* at all, so the canonical entry
+# point is exactly what 3.0 keeps.
+#
 # "capybara/dsl" is needed directly (not just transitively) so
 # `Capybara.default_max_wait_time` in Config#default_options resolves even
 # when "snap_diff" is required standalone (SnapDiffTest's
 # "standalone-loadable in a fresh process" regression test).
+#
+# snap_diff/legacy_shims is deliberate and is the ONE line here that 3.0
+# drops: it carries the whole v1 surface (const_missing forwarders, the old
+# mattr_accessors, SnapDiff.start), so a process that only ever requires
+# "snap_diff" still resolves the old Capybara::Screenshot::Diff names --
+# with deprecation warnings -- exactly as it did when this file reached
+# through the capybara/screenshot/diff/* forwarders to get them.
 require "capybara/dsl"
-require "capybara/screenshot/diff/config_legacy"
-require "capybara/screenshot/diff/image_compare"
-require "snap_diff/errors"
 require "snap_diff/config"
+require "snap_diff/comparison"
+require "snap_diff/legacy_shims"
+require "snap_diff/version"
+# SnapDiff.session/.reset/.pending_screenshots_message are part of the
+# documented core surface (docs/snapdiff.md object map lists them with no
+# extra require), so the entry point owns them rather than leaving them to
+# whichever integration happens to be loaded.
+require "snap_diff/screenshot_assertion"
 
-# Forward-looking namespace for the gem, per ADR-004.
-#
-# Since v2 step 5 the comparison implementation lives here
-# ({SnapDiff::Comparison}, {SnapDiff::ComparisonResult}); since step 6 the
-# old +Capybara::Screenshot::Diff+ constants are same-object const_missing
-# shims (snap_diff/legacy_shims) that emit a deprecation warning once per
-# constant per process. See ADR-004 for the full migration plan.
+# The canonical namespace for the gem. The old
+# +Capybara::Screenshot::Diff+ constants are same-object const_missing shims
+# (snap_diff/legacy_shims) that warn once per constant per process.
 module SnapDiff
-  # Compare two images on disk with the configured defaults. Canonical home
-  # since ADR-008 step 7b; +Capybara::Screenshot::Diff.compare+ now forwards
-  # here rather than the other way round.
+  # Compare two images on disk with the configured defaults. Canonical home;
+  # +Capybara::Screenshot::Diff.compare+ forwards here.
   #
   # Note the argument order swap: callers pass baseline first (reading
   # "compare baseline against current"), Comparison takes current first.
   def self.compare(baseline_path, current_path, **options)
+    # BEFORE the merge, which is the last moment `driver:` still means "the
+    # caller asked for a backend" rather than "config.default_options
+    # carries the key for everyone".
+    Removal.warn_once(:driver_setting, Removal::DRIVER_REMOVED) if options.key?(:driver)
     Comparison.new(current_path, baseline_path, config.default_options.merge(options))
   end
 
-  # v1-style configuration: yields the two legacy accessor holders
-  # (+Capybara::Screenshot+, +Capybara::Screenshot::Diff+) exactly as
-  # +Capybara::Screenshot::Diff.configure+ always has -- and, since ADR-008
-  # step 7b, this is where that yield actually happens; Diff.configure
-  # forwards here. Both names stay identical in call shape.
-  #
-  #   SnapDiff.start do |screenshot, diff|
-  #     screenshot.window_size = [1280, 1024]
-  #     diff.tolerance = 0.0005
-  #   end
-  def self.start
-    yield Capybara::Screenshot, Capybara::Screenshot::Diff
-  end
+  # SnapDiff.start -- the v1-shaped two-holder config block -- is defined in
+  # snap_diff/legacy_shims (required above), because the holders it yields
+  # are the v1 surface and it cannot outlive them.
 
   # Forward-looking configuration: yields the single consolidated
   # {SnapDiff::Config} object instead of the two old holders. Same