snap_diff-capybara 2.0.0.beta3 → 2.0.0.beta4

data/docs/thread_safety.md

@@ -1,100 +1,91 @@
-# Thread Safety Guide for Parallel Testing
+# Parallel and Thread Safety Guide
+
+How `snap_diff` behaves when your test suite runs tests concurrently — Rails
+`parallelize`, `parallel_tests`, or CI sharding.
+
+## Summary
+
+| How the suite runs | Assertions and results | HTML report |
+| --- | --- | --- |
+| Serial | Correct | Written, complete |
+| `parallelize(with: :threads)` — also the default on JRuby | **Correct — fully supported** | Written, complete |
+| `parallelize(workers: N)` — Rails' default, forks | Correct | Written, complete — merged from every worker ([how](reporters.md#parallel-test-runs)) |
+| One process per worker (`parallel_tests`, RSpec, CI sharding) | Correct | Written, but only the last process to finish is in it |
+
+Two rules make all of these safe:
+
+1. **Set configuration once, before tests run.** There is one `SnapDiff::Config`
+   per process and nothing guards it.
+2. **Give every screenshot a name no other test uses.** See
+   [Screenshot names must be unique](#screenshot-names-must-be-unique-across-tests)
+   — this one is not cosmetic.
+
+## What is shared, and what protects it
+
+| State | Scope | Protection |
+| --- | --- | --- |
+| `SnapDiff.config` — every setting | One instance per process | None. Set it before tests start; do not mutate it during the run |
+| `SnapDiff.session` — the assertion registry, the new-screenshot list, and the `ScreenshotNamer` (section, group, counter) | Per fiber (`Thread.current[]` is fiber-local) | Isolation — threads never share one |
+| `SnapDiff::SnapManager.instance` and its tracked-snapshot set | Per fiber, memoized; rebuilt when the manager class or screenshot root changes | Isolation |
+| `SnapDiff::Reporting.reporters` | One list per process | A mutex: `register` appends under it, `notify`/`finalize!` iterate a snapshot taken under it |
+| `SnapDiff::Reporters::HTML` totals and failures | One reporter per process | Its own mutex around `record` and `finalize` |
+| Deprecation "warn once" memos | Per process | A mutex. Note "once per process" means once *per fork worker* — expect N copies under forking parallelism |
+| `SnapDiff::Vcs` repository-root memo | One hash per process | None. Values are idempotent (same directory, same answer), so a lost write costs one extra `git rev-parse`, but a plain Hash is not a concurrent container on JRuby or TruffleRuby |
+| Screenshot files: `<name>.png`, `<name>.base.png`, `<name>.attempt_NN.png`, `<name>.diff.png`, … | On disk, shared by every thread and every process | **None — the paths derive from the screenshot name alone** |
+
+## Screenshot names must be unique across tests
+
+Every artifact path is built from the screenshot name and nothing else — not the
+test name, not the worker, not the thread. Two tests using the same name share
+every file involved in the comparison.
+
+Serially that is merely wasteful: the tests overwrite each other in order. In
+parallel it is dangerous. When two concurrently running tests share a name, one
+test's post-pass baseline archiving moves the baseline that the other just
+checked out, and the second test then finds no baseline. A run of 64 concurrent
+assertions sharing 8 names measured between 18 and 34 comparisons lost this way,
+alongside a scatter of loud errors from the same collisions (truncated PNG reads,
+`mv` failures).
+
+Losing the baseline used to be **silent**: the screenshot was recorded as *new*
+and the test passed green having compared nothing. It is now an error — "no
+baseline was ever committed" (legitimate, warned about) is told apart from "the
+baseline I just checked out has disappeared" (impossible in a correct run):
 
-This document explains how `snap_diff` behaves under Rails parallel tests with the `:thread` strategy.
-
-## Overview
-
-`snap_diff` is thread safe for parallel test execution as long as global configuration is set before tests run. Per-thread state is isolated, and shared state is protected where it matters.
-
-## Architecture Summary
-
-### Per-thread Assertion Registry
-
-Each thread gets its own `AssertionRegistry` stored in thread-local storage:
-
-```ruby
-def registry
-  Thread.current[:capybara_screenshot_diff_registry] ||= AssertionRegistry.new
-end
 ```
-
-This prevents cross-thread leakage for assertions and screenshot naming.
-
-### Reporters Snapshot on Notify
-
-Reporters are notified using a snapshot protected by an eagerly initialized mutex:
-
-```ruby
-@reporters_mutex = Mutex.new
-
-def notify_reporters(assertions)
-  reporters_snapshot = reporters_mutex.synchronize { reporters.dup }
-  reporters_snapshot.each { |reporter| reporter.record(assertions) }
-end
-```
-
-This ensures a stable list while notifying without forcing a global lock around reporter work.
-
-### HTML Reporter Internal Lock
-
-The HTML reporter protects `@failures`, `@total`, and `@finalized` with a mutex so `record` and `finalize` can run safely:
-
-```ruby
-@mutex.synchronize do
-  return if @finalized
-  @total += total
-  @failures.concat(failures)
-end
+The baseline for 'dashboard' was checked out and then disappeared before it could be compared -- nothing was verified.
 ```
 
-`@finalized` is set only after `write_report` succeeds, so a failed write can be retried.
-
-### Screenshot Naming Isolation
-
-Each thread gets its own `ScreenshotNamer` via the per-thread registry, so counters, sections, and groups do not collide.
-
-### SnapManager Per Call
-
-`SnapManager` returns a new instance for each call, avoiding shared mutable state.
+Use `screenshot_section` / `screenshot_group`, or name screenshots after the test,
+so no two tests can collide.
 
-## Global Configuration
+## Configuration
 
-Configuration uses `mattr_accessor` and should be set once before tests run. Do not mutate config during parallel execution.
-
-## Parallel Test Lifecycle
-
-- Setup: per-thread registry is created, config is read
-- Execution: assertions are added to the thread-local registry
-- Teardown: `verify` and `reset` operate on the thread-local registry, reporters are notified
-- Exit: reporters finalize once per process (using mutex-protected snapshot)
-
-## Usage Examples
+Configure once, in `test_helper.rb` / `spec_helper.rb`, before any test runs:
 
 ```ruby
-parallelize(workers: :number_of_processors, with: :threads)
-
-Capybara::Screenshot::Diff.configure do |screenshot, diff|
-  screenshot.window_size = [1280, 1024]
-  screenshot.save_path = "doc/screenshots"
-  diff.tolerance = 0.001
+SnapDiff.configure do |config|
+  config.window_size = [1280, 1024]
+  config.save_path = "doc/screenshots"
+  config.tolerance = 0.001
 end
 ```
 
-## Do and Do Not
-
-Do:
-- Set config once in test helper
-- Pass per-screenshot options in the call
-
-Do not:
-- Change global config inside tests
-- Manually mutate registry internals
-
-## File System Notes
-
-- Paths are unique per screenshot name and counter
-- `FileUtils.mv` is atomic on most file systems
-- Directory creation uses `mkpath`
+Pass anything that varies per screenshot as an argument instead
+(`assert_matches_screenshot("name", tolerance: 0.02)`) rather than reassigning
+config mid-run: one process's config is shared by all of its threads, so a test
+that mutates it changes what every concurrently running test sees.
+
+## Test lifecycle
+
+- **Setup** — the fiber-local session is created on first use.
+- **Execution** — assertions accumulate in the fiber's own registry.
+- **Teardown** — `verify` and `reset` act on that fiber's registry, then hand its
+  assertions to the process's reporters.
+- **End of suite** — reporters finalize once per process, from the framework's
+  end-of-suite hook (`Minitest.after_run`, RSpec `after(:suite)`, Cucumber
+  `AfterAll`). Forked workers are the exception: see
+  [Parallel test runs](reporters.md#parallel-test-runs).
 
 ## Load-time thread safety
 

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Diff::AnnotationService
-# now resolves lazily via snap_diff/legacy_shims' const_missing, with a
-# deprecation warning pointing at SnapDiff::AnnotationService.
+# Legacy-name forwarder: the old constant resolves via snap_diff/legacy_shims.
 require "snap_diff/annotation_service"
 require "snap_diff/legacy_shims"

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Diff::AreaCalculator
-# now resolves lazily via snap_diff/legacy_shims' const_missing, with a
-# deprecation warning pointing at SnapDiff::AreaCalculator.
+# Legacy-name forwarder: the old constant resolves via snap_diff/legacy_shims.
 require "snap_diff/area_calculator"
 require "snap_diff/legacy_shims"

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::BrowserHelpers now
-# resolves lazily via snap_diff/legacy_shims' const_missing, with a
-# deprecation warning pointing at SnapDiff::BrowserHelpers.
+# Legacy-name forwarder: the old constant resolves via snap_diff/legacy_shims.
 require "snap_diff/browser_helpers"
 require "snap_diff/legacy_shims"

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

@@ -2,66 +2,21 @@
 
 # Legacy Capybara::Screenshot / Capybara::Screenshot::Diff config surface.
 #
-# Since ADR-008 step 1 the storage lives in SnapDiff::Config -- the require
-# leaf of the config graph (see its own header) -- and since step 7b the
-# DERIVED values (active?, screenshot_area, default_options) live there
-# too. snap_diff/config.rb also generates the old accessor names as thin
-# delegators from SnapDiff::Config::MAPPING, so nothing but forwarders is
-# left here. The v1 surface (Capybara::Screenshot.window_size = ...,
-# Diff.configure { ... }, Diff.compare) keeps working unchanged: one
-# storage, two views.
+# Nothing but requires is left here. The storage is SnapDiff::Config
+# (ADR-008 step 1, the require leaf of the config graph); the derived values
+# (active?, screenshot_area, default_options) live there too since step 7b;
+# and the old accessor names, Diff.configure/.compare, SnapDiff.start and
+# the AVAILABLE_DRIVERS alias are generated by snap_diff/legacy_shims -- the
+# one file that holds the v1 surface as code, so that the canonical core
+# needs nothing from this tree and 3.0 can delete both together. The v1
+# surface (Capybara::Screenshot.window_size = ..., Diff.configure { ... },
+# Diff.compare) keeps working unchanged: one storage, two views.
 #
 # Load order: requiring snap_diff/config first also eagerly evaluates the
-# require-time defaults (ENV["CI"] for fail_if_new, Rails.root/pwd for
-# root) at this same load moment, exactly when the old mattr_accessor
-# default blocks used to run. snap_diff/config never requires back here,
-# so the graph stays acyclic.
+# require-time defaults (Rails.root/pwd for root) at this same load moment,
+# exactly when the old mattr_accessor default blocks used to run.
+# fail_if_new is the exception -- its ENV["CI"] fallback is read live, so an
+# explicit setting outranks the environment whenever the variable appears.
+# Neither file requires back here, so the graph stays acyclic.
 require "snap_diff/config"
-# AVAILABLE_DRIVERS below is evaluated at class-body eval time, so Utils
-# must be a real, already-loaded module before this module body runs.
-require "snap_diff/utils"
-
-module Capybara
-  module Screenshot
-    class << self
-      def active?
-        SnapDiff.config.active?
-      end
-
-      def screenshot_area
-        SnapDiff.config.screenshot_area
-      end
-
-      def screenshot_area_abs
-        SnapDiff.config.screenshot_area_abs
-      end
-    end
-
-    # Module to track screenshot changes
-    module Diff
-      AVAILABLE_DRIVERS = SnapDiff::Utils.detect_available_drivers.freeze
-
-      # Configure screenshot and diff settings in one block.
-      #
-      #   Capybara::Screenshot::Diff.configure do |screenshot, diff|
-      #     screenshot.window_size = [1280, 1024]
-      #     screenshot.stability_time_limit = 1
-      #     diff.driver = :vips
-      #     diff.tolerance = 0.0005
-      #   end
-      # The bare `yield` (rather than an explicit &block) keeps this
-      # method's published arity byte-identical to what it always had.
-      def self.configure
-        SnapDiff.start { |screenshot, diff| yield screenshot, diff }
-      end
-
-      def self.compare(baseline_path, current_path, **options)
-        SnapDiff.compare(baseline_path, current_path, **options)
-      end
-
-      def self.default_options
-        SnapDiff.config.default_options
-      end
-    end
-  end
-end
+require "snap_diff/legacy_shims"

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

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): the comparison-result value object lives at
-# SnapDiff::ComparisonResult (ex-Difference); the old name now resolves
-# lazily via snap_diff/legacy_shims' const_missing, with a deprecation
-# warning.
+# Legacy-name forwarder: the old constant resolves via snap_diff/legacy_shims.
 require "snap_diff/comparison_result"
 require "snap_diff/legacy_shims"

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 4): ChunkyPNGDriver lives in SnapDiff::Drivers
-# now; the module alias in capybara/screenshot/diff/drivers.rb makes it
-# reachable as Capybara::Screenshot::Diff::Drivers::ChunkyPNGDriver.
+# Legacy-name forwarder: the module alias in capybara/screenshot/diff/drivers.rb
+# makes ChunkyPNGDriver reachable as
+# Capybara::Screenshot::Diff::Drivers::ChunkyPNGDriver.
 require "capybara/screenshot/diff/drivers"
 require "snap_diff/drivers/chunky_png_driver"

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

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 4): VipsDriver lives in SnapDiff::Drivers now;
-# the module alias in capybara/screenshot/diff/drivers.rb makes it reachable
-# as Capybara::Screenshot::Diff::Drivers::VipsDriver.
+# Legacy-name forwarder: the module alias in capybara/screenshot/diff/drivers.rb
+# makes VipsDriver reachable as Capybara::Screenshot::Diff::Drivers::VipsDriver.
 require "capybara/screenshot/diff/drivers"
 require "snap_diff/drivers/vips_driver"

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

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Diff::Drivers now
-# resolves lazily via snap_diff/legacy_shims' const_missing, with a
-# deprecation warning pointing at SnapDiff::Drivers. The forwarded module is
-# the same object, so Drivers.for and the Drivers::VipsDriver /
-# Drivers::ChunkyPNGDriver constants keep resolving through the old name.
+# Legacy-name forwarder: the old constant resolves via snap_diff/legacy_shims.
+# The forwarded module is the same object, so Drivers.for and the
+# Drivers::VipsDriver / Drivers::ChunkyPNGDriver constants keep resolving
+# through the old name.
 require "snap_diff/drivers"
 require "snap_diff/legacy_shims"

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

