snap_diff-capybara 2.0.0.beta2 → 2.0.0.beta4

data/lib/capybara_screenshot_diff.rb

@@ -1,5 +1,12 @@
 # frozen_string_literal: true
 
+# The v1 umbrella, and the file every legacy entry point except
+# capybara_screenshot_diff/dsl reaches. Marked here rather than in each of
+# them; snap_diff-capybara.rb (which loads this umbrella for canonical
+# users) claims the process first, so this stays quiet for them.
+require "snap_diff/deprecation"
+SnapDiff::Deprecation.legacy_entry_point!
+
 require "capybara/dsl"
 require "capybara/screenshot/diff/config_legacy"
 require "capybara/screenshot/diff/version"
@@ -24,24 +31,15 @@ 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.
-
-  # 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
-
-  ExpectationNotMet = SnapDiff::ExpectationNotMet
-
-  UnstableImage = SnapDiff::UnstableImage
-
-  WindowSizeMismatchError = SnapDiff::WindowSizeMismatchError
-end
+# 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.
+#
+# The four error classes (CapybaraScreenshotDiffError, ExpectationNotMet,
+# UnstableImage, WindowSizeMismatchError) used to be assigned here as EAGER
+# same-object aliases. They still are eager -- just from
+# snap_diff/legacy_shims, so a canonical-only require gets them too.
+require "snap_diff/legacy_shims"
 
 require "capybara_screenshot_diff/dsl"
 
@@ -50,7 +48,5 @@ require "capybara_screenshot_diff/dsl"
 # any registered `autoload :SnapDiff` before it ever fires (Ruby resolves
 # the constant the first time anything reopens it, autoload or not) --
 # so SnapDiff.start/.compare/.config would silently never be defined
-# without this. Safe to do eagerly, unlike before this file's units
-# moved: snap_diff.rb no longer requires this file back (it only needs
-# the leaf config_legacy.rb + image_compare.rb), so there is no cycle.
+# without this. Safe eagerly: snap_diff.rb never requires this file back.
 require "snap_diff"

data/lib/snap_diff/browser_helpers.rb

@@ -1,13 +1,16 @@
 # frozen_string_literal: true
 
 require "snap_diff/region"
+require "snap_diff/reporting"
 
 module SnapDiff
   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
+      # The respond_to? guard this replaced existed because the legacy
+      # mattr_accessor might not be installed yet; Config always has the
+      # attribute, so only the value matters now.
+      window_size = SnapDiff.config.window_size
+      resize_to(window_size) if window_size
     end
 
     def self.resize_to(window_size)
@@ -27,9 +30,16 @@ module SnapDiff
         session.driver.browser.manage.window.size != ::Selenium::WebDriver::Dimension.new(*expected_window_size)
     end
 
+    # The one seam that knows, per selector, whether it found anything --
+    # `all_visible_regions_for` is called once per selector and the caller
+    # gets back one flattened list. The run-level tally is fed here (#277b)
+    # rather than in AreaCalculator for exactly that reason: by the time
+    # the regions are concatenated the attribution is gone.
     def self.bounds_for_css(*css_selectors)
       css_selectors.reduce([]) do |regions, selector|
-        regions.concat(all_visible_regions_for(selector))
+        found = all_visible_regions_for(selector)
+        SnapDiff::Reporting.record_selector_use(selector, matched: !found.empty?)
+        regions.concat(found)
       end
     end
 
@@ -96,8 +106,19 @@ module SnapDiff
       ]
     JS
 
+    # `minimum: 0` is load-bearing (issue #272). Capybara's `all` defaults to
+    # `minimum: 1` and blocks in `synchronize` until the count is satisfied,
+    # so every `skip_area`/`crop` selector matching nothing burned a full
+    # `Capybara.default_max_wait_time` -- 5s by default, per selector, per
+    # screenshot. One project measured `%w[picture img]` on an image-less
+    # page at 10s per screenshot, 44% of their suite.
+    #
+    # Waiting is the wrong semantic here regardless of the cost: these
+    # selectors describe a MASK over whatever is currently on the page. A
+    # selector that matches nothing has nothing to mask, and that answer is
+    # available immediately.
     def self.all_visible_regions_for(selector)
-      BrowserHelpers.session.all(selector, visible: true).map { |el| region_for(el) }
+      BrowserHelpers.session.all(selector, visible: true, minimum: 0).map { |el| region_for(el) }
     end
 
     def self.region_for(element)

