active_storage-async_variants 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4395d49e7c04b9206145e2c8dbe0bf3f4466ed736054ec5e9fc3b8fc7dea3a1c
-  data.tar.gz: 1cf4f1090be29b6ff6a7a50be05ecaa2bcc79f50de9a203ec26d99c9d8e58fc8
+  metadata.gz: 003cbfe68ded6c238669546679e76b7d0c8e856842450181ceb8497a9e452361
+  data.tar.gz: 0b41dad0aa8a59e81e9b2e384d6d04e55ee479c0c35822d71e3a06a46b0c64cd
 SHA512:
-  metadata.gz: 1d696905633e0039f8489377d41ea120fd89d5fccfcadbd8872981ea916d9032395f5f66091eba170de40f03547b7b93c90457e6796f15868ae3e7d3ecf937c4
-  data.tar.gz: 21c13be811dc6c6b9b19123f6ef8c9c23c1e2cbc0360ee9f79a88b4bf83d023f514d61964e75b749c2b073ad19e7db52f878a2b55de8c90b4018ff831a4d3f2d
+  metadata.gz: e5eb0728baf9f4d9cfc591625f6035d362d9df192c2c64fb7cef4e397fcef9817a460dbfba24210f01d777360a1d2e73e4dabf7d00306f8c9685ff1df4641b0e
+  data.tar.gz: 4c87c749a9dad93f251fcddf5830996f53d7c054becabdd529ea89000eb75e5f2360b6332aea764fc615931b0c350a15bfe8610d4b5efa1561a22ffd3d966ee6

data/.github/workflows/ci.yml

@@ -14,9 +14,6 @@ jobs:
       matrix:
         ruby: ["3.3", "3.4", "4.0"]
         rails: ["rails-7.2", "rails-8.0", "rails-8.1"]
-        exclude:
-          - ruby: "4.0"
-            rails: "rails-7.2"
     steps:
       - uses: actions/checkout@v4
       - uses: ruby/setup-ruby@v1

data/CHANGELOG.md

