fix: skip at_exit when framework adapter handles finalization (#183)

* fix: skip at_exit when framework adapter handles finalization

Minitest, RSpec, and Cucumber adapters call finalize_reporters! via
native hooks. The at_exit fallback in html.rb was firing as a wasted
no-op for those frameworks (hitting @Finalized guard every time).

Now only registers at_exit when no known framework is loaded.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: adopt SimpleCov's external_at_exit pattern

Framework adapters set external_at_exit = true and register native
hooks (Minitest.after_run, RSpec after(:suite), Cucumber AfterAll).
The at_exit block checks the flag and skips when a framework adapter
handles finalization.

This eliminates both the double-call problem and the LIFO ordering
problem cleanly — same pattern SimpleCov uses successfully.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add custom framework finalize_reporters! and vips install notes

- Document how to call finalize_reporters! for custom test frameworks
- Add brew/apt install commands for libvips in Requirements

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: remove external_at_exit flag, rely on @Finalized guard

The external_at_exit flag was overkill — @Finalized in #finalize already
prevents double work. Simpler: at_exit always registers, framework
adapters also register native hooks, @Finalized ensures only the first
call does work.

Also move custom framework docs from README to docs/framework-setup.md.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: remove at_exit hook entirely

Framework adapters (Minitest, RSpec, Cucumber) call finalize_reporters!
via native hooks. at_exit was unreliable due to LIFO ordering and added
complexity for a case nobody hits. Custom frameworks can call
finalize_reporters! manually (documented in docs/framework-setup.md).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: pftg

README.md

@@ -196,7 +196,7 @@ Comparisons add ~50ms per image with VIPS. Without `ruby-vips`, ChunkyPNG is use
 
 ## Installation
 
-**Requirements:** Ruby 3.2+. Rails 7.1+ for Rails integration; non-Rails projects supported via `CapybaraScreenshotDiff.serve()`. For the `:vips` driver: [libvips 8.9+](https://libvips.github.io/libvips/install.html).
+**Requirements:** Ruby 3.2+. Rails 7.1+ for Rails integration; non-Rails projects supported via `CapybaraScreenshotDiff.serve()`. For the `:vips` driver: [libvips 8.9+](https://libvips.github.io/libvips/install.html). On macOS: `brew install vips`. On Ubuntu: `apt-get install libvips-dev`.
 
 ## Docs
 

docs/framework-setup.md

@@ -74,4 +74,14 @@ Then('I should not see any visual difference') do
 end
 ```
 
+## Custom Test Frameworks
+
+Minitest, RSpec, and Cucumber are supported out of the box. For other frameworks, call `finalize_reporters!` in your framework's "after suite" hook:
+
+```ruby
+CapybaraScreenshotDiff.finalize_reporters!
+```
+
+This generates the HTML report and prints the summary.
+
 [← Back to README](../README.md)

lib/capybara_screenshot_diff/reporters/html.rb

@@ -129,13 +129,9 @@ def write_report
   end
 end
 
-# Auto-register reporter and at_exit hook.
-# The reporter only writes when there are failures (finalize checks failures.empty?).
-# Scripts that create their own reporter instance call record/finalize directly.
+# Auto-register reporter.
+# Framework adapters (Minitest, RSpec, Cucumber) call finalize_reporters! via native hooks.
+# For custom frameworks, call CapybaraScreenshotDiff.finalize_reporters! manually.
 unless CapybaraScreenshotDiff.reporters.any?(CapybaraScreenshotDiff::Reporters::HTML)
   CapybaraScreenshotDiff.reporters << CapybaraScreenshotDiff::Reporters::HTML.new(embed_images: !!ENV["CI"])
 end
-
-# Fallback for frameworks without explicit integration (e.g., Cucumber).
-# Minitest and RSpec adapters call finalize_reporters! via their native hooks.
-at_exit { CapybaraScreenshotDiff.finalize_reporters! }