data/lib/snap_diff/capture/viewport.rb

@@ -7,11 +7,8 @@ module SnapDiff
     # Per-capture viewport preparation seam.
     #
     # 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. 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.
+    # any stability retry loop. It only validates the window size
+    # (raise-only, never resizes).
     module Viewport
       module_function
 

data/lib/snap_diff/comparison.rb

@@ -6,6 +6,7 @@ require "fileutils"
 require "snap_diff/comparison_result"
 require "snap_diff/drivers"
 require "snap_diff/image_preprocessor"
+require "snap_diff/removal"
 require "snap_diff/reporters/default"
 
 module SnapDiff
@@ -42,6 +43,31 @@ module SnapDiff
 
     TOLERABLE_OPTIONS = [:tolerance, :color_distance_limit, :shift_distance_limit, :area_size_limit].freeze
 
+    # Every key anything downstream of here actually reads -- capture
+    # options included, because ScreenshotMatcher hands the same hash to the
+    # screenshoter and only carves :crop / :stability_time_limit / :wait out
+    # of the copy it passes on.
+    #
+    # Written out rather than derived from Config#default_options: that hash
+    # is what the gem merges in, so deriving from it would make the check
+    # agree with itself and validate nothing about the keys a USER adds.
+    KNOWN_OPTIONS = %i[
+      area_size_limit
+      capybara_screenshot_options
+      color_distance_limit
+      crop
+      delayed
+      driver
+      median_filter_window_size
+      perceptual_threshold
+      screenshot_format
+      shift_distance_limit
+      skip_area
+      stability_time_limit
+      tolerance
+      wait
+    ].freeze
+
     attr_reader :driver, :driver_options
     attr_reader :image_path, :base_image_path
     attr_reader :difference, :error_message
@@ -53,6 +79,20 @@ module SnapDiff
       ensure_files_exist!
 
       @driver_options = options.freeze
+      # THE no-silent-no-op check (ADR-010). Every option hash in the gem
+      # reaches this constructor, so a key nothing reads is caught here
+      # whichever entry point produced it. Frozen-but-unvalidated is how a
+      # misspelt `tolerence:` bought a green suite that compared nothing.
+      (options.keys - KNOWN_OPTIONS).each do |key|
+        Removal.warn_once(:"unknown_option_#{key}", Removal.unknown_option(key))
+      end
+      # The per-comparison half of the shift_distance_limit removal (the
+      # global half is Config#shift_distance_limit=). Presence is not enough:
+      # config.default_options carries the key on EVERY comparison, nil for
+      # everyone who never set it.
+      if options[:shift_distance_limit]
+        Removal.warn_once(:shift_distance_limit, Removal::SHIFT_DISTANCE_LIMIT_REMOVED)
+      end
       @driver = Drivers.for(@driver_options)
       @without_tolerable_options = (driver_options.keys & TOLERABLE_OPTIONS).empty?
     end
@@ -68,9 +108,7 @@ module SnapDiff
     #
     # @note This method will raise ArgumentError if either image file is missing.
     def quick_equal?
-      if base_image_path.size == image_path.size
-        return true if files_identical?(base_image_path, image_path)
-      end
+      return true if identical_files?
 
       result, difference = find_difference(quick_mode: true)
       self.difference = difference
@@ -134,6 +172,13 @@ module SnapDiff
       # Validate images exist
       return build_null_difference("missing_image") unless images_exist?
 
+      # Step 1 of the layered strategy documented on this class: byte-identical
+      # files cannot have different pixels. quick_equal? has always checked
+      # this; the full path did not, and paid a decode of BOTH PNGs (11ms at
+      # 1440x900, 25ms at 2880x1800) to reach the same "no difference" answer
+      # on every screenshot that matches its baseline byte for byte.
+      return build_null_difference if !quick_mode && identical_files?
+
       # Create comparison with preprocessed images
       comparison = load_comparison(base_image_path, image_path, driver_options)
 
@@ -215,6 +260,12 @@ module SnapDiff
       base_image_path.exist? && image_path.exist?
     end
 