@@ -1,27 +1,16 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): the comparison class lives at
-# SnapDiff::Comparison (ex-ImageCompare); the old name now resolves lazily
-# via snap_diff/legacy_shims' const_missing, with a deprecation warning.
-# snap_diff/comparison itself pulls in the ComparisonResult and Drivers
-# units, and the shims keep the old ::Difference / ::Drivers names
-# resolvable, so this path still provides everything the pre-move
-# image_compare.rb did. The images-holder struct lives at
-# SnapDiff::Comparison::Images and the driver cache at
-# SnapDiff::Drivers.loaded, with LOADED_DRIVERS kept as an eager same-object
-# alias by legacy_shims (ADR-008 step 5).
+# Legacy-name forwarder for SnapDiff::Comparison (ex-ImageCompare). Requiring
+# this path must keep providing everything the pre-move image_compare.rb did:
+# snap_diff/comparison pulls in the ComparisonResult and Drivers units, and the
+# shims keep ::Difference, ::Drivers, ::Comparison (the images struct) and
+# LOADED_DRIVERS resolvable.
 require "snap_diff/comparison"
 require "snap_diff/legacy_shims"
 
-# Deliberately EAGER and silent (v2 step 6 exception): Comparison is a
-# documented user-facing struct, so adopters feature-detect it with
-# defined?/const_defined? -- neither of which triggers const_missing, so a
-# lazy shim reported it permanently absent. See snap_diff/legacy_shims.rb
-# for the full exception list.
-module Capybara
-  module Screenshot
-    module Diff
-      Comparison = SnapDiff::Comparison::Images
-    end
-  end
-end
+# Capybara::Screenshot::Diff::Comparison (the images-holder struct) is a
+# documented user-facing name that adopters feature-detect with
+# defined?/const_defined?, so it is assigned EAGERLY rather than shimmed --
+# const_defined? never triggers const_missing. That assignment now lives in
+# snap_diff/legacy_shims (required above), with the rest of the v1 surface,
+# so `require "snap_diff"` alone provides it too.

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Diff::ImagePreprocessor
-# now resolves lazily via snap_diff/legacy_shims' const_missing, with a
-# deprecation warning pointing at SnapDiff::ImagePreprocessor.
+# Legacy-name forwarder: the old constant resolves via snap_diff/legacy_shims.
 require "snap_diff/image_preprocessor"
 require "snap_diff/legacy_shims"

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

