capybara-storyboard 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0f2357cb5edac81b907bc4196d8469d85c5de0636932fa2dbe25d2985edaa6a9
+  data.tar.gz: 2c4dffec621810ef339178aafacefffaefec409c3f6b72ef7c4944d1b770e7c3
+SHA512:
+  metadata.gz: 57a736051c0a33c64227ae7f576d1c5b4739e8c3e1a9c5e969be1534abf1b1072463845a92bbff69b1396df8dbc0a5fa3fd4211c9412ed69133ca2d81a3cfe95
+  data.tar.gz: c366ae904aada06f091ded0cb7697754506f40a5ceac87f6383a1a83cf0bda2f619e3a4901afc9c53690a399f5ace1a1064fcb6e7bc0b3e006b725e78e770f43

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-07-21
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"capybara-storyboard" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["lala.akira@gmail.com"](mailto:"lala.akira@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 aki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,266 @@
+# Capybara::Storyboard
+
+Capybara::Storyboard records the Capybara operations performed during your RSpec system
+tests — `visit`, `click_on`, and more — together with a screenshot taken at each step, and
+organizes them into an ordered "storyboard" per test. This lets you review the flow of a
+system test at a glance, without re-running it or reading through the spec line by line.
+
+## Requirements
+
+- Ruby >= 3.4.0
+- A Rails application with RSpec system specs. ActiveSupport is expected to already be
+  loaded (the gem relies on core extensions such as `present?`); it is not declared as a
+  gemspec dependency, since a Rails application loads it already.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add capybara-storyboard
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install capybara-storyboard
+```
+
+## Setup
+
+Require the gem from `spec_helper.rb` or `rails_helper.rb`:
+
+```ruby
+require "capybara/storyboard"
+```
+
+Then include `Capybara::Storyboard::TestHelper` in your system specs via `RSpec.configure`,
+and register a `before(:suite)` hook that clears stale screenshots from previous runs (see
+[Clearing previous screenshots](#clearing-previous-screenshots)):
+
+```ruby
+RSpec.configure do |config|
+  config.include Capybara::Storyboard::TestHelper, type: :system
+  config.before(:suite) { Capybara::Storyboard.clear_output! }
+end
+```
+
+`TestHelper` overrides Capybara DSL methods (`visit`, `click_on`, etc.) and chains into them
+via `super`, so it must be included **after** `Capybara::DSL` has been included. In a normal
+RSpec system spec setup, Capybara is already configured for `type: :system` examples, so
+including `TestHelper` for the same `type: :system` examples (as shown above) works without
+any extra ordering concerns.
+
+## Usage
+
+Once `TestHelper` is included, the Capybara DSL calls in your system specs are automatically
+hooked, and — when enabled (see [Enabling screenshots](#enabling-screenshots)) — a screenshot
+is captured before and/or after each call.
+
+The following DSL methods are hooked: `visit`, `click_on`, `click_link`, `click_button`,
+`fill_in`, `select`, `check`, `uncheck`, `choose`, `attach_file`, `accept_confirm`,
+`accept_alert`.
+
+- The click methods (`click_on`, `click_link`, `click_button`) capture **two** screenshots:
+  one before and one after the operation.
+- All other methods capture **one** screenshot, taken after the operation.
+
+You can also take a screenshot manually at any point in a spec by calling
+`storyboard_screenshot`:
+
+```ruby
+storyboard_screenshot("some label")
+```
+
+Manual screenshots taken via `storyboard_screenshot` obey the same enabling switch as the
+automatic hooks: they are captured **only when the mechanism is enabled** (i.e. when the
+policy — driven by `SCREENSHOTS` and the target list — evaluates to true), and are skipped
+otherwise. If you need an unconditional screenshot regardless of that switch, use Capybara's
+own `save_screenshot` instead.
+
+Example:
+
+```ruby
+RSpec.describe "Login", type: :system do
+  it "logs in successfully" do
+    visit "/login"
+    fill_in "Email", with: "user@example.com"
+    fill_in "Password", with: "password"
+    click_on "Log in"
+
+    storyboard_screenshot("logged in")
+
+    expect(page).to have_content("Welcome")
+  end
+end
+```
+
+## Enabling screenshots
+
+Whether screenshots are captured at all is controlled by two independent layers: an
+enabling switch (`SCREENSHOTS`), and, within that, an optional target list that narrows
+which test files are captured.
+
+| Case | `SCREENSHOTS` | Target list | Behavior |
+|---|---|---|---|
+| Disabled | unset | — | No screenshots. Hooks have effectively zero overhead. |
+| Capture all (default) | `1` | unset (both ENV vars unset) | Screenshots for all system tests. |
+| Selective capture | `1` | set via `SCREENSHOT_TESTS_FILE` / `SCREENSHOT_TESTS` | Only the listed test files are captured. If the resulting set is empty, zero screenshots are taken (an empty selection does NOT fall back to capturing everything). |
+
+In short: `SCREENSHOTS` arms the mechanism as a whole, and the target list — when present —
+filters down which tests are captured within that armed mechanism.
+
+## Selecting which tests to capture
+
+When `SCREENSHOTS` is enabled, you can narrow capture to specific test files using either
+(or both) of these environment variables:
+
+| ENV var | Format | Purpose |
+|---|---|---|
+| `SCREENSHOT_TESTS_FILE` | Path to a file containing newline-separated test file paths | Primary channel. Suited for large lists / CI generation. |
+| `SCREENSHOT_TESTS` | Comma-separated test file paths | Secondary. For a small number of manual paths. |
+
+When both are set, the union of the two lists is used.
+
+If `SCREENSHOT_TESTS_FILE` points to a file that does not exist, `Capybara::Storyboard::Error`
+is raised. (This existence check only runs when `SCREENSHOTS` is enabled; when the mechanism
+is disabled, the target list is never read.)
+
+Examples:
+
+```bash
+# Inline list of test files
+SCREENSHOTS=1 SCREENSHOT_TESTS=spec/system/login_spec.rb,spec/system/signup_spec.rb bundle exec rspec
+
+# List generated into a file (e.g. by CI, listing only changed specs)
+SCREENSHOTS=1 SCREENSHOT_TESTS_FILE=tmp/screenshot_targets.txt bundle exec rspec
+```
+
+## Output layout
+
+Screenshots are written under:
+
+```
+tmp/screenshots/{spec_path}/{example_name}/{NNN_action_detail}.png
+```
+
+`{spec_path}` mirrors the spec file's own path, with the leading `spec/` segment and the
+`_spec.rb` suffix removed. For example, `spec/system/signup_spec.rb` becomes
+`system/signup/...`, and a nested spec such as `spec/system/admin/users_spec.rb` becomes
+`system/admin/users/...`.
+
+Each test gets its own directory, and a zero-padded sequence number (`NNN`) preserves the
+order in which actions occurred. For example:
+
+- Click methods capture two files: `001_before_click_on_Done.png`, `002_after_click_on_Done.png`
+- Other methods capture one file: `001_visit_users.png`
+
+Non-ASCII descriptions and labels (e.g. Japanese) are preserved as-is in file and directory
+names; only symbols and whitespace are replaced with underscores.
+
+The default output root is `<Rails.root>/tmp/screenshots` (overridable, see
+[Configuration](#configuration)).
+
+### Clearing previous screenshots
+
+To avoid a run's screenshots mixing with stale files left behind by a previous
+run, register `Capybara::Storyboard.clear_output!` in a `before(:suite)` hook (as
+shown in [Setup](#setup)):
+
+```ruby
+RSpec.configure do |config|
+  config.before(:suite) { Capybara::Storyboard.clear_output! }
+end
+```
+
+When screenshots are enabled (`SCREENSHOTS` is set), this empties the output root
+once at the start of the rspec run.
+
+- When `SCREENSHOTS` is unset, `clear_output!` leaves the output root untouched
+  (preserving the "disabled → nothing happens" contract), so the hook is safe to
+  register unconditionally.
+- `clear_output!` clears at most once per process, so registering the hook is
+  idempotent even if it runs more than once.
+- **With `parallel_tests`**: `before(:suite)` fires once per RSpec process, so
+  each worker empties the shared output root at startup — the root is not cleared
+  exactly once across all processes.
+
+## Configuration
+
+Use `Capybara::Storyboard.configure` to override the defaults:
+
+```ruby
+Capybara::Storyboard.configure do |config|
+  config.output_dir = Rails.root.join("tmp", "my_screenshots")
+  config.policy = ->(context) { ... } # or any object responding to #call(context) -> Boolean
+
+  config.page_stability_interval = 0.5
+  config.page_stability_max_attempts = 10
+  config.page_stability_excluded_animations = []
+end
+```
+
+- `config.output_dir`: overrides the output root directory. Defaults to
+  `<Rails.root>/tmp/screenshots`.
+- `config.policy`: overrides the policy that decides whether to capture. Must respond to
+  `#call(context) -> Boolean` (a proc works too). Defaults to a policy composed from
+  `SCREENSHOTS` and the target list, as described in
+  [Enabling screenshots](#enabling-screenshots).
+
+If you don't set `config.policy` explicitly, the default policy described above (driven by
+`SCREENSHOTS` and the target list) is used.
+
+### Page-stability wait
+
+Just before each screenshot is captured, the gem waits for the page to become visually
+stable — no running CSS/JS animations (via `document.getAnimations()`) and no DOM mutations
+for a short quiet window (tracked by a `MutationObserver`) — so screenshots don't catch the
+page mid-transition. The wait never blocks the screenshot itself: on a non-JS driver (e.g.
+`Rack::Test`), or if anything goes wrong while waiting, it's a safe no-op and the screenshot
+is still taken. The wait is tunable via:
+
+- `config.page_stability_interval`: seconds between polls, and the required DOM-quiet window.
+  Defaults to `0.5`.
+- `config.page_stability_max_attempts`: maximum number of polls before giving up. On timeout
+  the gem does not raise; it prints a warning to STDERR and captures the screenshot anyway.
+  Defaults to `10`.
+- `config.page_stability_excluded_animations`: an array of CSS animation names to ignore when
+  deciding whether animations are still running (e.g. perpetual spinners). Defaults to `[]`.
+
+## Caveats and limitations
+
+- Test files are expected to be laid out flat as `spec/system/*_spec.rb`. Nested
+  subdirectories may work but are not comprehensively verified in this initial version.
+- The target-list selection matches on test file paths. A PR that changes only views
+  (leaving the system spec file itself unchanged) cannot be picked up by the target-list
+  approach — this is a known, deliberate limitation of the initial version.
+
+## Guides
+
+- [docs/github-actions.md](docs/github-actions.md) — a recipe for capturing screenshots on a
+  diff basis in GitHub Actions.
+- [skills/capybara-storyboard](skills/capybara-storyboard) — an agent skill for visually
+  verifying captured screenshots (Claude Code, or any agent that can read PNG files from the
+  filesystem).
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/aki77/capybara-storyboard. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/aki77/capybara-storyboard/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Capybara::Storyboard project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/aki77/capybara-storyboard/blob/main/CODE_OF_CONDUCT.md).
+
+## Acknowledgments
+
+The idea for this gem was inspired by [Giving Claude Code Eyes: Round Trip Screenshot Testing](https://medium.com/@rotbart/giving-claude-code-eyes-round-trip-screenshot-testing-ce52f7dcc563).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docs/github-actions.md

@@ -0,0 +1,95 @@
+# GitHub Actions recipe: capture screenshots on a diff basis
+
+Capybara::Storyboard only receives a target set — it does not know how to compute one. This
+recipe shows the CI side of that split: diff against the PR base branch, extract the changed
+system spec files, write them to a file, and pass that file in via `SCREENSHOT_TESTS_FILE`.
+
+For how enabling and target-list selection actually behave inside the gem, see the README's
+[Enabling screenshots](../README.md#enabling-screenshots) and
+[Selecting which tests to capture](../README.md#selecting-which-tests-to-capture) sections —
+this document does not repeat that reference material.
+
+## Workflow
+
+```yaml
+name: Screenshot storyboard
+
+on:
+  pull_request:
+
+jobs:
+  storyboard:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Fetch base branch
+        run: git fetch origin "${{ github.event.pull_request.base.ref }}"
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      - name: Extract changed system spec files
+        run: |
+          mkdir -p tmp
+          git diff --name-only --diff-filter=d \
+            "origin/${{ github.event.pull_request.base.ref }}...HEAD" \
+            | grep -E '^spec/system/.*_spec\.rb$' \
+            > tmp/screenshot_targets.txt || true
+          touch tmp/screenshot_targets.txt
+
+      - name: Run system specs
+        env:
+          SCREENSHOTS: "1"
+          SCREENSHOT_TESTS_FILE: tmp/screenshot_targets.txt
+        run: bundle exec rspec spec/system
+
+      - name: Upload screenshots
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: storyboard-screenshots
+          path: tmp/screenshots/**
+          if-no-files-found: ignore
+```
+
+Notes on the steps above:
+
+- `fetch-depth: 0` on checkout, plus explicitly fetching the base branch, ensures the
+  three-dot diff (`origin/<base>...HEAD`) has both sides of history available. A shallow
+  checkout without fetching the base ref will fail or produce an incomplete diff.
+- The extraction step pipes through `grep -E` and always ends with `touch
+  tmp/screenshot_targets.txt`. `grep` exits non-zero when there are no matches, so `|| true`
+  keeps the step from failing, and the trailing `touch` guarantees the file exists — empty if
+  nothing matched. This is required: see the notes below on why the file must always be
+  created.
+- The run step passes `SCREENSHOTS=1` and `SCREENSHOT_TESTS_FILE=tmp/screenshot_targets.txt`
+  as env for that step only, scoping the target list to this job.
+- The upload step uses `if: always()` so screenshots are attached even if a spec fails
+  partway through, and `if-no-files-found: ignore` so an empty target list (and therefore no
+  screenshots) doesn't fail the upload step.
+
+## Notes
+
+- **View-only PRs are not picked up.** This recipe selects targets by matching test file
+  paths in the diff. A PR that only changes views or other application code — leaving the
+  system spec file itself untouched — will not add anything to
+  `tmp/screenshot_targets.txt`, because the spec file never appears in the diff. This is a
+  known, deliberate limitation of the initial version; see the README's
+  [Caveats and limitations](../README.md#caveats-and-limitations).
+- **An empty target file producing zero screenshots is correct, not a bug.** When no changed
+  file matches `spec/system/.*_spec\.rb`, `tmp/screenshot_targets.txt` is empty, the target
+  list narrows down to nothing, and zero screenshots are taken. That's the narrowing working
+  as intended — it is not the same as omitting `SCREENSHOT_TESTS_FILE` entirely, which instead
+  captures every system spec.
+- **A missing file fails the job loudly.** If the extraction step were to fail in a way that
+  leaves `SCREENSHOT_TESTS_FILE` pointing at a path that doesn't exist, the run raises
+  `Capybara::Storyboard::Error` instead of silently capturing everything or nothing. This
+  detection only happens in a job that also passes `SCREENSHOTS=1` — a job without it never
+  reads the target list at all. This is exactly why the extraction step above always creates
+  the file (empty when there are no matches) rather than skipping the write on no matches.

data/lib/capybara/storyboard/configuration.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Capybara
+  module Storyboard
+    # Holds the user-overridable settings: where screenshots are rooted and
+    # which policy decides whether to capture. Defaults are resolved lazily in
+    # the getters so that merely constructing (or loading the gem) never reads
+    # ENV or builds the default policy — that keeps the "disabled -> zero
+    # overhead" contract intact.
+    class Configuration
+      DEFAULT_PAGE_STABILITY_INTERVAL = 0.5
+      DEFAULT_PAGE_STABILITY_MAX_ATTEMPTS = 10
+      DEFAULT_PAGE_STABILITY_EXCLUDED_ANIMATIONS = [].freeze
+
+      # An object responding to #call(context) -> Boolean. Assign nil (or call
+      # reset_policy!) to restore the default on the next read.
+      attr_writer :policy
+
+      # Assign nil to any of these to restore its default on the next read:
+      #   page_stability_interval=            seconds between polls (default 0.5)
+      #   page_stability_max_attempts=        poll count before warning (default 10)
+      #   page_stability_excluded_animations= names to ignore (default [])
+      attr_writer :page_stability_interval, :page_stability_max_attempts, :page_stability_excluded_animations
+
+      # The output root under which Session appends <group>/<example>. Returns
+      # the default (<base>/tmp/screenshots) until overridden.
+      def output_dir
+        @output_dir || default_output_dir
+      end
+
+      # Accepts nil (restore default) or any value coercible to a Pathname.
+      # A non-nil value is stored as a Pathname because Session calls #join on
+      # it; a relative path is kept as-is (resolved against the cwd, which is
+      # Rails.root under normal use).
+      def output_dir=(value)
+        @output_dir = value.nil? ? nil : Pathname(value)
+      end
+
+      def policy
+        @policy ||= Capybara::Storyboard.default_policy
+      end
+
+      # Equivalent to `self.policy = nil`; named for readable `after` hooks that
+      # prevent a custom policy from leaking into later examples.
+      def reset_policy!
+        @policy = nil
+      end
+
+      # Seconds to wait between page-stability polls, and the same value the
+      # DOM-quiet check must exceed. Returns the default (0.5) until overridden.
+      def page_stability_interval
+        @page_stability_interval || DEFAULT_PAGE_STABILITY_INTERVAL
+      end
+
+      # Maximum number of stability polls before giving up (and warning rather
+      # than raising). Returns the default (10) until overridden.
+      def page_stability_max_attempts
+        @page_stability_max_attempts || DEFAULT_PAGE_STABILITY_MAX_ATTEMPTS
+      end
+
+      # Animation names ignored by the running-animation check (e.g. infinite
+      # spinners). Returns the default (empty list) until overridden.
+      def page_stability_excluded_animations
+        @page_stability_excluded_animations || DEFAULT_PAGE_STABILITY_EXCLUDED_ANIMATIONS
+      end
+
+      private
+
+      # Screenshots live under <base>/tmp/screenshots, where the base directory
+      # (Rails.root or the cwd fallback) is resolved in one shared place.
+      def default_output_dir
+        Capybara::Storyboard.rails_root_or_pwd.join('tmp', 'screenshots')
+      end
+    end
+  end
+end

data/lib/capybara/storyboard/context.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Storyboard
+    # Value object passed to a policy's #call. Derivation from the RSpec example
+    # lives in TestHelper; this object only carries values.
+    #
+    # test_file is the raw RSpec file_path string; this object never normalizes
+    # it. Canonicalization to a base-relative path is done on demand by
+    # Capybara::Storyboard.normalize_test_path (used by TargetListPolicy).
+    Context = Data.define(:test_class_name, :test_method_name, :test_file)
+  end
+end

data/lib/capybara/storyboard/page_stability.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Capybara
+  module Storyboard
+    # Waits for a page to become visually stable before a screenshot is taken:
+    # no running CSS/JS animations (via document.getAnimations()) AND no DOM
+    # mutations for at least +interval+ seconds (tracked by a MutationObserver).
+    #
+    # Ported from SonicGarden/wlb-morning-mail's capybara_screenshot_helper.rb.
+    #
+    # Stateless, so exposed as module functions. On a non-JS driver (Rack::Test)
+    # or when the driver rejects the script, the whole thing is a safe no-op: a
+    # failed wait must never prevent the screenshot itself from being taken.
+    module PageStability
+      # Reports the running-animation count and time since the last DOM mutation.
+      # Static (no interpolation), so built once and reused on every poll.
+      CHECK_SCRIPT = <<~JS
+        (function() {
+          const timeSinceLastMutation = Date.now() - window._lastMutationTime;
+          const excludedAnimations = window._excludedAnimations ?? [];
+          const animations = document.getAnimations();
+          const runningAnimations = animations.filter(animation => {
+            // getAnimations() keeps finished/paused animations attached to the
+            // element until they are cancelled or the node is removed, so only
+            // count the ones actually playing.
+            if (animation.playState !== 'running') {
+              return false;
+            }
+            if (animation instanceof CSSAnimation) {
+              return !excludedAnimations.includes(animation.animationName);
+            }
+            return true;
+          }).length;
+          return { timeSinceLastMutation: timeSinceLastMutation, runningAnimations: runningAnimations };
+        })();
+      JS
+
+      # Tears down the observer and its globals. Static, so built once and reused.
+      CLEANUP_SCRIPT = <<~JS
+        if (window._pageStabilityObserver) {
+          window._pageStabilityObserver.disconnect();
+          delete window._pageStabilityObserver;
+          delete window._lastMutationTime;
+          delete window._excludedAnimations;
+        }
+      JS
+
+      module_function
+
+      # Polls +page+ until stable or +max_attempts+ is reached. When the limit
+      # is hit the page is deemed "good enough": a warning is printed to STDERR
+      # and control returns normally (no exception), so capture proceeds.
+      def wait_for_stable_page(page, interval:, max_attempts:, excluded_animations:)
+        setup(page, excluded_animations)
+
+        result = nil
+        stable = false
+        max_attempts.times do |attempt|
+          result = check(page)
+          stable = stable?(result, interval)
+          break if stable
+
+          # No point sleeping after the final check — nothing re-checks it.
+          sleep(interval) unless attempt == max_attempts - 1
+        end
+
+        # Unstable (or max_attempts was 0): the page is deemed good enough.
+        warn_unstable(result, interval) unless stable
+      rescue StandardError => e
+        # A failed wait must never prevent the screenshot from being taken, so
+        # swallow every error and let capture proceed. Expected "this driver
+        # can't run JS" errors (e.g. Rack::Test) are silent; anything else is
+        # surfaced via warn so a real driver problem stays visible.
+        warn("capybara-storyboard: page stability wait skipped after error: #{e.class}: #{e.message}") unless
+          non_js_driver_error?(e)
+        nil
+      ensure
+        cleanup(page)
+      end
+
+      def setup(page, excluded_animations)
+        page.execute_script(<<~JS)
+          window._lastMutationTime = Date.now();
+          window._excludedAnimations = #{excluded_animations.to_json};
+          window._pageStabilityObserver = new MutationObserver(() => {
+            window._lastMutationTime = Date.now();
+          });
+          window._pageStabilityObserver.observe(document.body, {
+            childList: true, subtree: true, attributes: true, characterData: true
+          });
+        JS
+      end
+
+      def check(page)
+        page.evaluate_script(CHECK_SCRIPT)
+      end
+
+      # Best-effort teardown so no globals leak between screenshots. Runs from an
+      # ensure block, so it must never raise even when setup never happened or
+      # the driver can't run JS.
+      def cleanup(page)
+        page.execute_script(CLEANUP_SCRIPT)
+      rescue StandardError
+        nil
+      end
+
+      # evaluate_script returns string-keyed hashes on the real drivers; the
+      # DOM-quiet window is measured in ms, so compare against interval * 1000.
+      def stable?(result, interval)
+        result['runningAnimations'].zero? && result['timeSinceLastMutation'] >= (interval * 1000)
+      end
+
+      # Warns using the last observed poll result (nil when max_attempts is 0),
+      # so no extra JS round-trip is made and the reported numbers match the
+      # values that actually failed the stability check.
+      def warn_unstable(result, interval)
+        warn(
+          'capybara-storyboard: page did not become stable before the screenshot ' \
+          "(runningAnimations=#{result && result['runningAnimations']}, " \
+          "timeSinceLastMutation=#{result && result['timeSinceLastMutation']}ms, threshold=#{interval * 1000}ms)."
+        )
+      end
+
+      # True when +error+ means "this driver can't run our JS" — the expected,
+      # non-alarming case (e.g. Rack::Test) that should skip silently rather
+      # than warn. Capybara is optional at load time (the gem's own specs don't
+      # require it) and Selenium may be absent, so resolve each constant only
+      # when defined; an undefined constant simply never matches.
+      def non_js_driver_error?(error)
+        return true if defined?(Capybara::NotSupportedByDriverError) &&
+                       error.is_a?(Capybara::NotSupportedByDriverError)
+        return true if defined?(Selenium::WebDriver::Error::JavascriptError) &&
+                       error.is_a?(Selenium::WebDriver::Error::JavascriptError)
+
+        false
+      end
+    end
+  end
+end

data/lib/capybara/storyboard/policies/env_policy.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Storyboard
+    module Policies
+      # Arms the whole mechanism from ENV. Backward-compatible with the gist:
+      # true iff SCREENSHOTS is set to a non-blank value. Ignores the context
+      # entirely — the argument exists only to honor the call(context) contract.
+      class EnvPolicy
+        def call(_context)
+          ENV['SCREENSHOTS'].present?
+        end
+      end
+    end
+  end
+end