+    # Are the two screenshots the same bytes? Sizes first: a stat each rules
+    # out most pairs without reading either file.
+    def identical_files?
+      base_image_path.size == image_path.size && files_identical?(base_image_path, image_path)
+    end
+
     # Check if files are identical by content
     def files_identical?(file1, file2)
       FileUtils.compare_file(file1, file2)

data/lib/snap_diff/comparison_result.rb

@@ -67,8 +67,10 @@ module SnapDiff
       meta[:difference_level]
     end
 
+    # Serializable difference metrics. The raw diff mask image is excluded —
+    # it is an image object, not a metric, and is reachable via #diff_mask.
     def to_h
-      {area_size: region_area_size, region: coordinates}.merge!(meta)
+      {area_size: region_area_size, region: coordinates}.merge!(meta.except(:diff_mask))
     end
 
     def coordinates

data/lib/snap_diff/config.rb

@@ -4,21 +4,15 @@ 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
+# anything that leads back to either entry point. It also names nothing from
+# the v1 trees at all (3.0 readiness): which legacy accessor each setting is
+# exposed as is snap_diff/legacy_shims' business, and that file is deleted
+# together with lib/capybara* -- see LegacyShims::CONFIG_MAPPING.
 
 # 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/removal"
 require "snap_diff/screenshoter"
 require "snap_diff/snap_manager"
 
@@ -30,71 +24,101 @@ module SnapDiff
   # 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.
+  # delegators generated by snap_diff/legacy_shims from its CONFIG_MAPPING
+  # -- one storage, two views, so a write through either surface is visible
+  # through the other structurally, not by synchronization.
   #
   # 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+.
+  # every stored 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 +root+ (from +Rails.root+ / pwd) must never become a
+  # lazy read-time default, memoized or not.
+  #
+  # Two values are deliberately LIVE and are not storage at all:
+  # +default_options[:wait]+ stays a method-body read of
+  # +Capybara.default_max_wait_time+ in +#default_options+, and
+  # +fail_if_new+ falls back to <tt>ENV["CI"]</tt> in its reader whenever
+  # nothing explicit was set -- see {#fail_if_new} for why freezing that
+  # sniff into storage let the environment outrank the user.
   class Config
-    # config attr name => [legacy module, legacy accessor name].
+    # Every setting this object stores, in the order the two legacy holders
+    # used to declare them.
     #