@@ -1,14 +1,7 @@
 # frozen_string_literal: true
 
+# Legacy-name forwarder. `Capybara::Screenshot::Os` is an EAGER same-object
+# alias assigned in snap_diff/legacy_shims -- the one file every entry point
+# loads, canonical ones included, so a half-migrated app keeps the name.
 require "snap_diff/os"
-
-# Deliberately EAGER and silent (v2 step 6 exception): Os is an advertised
-# entry-point constant probed with Object.const_defined? by
-# support_load_probe_test.rb, and const_defined? never triggers
-# const_missing -- a lazy shim would break that contract. See
-# snap_diff/legacy_shims.rb for the full exception list.
-module Capybara
-  module Screenshot
-    Os = SnapDiff::Os
-  end
-end
+require "snap_diff/legacy_shims"

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-008 step 3): Region now lives at SnapDiff::Region;
-# snap_diff/region also defines the eager top-level `Region` alias.
+# Legacy-name forwarder: snap_diff/region also defines the eager top-level
+# `Region` alias.
 require "snap_diff/region"

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

@@ -1,21 +1,8 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-008 step 4): the default reporter lives at
-# SnapDiff::Reporters::Default.
+# Legacy-name forwarder for SnapDiff::Reporters::Default.
+# `Capybara::Screenshot::Diff::Reporters::Default` is an EAGER same-object
+# alias assigned in snap_diff/legacy_shims -- the one file every entry point
+# loads, canonical ones included, so a half-migrated app keeps the name.
 require "snap_diff/reporters/default"
 require "snap_diff/legacy_shims"
