snap_diff-capybara 2.0.0.beta3 → 2.0.0.beta4

data/docs/UPGRADING.md

@@ -1,12 +1,12 @@
 # Upgrading
 
-## Upgrading to v2.0 (alpha)
+## Upgrading to v2.0
 
 ### Overview
 
 Version 2.0 introduces a new canonical namespace (`SnapDiff`) for cleaner, more discoverable code. The public DSL remains unchanged — your existing `screenshot` and `assert_matches_screenshot` calls work without modification. This guide covers the optional migration path for settings and the new namespace.
 
-**Status:** `2.0.0.beta3` is an opt-in prerelease. RubyGems never installs prereleases by default resolution — normal `bundle update` keeps you on the 1.x line. The final 2.0.0 ships only after adopter feedback; please report anything surprising on [#166](https://github.com/snap-diff/snap_diff-capybara/issues/166).
+**Status:** 2.0 is the **transitional** release — the v1 API and the canonical `SnapDiff` API both work. **2.1 removes** everything 2.0 warns about (the legacy namespaces, the ChunkyPNG driver, `shift_distance_limit`, the `driver:` setting and the driver abstraction, and the `fail_if_new` / `pending_if_new` / `fail_on_difference` booleans that `record` replaces). There is no 3.0. Migrating on 2.0 is optional; doing it before 2.1 is not.
 
 **Estimated upgrade time:** 5–15 minutes (most users need only the Gemfile pin)
 
@@ -14,22 +14,37 @@ Version 2.0 introduces a new canonical namespace (`SnapDiff`) for cleaner, more
 [SnapDiff — the canonical API](snapdiff.md): the same setup, configuration, and extension points
 with canonical names only, no legacy shapes to unlearn.
 
-**Breaking changes:** None for the DSL; deprecation warnings if you reference legacy constants (suppressible), plus two known alpha caveats (see below)
+**Breaking changes:** None for the DSL; one migration notice per process plus a deprecation warning per legacy constant you reference (both suppressible), plus the [known caveats](#known-caveats) below
 
 ---
 
 ### The Short Version (Most Users)
 
 ```ruby
-# In your Gemfile — the exact prerelease version is required to opt in
-gem "capybara-screenshot-diff", "2.0.0.beta3" # or the latest 2.0.0 prerelease
+# In your Gemfile
+gem "capybara-screenshot-diff", "2.0.0.beta4"   # current 2.0 prerelease; 2.0.0 final is not out yet
 ```
 
+**Pin the exact prerelease.** An unpinned `gem "capybara-screenshot-diff"` resolves to the 1.x
+line, and `"~> 2.0"` does not resolve at all — Bundler never picks a prerelease from a plain
+requirement, so it fails with `Could not find gem 'capybara-screenshot-diff (~> 2.0)'`. Once
+2.0.0 ships, `"~> 2.0"` is the pin to use.
+
+The same content is also published as `snap_diff-capybara` from 2.0.0 on, but that name's
+only earlier non-prerelease is a `0.0.1` placeholder with no Ruby files in it — unpinned, it
+installs an empty gem and raises `LoadError`. Stay on `capybara-screenshot-diff`, and install
+**one** name: with both in a Gemfile the gem raises `SnapDiff::DualInstallError` at require
+time.
+
 ```bash
 bundle install
-bundle exec rake test
+bin/rails test:system     # the task that actually runs your screenshot tests
 ```
 
+> **Not `rake test` / `rails test`.** In a Rails app those skip `test/system/`, so you get
+> `0 runs, 0 assertions, 0 failures` — a clean-looking pass that compared nothing. Outside
+> Rails, run whatever task loads your Capybara tests.
+
 **That's it.** Your existing code works unchanged. The old namespaces (`Capybara::Screenshot::Diff`, `CapybaraScreenshotDiff`) are shimmed with deprecation warnings; the new one (`SnapDiff`) is available if you want to modernize.
 
 ---
@@ -38,13 +53,14 @@ bundle exec rake test
 
 #### 1. New Canonical Namespace: `SnapDiff`
 
-The implementation now lives in `lib/snap_diff/` under the `SnapDiff` namespace. Every legacy constant still resolves — lazily, to the *same object* — but emits a one-time-per-constant deprecation warning. The main renames:
+The implementation now lives in `lib/snap_diff/` under the `SnapDiff` namespace. Every legacy constant still resolves to the *same object*. Most do so lazily and warn once each; a documented set stays eagerly defined and silent — see [Deprecation Warnings](#deprecation-warnings) for exactly which. The main renames:
 
 | Legacy name | v2 canonical name |
 |-------------|-------------------|
 | `Capybara::Screenshot::Diff::ImageCompare` | `SnapDiff::Comparison` |
 | `Capybara::Screenshot::Diff::Difference` | `SnapDiff::ComparisonResult` |
 | `Capybara::Screenshot::Diff::Drivers::BaseDriver` | `SnapDiff::Driver` (now a mixin — see below) |
+| `Capybara::Screenshot::Os` | `SnapDiff::Os` |
 | `CapybaraScreenshotDiff::SnapManager` / `::Snap` | `SnapDiff::SnapManager` / `SnapDiff::Snap` |
 | `CapybaraScreenshotDiff::RED_RGBA` / `::ORANGE_RGBA` | `SnapDiff::RED_RGBA` / `SnapDiff::ORANGE_RGBA` |
 | `CapybaraScreenshotDiff::Minitest::Assertions` | `SnapDiff::Minitest::Assertions` |
@@ -98,7 +114,7 @@ The most commonly-used settings and how to update them:
 | `save_path` | `Capybara::Screenshot.save_path = "doc/screenshots"` | `SnapDiff.config.save_path = "doc/screenshots"` | Where baseline screenshots are stored |
 | `window_size` | `Capybara::Screenshot.window_size = [1280, 1024]` | `SnapDiff.config.window_size = [1280, 1024]` | Browser viewport size for consistent screenshots |
 
-**All 27 settings** from both legacy namespaces are available via `SnapDiff.config.<attr_name>` — see the [Configuration Reference](configuration.md) for the full list. One rename to note: `Capybara::Screenshot.enabled` becomes `SnapDiff.config.screenshot_enabled` (it would otherwise collide with `Capybara::Screenshot::Diff.enabled`, which keeps the bare `enabled` name).
+**All 28 settings** from both legacy namespaces are available via `SnapDiff.config.<attr_name>` — see the [Configuration Reference](configuration.md) for the full list. One rename to note: `Capybara::Screenshot.enabled` becomes `SnapDiff.config.screenshot_enabled` (it would otherwise collide with `Capybara::Screenshot::Diff.enabled`, which keeps the bare `enabled` name).
 
 ---
 
@@ -114,7 +130,6 @@ Capybara::Screenshot::Diff.configure do |screenshot, diff|
   screenshot.window_size = [1280, 1024]
   screenshot.blur_active_element = false
   diff.tolerance = 0.0005
-  diff.driver = :vips
 end
 ```
 
@@ -125,7 +140,6 @@ SnapDiff.start do |screenshot, diff|
   screenshot.window_size = [1280, 1024]
   screenshot.blur_active_element = false
   diff.tolerance = 0.0005
-  diff.driver = :vips
 end
 ```
 
@@ -136,7 +150,6 @@ SnapDiff.configure do |config|
   config.window_size = [1280, 1024]
   config.blur_active_element = false
   config.tolerance = 0.0005
-  config.driver = :vips
 end
 ```
 
@@ -159,19 +172,187 @@ This means you can migrate your codebase incrementally **now**, before opting in
 
 ### Deprecation Warnings
 
-In v2.0, resolving a legacy *constant* emits one deprecation warning per constant per process:
+v2.0 emits five different things, and it is worth knowing which is which. The first two are
+about the old namespaces; the third is about the driver features 2.1 removes; the fourth is
+about options that never did anything; the fifth is about the new-screenshot booleans that
+`record` replaces.
+
+Everything 2.1 removes warns in 2.0, and every warning names 2.1. Nothing you can still write
+in 2.0 does nothing quietly — if a setting is on its way out, or was never read at all, you
+hear about it once per process.
+
+#### 1. The migration notice — one line per process
+
+The first time a process touches *any* hookable legacy API, you get a single line:
+
+```
+[snap_diff deprecation] This process uses the v1 `Capybara::Screenshot*` / `CapybaraScreenshotDiff*` API. It still works in 2.0 and is REMOVED in 2.1 -- see docs/UPGRADING.md for the SnapDiff replacements. Silence with `SnapDiff.silence_deprecations = true` or SNAP_DIFF_SILENCE_DEPRECATIONS=1. (shown once per process)
+```
+
+It fires once and never again, whichever door you came through:
+
+- **requiring a v1-named entry point** — `require "capybara/screenshot/diff"`,
+  `"capybara-screenshot-diff"`, `"capybara_screenshot_diff"`, or any of
+  `capybara_screenshot_diff/{dsl,minitest,rspec,cucumber}`. With `gem "capybara-screenshot-diff"`
+  in the Gemfile, `Bundler.require` opens this door for you at boot.
+- a legacy config accessor — `Capybara::Screenshot.window_size = ...`, `Capybara::Screenshot::Diff.tolerance`
+- a lazily shimmed legacy constant (see below)
+- `include Capybara::Screenshot` / `include Capybara::Screenshot::Diff`
+
+It exists because most of the v1 surface **cannot** warn per use, so without it a 2.x app could
+be entirely silent right up to the bare `NameError` it would get on 2.1. The require door is
+what makes the rest of the list a safety net rather than the only mechanism: a suite that
+requires the gem and only calls `screenshot` touches none of the other four.
+
+The canonical entry points — `require "snap_diff"`, `"snap_diff-capybara"`, `"snap_diff/dsl"`,
+`"snap_diff/integrations/*"` — never fire it, even though `snap_diff-capybara` loads the v1
+compatibility files internally.
+
+> **Silencing a require-time notice needs the env var.** `SnapDiff.silence_deprecations = true`
+> only takes effect from the line that sets it, and you cannot set it before the require that
+> defines `SnapDiff`. Under `Bundler.require` there is no earlier moment at all. Use
+> `SNAP_DIFF_SILENCE_DEPRECATIONS=1` in the environment, or
+> `require "snap_diff/deprecation"; SnapDiff.silence_deprecations = true` ahead of everything
+> else.
+
+#### 2. Per-constant warnings — one line per lazily shimmed constant
+
+Resolving a legacy constant that is shimmed through `const_missing` also warns, once per constant
+per process:
 
 ```
 [snap_diff deprecation] `Capybara::Screenshot::Diff::ImageCompare` is deprecated (constant); use `SnapDiff::Comparison` instead.
 ```
 
-**Warnings appear for:** legacy constant access — `Capybara::Screenshot::Diff::ImageCompare`, `::Difference`, `::Drivers`, `CapybaraScreenshotDiff::SnapManager`, etc.
+**These appear for:** `Capybara::Screenshot::{BrowserHelpers, Screenshoter}`;
+`Capybara::Screenshot::Diff::{Vcs, StableScreenshoter, ImagePreprocessor, AreaCalculator,
+AnnotationService, Utils, ScreenshotMatcher, Drivers, ImageCompare, Difference}`;
+`Capybara::Screenshot::Diff::Drivers::BaseDriver`; `CapybaraScreenshotDiff::{RED_RGBA,
+ORANGE_RGBA, SnapManager, Snap, ScreenshotNamer, AttemptsReporter, BacktraceFilter,
+ErrorWithFilteredBacktrace, ScreenshotAssertion, AssertionRegistry}`;
+`CapybaraScreenshotDiff::Reporters::HTML`.
+
+`CapybaraScreenshotDiff::DSL` and `::Minitest::Assertions` are shimmed this way **only under a
+canonical `snap_diff*` require**. Under the v1 entry points — what an unmigrated app actually
+uses — they are eagerly defined and silent, like everything in the next section.
+
+#### 3. Removal warnings — the driver half, removed in 2.1
+
+The warnings above are about *names*. These are about *features*: 2.1 makes **libvips the only
+image backend** and deletes the rest of the driver machinery. 2.0 still supports all of it and
+warns once per process per subject, through the same channel and the same silencing switches.
+
+| You will see it when you… | Removed in 2.1 | Do this instead |
+|---|---|---|
+| select the ChunkyPNG driver — `driver: :chunky_png`, `SnapDiff.config.driver = :chunky_png`, or the legacy `Capybara::Screenshot::Diff.driver =` | the `:chunky_png` driver | add `gem "ruby-vips"` (plus the libvips system package) and drop the option |
+| run on `driver: :auto` **without `ruby-vips` installed** | the `:auto` fallback to ChunkyPNG | same — install libvips + `ruby-vips`. This is the case worth reading twice: nothing in your setup says `chunky_png`, so the warning is the only sign that 2.1 will break this process |
+| set `shift_distance_limit` — globally or per screenshot | `shift_distance_limit` (ChunkyPNG-only) | `median_filter_window_size`, `tolerance`, or `color_distance_limit` — see [Configuration](configuration.md#allowed-shift-distance) |
+| read `SnapDiff::Drivers.loaded` (the custom-driver registry) | the registry | nothing — custom drivers are removed, see below |
+| read `SnapDiff::Drivers.available` | driver detection | require `ruby-vips` instead of branching on a detected list |
+| `include SnapDiff::Driver` in your own driver class | the driver mixin | nothing — see below |
+| set a driver **at all** — `SnapDiff.config.driver =`, the legacy `Capybara::Screenshot::Diff.driver =`, or `screenshot "index", driver: …` | the `driver` setting and the `driver:` option | delete the line. With libvips the only backend there is nothing to select |
+
+> **`driver: :vips` warns too, and that is deliberate.** The warning is not about the *value*
+> you picked — it is about the setting existing. `SnapDiff.config.driver = :vips` raises
+> `NoMethodError: undefined method 'driver='` in 2.1, at config time before any test runs, and
+> `screenshot "index", driver: :vips` becomes an `ArgumentError` for an unknown option. Both
+> are lines to delete, not lines to change. `driver: :auto` on a machine that *has* libvips is
+> the one place the option still says something — and the `:auto` row above covers the case
+> that matters, where `:auto` silently lands on ChunkyPNG.
+
+```
+[snap_diff deprecation] `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. Silence with `SnapDiff.silence_deprecations = true` or SNAP_DIFF_SILENCE_DEPRECATIONS=1. (shown once per process) (called from /app/test/test_helper.rb:12)
+```
+
+**Custom drivers have no migration path.** The whole abstraction goes: the `SnapDiff::Driver`
+mixin, the `SnapDiff::Drivers.loaded` registry, `SnapDiff::Drivers.available` /
+`SnapDiff::Utils.detect_available_drivers`, and selecting a driver by name. Nothing replaces
+them, and this guide is not going to pretend otherwise — if you maintain a third-party driver,
+say so on [the issue tracker](https://github.com/snap-diff/snap_diff-capybara/issues) before 2.1 ships.
+
+Three spots on the same chopping block stay silent: the legacy
+`Capybara::Screenshot::Diff::LOADED_DRIVERS` / `::AVAILABLE_DRIVERS` aliases are plain constants
+with nothing to hook (use `SnapDiff::Drivers.loaded` / `.available` to hear the warning);
+`SnapDiff::Drivers.for` is not warned on at all — the gem itself calls it for every comparison,
+so warning there would fire on setups that are not affected by anything on this list; and
+detection (`SnapDiff::Drivers.detect_available` / `SnapDiff::Utils.detect_available_drivers`)
+runs at load, before any user code.
+
+#### 4. Unknown screenshot options — warned in 2.0, raised in 2.1
+
+Per-screenshot options used to be a free-form hash: anything the gem did not read was frozen,
+carried around, and ignored. A misspelt `tolerence:` bought you a green suite that compared
+nothing and never said so. 2.0 warns once per unknown key; 2.1 raises `ArgumentError`.
+
+```
+[snap_diff deprecation] `:tolerence` is not a recognised screenshot option, so it does nothing. 2.1 raises ArgumentError for it. Check the spelling against the option list in docs/configuration.md. Silence with `SnapDiff.silence_deprecations = true` or SNAP_DIFF_SILENCE_DEPRECATIONS=1. (shown once per process) (called from /app/test/features/home_test.rb:14)
+```
+
+It applies to every route into a comparison — `screenshot`, `assert_matches_screenshot`,
+`capture_screenshot` and `SnapDiff.compare`. Recognised keys are `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` and `wait`.
+
+#### 5. The new-screenshot booleans — superseded by `record`, removed in 2.1
+
+`fail_if_new`, `pending_if_new` and `fail_on_difference` each answered part of "what happens when
+there is no baseline, or when there is a difference" — and none of them named the action people
+actually want, which is *accept this change*. 2.0 adds the verb:
+
+```ruby
+SnapDiff.config.record = :once   # default. Record a screenshot that has no baseline.
+SnapDiff.config.record = :none   # strict. A missing baseline always fails.
+SnapDiff.config.record = :all    # re-record everything. THE BULK-ACCEPT MODE.
+```
+
+| Old | New | Note |
+|-----|-----|------|
+| `fail_if_new = true` | `record = :none` | the mode means the same thing on CI and off it |
+| `fail_if_new = false` | `record = :once` | |
+| `pending_if_new = true` | `record = :none`, or `:once` | `:none` fails with the `git add` command attached; `:once` records and lists it in the end-of-run summary |
+| `fail_on_difference = false` | `record = :all` | to *accept* the new rendering rather than ignore the difference |
 
-**Warnings do NOT appear for:**
-- Requiring the gem: `require "capybara_screenshot_diff/minitest"` etc. is not deprecated
-- The DSL: `screenshot`, `assert_matches_screenshot`, `capture_screenshot` are never deprecated
-- Settings access: `Capybara::Screenshot.blur_active_element`, `Capybara::Screenshot::Diff.tolerance=`, and the `Diff.configure` block stay silent — they remain the canonical storage that `SnapDiff.config` forwards to
-- A few advertised entry-point constants that stay eagerly defined by design: `Capybara::Screenshot::Os`, `CapybaraScreenshotDiff::DSL`, `Capybara::Screenshot::Diff::VERSION`, and the driver leaf classes (`Drivers::VipsDriver`, `Drivers::ChunkyPNGDriver`)
+All three keep working for the whole 2.x line (2.0 deletes nothing) and each warns once per
+process, from the point you set it:
+
+```
+[snap_diff deprecation] `fail_if_new` is REMOVED in 2.1: the record modes replace it. `SnapDiff.config.record = :none` is `fail_if_new = true`, `= :once` is `fail_if_new = false` -- and unlike the boolean, a mode means the same thing on CI and off it. See docs/configuration.md. Silence with `SnapDiff.silence_deprecations = true` or SNAP_DIFF_SILENCE_DEPRECATIONS=1. (shown once per process) (called from /app/test/test_helper.rb:9)
+```
+
+**Nothing changes if you set none of them.** With no `record` line, `record` reads back as `:none`
+under CI and `:once` off it — exactly what `fail_if_new` already did, sniff and all. The
+missing-baseline default is deliberately unchanged; `:none` is how you opt into strictness
+explicitly. **Precedence:** an explicitly set mode outranks `fail_if_new`, and `fail_if_new`
+decides only when no mode was set — the same rule `fail_if_new` itself has over the `CI` sniff.
+
+`record = :all` **refuses to run under CI**: it accepts every rendering by design, so left in a
+committed config file it would be a build that compares nothing and passes forever. See
+[Record modes](configuration.md#record-modes--accepting-changes).
+
+#### Silent by design
+
+Some legacy names never warn individually, and that is deliberate — the migration notice above is
+the signal for all of them:
+
+- **The DSL.** `screenshot`, `assert_matches_screenshot`, `capture_screenshot` are never deprecated.
+- **Settings access.** `Capybara::Screenshot.blur_active_element`, `Capybara::Screenshot::Diff.tolerance=`
+  and the `Diff.configure` block are plain delegators onto `SnapDiff.config`. There is no
+  `const_missing` to hook, so they cannot warn per call without adding one on every read.
+- **Eagerly defined constants.** `Capybara::Screenshot::Os`, `Capybara::Screenshot::Diff::VERSION`,
+  `::Comparison`, `::LOADED_DRIVERS`, `::AVAILABLE_DRIVERS`, `::Reporters::Default`, the top-level
+  `Region`, the `CapybaraScreenshotDiff` error classes, and — under the v1 entry points —
+  `CapybaraScreenshotDiff::DSL` / `::Minitest::Assertions`. `const_defined?` never triggers
+  `const_missing`, so these have to be real constants for adopter feature detection and `rescue`
+  clauses to keep working — which means nothing is left to hook.
+- **The driver leaf classes.** `Drivers::VipsDriver` / `Drivers::ChunkyPNGDriver` are autoloaded on
+  `SnapDiff::Drivers`, so the leaf name itself never warns. Reaching them through the old path still
+  warns once for `Capybara::Screenshot::Diff::Drivers` — that part is a `const_missing` shim.
+  Each leaf is only declared when its gem is actually installed, so
+  `defined?(...Drivers::VipsDriver)` stays `nil` without `ruby-vips`, exactly as in v1.
+
+Every one of those names resolves under a canonical `snap_diff*` require too, so migrating your
+`require` line first (as this guide recommends) never breaks a constant you have not renamed yet.
 
 Warnings go through `Kernel#warn`, so test suites that hook `Warning.warn` (e.g. raise-on-warning setups) see them like any other Ruby warning.
 
@@ -191,14 +372,28 @@ export SNAP_DIFF_SILENCE_DEPRECATIONS=1
 
 ---
 
-### Known Alpha Caveats
+### Known Caveats
 
-Two deliberate consequences of the lazy shim design — both flagged for feedback on [#166](https://github.com/snap-diff/snap_diff-capybara/issues/166):
+Two deliberate consequences of the lazy shim design. Both go away at 2.1, when the shimmed
+names go away with them:
 
-1. **`defined?` / `const_defined?` on lazily-shimmed legacy names returns `false`/`nil`.** The shims resolve via `const_missing`, which those checks never trigger. Feature detection like `defined?(Capybara::Screenshot::Diff::ImageCompare)` must move to the `SnapDiff::` name. Rescuing legacy *error classes* is unaffected — they remain eagerly defined.
+1. **`defined?` / `const_defined?` on lazily-shimmed legacy names returns `false`/`nil`.** The shims resolve via `const_missing`, which those checks never trigger. Feature detection like `defined?(Capybara::Screenshot::Diff::ImageCompare)` must move to the `SnapDiff::` name. Everything in [Silent by design](#silent-by-design) is unaffected — those names are real constants, so `defined?`, `const_defined?` and `rescue` all behave as they always did.
 
 2. **Reopening `module Capybara::Screenshot::Diff::Drivers` shadows the shim.** The historical custom-driver monkey-patch pattern defines a fresh, empty `Drivers` module instead of reaching the real one. Define custom drivers under `SnapDiff::Drivers` instead — and note `BaseDriver` is gone as a superclass: `class MyDriver < BaseDriver` becomes `include SnapDiff::Driver` (it's a mixin now).
 
+#### Two moves that fail *silently* if you miss them
+
+**Stubbing the detected-drivers list.** The value moved to `SnapDiff::Drivers::AVAILABLE_DRIVERS`, and `Capybara::Screenshot::Diff::AVAILABLE_DRIVERS` is now an eager alias of it. *Reading* either is identical, but **stubbing the legacy name only rebinds the alias** — the gem keeps reading the canonical constant, so a test that stubs it to `[]` no longer exercises the no-drivers path and just passes for the wrong reason:
+
+```ruby
+# before
+Capybara::Screenshot::Diff.stub_const(:AVAILABLE_DRIVERS, []) { ... }
+# now
+SnapDiff::Drivers.stub_const(:AVAILABLE_DRIVERS, []) { ... }
+```
+
+**`SnapDiff::Config::MAPPING` is gone.** It split in two: `SnapDiff::Config::SETTINGS` (the setting names, no legacy knowledge) and `SnapDiff::LegacyShims::CONFIG_MAPPING` (which legacy holder each name hangs off). If you referenced `MAPPING` — iterating settings in a test helper, say — use `SETTINGS`; `CONFIG_MAPPING` is `@api private` and disappears in 2.1 with the rest of the v1 surface.
+
 ---
 
 ### FAQ
@@ -233,12 +428,15 @@ All settings and baselines are compatible with v1.x. Simply pin your Gemfile bac
 
 ### Summary Checklist
 
-- [ ] Pin `gem "capybara-screenshot-diff", "2.0.0.beta3"` (or the latest 2.0.0 prerelease) in your Gemfile
+- [ ] Pin `gem "capybara-screenshot-diff", "2.0.0.beta4"` in your Gemfile (`"~> 2.0"` once 2.0.0 ships)
 - [ ] Run `bundle install`
-- [ ] Run your test suite to verify no regressions
-- [ ] (Optional) Migrate config to the `SnapDiff` namespace
+- [ ] Run your system tests (`bin/rails test:system`, not `rake test`) to verify no regressions
+- [ ] Read the warnings it prints — each one names something 2.1 removes
+- [ ] Add `gem "ruby-vips"` if you are not already on it (2.1 makes libvips the only backend)
+- [ ] Drop `driver:` from your config and your `screenshot` calls — 2.0 warns about it, 2.1 removes it
+- [ ] (Optional, but do it before 2.1) Migrate config and constants to the `SnapDiff` namespace
 - [ ] (Optional) Silence deprecation warnings if not ready to migrate
-- [ ] Report anything surprising on [#166](https://github.com/snap-diff/snap_diff-capybara/issues/166)
+- [ ] Report anything surprising on [the issue tracker](https://github.com/snap-diff/snap_diff-capybara/issues)
 
 ---
 
@@ -261,7 +459,7 @@ gem 'capybara-screenshot-diff', '~> 1.13.0'
 
 ```bash
 bundle update capybara-screenshot-diff
-bundle exec rake test
+bin/rails test:system   # `rake test` skips test/system/ — 0 runs, no comparison
 ```
 
 **That's it!** Existing `screenshot` calls work unchanged. New methods available if needed.
@@ -346,7 +544,7 @@ gem 'capybara-screenshot-diff', '~> 1.12.0'
 
 ```bash
 bundle update capybara-screenshot-diff
-bundle exec rake test  # Verify tests still pass
+bin/rails test:system  # Verify tests still pass (`rake test` skips test/system/)
 ```
 
 **That's it!** The zero-config setup still works out of the box. Your existing screenshot comparisons will continue to work with v1.12.0.
@@ -551,7 +749,6 @@ Use the new `Diff.configure` 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
 ```
@@ -602,7 +799,7 @@ bundle update capybara-screenshot-diff
 ### Step 3: Run Tests
 
 ```bash
-bundle exec rake test
+bin/rails test:system   # `rake test` skips test/system/ — 0 runs, no comparison
 ```
 
 ### Step 4: Check for New Screenshot Failures
@@ -656,13 +853,14 @@ Capybara::Screenshot.hide_caret = false
 Then re-record baselines with the new defaults (recommended):
 
 ```bash
-# Delete old baselines
-rm doc/screenshots/*.png
+# Do NOT delete the baselines — they are read from git (`git show HEAD:<path>`), so
+# removing the files changes nothing. Re-recording is a commit.
 
-# Run tests to generate new baselines
-bundle exec rake test
+# The run fails and rewrites every changed baseline in place
+bin/rails test:system
 
-# Commit new baselines
+# Review the diffs, then commit the new baselines
+git status
 git add doc/screenshots/
 git commit -m "Re-record baselines with v1.12.0 defaults"
 ```

data/docs/architecture.md

@@ -125,9 +125,9 @@ Drivers abstract image processing operations. Shared default behavior lives in t
 | `merge` | Composite images | Not applicable |
 | `highlight_mask` | Conditional color overlay | Not applicable |
 
-**Auto-detection:** `Utils.detect_available_drivers` tries to load `:vips` first (via `ruby-vips` gem), then `:chunky_png`. The `:auto` driver mode picks the first available.
+**Auto-detection:** `SnapDiff::Drivers.detect_available` tries to load `:vips` first (via `ruby-vips` gem), then `:chunky_png`. The `:auto` driver mode picks the first available. `Utils.detect_available_drivers` is the older name and one-lines into it.
 
-**Registry (ADR-008 step 5b):** `SnapDiff::Drivers.loaded` is the canonical driver-class cache — a `name => class` hash filled lazily by `Utils.find_driver_class_for`, and the registration point for custom drivers (the legacy `Capybara::Screenshot::Diff::LOADED_DRIVERS` is an eager same-object alias, so registrations through either land in the same hash). `SnapDiff::Drivers.available` is the canonical read API for the detected list; the value itself still lives on `Capybara::Screenshot::Diff::AVAILABLE_DRIVERS`, which stays the published stubbing point. `SnapDiff::Drivers.for` resolves an options hash to a driver instance. See [Custom drivers](snapdiff.md#custom-drivers).
+**Registry (ADR-008 step 5b):** `SnapDiff::Drivers.loaded` is the canonical driver-class cache — a `name => class` hash filled lazily by `Utils.find_driver_class_for`, and the registration point for custom drivers (the legacy `Capybara::Screenshot::Diff::LOADED_DRIVERS` is an eager same-object alias, so registrations through either land in the same hash). `SnapDiff::Drivers.available` is the canonical read API for the detected list, and since the 2.1-readiness pass the value lives with it, as `SnapDiff::Drivers::AVAILABLE_DRIVERS` — that constant is now the published stubbing point, and the legacy `Capybara::Screenshot::Diff::AVAILABLE_DRIVERS` is an eager same-object alias of it. `SnapDiff::Drivers.for` resolves an options hash to a driver instance. See [Custom drivers](snapdiff.md#custom-drivers).
 
 ### 6. Difference Region Detection
 
@@ -221,7 +221,9 @@ Test begins
 
 Since ADR-008 step 1 the storage ownership is inverted from the original v2 consolidation: **`SnapDiff::Config` (`lib/snap_diff/config.rb`) IS the storage** — one eagerly-created instance, reachable as `SnapDiff.config`, holding every setting as a plain `attr_accessor`. It is the leaf of the config require graph and requires nothing that leads back to either entry point.
 
-The legacy `Capybara::Screenshot.*` / `Capybara::Screenshot::Diff.*` accessors are thin delegators generated from `Config::MAPPING` (both singleton and instance methods, matching what `mattr_accessor` used to define) that forward to that one object. One storage, two views — a write through either surface is visible through the other structurally, not by synchronization. `lib/capybara/screenshot/diff/config_legacy.rb` remains at the old path, but it now installs the delegating surface rather than owning the state.
+The legacy `Capybara::Screenshot.*` / `Capybara::Screenshot::Diff.*` accessors are thin delegators generated from `SnapDiff::LegacyShims::CONFIG_MAPPING` (both singleton and instance methods, matching what `mattr_accessor` used to define) that forward to that one object. One storage, two views — a write through either surface is visible through the other structurally, not by synchronization.
+
+Since the 2.1-readiness pass, `lib/snap_diff/legacy_shims.rb` is the single file that holds the v1 surface as code: the `const_missing` forwarders, `CONFIG_MAPPING` and its generator, the derived forwarders (`Screenshot.active?`, `Diff.configure`, `Diff.default_options`, …) and `SnapDiff.start`. `Config` itself names nothing from the v1 namespaces — it declares its settings in `Config::SETTINGS`, and `LegacyShims::CONFIG_MAPPING` says which legacy holder each one is exposed on (an invariant pinned by `snap_diff_config_test.rb`). `lib/capybara/screenshot/diff/config_legacy.rb` remains at the old path as a pair of requires.
 
 The two legacy views are organized into two namespaces:
 
@@ -232,13 +234,13 @@ The two legacy views are organized into two namespaces:
 
 **`Capybara::Screenshot::Diff`** — comparison settings:
 - `driver`, `tolerance`, `color_distance_limit`, `perceptual_threshold`, `shift_distance_limit`
-- `area_size_limit`, `skip_area`, `fail_if_new`, `fail_on_difference`, `delayed`
+- `area_size_limit`, `skip_area`, `record`, `fail_if_new`, `fail_on_difference`, `delayed`
 
-The canonical way in is `SnapDiff.configure { |config| ... }` (all 27 settings flat on one object). `SnapDiff.start` and `Capybara::Screenshot::Diff.configure` are the two-holder block shape over the same storage — since ADR-008 step 7b, `Diff.configure` forwards to `SnapDiff.start` rather than the other way round.
+The canonical way in is `SnapDiff.configure { |config| ... }` (all 28 settings flat on one object). `SnapDiff.start` and `Capybara::Screenshot::Diff.configure` are the two-holder block shape over the same storage — since ADR-008 step 7b, `Diff.configure` forwards to `SnapDiff.start` rather than the other way round.
 
 `Config` also owns the derived values that used to live on the legacy modules: `active?` (ex `Capybara::Screenshot.active?`), `screenshot_area` / `screenshot_area_abs`, and `default_options` (ex `Capybara::Screenshot::Diff.default_options`, the option hash handed to `SnapDiff::Comparison`). The legacy module methods one-line forward here.
 
-**Default timing contract:** every default is evaluated once, in `Config#initialize`, which runs at require time of `config.rb` — the same load moment the old `mattr_accessor` default blocks evaluated at. `fail_if_new` (from `ENV["CI"]`) and `root` (from `Rails.root`) must never become lazy read-time defaults. The one deliberately live value is `default_options[:wait]`, a method-body read of `Capybara.default_max_wait_time`.
+**Default timing contract:** every *stored* default is evaluated once, in `Config#initialize`, which runs at require time of `config.rb` — the same load moment the old `mattr_accessor` default blocks evaluated at. `root` (from `Rails.root`) must never become a lazy read-time default. Two values are deliberately live: `default_options[:wait]`, a method-body read of `Capybara.default_max_wait_time`, and `fail_if_new`, whose reader falls back to `ENV["CI"]` whenever nothing explicit was set — an explicit setting outranks the environment, so the sniff cannot be frozen into storage. `record` is the third: its reader falls back to `fail_if_new` (`:none` when it is on, `:once` when it is off), which is what makes the record modes a rename of the existing behaviour rather than a change to it — the matcher branches on the mode alone and a suite with no `record` line takes exactly the branches it always took.
 
 ## File Layout
 
@@ -247,7 +249,7 @@ lib/
   snap_diff.rb                                 # SnapDiff module: compare/start/configure/config
   snap_diff/                                   # Canonical implementation (v2)
     dsl.rb                                     # screenshot(), screenshot_group(), etc.
-    config.rb                                  # SnapDiff::Config — THE storage for all 27 settings
+    config.rb                                  # SnapDiff::Config — THE storage for all 28 settings
     errors.rb                                  # Error / ExpectationNotMet / UnstableImage / WindowSizeMismatchError
     region.rb                                  # SnapDiff::Region — bounding box (+ eager top-level ::Region alias)
     deprecation.rb                             # Warn-once-per-constant machinery

data/docs/ci-integration.md

@@ -58,7 +58,7 @@ jobs:
           bundler-cache: true
 
       - name: Run tests
-        run: bundle exec rake test
+        run: bin/rails test:system   # not `rake test` — it skips test/system/
 
       - name: Upload screenshot reports
         if: failure()
@@ -68,6 +68,10 @@ jobs:
           pr-comment: 'true'
 ```
 
+The three workflows on this page all run `bin/rails test:system`, because `rake test` and
+`rails test` skip `test/system/` and report `0 runs` — a green CI job that compared nothing.
+Not on Rails? Substitute whatever task loads your Capybara tests.
+
 That's it. On failure, this will:
 - Upload diff images + HTML report as artifacts
 - Post a PR comment with links to the inline report and full artifact download
@@ -129,7 +133,7 @@ jobs:
           ruby-version: '4.0'
           cache-apt-packages: true
 
-      - run: bundle exec rake test
+      - run: bin/rails test:system   # not `rake test` — it skips test/system/
 
       - uses: snap-diff/snap_diff-capybara/.github/actions/upload-screenshots@master
         if: failure()
@@ -160,7 +164,7 @@ jobs:
         run: sudo apt-get install -y libvips-dev
 
       - name: Run tests
-        run: bundle exec rake test
+        run: bin/rails test:system   # not `rake test` — it skips test/system/
 
       - name: Upload screenshot report
         if: failure()
@@ -184,14 +188,21 @@ jobs:
 
 ## Update Baselines in CI
 
-When intentional UI changes are made, baselines need to be re-recorded. You can do this locally:
+When intentional UI changes are made, baselines need to be re-recorded. Baselines are
+read from git, so accepting a change is a commit — the failing run has already written
+the new capture to the baseline path:
 
 ```bash
-RECORD_SCREENSHOTS=1 bundle exec rake test
-git add test/fixtures/screenshots/
+bin/rails test:system                  # fails, and rewrites the changed baselines
+git status                             # review what moved
+git add doc/screenshots/               # the default save_path; adjust if you changed it
 git commit -m "chore: update screenshot baselines"
 ```
 
+With the [recommended `.gitignore`](../README.md#quick-start-5-minutes) in place, `git add
+doc/screenshots/` stages only the baselines — the `.diff.png` / `.base.png` artifacts are
+ignored.
+
 Or add a workflow that maintainers can trigger manually:
 
 <details>
@@ -225,24 +236,44 @@ jobs:
           ruby-version: '4.0'
           cache-apt-packages: true
 
-      - name: Record new baselines
-        run: RECORD_SCREENSHOTS=1 bundle exec rake test
-        continue-on-error: true
+      - name: Record baselines
+        run: bin/rails test:system
+        continue-on-error: true    # the run fails by design; it rewrites the baselines
+        env:
+          CI: ""                   # see below — without this, a NEW screenshot is never written
 
       - name: Commit updated baselines
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add test/fixtures/ doc/screenshots/
+          git add doc/screenshots/
           git diff --staged --quiet || git commit -m "chore: update screenshot baselines"
           git push
 ```
 
 </details>
 
+> **Set the record mode, or clear `CI`, to let this job record a *new* baseline.** With
+> nothing set, a missing baseline fails whenever `ENV["CI"]` is set and non-empty — so on a
+> stock GitHub Actions runner a screenshot with no committed baseline raises `No existing
+> screenshot found for …`. `SnapDiff.config.record = :once`
+> (or clearing `CI` for this one step, or the older `SnapDiff.config.fail_if_new = false`)
+> records new baselines instead. *Changed* baselines are rewritten either way; only new ones
+> need this. See [Record modes](configuration.md#record-modes--accepting-changes).
+>
+> The screenshot itself **is** written before the raise ([`screenshot_matcher.rb`](https://github.com/snap-diff/snap_diff-capybara/blob/master/lib/snap_diff/screenshot_matcher.rb)
+> — `capture_screenshot` precedes `fail_if_new_screenshot`), so the `git add` the message names
+> is a command you can actually run. But the raise still fails the test it happened in, and a red
+> job usually never reaches the commit step — which is why a recording job sets the mode rather
+> than relying on the files being there.
+>
+> **`record = :all` is not the mode for this job** — it refuses to run under CI, because it
+> would accept every *changed* rendering unreviewed as well. `:once` records what is new and
+> keeps comparing everything that already has a baseline.
+
 **How it works:**
 1. Go to Actions → "Update Screenshot Baselines" → "Run workflow"
 2. Enter the branch name (e.g. your PR branch)
-3. The workflow records new baselines, commits, and pushes
+3. The workflow records new and changed baselines, commits, and pushes
 
 [← Back to README](../README.md)