action_version_preview 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6d263561ee95f415d87df090bb1e0008500048a1a896c96ae2df8ba7690e6b7
-  data.tar.gz: fc72870345f275e9e40fe4d75a5bba496467239e577fb524ecfd2e4b9b740fb2
+  metadata.gz: e06ec511eedee6043f22f30770eba50bbaaf4e084607fa22aefc3dd0bec1c590
+  data.tar.gz: c0b5c97188fc3e16d3a68d2df693198f96957f035fc565af62b07cac569d153e
 SHA512:
-  metadata.gz: f8353f9edc0f76a49425d6a5147b814fc6ca82304c465c186f33a94a8c42f61cea4d8120c0f8c5332636f277705e43e3755f1d38b10706137902d356d5c98011
-  data.tar.gz: 87099d11c6a79710263dc7c5b8f58a0e91a066279f60a9f4ad8b2c2a011096f1e33b79db414719b61a237e4f755b0c3950dedc77dd48272135b5138a03e7af80
+  metadata.gz: c4a6ecab2cdcff048f1de1181d2924f6a5f7531fa20855a0c2af6fbeafd632e394e385fe34d95f5e447bb5e65cf30215f1cf1adf837a39b94ec60e1945e21b00
+  data.tar.gz: '089c2fb8619a595af161f68c3f5e73f1ce16cd0df053c6b53320bebfb6954764a86608efe93b944e2a030c68031f453198974c0c0279a7584e6009e967d80b21'

data/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## [0.2.0] - 2026-09-15
+
+### Fixed
+
+- Fixed `ActionVersionPreview::SwitcherHelper` load-order errors during Rails boot
+  and asset precompilation, including early controller/view loading.
+- Kept switcher links on the current path, preserving mounted prefixes, nested
+  query filters, and configured preview parameter names. Query keys are no longer
+  interpreted as Rails routing options.
+- Excluded POST body fields from switcher URLs.
+
+### Added
+
+- Fresh-process regression tests for early/lazy framework loading, development
+  reloading, and production asset precompilation using a built and installed gem.
+- Integration tests for switcher URL safety, mounted paths, custom parameters,
+  nested filters, and POST-body exclusion.
+- Comprehensive public usage documentation and upgrade instructions, included
+  with the gem alongside this changelog.
+
+### Changed
+
+- Explicitly load the stateless switcher helper from `lib` so its availability does
+  not depend on Rails autoloading or reloading.
+- Updated development dependency resolution and GitHub Actions versions.
+- Clarified supported integration behavior and current discovery limitations.
+
+No migrations or required configuration changes. Declared Ruby/Rails requirements,
+preview access defaults, and Default-link behavior are unchanged. Full details are
+in the [0.2.0 release notes](docs/releases/0.2.0.md).
+
+## [0.1.0] - 2025-12-17
+
+### Added
+
+- Initial release.
+- Side-by-side UI previews in separate tabs using Rails view variants.
+- Automatic integration with `ActionController::Base`.
+- Optional variant switcher and configurable preview parameter/access check.
+- Declared support for Rails 7.0 through 8.x.

data/README.md

@@ -1,118 +1,136 @@
 # ActionVersionPreview
 
-Preview multiple versions of your UI simultaneously using Rails' built-in view variants. No feature flags, no complex setup. Just create variant templates and visit them via URL.
+Preview multiple versions of a Rails UI in separate browser tabs using native
+view variants. Add variant templates, open their URLs, and compare designs while
+signed in as the same user. No additional database, feature-flag service, or
+JavaScript is required.
 