-
-# Deliberately EAGER and silent (v2 step 6 exception): Default is a
-# documented subclassing extension point, so adopters feature-detect it with
-# defined?/const_defined? -- neither of which triggers const_missing, so a
-# lazy shim reported it permanently absent. See snap_diff/legacy_shims.rb
-# for the full exception list.
-module Capybara
-  module Screenshot
-    module Diff
-      module Reporters
-        Default = SnapDiff::Reporters::Default
-      end
-    end
-  end
-end

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Diff::ScreenshotMatcher
-# now resolves lazily via snap_diff/legacy_shims' const_missing, with a
-# deprecation warning pointing at SnapDiff::ScreenshotMatcher.
+# Legacy-name forwarder: the old constant resolves via snap_diff/legacy_shims.
 require "snap_diff/screenshot_matcher"
 require "snap_diff/legacy_shims"

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Screenshoter now
-# resolves lazily via snap_diff/legacy_shims' const_missing, with a
-# deprecation warning pointing at SnapDiff::Screenshoter.
+# Legacy-name forwarder: the old constant resolves via snap_diff/legacy_shims.
 require "snap_diff/screenshoter"
 require "snap_diff/legacy_shims"

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Diff::StableScreenshoter
-# now resolves lazily via snap_diff/legacy_shims' const_missing, with a
-# deprecation warning pointing at SnapDiff::StableScreenshoter.
+# Legacy-name forwarder: the old constant resolves via snap_diff/legacy_shims.
 require "snap_diff/stable_screenshoter"
 require "snap_diff/legacy_shims"

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Diff::Utils now
-# resolves lazily via snap_diff/legacy_shims' const_missing, with a
-# deprecation warning pointing at SnapDiff::Utils.
+# Legacy-name forwarder: the old constant resolves via snap_diff/legacy_shims.
 require "snap_diff/utils"
 require "snap_diff/legacy_shims"

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Diff::Vcs now
-# resolves lazily via snap_diff/legacy_shims' const_missing, with a
-# deprecation warning pointing at SnapDiff::Vcs.
+# Legacy-name forwarder: the old constant resolves via snap_diff/legacy_shims.
 require "snap_diff/vcs"
 require "snap_diff/legacy_shims"

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