-    # The two names differ only for +screenshot_enabled+:
-    # +Capybara::Screenshot.enabled+ and +Capybara::Screenshot::Diff.enabled+
-    # are independent settings (see +Capybara::Screenshot.active?+, which
-    # reads both) that happen to share a bare name in their own modules. A
-    # flat Config can't expose two attributes both called +enabled+, so the
-    # Screenshot-side one is renamed here; Diff's keeps the bare +enabled+
-    # name since it's the one most existing configuration touches directly.
-    MAPPING = {
-      # Capybara::Screenshot
-      add_driver_path: [Capybara::Screenshot, :add_driver_path],
-      add_os_path: [Capybara::Screenshot, :add_os_path],
-      blur_active_element: [Capybara::Screenshot, :blur_active_element],
-      screenshot_enabled: [Capybara::Screenshot, :enabled],
-      hide_caret: [Capybara::Screenshot, :hide_caret],
-      disable_animations: [Capybara::Screenshot, :disable_animations],
-      root: [Capybara::Screenshot, :root],
-      stability_time_limit: [Capybara::Screenshot, :stability_time_limit],
-      window_size: [Capybara::Screenshot, :window_size],
-      save_path: [Capybara::Screenshot, :save_path],
-      use_lfs: [Capybara::Screenshot, :use_lfs],
-      screenshot_format: [Capybara::Screenshot, :screenshot_format],
-      capybara_screenshot_options: [Capybara::Screenshot, :capybara_screenshot_options],
-      # Capybara::Screenshot::Diff
-      delayed: [Capybara::Screenshot::Diff, :delayed],
-      area_size_limit: [Capybara::Screenshot::Diff, :area_size_limit],
-      fail_if_new: [Capybara::Screenshot::Diff, :fail_if_new],
-      pending_if_new: [Capybara::Screenshot::Diff, :pending_if_new],
-      fail_on_difference: [Capybara::Screenshot::Diff, :fail_on_difference],
-      color_distance_limit: [Capybara::Screenshot::Diff, :color_distance_limit],
-      enabled: [Capybara::Screenshot::Diff, :enabled],
-      shift_distance_limit: [Capybara::Screenshot::Diff, :shift_distance_limit],
-      skip_area: [Capybara::Screenshot::Diff, :skip_area],
-      driver: [Capybara::Screenshot::Diff, :driver],
-      tolerance: [Capybara::Screenshot::Diff, :tolerance],
-      perceptual_threshold: [Capybara::Screenshot::Diff, :perceptual_threshold],
-      screenshoter: [Capybara::Screenshot::Diff, :screenshoter],
-      manager: [Capybara::Screenshot::Diff, :manager]
-    }.freeze
-
-    attr_accessor(*(MAPPING.keys - [:root]))
-    attr_reader :root
+    # +screenshot_enabled+ is the one name that differs from its legacy
+    # spelling: +Capybara::Screenshot.enabled+ and
+    # +Capybara::Screenshot::Diff.enabled+ are independent settings (see
+    # {#active?}, which reads both) that happened to share a bare name in
+    # their own modules. A flat Config can't expose two attributes both
+    # called +enabled+, so the Screenshot-side one is renamed here; Diff's
+    # keeps the bare +enabled+ name since it's the one most existing
+    # configuration touches directly.
+    SETTINGS = %i[
+      add_driver_path
+      add_os_path
+      blur_active_element
+      screenshot_enabled
+      hide_caret
+      disable_animations
+      root
+      stability_time_limit
+      window_size
+      save_path
+      use_lfs
+      screenshot_format
+      capybara_screenshot_options
+      delayed
+      area_size_limit
+      record
+      fail_if_new
+      pending_if_new
+      fail_on_difference
+      color_distance_limit
+      enabled
+      shift_distance_limit
+      skip_area
+      driver
+      tolerance
+      perceptual_threshold
+      screenshoter
+      manager
+    ].freeze
+
+    # The record modes, in the order they escalate: do nothing new, refuse
+    # to record, record everything. See {#record}.
+    RECORD_MODES = %i[once none all].freeze
+
+    # @api private
+    #
+    # Shared by {#record=} and the per-screenshot `record:` option, which is
+    # resolved in {SnapDiff::ScreenshotMatcher}. A misspelt mode must not
+    # read back as "nobody said" and silently mean today's behaviour --
+    # that is the exact silent no-op ADR-010 exists to stop.
+    def self.validate_record_mode!(mode)
+      return mode if mode.nil? || RECORD_MODES.include?(mode)
+
+      raise ArgumentError,
+        "unknown record mode #{mode.inspect} -- one of #{RECORD_MODES.map(&:inspect).join(", ")} (or nil)"
+    end
+
+    # shift_distance_limit, driver and the three older new-screenshot
+    # booleans are excluded from the generated writers and hand written
+    # below (they announce their 2.1 removal, or validate); fail_if_new and
+    # record are excluded from the generated READER (both fall back rather
+    # than returning storage). Generating them here too would print Ruby's
+    # "method redefined" warning on every load.
+    attr_accessor(*(SETTINGS - %i[
+      root shift_distance_limit driver record fail_if_new pending_if_new fail_on_difference
+    ]))
+    attr_reader :root, :shift_distance_limit, :driver, :pending_if_new, :fail_on_difference
 
     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) }
+      # Every 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.
+      SETTINGS.each { |key| instance_variable_set(:"@#{key}", nil) }
       # Capybara::Screenshot side.
       @blur_active_element = true
       @hide_caret = true
@@ -106,7 +130,7 @@ module SnapDiff
       @capybara_screenshot_options = {}
       # Capybara::Screenshot::Diff side.
       @delayed = true
-      @fail_if_new = !ENV["CI"].nil? && !ENV["CI"].empty?
+      # No stored default for fail_if_new on purpose -- see the reader.
       @pending_if_new = false
       @fail_on_difference = true
       @enabled = true
@@ -119,12 +143,105 @@ module SnapDiff
       @root = Pathname(path).expand_path
     end
 