@@ -1,4 +1,24 @@
-## [Unreleased]
+## [0.4.0]
+
+- **Breaking:** Replaced the polling-`<img>` architecture with a `<turbo-frame>` for unprocessed variants. `image_tag`/`video_tag` with `async: true` now emits a normal `<img>`/`<video>` when the variant is already processed, and a `<turbo-frame src="…">` otherwise. The frame hits a new gem-shipped endpoint (`GET /active_storage/async_variants/states/:signed_blob_id/:variation_key`) that renders one of `_processing`/`_failed`/`_processed` partials. Non-terminal renders include an inline `<script>` that schedules the frame's next reload, so the state polls itself until it terminates.
+- New `app/views/active_storage/async_variants/states/` partial set — apps can override any partial by creating a same-named file in their own `app/views/active_storage/async_variants/states/`. The processing state defaults to a bare `<img>`/`<video>` pointing at the variant's URL, which the gem redirects to the app's configured `processing:` SVG.
+- All CSS and JavaScript ship inline in the per-response state partials — no asset-pipeline footprint. Apps don't need to include any stylesheet or script.
+- **Breaking:** `Variant#processed` and `Preview#processed` are now no-ops on bucket-backed services (they previously also lazy-enqueued `ProcessJob` for any record that wasn't already processed). Enqueue now happens only at attachment time (via `AttachmentExtension#transform_variants_later`). Pre-existing blobs that missed the auto-enqueue won't self-heal on first view; backfill via a rake task.
+- New public `#enqueue!` method on both `Variant` and `Preview` with the same signature — no `respond_to?` dance. Creates a pending `VariantRecord` (RecordNotUnique guards dedupe) and dispatches `ProcessJob`. Replaces the previously private `enqueue_processing` / `enqueue_async_preview`.
+- The named-variant lookup now walks one level back through `preview_image` attachments, so a request for a Variant of a video's extracted preview frame can recover the named-variant declaration from the parent record's source-video field. Fixes nil-URL 500s in dev where the cold Registry can't resolve a redirect-controller request.
+- Added `turbo-rails >= 2.0` as a runtime dependency.
+- Removed `RepresentationsRedirectControllerExtension`, the `[data-async-variant-*]` polling JS, the bundled `app/assets/stylesheets/active_storage_async_variants.css`, the engine's asset precompile initializer, and the `apply_async_data!` helper machinery. Consumers depending on those data attributes must migrate to targeting the new `.async-variant-state` classes or override the partials.
+
+## [0.3.1]
+
+- Bound the stored variant `error` to 16k chars at both write sites (the failed-status callback and `ProcessJob`'s rescue). An external transformer reporting a >64KB error payload was overflowing the `TEXT` column and 500ing the callback, leaving the variant stuck instead of marked failed.
+
+## [0.3.0]
+
+- Touch attached records when a variant transitions to processed, so consumer caches keyed on `cache_key_with_version` invalidate without needing manual cascading. Multi-hop cascades remain the consumer's responsibility via standard Rails `touch:` or `after_touch`.
+- Dedupe concurrent `.processed` calls so they enqueue at most one `ProcessJob` per blob+variation. Previously, every call before the first job flipped state to "processing" enqueued another job; each job created a fresh variant blob, leaving the others as orphans. The record is now created as `pending` at enqueue time, using the unique index on `active_storage_variant_records (blob_id, variation_digest)` (already shipped by the standard Active Storage migration) as the dedupe key. Once a record reaches `failed` (after `ProcessJob` exhausts its 3-attempt `retry_on` cycle), further `.processed` calls no longer re-enqueue — the variant is permanently failed.
+- Renamed the `fallback:` variant option to `processing:` to better describe what it represents — the placeholder served while the variant is being processed.
+- New `failed:` variant option that specifies a distinct placeholder to render when the variant has permanently failed, separate from the `processing:` placeholder. Accepts `:original`, `:blank`, a String URL, or a Proc that receives the blob. Defaults to `processing:` when unspecified. Also extends `processing:` to accept a String URL directly (previously you had to wrap a static URL in a Proc).
 
 ## [0.1.0] - 2026-03-03
 

data/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What This Is
 
-A Rails engine gem that extends Active Storage with async-safe variant processing. Solves the problem where slow transformations (e.g., video transcoding) block requests or fail silently. The `fallback:` option on a variant definition opts it into async processing.
+A Rails engine gem that extends Active Storage with async-safe variant processing. Solves the problem where slow transformations (e.g., video transcoding) block requests or fail silently. The `processing:` option on a variant definition opts it into async processing.
 
 ## Commands
 
@@ -19,9 +19,9 @@ bundle exec rspec spec/active_storage/async_variants_spec.rb -e "description" #
 
 The gem works by prepending extension modules onto Active Storage classes:
 
-- **`VariationExtension`** → `ActiveStorage::Variation` — extracts async options (`fallback:`, `transformer:`, `max_retries:`) from variant config before passing the rest to standard Active Storage
-- **`AttachmentExtension`** → `ActiveStorage::Attachment` — hooks into `transform_variants_later` to enqueue `ProcessJob` for variants with `fallback:`
-- **`VariantWithRecordExtension`** → `ActiveStorage::VariantWithRecord` — overrides URL generation to serve fallback while processing; adds state query methods (`ready?`, `processing?`, `pending?`, `failed?`)
+- **`VariationExtension`** → `ActiveStorage::Variation` — extracts async options (`processing:`, `failed:`, `transformer:`) from variant config before passing the rest to standard Active Storage
+- **`AttachmentExtension`** → `ActiveStorage::Attachment` — hooks into `transform_variants_later` to enqueue `ProcessJob` for variants with `processing:`
+- **`VariantWithRecordExtension`** → `ActiveStorage::VariantWithRecord` — overrides URL generation to serve the `processing:` (or `failed:`) placeholder while not ready; adds state query methods (`processed?`, `processing?`, `pending?`, `failed?`)
 - **`ProcessJob`** — background job that determines transformer type (inline vs external) and processes accordingly
 
 ### Transformer Types

data/README.md

@@ -19,7 +19,7 @@ bin/rails db:migrate
 
 ## Usage
 
-Add `fallback:` to any named variant to opt into the async pipeline:
+Add `processing:` to any named variant to opt into the async pipeline. The value is what to serve while the variant is being processed:
 
 ```ruby
 class User < ApplicationRecord
@@ -28,12 +28,12 @@ class User < ApplicationRecord
       transformer: VideoTranscoder,
       codec: "vp9",
       resolution: "720p",
-      fallback: :original
+      processing: :original
   end
 end
 ```
 
-The presence of `fallback:` is what opts a variant into async processing. Without it, variants behave exactly as they do in standard Active Storage. The `transformer:` option is independent -- you can use a custom transformer synchronously, or use the default transformer asynchronously:
+The presence of `processing:` is what opts a variant into async processing. Without it, variants behave exactly as they do in standard Active Storage. The `transformer:` option is independent -- you can use a custom transformer synchronously, or use the default transformer asynchronously:
 
 ```ruby
 has_one_attached :video do |attachable|
@@ -41,14 +41,14 @@ has_one_attached :video do |attachable|
   attachable.variant :web,
     transformer: VideoTranscoder,
     codec: "vp9",
-    fallback: :original
+    processing: :original
 
   # Async with default transformer (large image resize that's too slow for inline)
   attachable.variant :thumbnail,
     resize_to_limit: [200, 200],
-    fallback: :original
+    processing: :original
 
-  # Sync with custom transformer (fast custom processing, no fallback needed)
+  # Sync with custom transformer (fast custom processing, no opt-in needed)
   attachable.variant :watermarked,
     transformer: WatermarkStamper
 end
@@ -62,6 +62,45 @@ In views, use the same Active Storage helpers:
 
 If the variant is still processing, this serves the original video. Once processing completes, it serves the transcoded variant.
 
+## `image_tag` / `video_tag` with `async:` and `direct:`
+
+For a polish layer that swaps in placeholder content while a variant is being processed, polls for completion in the background, and optionally serves the finished variant straight from your CDN, the gem adds two options to `image_tag` and `video_tag`:
+
+```erb
+<%# Variant URL with the async client wired up: spinner while pending,
+    polls for completion, swaps to the real image when ready. %>
+<%= image_tag user.avatar.variant(:web), async: true %>
+
+<%# When the variant is ready, render its direct CDN/S3 URL instead of
+    routing through Rails. While pending/failed, falls back to the
+    Rails representation URL (which serves the placeholder). %>
+<%= image_tag user.avatar.variant(:web), direct: true %>
+
+<%# Both together: direct URL once processed, placeholder while pending,
+    polling for completion. %>
+<%= image_tag user.avatar.variant(:web), async: true, direct: true %>
+
+<%# Same for videos. %>
+<%= video_tag user.video.variant(:web), async: true, controls: true %>
+```
+
+The first argument must be a `VariantWithRecord` or `Preview` when either option is set; otherwise `image_tag` / `video_tag` behave exactly as in stock Rails.
+
+### Configure the direct URL host
+
+By default `direct:` uses the storage service's URL (presigned for private buckets, unsigned for public). To serve from a CDN, set the host in an initializer:
+
+```ruby
+# config/initializers/active_storage_async_variants.rb
+ActiveStorage::AsyncVariants.cdn_host = "https://d1234abcd.cloudfront.net"
+```
+
+The resulting URL is `"#{cdn_host}/#{variant.key}"`.
+
+### JavaScript
+
+No manual wiring is required. The async state partials are self-contained `<turbo-frame>`s. The only requirement is that the host app loads **Turbo** -- the gem depends on `turbo-rails`, which a default Rails app already includes.
+
 ## Writing a Transformer
 
 Transformers come in two flavors: **inline** (the job blocks until processing completes) and **external** (the job kicks off remote work and a webhook signals completion).
@@ -158,41 +197,42 @@ The gem determines the mode by which method the transformer implements: `initiat
 ```ruby
 variant = user.video.variant(:web)
 
-variant.ready?       # => true if processed successfully
+variant.processed?   # => true if processed successfully
 variant.processing?  # => true if job is running or external service is working
 variant.pending?     # => true if job is enqueued
 variant.failed?      # => true if permanently failed
 variant.error        # => error message string, or nil
 ```
 
-## Fallback Options
+## Placeholder Options
 
-The `fallback:` option controls what gets served while a variant is processing (or after it fails):
+The `processing:` option controls what gets served while a variant is being processed. The `failed:` option (optional) controls what gets served once the variant has permanently failed; if omitted, it defaults to the `processing:` value.
 
 ```ruby
-# Serve the original unprocessed file
-attachable.variant :web, fallback: :original
+# Serve the original unprocessed file while processing
+attachable.variant :web, processing: :original
 
 # Return nil -- let the view handle it
-attachable.variant :web, fallback: :blank
+attachable.variant :web, processing: :blank
+
+# Static URL while processing
+attachable.variant :web, processing: "/placeholders/processing.svg"
+
+# Dynamic placeholder via Proc
+attachable.variant :web,
+  processing: -> (blob) { "/placeholders/processing.svg" }
 
-# Custom fallback
+# Distinct placeholder when permanently failed
 attachable.variant :web,
-  fallback: -> (blob) { "/placeholders/processing.svg" }
+  processing: :original,
+  failed: "/icons/broken.svg"
 ```
 
-## Failure Handling
+Both options accept the same set of values: `:original`, `:blank`, a String URL, or a Proc that receives the blob.
 
-By default, a variant is retried 3 times before being marked as permanently failed. Configure per-variant:
+## Failure Handling
 
-```ruby
-attachable.variant :web,
-  transformer: VideoTranscoder,
-  codec: "vp9",
-  resolution: "720p",
-  fallback: :original,
-  max_retries: 5
-```
+A variant is retried up to 3 times before being marked as permanently failed. Once permanently failed, `.processed` no longer re-enqueues the job — the variant stays failed until you delete the `ActiveStorage::VariantRecord` row manually (or re-attach a fresh blob).
 
 Inspect failures:
 
@@ -213,15 +253,15 @@ variant.error   # => "ffmpeg exited with status 1: ..."
 5. The external service processes the file, uploads the result to the destination URL
 6. The external service POSTs to the callback URL with success/failure status
 7. The gem's callback endpoint transitions the `VariantRecord` to `processed` or `failed`
-8. When a view requests the variant URL, the gem checks state and serves the variant or the fallback
+8. When a view requests the variant URL, the gem checks state and serves the variant or the `processing:`/`failed:` placeholder
 
 ### Inline transformer flow
 
 1-3. Same as above
 4. The job calls the transformer's `process` method, blocking until complete
 5. On success, the output is uploaded, the `VariantRecord` transitions to `processed`
-6. On failure, the error is recorded and the job is re-enqueued (up to `max_retries`)
-7. When a view requests the variant URL, the gem checks state and serves the variant or the fallback
+6. On failure, the error is recorded and the job is re-enqueued (up to 3 attempts)
+7. When a view requests the variant URL, the gem checks state and serves the variant or the `processing:`/`failed:` placeholder
 
 ## License
 

data/Rakefile

@@ -5,4 +5,12 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-task default: :spec
+desc "Run browser-level acceptance tests (cucumber + cuprite against spec/dummy)"
+task :cucumber do
+  sh "bundle exec cucumber"
+end
+
+desc "Run rspec and cucumber"
+task all: [:spec, :cucumber]
+
+task default: :all

data/app/controllers/active_storage/async_variants/callbacks_controller.rb

@@ -10,8 +10,10 @@ module ActiveStorage
         case params[:status]
         when "success"
           variant_record.update!(state: "processed")
+          apply_reported_metadata(variant_record, params)
         when "failed"
-          variant_record.update!(state: "failed", error: params[:error])
+          # error column is TEXT (64KB); utf8mb4 is up to 4 bytes/char, so cap at 16k chars.
+          variant_record.update!(state: "failed", error: params[:error].to_s.truncate(16_000))
         else
           head :unprocessable_entity and return
         end
@@ -20,6 +22,37 @@ module ActiveStorage
       rescue ActiveSupport::MessageVerifier::InvalidSignature
         head :unauthorized
       end
+
+      private
+
+      # External transformers (Crucible) write the file directly to the bucket
+      # and report its byte_size/checksum on the success callback. Reconcile the
+      # placeholder blobs created with byte_size: 0, checksum: "0" -- the variant
+      # itself, and (for video previews) the extracted frame on the source blob.
+      def apply_reported_metadata(variant_record, params)
+        reconcile(variant_record.image.blob, params[:byte_size], params[:checksum])
+        reconcile(variant_record.blob, params[:preview_image_byte_size], params[:preview_image_checksum])
+      end
+
+      # The placeholder sentinels (byte_size 0, checksum "0") gate each field, so
+      # this is idempotent and never overwrites a real source blob's metadata.
+      def reconcile(blob, byte_size, checksum)
+        return unless blob
+
+        attrs = {}
+        if (bytes = positive_int(byte_size)) && blob.byte_size.zero?
+          attrs[:byte_size] = bytes
+        end
+        if checksum.present? && checksum != "0" && blob.checksum == "0"
+          attrs[:checksum] = checksum
+        end
+        blob.update!(attrs) if attrs.any?
+      end
+
+      def positive_int(value)
+        int = value.to_i
+        int.positive? ? int : nil
+      end
     end
   end
 end

data/app/controllers/active_storage/async_variants/states_controller.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    class StatesController < ActiveStorage::AsyncVariants.parent_controller.constantize
+      # signed_blob_id + variation_key in URL act as CSRF: both require app's secret.
+      skip_forgery_protection
+
+      helper "turbo/frames"
+      helper ActiveStorage::AsyncVariants::Helper
+
+      layout false
+
+      before_action :set_variant
+
+      def show
+      end
+
+      helper_method :async_variant_kind, :async_variant_direct?, :async_variant_html_options
+
+      private
+
+      def set_variant
+        blob = ActiveStorage::Blob.find_signed!(params[:signed_blob_id])
+        variation = ActiveStorage::Variation.decode(params[:variation_key])
+        @variant = blob.variant(variation)
+      rescue ActiveSupport::MessageVerifier::InvalidSignature
+        head :not_found
+      end
+
+      def async_variant_kind
+        params[:kind].to_s == "video" ? :video : :image
+      end
+
+      def async_variant_direct?
+        ActiveModel::Type::Boolean.new.cast(params[:direct])
+      end
+
+      def async_variant_html_options
+        params[:opts]
+          &.permit(*ActiveStorage::AsyncVariants::PASS_THROUGH_HTML_OPTIONS)
+          .to_h
+      end
+    end
+  end
+end

data/app/views/active_storage/async_variants/states/_failed.html.erb

@@ -0,0 +1,4 @@
+<div class="async-variant-state async-variant-failed">
+  <% method = kind == :video ? :video_tag : :image_tag %>
+  <%= send method, async_variant_representation_path(variant), **html_options.symbolize_keys %>
+</div>

data/app/views/active_storage/async_variants/states/_pending.html.erb

@@ -0,0 +1 @@
+<%= render "active_storage/async_variants/states/processing", local_assigns %>

data/app/views/active_storage/async_variants/states/_processed.html.erb

@@ -0,0 +1,5 @@
+<%
+  method = kind == :video ? :video_tag : :image_tag
+  src = direct ? async_variant_direct_url(variant) : async_variant_representation_path(variant)
+%>
+<%= send method, src, **html_options.symbolize_keys %>

data/app/views/active_storage/async_variants/states/_processing.html.erb

@@ -0,0 +1,10 @@
+<div class="async-variant-state async-variant-processing">
+  <% method = kind == :video ? :video_tag : :image_tag %>
+  <%= send method, async_variant_representation_path(variant), **html_options.symbolize_keys %>
+</div>
+<%# Self-perpetuating poll: Turbo runs <script>s in frame swaps, so each
+    pending/processing response schedules its own next reload. Terminal
+    partials (_failed, _processed) emit no script -> chain stops. %>
+<script>
+  setTimeout(() => document.getElementById("<%= async_variant_frame_id(variant) %>")?.reload(), 3000)
+</script>

data/app/views/active_storage/async_variants/states/show.html.erb

@@ -0,0 +1,8 @@
+<%= turbo_frame_tag async_variant_frame_id(@variant) do %>
+  <%= render "active_storage/async_variants/states/#{@variant.async_state}", {
+    variant: @variant,
+    html_options: async_variant_html_options,
+    kind: async_variant_kind,
+    direct: async_variant_direct?,
+  } %>
+<% end %>

data/config/routes.rb

@@ -4,4 +4,8 @@ Rails.application.routes.draw do
   post "/active_storage/async_variants/callbacks/:token",
     to: "active_storage/async_variants/callbacks#create",
     as: :active_storage_async_variant_callback
+
+  get  "/active_storage/async_variants/states/:signed_blob_id/:variation_key",
+    to: "active_storage/async_variants/states#show",
+    as: :async_variant_state
 end

data/features/state_rendering.feature

@@ -0,0 +1,21 @@
+Feature: image_tag with async: true emits the right markup per variant state
+
+  Scenario: A processed variant emits a plain <img> -- no turbo-frame, no chrome
+    Given a user with an attached avatar
+    And the avatar's :thumb_proc variant is in processed state
+    When I visit the avatar page for the :thumb_proc variant
+    Then the page should NOT contain a turbo-frame
+
+  Scenario: An unprocessed variant emits a turbo-frame in processing state
+    Given a user with an attached avatar
+    And the avatar's :thumb_proc variant is in processing state
+    When I visit the avatar page for the :thumb_proc variant
+    Then the page should contain a turbo-frame
+    And the frame should render the processing state
+
+  Scenario: A failed variant renders the failed partial inside the frame
+    Given a user with an attached avatar
+    And the avatar's :thumb_proc variant is in failed state with error "boom"
+    When I visit the avatar page for the :thumb_proc variant
+    Then the page should contain a turbo-frame
+    And the frame should render the failed state

data/features/step_definitions/dummy_steps.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+Given /^a user with an attached avatar$/ do
+  @user = User.create!
+  attach_avatar_to(@user)
+end
+
+Given /^the avatar's :(\w+) variant is in (pending|processing|processed|failed) state(?: with error "([^"]+)")?$/ do |variant_name, state, error|
+  variant = @user.avatar.variant(variant_name.to_sym)
+  if state == "processed"
+    simulate_processed_variant(variant)
+  else
+    create_variant_record(variant, state: state, error: error)
+  end
+end
+
+Given /^the retry affordance is visible to everyone$/ do
+  ActiveStorage::AsyncVariants.retry_visible_if { true }
+end
+
+Given /^the retry affordance is hidden$/ do
+  ActiveStorage::AsyncVariants.retry_visible_if { false }
+end
+
+Given /^the retry affordance requires a signed-in user$/ do
+  ActiveStorage::AsyncVariants.retry_visible_if { current_user.present? }
+end
+
+When /^I sign in as the (admin|user)$/ do |_kind|
+  visit "/session/#{@user.id}"
+end
+
+When /^I visit the avatar page for the :(\w+) variant$/ do |variant_name|
+  visit "/avatars/#{@user.id}/#{variant_name}"
+end
+
+Then /^the page should contain a turbo-frame$/ do
+  expect(page).to have_css("turbo-frame")
+end
+
+Then /^the page should NOT contain a turbo-frame$/ do
+  expect(page).to have_no_css("turbo-frame")
+  expect(page).to have_css("img")
+end
+
+Then /^the frame should render the (failed|processing|processed) state$/ do |state|
+  expect(page).to have_css("turbo-frame .async-variant-#{state}")
+end
+
+Then /^the retry affordance should be visible$/ do
+  expect(page).to have_css("async-variant-retry", visible: :all)
+end
+
+Then /^the retry affordance should NOT be visible$/ do
+  expect(page).to have_no_css("async-variant-retry", visible: :all)
+end
+
+Then /^the page should not have navigated away$/ do
+  expect(page).to have_css("h1#page-marker")
+end
+
+Then /^the failure dialog should be open$/ do
+  expect(page).to have_css("async-variant-retry", visible: :all)
+  open = page.evaluate_script(<<~JS)
+    (() => {
+      const host = document.querySelector("async-variant-retry")
+      if (!host || !host.shadowRoot) return false
+      const dialog = host.shadowRoot.querySelector("dialog")
+      return dialog ? dialog.open : false
+    })()
+  JS
+  expect(open).to eq(true)
+end
+
+Then /^the failure dialog should contain "([^"]+)"$/ do |text|
+  contains = page.evaluate_script(<<~JS)
+    (() => {
+      const host = document.querySelector("async-variant-retry")
+      if (!host || !host.shadowRoot) return false
+      return host.shadowRoot.textContent.includes(#{text.inspect})
+    })()
+  JS
+  expect(contains).to eq(true)
+end
+
+# Wait for Turbo to swap the frame and our shim to attach the shadow root.
+def wait_for_shadow!
+  Timeout.timeout(5) do
+    loop do
+      attached = page.evaluate_script("!!document.querySelector('async-variant-retry')?.shadowRoot")
+      break if attached
+      sleep 0.05
+    end
+  end
+end
+
+When /^I click the retry opener$/ do
+  wait_for_shadow!
+  page.evaluate_script(<<~JS)
+    document.querySelector("async-variant-retry").shadowRoot.querySelector(".opener").click()
+  JS
+end
+
+When /^I click "Retry processing"$/ do
+  wait_for_shadow!
+  page.evaluate_script(<<~JS)
+    document.querySelector("async-variant-retry").shadowRoot.querySelector("footer button").click()
+  JS
+end
+
+When /^I close the failure dialog$/ do
+  wait_for_shadow!
+  page.evaluate_script(<<~JS)
+    document.querySelector("async-variant-retry").shadowRoot.querySelector("dialog > button[type=button]").click()
+  JS
+end

data/features/support/env.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+ENV["RAILS_ENV"] ||= "test"
+require File.expand_path("../../spec/dummy/config/environment", __dir__)
+
+require "capybara"
+require "capybara/cucumber"
+require "capybara/cuprite"
+require_relative "../../spec/support/schema"
+
+DummySchema.load!
+
+Capybara.register_driver(:cuprite) do |app|
+  Capybara::Cuprite::Driver.new(app, window_size: [1200, 900], timeout: 10, process_timeout: 20, js_errors: true)
+end
+Capybara.app                = Rails.application
+Capybara.javascript_driver  = :cuprite
+Capybara.default_driver     = :cuprite
+Capybara.server             = :puma, { Silent: true }
+
+ActionController::Base.allow_forgery_protection = false
+
+# Test adapter just records enqueued jobs -- we don't want them to actually run
+# during browser tests (they'd call real transformers and modify variant_records
+# behind the test's back). The retry step seeds the new state explicitly.
+ActiveJob::Base.queue_adapter = :test
+
+Before { DummySchema.cleanup! }

data/gemfiles/rails_7.2.gemfile

@@ -6,6 +6,7 @@ gem "appraisal"
 gem "irb"
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"
+gem "simplecov", require: false
 gem "rspec-rails"
 gem "rails", "~> 7.2.0"
 gem "sqlite3"

data/gemfiles/rails_8.0.gemfile

@@ -6,6 +6,7 @@ gem "appraisal"
 gem "irb"
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"
+gem "simplecov", require: false
 gem "rspec-rails"
 gem "rails", "~> 8.0.0"
 gem "sqlite3"

data/gemfiles/rails_8.1.gemfile

@@ -6,6 +6,7 @@ gem "appraisal"
 gem "irb"
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"
+gem "simplecov", require: false
 gem "rspec-rails"
 gem "rails", "~> 8.1.0"
 gem "sqlite3"

data/lib/active_storage/async_variants/asset_tag_helper_extension.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    # Prepended onto ActionView::Helpers::AssetTagHelper. Adds `async:` and
+    # `direct:` options to image_tag/video_tag; routes unprocessed variants
+    # through a <turbo-frame> whose body lives in StatesController#show.
+    module AssetTagHelperExtension
+      include ActiveStorage::AsyncVariants::Helper
+
+      def image_tag(source, options = {})
+        async_variant_tag(:image, [source], options) do |urls, opts|
+          super(urls.first, opts)
+        end
+      end
+
+      def video_tag(*sources)
+        options = sources.extract_options!
+        async_variant_tag(:video, sources, options) do |urls, opts|
+          super(*urls, opts)
+        end
+      end
+
+      private
+
+      def async_variant_tag(kind, sources, options)
+        options = options.symbolize_keys
+        async = options.delete(:async)
+        direct = options.delete(:direct)
+        return yield(sources, options) if !async && !direct
+
+        variant, *rest = sources
+        assert_async_variant!(variant)
+
+        if async && !async_variant_processed_inline?(variant)
+          async_variant_turbo_frame(variant, kind:, direct:, html_options: options) do
+            # populate TurboFrame with a placeholder image/video, so there's valid markup right away
+            yield [async_variant_representation_path(variant), *rest], options.except(:data)
+          end
+        else
+          yield [async_variant_resolved_src(variant, direct:), *rest], options
+        end
+      end
+
+      def assert_async_variant!(source)
+        unless source.is_a?(ActiveStorage::VariantWithRecord) || source.is_a?(ActiveStorage::Preview)
+          raise ArgumentError, "image_tag/video_tag with async:/direct: requires an ActiveStorage::VariantWithRecord or Preview, got #{source.class}"
+        end
+      end
+
+      def async_variant_turbo_frame(variant, kind:, direct:, html_options:, &block)
+        content_tag(
+          :"turbo-frame",
+          id: async_variant_frame_id(variant),
+          src: async_variant_frame_src(variant, kind: kind, direct: direct, html_options: html_options),
+          refresh: "morph",
+          &block
+        )
+      end
+    end
+  end
+end