@@ -1,15 +1,10 @@
 # frozen_string_literal: true
 
-require "snap_diff/version"
-
-# Deliberately EAGER and silent (v2 step 6 exception): the gemspec resolves
-# Capybara::Screenshot::Diff::VERSION at build time, so a lazy warning shim
-# would make every `gem build` warn. See snap_diff/legacy_shims.rb for the
-# full exception list.
-module Capybara
-  module Screenshot
-    module Diff
-      VERSION = SnapDiff::VERSION
-    end
-  end
-end
+# Capybara::Screenshot::Diff::VERSION is a documented name adopters read
+# directly, so it is assigned EAGERLY rather than shimmed -- const_defined?
+# never triggers const_missing. That assignment lives in
+# snap_diff/legacy_shims (required below) with the rest of the v1 surface,
+# because this file is no longer on any entry point's require path: the core
+# reads SnapDiff::VERSION, and so does the gemspec. Assigning it here too
+# would be a duplicate-constant warning, not a second safety net.
+require "snap_diff/legacy_shims"

data/lib/capybara-screenshot-diff.rb

@@ -1,3 +1,12 @@
 # frozen_string_literal: true
 
-require "capybara_screenshot_diff/minitest"
+# Bundler.require entry point for `gem "capybara-screenshot-diff"` -- the v1
+# gem name, deleted in 3.0. The surviving name owns the logic (including the
+# minitest feature detection this door needs just as much).
+#
+# The marker goes BEFORE that require: snap_diff-capybara claims the process
+# as canonical, and a marker after it would be swallowed.
+require "snap_diff/deprecation"
+SnapDiff::Deprecation.legacy_entry_point!
+
+require "snap_diff-capybara"