+    # An explicit setting outranks the environment. nil means nobody said,
+    # and only then does the CI sniff answer -- read live, so a CI variable
+    # that appears at any point is honoured, not just one that happened to
+    # be exported before the gem was required. Assigning nil hands the
+    # setting back to the environment.
+    #
+    # This is a precedence rule, not a change of default: failing only under
+    # CI stays (a locally recorded baseline is often worthless across OS).
+    # Storing the sniff instead, as this did, made the two indistinguishable
+    # -- `fail_if_new = false` and "CI was absent at require time" were the
+    # same false, so the environment could win. Same fix as insta#924
+    # ("normally, CLI flags take precedence over environment variables") and
+    # the inverse of jest#12288.
+    def fail_if_new
+      @fail_if_new.nil? ? !ENV["CI"].to_s.empty? : @fail_if_new
+    end
+
+    # Announces the 2.1 removal. The writer, not the reader: {#record} reads
+    # +fail_if_new+ on every screenshot for everyone, and #initialize stores
+    # no default at all, so only a user who sets it hears about it.
+    def fail_if_new=(value)
+      Removal.warn_once(:fail_if_new, Removal::FAIL_IF_NEW_REMOVED)
+      @fail_if_new = value
+    end
+
+    # Same shape, same reason: SnapDiff.pending_screenshots_message reads
+    # this for everyone, and #initialize seeds the +false+ default straight
+    # into the ivar.
+    def pending_if_new=(value)
+      Removal.warn_once(:pending_if_new, Removal::PENDING_IF_NEW_REMOVED)
+      @pending_if_new = value
+    end
+
+    # Same: ScreenshotAssertion.verify_screenshots! reads it once per test
+    # for everyone, and #initialize seeds the +true+ default.
+    def fail_on_difference=(value)
+      Removal.warn_once(:fail_on_difference, Removal::FAIL_ON_DIFFERENCE_REMOVED)
+      @fail_on_difference = value
+    end
+
+    # THE ACCEPT WORKFLOW (#259). What to do about a screenshot whose
+    # baseline is missing -- or, for +:all+, about every screenshot there
+    # is. VCR-shaped: modes in config, because there is no runner to hang a
+    # CLI flag on.
+    #
+    # +:once+:: (default) record a screenshot that has no committed
+    #           baseline; compare against the baseline when there is one.
+    # +:none+:: strict. A missing baseline always fails.
+    # +:all+::  re-record. Every screenshot is written as the new baseline
+    #           and nothing is compared -- the bulk-accept verb, for the
+    #           redesign that changed forty screenshots at once. Refused
+    #           under CI (see {SnapDiff::ScreenshotMatcher}).
+    #
+    # PRECEDENCE: an explicitly set mode outranks +fail_if_new+; nil means
+    # nobody said, and only then does +fail_if_new+ answer -- so a setup
+    # with no +record+ line behaves EXACTLY as it did before this setting
+    # existed, CI sniff and all. +:none+ is the mode spelling of
+    # <tt>fail_if_new = true</tt> and +:once+ of <tt>= false</tt>, which is
+    # why the fallback can express today's behaviour without a special case
+    # anywhere downstream: the matcher branches on the mode alone.
+    #
+    # The missing-baseline DEFAULT is deliberately unchanged -- failing only
+    # under CI is what Jest, AVA, Vitest, testthat and jest-image-snapshot
+    # all chose, and a locally recorded screenshot baseline is often
+    # worthless across OS. +:none+ makes strictness an explicit choice
+    # instead; that is the whole point of having the mode.
+    def record
+      @record || (fail_if_new ? :none : :once)
+    end
+
+    def record=(mode)
+      @record = Config.validate_record_mode!(mode)
+    end
+
+    # Overrides the generated accessor above to announce the 2.1 removal
+    # (chunky_png-only, and chunky_png goes too). The writer, not the reader:
+    # the reader runs on every comparison through #default_options, including
+    # for the overwhelming majority who never set this. #initialize seeds the
+    # ivar directly, so booting the gem stays silent.
+    def shift_distance_limit=(value)
+      Removal.warn_once(:shift_distance_limit, Removal::SHIFT_DISTANCE_LIMIT_REMOVED) unless value.nil?
+      @shift_distance_limit = value
+    end
+
+    # Same shape, same reason: the writer only. #default_options reads
+    # +driver+ on every comparison for everyone, and #initialize seeds the
+    # +:auto+ default straight into the ivar, so only a user deliberately
+    # picking a backend hears about it.
+    def driver=(value)
+      Removal.warn_once(:driver_setting, Removal::DRIVER_REMOVED)
+      @driver = value
+    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
+    # independent (see {SETTINGS}): 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?
@@ -176,25 +293,4 @@ module SnapDiff
   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