-## Why?
+[Full usage guide](docs/usage.md) · [Changelog](CHANGELOG.md) · [RubyGems](https://rubygems.org/gems/action_version_preview)
 
-Feature flag gems like Flipper are designed for toggling features on/off for users, not for showing multiple versions at once. For design iterations and feedback collection, you want to open three browser tabs side by side, each showing a different version, all logged in as the same user.
+## Install
 
-ActionVersionPreview makes this trivial using Rails' native view variants.
-
-<img width="2146" height="2014" alt="image" src="https://github.com/user-attachments/assets/c39b1305-ad14-4958-be39-d714d53d1990" />
-
-## Installation
-
-Add to your Gemfile:
+Add the gem to your Rails application's Gemfile:
 
 ```ruby
-gem "action_version_preview"
+gem "action_version_preview", "~> 0.2.0"
 ```
 
-Run `bundle install`. That's it. The concern is automatically included in all controllers.
+Run `bundle install` and restart the application. No generator or engine mount is
+needed. Preview selection is added to controllers inheriting from
+`ActionController::Base`.
 
-## Usage
+## Quick start
 
-### 1. Create Variant Templates
+### 1. Create variant templates
 
-Rails looks for variant templates using this naming convention:
+For a `DashboardController#show` action, keep a default template and add variants:
 
-```
-app/views/dashboard/show.html.erb           # default
-app/views/dashboard/show.html+v2.erb        # variant :v2
-app/views/dashboard/show.html+redesign.erb  # variant :redesign
+```text
+app/views/dashboard/show.html.erb
+app/views/dashboard/show.html+v2.erb
+app/views/dashboard/show.html+redesign.erb
 ```
 
-This works for layouts, partials, mailers, and ViewComponent templates too.
+Use names such as `v2`, `redesign`, or `new_layout` for automatic switcher discovery.
 
-### 2. Visit the Variant URL
+### 2. Open the preview URLs
 
-```
-/dashboard           # renders show.html.erb
-/dashboard?vv=v2     # renders show.html+v2.erb
-/dashboard?vv=true   # renders default, but activates the switcher
-```
+In development or test:
+
+| URL | Result |
+| --- | --- |
+| `/dashboard` | Normal rendering |
+| `/dashboard?vv=v2` | Selects the `v2` variant |
+| `/dashboard?vv=redesign` | Selects the `redesign` variant |
+| `/dashboard?vv=true` | Enables the switcher without selecting a variant |
 
-### 3. Add the Variant Switcher (Optional)
+The last example keeps any variant your application already set, such as a mobile
+variant. Otherwise it renders the default template.
 
-Drop the built-in switcher widget in your layout:
+### 3. Add the optional switcher
+
+Put this near the end of your application layout's body:
 
 ```erb
 <%= variant_switcher %>
 ```
 
-The switcher automatically detects available variants by scanning the view directory for `+variant` template files. It only appears when:
-- The `vv` param is present in the URL (e.g., `?vv=true` or `?vv=v2`)
-- The current action has variant templates available
-- The user can preview variants (dev/test by default)
+The switcher appears only when preview mode is requested, access is allowed, and
+variant templates are discovered for the current action. Its links preserve the
+current path, mounted prefix, and query filters. **Default** removes the preview
+parameter and closes the switcher. Add `?vv=true` again to reopen it.
 
-Standard Rails variants (`mobile`, `tablet`, `phone`, `desktop`) are excluded from detection.
+Automatic discovery in 0.2.0 covers HTML ERB action templates in the host app's
+`app/views/<controller_path>` directory. See the [discovery limits](docs/usage.md#template-discovery)
+for layouts, partials, other handlers, and engine views.
 
-## Configuration
+## Enable previews for your users
 
-Zero config is the default. But if you need to customize:
+By default, previews are enabled only in development and test. Production,
+staging, and other environments deny preview selection until you configure access.
 
 ```ruby
 # config/initializers/action_version_preview.rb
 ActionVersionPreview.configure do |config|
-  # Change the URL parameter (default: :vv)
-  config.param_name = :v
-
-  # Control who can preview variants (default: dev/test only)
-  # In production, you might want admins only:
+  config.param_name = :vv # Optional; a string also works.
   config.access_check = ->(controller) {
-    Rails.env.development? ||
-    Rails.env.test? ||
-    controller.current_user&.admin?
+    Rails.env.development? || Rails.env.test? ||
+      (controller.respond_to?(:current_user, true) &&
+        controller.send(:current_user)&.admin?)
   }
 end
 ```
 
-## Helper Methods
+Adapt `current_user` and `admin?` to your authentication system. The example also
+works when `current_user` is private. Your user/context must be available when the
+preview callback runs; see [access control and callback order](docs/usage.md#access-control-and-callback-order).
+
+The preview parameter applies to one request. Links and redirects elsewhere in
+your app do not inherit it automatically. Ordinary application authorization still
+controls access to data and actions.
 
-These are available in controllers and views:
+## What's new in 0.2.0
 
-| Method | Description |
-|--------|-------------|
-| `current_variant` | Returns the active variant symbol (e.g., `:v2`) or `nil` |
-| `detected_variants` | Returns array of variant names found for current action |
-| `variant_preview_active?` | Returns true if variant preview mode is active |
-| `can_preview_variants?` | Returns true if current user can access variants |
-| `variant_switcher` | Renders the switcher widget |
+- Fixes `ActionVersionPreview::SwitcherHelper` load-order errors during application
+  boot and asset precompilation, including early controller/view loading.
+- Keeps switcher links on the current request path. Query keys such as `host` and
+  `protocol` remain query data; POST body fields are not copied into URLs.
+- Adds boot, reload, packaged-gem precompilation, and switcher URL regression tests.
 
-## How It Works
+To upgrade from 0.1.0, update your Gemfile constraint if necessary, run
+`bundle update action_version_preview`, and rebuild/restart the application.
+No migration or configuration change is required. Read the [0.2.0 release notes](docs/releases/0.2.0.md).
 
-Under the hood, ActionVersionPreview sets `request.variant` based on the URL parameter. Rails' template resolver then automatically looks for matching variant templates.
+## Compatibility
 
-When you visit `/dashboard?vv=v2`:
-1. The `before_action` extracts `vv=v2` from params
-2. It sets `request.variant = :v2`
-3. Rails renders `show.html+v2.erb` instead of `show.html.erb`
-4. The switcher detects all `show.html+*.erb` variants in the view directory
+- Declared requirements: Ruby **3.1+**, Rails **7.0 or later, below 9.0**.
+- Each Rails version may require a newer Ruby; the reviewed Rails 8.1 bundle
+  requires Ruby 3.2+.
+- Release validation used Ruby 4.0.5 with Rails 8.1.3.1. CI is configured for Ruby
+  3.4.7. A full matrix of the declared versions is not yet in place.
+- Automatic controller integration targets `ActionController::Base`, not API-only
+  controllers inheriting directly from `ActionController::API`.
+
+## Development
+
+```sh
+bundle install
+bin/rails test
+bin/rubocop
+RAILS_ENV=test bundle exec rake app:zeitwerk:check
+bundle exec rake build
+```
 
-## Comparison: Feature Flags vs View Variants
+The test suite includes an isolated host that installs the built gem and compiles
+assets in production mode. See the [release procedure](docs/releasing.md) for
+security scans and publication.
 
-| Feature Flags (Flipper) | View Variants (This Gem) |
-|------------------------|--------------------------|
-| Toggle features on/off for users | Access all versions simultaneously |
-| One version "live" at a time | Side-by-side comparison in multiple tabs |
-| Percentage rollouts, A/B testing | Design iteration, feedback collection |
-| Requires database/Redis | Zero dependencies |
+## Background
 
-## Requirements
+[Why I built design previews for Rails](https://code.avi.nyc/design-previews-for-ruby-on-rails)
 
-- Rails 7.0+ or 8.x
-- Ruby 3.1+
+<img width="2146" height="2014" alt="Several Rails UI variants displayed for comparison" src="https://github.com/user-attachments/assets/c39b1305-ad14-4958-be39-d714d53d1990" />
 
 ## License
 
-MIT License. See [MIT-LICENSE](MIT-LICENSE).
+[MIT License](MIT-LICENSE).

data/app/views/action_version_preview/_variant_switcher.html.erb

@@ -2,11 +2,11 @@
   <div style="position: fixed; bottom: 1rem; right: 1rem; background: #18181b; color: white; padding: 0.75rem; border-radius: 0.5rem; box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1); z-index: 9999; font-size: 0.875rem; font-family: system-ui, -apple-system, sans-serif;">
     <span style="color: #a1a1aa; margin-right: 0.5rem;">View:</span>
     <%= link_to "Default",
-        url_for(request.params.except(ActionVersionPreview.param_name.to_s, ActionVersionPreview.param_name.to_sym)),
+        variant_preview_path,
         style: "padding: 0.25rem 0.5rem; border-radius: 0.25rem; text-decoration: none; color: white; #{current_variant.nil? ? 'background: #2563eb;' : ''}" %>
     <% detected_variants.each do |variant| %>
       <%= link_to variant.upcase,
-          url_for(request.params.merge(ActionVersionPreview.param_name => variant)),
+          variant_preview_path(variant),
           style: "padding: 0.25rem 0.5rem; border-radius: 0.25rem; text-decoration: none; color: white; #{current_variant.to_s == variant ? 'background: #2563eb;' : ''}" %>
     <% end %>
   </div>

data/docs/releases/0.2.0.md

@@ -0,0 +1,46 @@
+# ActionVersionPreview 0.2.0
+
+ActionVersionPreview 0.2.0 fixes deployment-time helper loading and makes the
+built-in switcher's links safe to use with arbitrary query filters.
+
+## Fixed
+
+- Fixed `NameError: uninitialized constant ActionVersionPreview::SwitcherHelper`
+  when Rails loads controllers or views early during application initialization
+  and asset precompilation. The helper is loaded explicitly and remains available
+  across development reloads.
+- Switcher links now use the current request path and query data. Parameters such
+  as `host`, `protocol`, and `script_name` cannot redirect links to another origin
+  or path. Nested filters, pagination, mounted prefixes, and custom preview
+  parameter names are preserved.
+- POST body fields, including submitted form fields, are no longer copied into
+  switcher URLs.
+
+## Documentation and validation
+
+- Added a [complete usage guide](https://github.com/aviflombaum/action_version_preview/blob/main/docs/usage.md) covering installation, permissions,
+  configuration, discovery, navigation, integrations, and troubleshooting.
+- Added regression tests for early/lazy loading, reloading, installed-gem
+  production asset precompilation, and switcher URLs.
+- Refreshed development dependency resolution and CI actions.
+
+## Upgrade
+
+```ruby
+gem "action_version_preview", "~> 0.2.0"
+```
+
+Run `bundle update action_version_preview` and restart or rebuild your application.
+There are no migrations or required configuration changes. The Default link still
+removes the preview parameter and closes the widget.
+
+## Compatibility and scope
+
+Declared requirements remain Ruby >= 3.1 and Rails >= 7.0, < 9.0; your Rails version
+may require a newer Ruby. Local release checks ran with Ruby 4.0.5 / Rails 8.1.3.1.
+A full supported-version matrix is not yet in place.
+
+This release does not add variant persistence or layout/partial/component
+scanning. Preview parameters must be scalar strings; malformed array/hash input
+handling remains a known limitation. See the [usage guide](https://github.com/aviflombaum/action_version_preview/blob/main/docs/usage.md) for the
+current discovery and access-check behavior.

data/docs/releasing.md

@@ -0,0 +1,97 @@
+# Releasing ActionVersionPreview
+
+Use this procedure to publish a tested gem and then attach a GitHub tag/release
+to the exact source revision used to build it. RubyGems publication is performed
+manually by the maintainer.
+
+## Prepare and validate
+
+1. Audit the local and remote release branches. Merge all intended changes into
+   the release branch, including any new commits from remote `main`.
+2. Update `lib/action_version_preview/version.rb`, the local gem entry in
+   `Gemfile.lock`, the changelog, README, usage guide, and release notes.
+3. Run the checks below. Security tools are maintainer tools, not runtime gem
+   dependencies. Use current installed versions and an updated advisory database.
+
+```sh
+bundle check
+bin/rails test
+CI=true bin/rails test
+bin/rubocop
+RAILS_ENV=test bundle exec rake app:zeitwerk:check
+bundle-audit check --update
+brakeman --force-scan --no-pager .
+brakeman --no-pager --add-engines-path ../.. --gemfile ../../Gemfile test/dummy
+erb_lint --lint-all --enable-linters erb_safety,parser_errors
+npx --yes markdownlint-cli2@0.23.2 README.md CHANGELOG.md SUGGESTIONS.md docs/usage.md docs/releasing.md docs/releases/0.2.0.md
+git diff --check
+```
+
+The test suite builds and installs the gem into a temporary directory, checks
+early loading/reloading, renders the real helper, and compiles a production asset
+with `SECRET_KEY_BASE_DUMMY=1`. Brakeman needs the relative `../../Gemfile` argument
+to identify the dummy app's shared dependency resolution correctly.
+
+Check Markdown and all local/public documentation links as part of release
+preparation. Avoid treating a remote server's rate limit as a broken link without
+checking it separately.
+
+## Merge and build
+
+After validation, commit the release changes, merge the release branch into
+`main`, and push `main`. Wait for GitHub CI to pass before publication. Verify that
+each intended release-branch tip is an ancestor of `main`.
+
+From a clean `main` checkout:
+
+```sh
+git rev-parse HEAD
+bundle exec rake build
+shasum -a 256 pkg/action_version_preview-0.2.0.gem
+```
+
+Record that commit SHA and the gem's checksum. Inspect the archive for the runtime
+files, helper partial, license, README, changelog, and public documentation. It
+must not contain development credentials, generated assets, tests, or research
+notes. Check that packaged files are readable by other users.
+
+## Maintainer publishes to RubyGems
+
+Use the already-built artifact:
+
+```sh
+gem push pkg/action_version_preview-0.2.0.gem
+```
+
+Complete RubyGems authentication/MFA as prompted. See the official
+[RubyGems publishing guide](https://guides.rubygems.org/publishing/) for account
+setup. Do not rebuild or change the release commit after this artifact is pushed.
+
+## Verify publication, then tag and release on GitHub
+
+Confirm RubyGems lists version 0.2.0 and compare its SHA-256 with the local artifact.
+The version API provides the published checksum:
+
+```text
+https://rubygems.org/api/v2/rubygems/action_version_preview/versions/0.2.0.json
+```
+
+Then use the recorded release commit, rather than assuming `main` has not moved:
+
+```sh
+git tag -a v0.2.0 RELEASE_COMMIT_SHA -m "ActionVersionPreview 0.2.0"
+git push origin v0.2.0
+gh release create v0.2.0 pkg/action_version_preview-0.2.0.gem \
+  --verify-tag \
+  --repo aviflombaum/action_version_preview \
+  --title "ActionVersionPreview 0.2.0" \
+  --notes-file docs/releases/0.2.0.md
+```
+
+Replace `RELEASE_COMMIT_SHA` with the recorded SHA. Inspect the resulting GitHub
+release and verify its tag targets that commit. If a tag or release already
+exists, inspect it before proceeding; do not move a published tag.
+
+`bundle exec rake release` combines tagging, Git pushes, and RubyGems publication.
+Do not use it for this staged workflow: the manual RubyGems push must happen before
+the GitHub tag and release.

data/docs/usage.md

@@ -0,0 +1,295 @@
+# ActionVersionPreview usage guide
+
+This guide describes the public behavior of ActionVersionPreview 0.2.0. The gem
+lets you compare Rails UI designs by selecting a view variant for an individual
+request. It does not assign visitors to experiments or store a selected design in
+a session.
+
+## Installation
+
+Add the gem to an application's Gemfile:
+
+```ruby
+gem "action_version_preview", "~> 0.2.0"
+```
+
+Run `bundle install` and restart Rails. You do not need to mount routes, run
+migrations, generate configuration, or install JavaScript. Controllers inheriting
+from `ActionController::Base` receive the preview behavior automatically. The
+switcher is optional; variant URLs work without it.
+
+The gem declares Ruby >= 3.1 and Rails >= 7.0, < 9.0. Choose a Ruby version supported
+by your Rails release. API-only controllers inheriting directly from
+`ActionController::API` are outside the automatic integration.
+
+## Create your first preview
+
+Suppose your application already renders `DashboardController#show` at
+`/dashboard`. Keep the default view and add a variant:
+
+```text
+app/views/dashboard/show.html.erb
+app/views/dashboard/show.html+v2.erb
+```
+
+For example, the variant might contain:
+
+```erb
+<h1>A new dashboard design</h1>
+<%= render "summary" %>
+```
+
+Visit `/dashboard?vv=v2` in development. Open `/dashboard` in another tab to compare
+the original. Both requests use your normal controller action, authentication,
+and data; only template selection changes.
+
+Add more files such as `show.html+redesign.erb` as needed. The name after `+` is
+case-sensitive. Lowercase letters, digits, and underscores work with the built-in
+discovery, for example `v2`, `redesign`, and `new_layout`.
+
+Rails performs the actual [variant template selection](https://guides.rubyonrails.org/layouts_and_rendering.html#the-variants-option).
+If an action has no matching variant template but does have a normal template,
+Rails can fall back to that normal template. Selecting a name does not prove a
+matching template was rendered.
+
+## URL behavior
+
+These examples use the default parameter name, `vv`, and assume access is allowed:
+
+| Request | Behavior |
+| --- | --- |
+| `/dashboard` | Leaves normal application variant selection unchanged |
+| `/dashboard?vv=v2` | Sets the request variant to `v2` |
+| `/dashboard?vv=true` | Enables preview mode without changing the request variant |
+| `/dashboard?vv=` | Does not enable preview mode or change the request variant |
+| `/dashboard?vv=unknown` | Requests `unknown`; Rails may render the default template |
+
+`true` is a reserved trigger string. It cannot be used to select a template variant
+named `true` through this parameter. `false` is an ordinary variant name, not a
+switch to disable previews. Remove the parameter to leave preview mode.
+
+Use scalar strings. In 0.2.0, array/hash forms such as `vv[]=v2` or `vv[name]=v2`
+are unsupported and may raise an exception when access is allowed. Malformed-input
+handling is a separate planned improvement.
+
+When access is denied, the gem leaves the request variant unchanged and hides the
+switcher. It does not render an access-denied page or change the response status.
+
+## Add the switcher
+
+Place this inside an HTML layout, usually near the closing `</body>` tag:
+
+```erb
+<%= variant_switcher %>
+```
+
+The widget appears when all three conditions hold:
+
+1. The configured preview parameter has a nonblank value.
+2. The access check permits the request.
+3. The current action has discoverable variant templates.
+
+It works when `config.action_controller.include_all_helpers = false`. It uses
+ordinary links and inline styles, with no JavaScript dependency.
+
+### Switching and returning to Default
+
+A variant link selects that name on the current path. Other query data, including
+nested filters and pagination, is preserved. For example:
+
+```text
+/reports?page=2&vv=v2
+/reports?page=2&vv=redesign
+```
+
+Mounted application prefixes are preserved. Query keys that happen to be named
+`host`, `protocol`, or `script_name` remain query data and cannot override the link
+destination. Request-body fields are not copied into the links.
+
+**Default** removes the preview parameter. The resulting page follows your normal
+application rendering and the switcher disappears. Use `?vv=true` to show it again.
+There is no separate persistent preview session or exit button in 0.2.0.
+
+The highlighted link reflects `current_variant`, the request's first variant.
+If the requested variant falls back to the normal template, the highlight is not
+a report of the template Rails ultimately rendered.
+
+### Styling
+
+The supplied widget is fixed at the bottom-right of the viewport and uses inline
+styles. A Content Security Policy that disallows style attributes can prevent
+those styles from applying. There are no theme or position configuration options
+in 0.2.0. You can override the engine partial in your host application at:
+
+```text
+app/views/action_version_preview/_variant_switcher.html.erb
+```
+
+Keep application-specific overrides under review when upgrading. Custom styles
+and markup are your application's responsibility.
+
+## Configuration
+
+Configure the gem once at application startup:
+
+```ruby
+# config/initializers/action_version_preview.rb
+ActionVersionPreview.configure do |config|
+  config.param_name = :design
+end
+```
+
+You can then use `/dashboard?design=v2` or `/dashboard?design=true`. The switcher
+uses the configured name for every link. Strings and symbols are both accepted.
+Choose a name that does not conflict with your application's existing parameters.
+Configuration is application-wide, not per-user or per-request.
+
+### Access control and callback order
+
+The default check allows only `Rails.env.development?` or `Rails.env.test?`.
+Production, staging, and custom environments are disabled by default. To allow
+administrators as well:
+
+```ruby
+ActionVersionPreview.configure do |config|
+  config.access_check = ->(controller) {
+    Rails.env.development? || Rails.env.test? ||
+      (controller.respond_to?(:current_user, true) &&
+        controller.send(:current_user)&.admin?)
+  }
+end
+```
+
+The callable receives the current controller. A truthy return value allows
+previewing; `false` or `nil` denies it. The example supports a private
+`current_user` method, but you must adapt the method and permission check to your
+application. Avoid performing side effects: the check can run during variant
+selection and again while rendering helpers.
+
+The gem registers its callback on `ActionController::Base`. A user lookup that
+happens only in a later host `before_action` may not be ready when selection runs.
+Prefer a current-user lookup that can resolve its own state when called. If your
+authentication requires a callback first, order that callback before preview
+selection using Rails' callback ordering facilities, and test the request in your
+host application. The gem has no callback-order configuration setting in 0.2.0.
+
+Keep your normal authorization checks for data and actions. The preview access
+check governs selection through this gem; it is not a replacement for host
+application authorization. Excluding a name from the widget is not an access rule.
+
+## Template discovery
+
+The built-in switcher scans:
+
+```text
+app/views/<controller_path>/<action_name>.html+<variant>.erb
+```
+
+For example, `Admin::ReportsController#index` is scanned under
+`app/views/admin/reports/index.html+*.erb`. Names are returned in sorted order and
+cached for that request.
+
+The following names are omitted from the widget: `mobile`, `tablet`, `phone`, and
+`desktop`. These are the gem's device-name convention, not names reserved by Rails.
+An authorized `?vv=mobile` request can still select a mobile template.
+
+In 0.2.0, automatic discovery does not enumerate:
+
+- Layout-only or partial-only variants.
+- Templates in engine-owned or custom/prepended view directories.
+- Locale-qualified filenames such as `show.en.html+v2.erb`.
+- Handlers other than ERB, such as Haml or Slim.
+- Variant names containing hyphens or other characters outside letters, digits,
+  and underscores.
+- A different template explicitly rendered by the action.
+
+Rails may still render these variants when selected directly by URL. Discovery
+controls the widget's choices; it is not an allowlist for request variants.
+
+## Layouts, partials, and components
+
+Native Rails rendering can apply the selected variant to layouts and partials.
+For example, a request selecting `v2` can use these files where your normal render
+calls refer to them:
+
+```text
+app/views/layouts/application.html+v2.erb
+app/views/dashboard/_summary.html+v2.erb
+```
+
+The switcher does not discover a `v2` choice from those files alone. Use the URL
+directly, or also provide an action variant when you want automatic discovery.
+
+ViewComponent and other rendering libraries have their own variant behavior.
+ActionVersionPreview sets `request.variant`; it does not scan component directories
+or provide a dedicated component integration. Test component rendering in your
+host application.
+
+Mailers and background jobs do not automatically inherit the preview URL or its
+variant. Pass and select the desired variant in those systems separately.
+
+## Navigation and existing application variants
+
+Selection lasts for the current request. Normal links, redirects, form submissions,
+and Turbo requests only keep preview mode if their destination includes the
+configured parameter. The gem does not modify `default_url_options`, cookies,
+sessions, localStorage, or Turbo behavior.
+
+For a link where you explicitly want to carry the current variant forward, add it
+with your application's route helper:
+
+```erb
+<%= link_to "Reports", reports_path(design: current_variant) %>
+```
+
+This example assumes `config.param_name = :design`. If you want to open the
+switcher without selecting a variant, pass `design: "true"` instead. Consider
+whether the destination action actually has the same variants.
+
+A nonblank preview name replaces the request's variant selection. Missing/blank
+parameters, denied access, and the `true` trigger leave an existing application
+variant unchanged. Other controller callbacks can still change it later.
+
+## Helper reference
+
+| Method | Available in | Meaning |
+| --- | --- | --- |
+| `variant_switcher` | Views | Renders the built-in widget, or no visible widget when its conditions are not met |
+| `current_variant` | Controller and views | First request variant as a symbol, or `nil` |
+| `detected_variants` | Controller and views | Sorted array of discovered names as strings |
+| `variant_preview_active?` | Controller and views | Truthy when the parameter is nonblank and access is allowed |
+| `can_preview_variants?` | Controller and views | Result of the configured access check |
+
+The controller methods are private and exposed as view helpers. Use the widget
+or normal Rails route helpers for your own links.
+
+## Troubleshooting
+
+| Symptom | What to check |
+| --- | --- |
+| No switcher | Include the helper, provide `vv=true`, allow access, and check that action ERB variants are discoverable |
+| Works locally but not in staging | Configure `access_check`; staging is denied by default |
+| Requested variant renders the original view | Check spelling, case, filename, access, callback order, and Rails fallback behavior |
+| Default makes the switcher disappear | Expected in 0.2.0; Default removes the parameter |
+| Variant disappears after navigation | Include the preview parameter in that destination if you want to retain it |
+| Device variant changes unexpectedly | A concrete preview name replaces the request variant; check other callbacks too |
+| Widget is unstyled | Check the host's Content Security Policy and any partial override |
+| 0.1.0 raises `SwitcherHelper` during asset precompilation | Upgrade to 0.2.0, update the lockfile, and rebuild the deployment image |
+
+## Upgrading from 0.1.0
+
+Update your version constraint if it pins 0.1.0, then run:
+
+```sh
+bundle update action_version_preview
+```
+
+Restart Rails or rebuild your deployment image so it installs the new lockfile
+resolution. No migration, route mount, or new initializer is required.
+
+0.2.0 fixes helper loading during boot and asset precompilation, and changes the
+built-in switcher to derive URLs from the current path and query data. POST body
+fields no longer appear in its links. The configuration names, default access
+policy, discovery scope, and Default behavior remain the same.
+
+See the [changelog](../CHANGELOG.md) and [release notes](releases/0.2.0.md).

data/lib/action_version_preview/engine.rb

@@ -1,4 +1,5 @@
 require "action_version_preview/controller_methods"
+require "action_version_preview/switcher_helper"
 
 module ActionVersionPreview
   class Engine < ::Rails::Engine
@@ -7,7 +8,12 @@ module ActionVersionPreview
     initializer "action_version_preview.controller_methods" do
       ActiveSupport.on_load(:action_controller_base) do
         include ActionVersionPreview::ControllerMethods
-        helper ActionVersionPreview::Engine.helpers
+      end
+    end
+
+    initializer "action_version_preview.helpers", after: :load_config_initializers do
+      ActiveSupport.on_load(:action_view) do
+        include ActionVersionPreview::SwitcherHelper
       end
     end
   end

data/lib/action_version_preview/switcher_helper.rb

@@ -0,0 +1,18 @@
+module ActionVersionPreview
+  # Required by the engine: load hooks may run before Rails sets up autoloading.
+  module SwitcherHelper
+    def variant_switcher
+      render partial: "action_version_preview/variant_switcher"
+    end
+
+    private
+
+    def variant_preview_path(variant = nil)
+      param_name = ActionVersionPreview.param_name.to_s
+      query = request.query_parameters.except(param_name)
+      query[param_name] = variant if variant
+
+      query.empty? ? request.path : "#{request.path}?#{query.to_query}"
+    end
+  end
+end

data/lib/action_version_preview/version.rb

@@ -1,3 +1,3 @@
 module ActionVersionPreview
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_version_preview
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Avi Flombaum
@@ -38,24 +38,29 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - MIT-LICENSE
 - README.md
 - Rakefile
-- app/helpers/action_version_preview/switcher_helper.rb
 - app/views/action_version_preview/_variant_switcher.html.erb
 - config/routes.rb
+- docs/releases/0.2.0.md
+- docs/releasing.md
+- docs/usage.md
 - lib/action_version_preview.rb
 - lib/action_version_preview/controller_methods.rb
 - lib/action_version_preview/engine.rb
+- lib/action_version_preview/switcher_helper.rb
 - lib/action_version_preview/version.rb
 - lib/tasks/action_version_preview_tasks.rake
 homepage: https://github.com/aviflombaum/action_version_preview
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/aviflombaum/action_version_preview
   source_code_uri: https://github.com/aviflombaum/action_version_preview
   changelog_uri: https://github.com/aviflombaum/action_version_preview/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/aviflombaum/action_version_preview/blob/main/docs/usage.md
+  bug_tracker_uri: https://github.com/aviflombaum/action_version_preview/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -70,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.14
 specification_version: 4
 summary: Preview multiple view variants side-by-side using Rails' built-in view variants.
 test_files: []

data/app/helpers/action_version_preview/switcher_helper.rb

@@ -1,7 +0,0 @@
-module ActionVersionPreview
-  module SwitcherHelper
-    def variant_switcher
-      render partial: "action_version_preview/variant_switcher"
-    end
-  end
-end