data/lib/capybara_screenshot_diff/attempts_reporter.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): CapybaraScreenshotDiff::AttemptsReporter now
-# resolves lazily via snap_diff/legacy_shims' const_missing, with a
-# deprecation warning pointing at SnapDiff::AttemptsReporter.
+# Legacy-name forwarder: the old constant resolves via snap_diff/legacy_shims.
 require "snap_diff/attempts_reporter"
 require "snap_diff/legacy_shims"

data/lib/capybara_screenshot_diff/dsl.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# The one legacy entry point that does NOT go through the umbrella, so it
+# carries its own marker.
+require "snap_diff/deprecation"
+SnapDiff::Deprecation.legacy_entry_point!
+
 require "snap_diff/dsl"
 
 # Deliberately EAGER and silent (v2 step 6 exception): DSL is an advertised

data/lib/capybara_screenshot_diff/error_with_filtered_backtrace.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): CapybaraScreenshotDiff::BacktraceFilter and
-# CapybaraScreenshotDiff::ErrorWithFilteredBacktrace now resolve lazily via
-# snap_diff/legacy_shims' const_missing, with deprecation warnings pointing
-# at their SnapDiff:: replacements.
+# Legacy-name forwarder: the old constant resolves via snap_diff/legacy_shims.
 require "snap_diff/error_with_filtered_backtrace"
 require "snap_diff/legacy_shims"

data/lib/capybara_screenshot_diff/reporters/html.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): CapybaraScreenshotDiff::Reporters::HTML now
-# resolves lazily via snap_diff/legacy_shims' const_missing, with a
-# deprecation warning pointing at SnapDiff::Reporters::HTML.
+# Legacy-name forwarder: the old constant resolves via snap_diff/legacy_shims.
 require "snap_diff/reporters/html"
 require "snap_diff/legacy_shims"

data/lib/capybara_screenshot_diff/screenshot_namer.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): CapybaraScreenshotDiff::ScreenshotNamer now
-# resolves lazily via snap_diff/legacy_shims' const_missing, with a
-# deprecation warning pointing at SnapDiff::ScreenshotNamer.
+# Legacy-name forwarder: the old constant resolves via snap_diff/legacy_shims.
 require "snap_diff/screenshot_namer"
 require "snap_diff/legacy_shims"

data/lib/capybara_screenshot_diff/snap.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): CapybaraScreenshotDiff::Snap now resolves
-# lazily via snap_diff/legacy_shims' const_missing, with a deprecation
-# warning pointing at SnapDiff::Snap.
+# Legacy-name forwarder: the old constant resolves via snap_diff/legacy_shims.
 require "snap_diff/snap"
 require "snap_diff/legacy_shims"

data/lib/capybara_screenshot_diff/snap_manager.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# Forwarder (ADR-004 v2 step 6): CapybaraScreenshotDiff::SnapManager now
-# resolves lazily via snap_diff/legacy_shims' const_missing, with a
-# deprecation warning pointing at SnapDiff::SnapManager.
+# Legacy-name forwarder: the old constant resolves via snap_diff/legacy_shims.
 require "snap_diff/snap_manager"
 require "snap_diff/legacy_shims"