active_storage-async_variants 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34c672d7d6d989bb7c633aa1e57e081d6879a8ea9695ffd65997b9df9cf8f8ab
-  data.tar.gz: aca54bb9b2ae6af16016f1e96e6e3f221bc7029b8eca9c145535eadefeb57d66
+  metadata.gz: fffff13cd7b602bc0139ae60dff32c4d38d573b738edaa244f21df5dfa331723
+  data.tar.gz: 1251c74b70fd15eaaf1e48e494b7fc9d773f2989f83e1b99ca6862fdaec6c144
 SHA512:
-  metadata.gz: e86b3777c71d70d2014fe439fb91f395f1711cce40efefa3c5e5291a22bd2fc6d1933aad3a1c095557726e45547d7112f9e2f2bbd24fece75726adebddd6f686
-  data.tar.gz: 591deb4316c685316084ebb26904e5fe5b2ecbea0328cc832469ae4185388239511e35507b53264e137cf85153bfe1a846e7bd0491ba023bb991333653cfb532
+  metadata.gz: 2bfef2ba7b3d4576d20a867095c7e75f8f36ab122d0718901856ce0bab8330521f5edeb73a0e75a12f3ed20250fe28c25304b4823929167daa910d240a7b9477
+  data.tar.gz: f0e5e7a9cfe3d75ff7afe960fc7675447b466dc6e8500b7db6fca3c6a24cd8d0dfa837e938b216898a8ee8d95f470c1aa80b03be7c407e8e0ee7a63a46d74775

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+## [0.10.0]
+
+- **Breaking:** Async previews now persist the same graph stock Active Storage builds. For a previewable blob (a video), an image-format variant is a `Preview`: the extracted frame is attached as the source blob's `preview_image`, and the variant record hangs off the *frame* blob, not the source. `ProcessJob` resolves the attachment's `representation` and takes the preview path when stock would. External transformers receive a frame placeholder (`byte_size: 0, checksum: "0"`) to write into; the success callback reconciles both placeholders. Read video stills through `representation`/`preview`, not `variant`.
+- **Breaking:** Naming a `transformer:` is now the only async opt-in. The `async:` option is gone and raises `ArgumentError`. The built-in `ActiveStorage::AsyncVariants::Standard` transformer replaces a bare `async: true` (the stock variant pipeline, run in the background). A transformer's kind follows from what it overrides: `Transformer#standard?` (neither), `#inline?` (`process`), `#external?` (`initiate`).
+- **Breaking:** Attaching a file enqueues an async variant only when it declares Active Storage's `preprocessed:` option (`true`, a method name, or a proc evaluated against the record). Previously every variant naming a `transformer:` was enqueued on every attach, whatever the file — so an image upload also ran the attachment's video transcode. Stock Active Storage no longer sees async variants when preprocessing, so `preprocessed: true` never also queues a `TransformJob` or a local `PreviewImageJob`.
+- Migration note: existing variant records for video stills live on the source blob under the old structure. Move them onto the frame blob (`UPDATE active_storage_variant_records SET blob_id = <frame>`), attaching a placeholder frame where none exists; the `variation_digest` is unchanged. Records whose output is itself a video (transcodes) stay on the source. Replace `async: true` with `transformer: ActiveStorage::AsyncVariants::Standard` where no transformer was named, and drop it where one was. Add `preprocessed: true` (or a condition) to each async variant that should process on attach.
+- `Preview` speaks the same progress protocol as `VariantWithRecord`: `async_state`, `progress`, `progress_known?`, `progress_rate`, `last_heartbeat_at`, `error`.
+- `async_record` is public on both `VariantWithRecord` and `Preview`, and both gain `retry!` (drop a failed record, then `enqueue!`), so callers need not know where a representation keeps its record.
+- `NamedVariantScan` compares declarations structurally instead of instantiating `attachment.variant`, which raises for videos.
+- Fix: declaring `preprocessed:` alongside a `transformer:` no longer breaks the declaration-time registry warm-up (a proc raised on `Marshal.dump`; other values registered the wrong digest).
+- MirrorService: the success callback mirrors reconciled variant blobs to the mirrors, as Rails does for direct uploads, and `bucket_backed?` resolves through the primary service.
+- Frame placeholder creation is serialized on the blob row: every image variant of one video reaches it concurrently, and a second `preview_image` attachment would be invisible to `has_one`, stranding the records hanging off it.
+- Ships the `state`/`error`/`attempts` migration for `active_storage_variant_records` (guarded with `if_not_exists`, so apps that added the columns themselves can install it harmlessly), and builds the test schema from `db/migrate` so a missing shipped migration fails the suite.
+- Fix: `ProcessJob` skips a variant record that is already processed or whose run is still heartbeating. Previously every enqueue re-dispatched the variant — attaching an already-processed blob to another record, a retry, or a duplicate job paid for a second render and flipped processed media back to processing.
+- Fix: the success callback applies the reported `byte_size` and `checksum` whenever they arrive, not only over the `0`/`"0"` placeholders, since a re-render writes over the record's existing output blob. Reported `preview_image_*` values land only on a frame, never on a variant's source blob.
+- Fix: destroying a variant record purges any output a racing render attached after the destroy read its attachments, so a purged source no longer leaves outputs pointing at a deleted record.
+
+## [0.9.0]
+
+- **Breaking:** Split the opinionated UI out into a separate gem, [`active_storage-async_variants-ui`](https://github.com/botandrose/active_storage-async_variants-ui). This gem is now UI-free plumbing — the async state machine, `ProcessJob`, the heartbeat watchdog, the external-service callback endpoint, and the `Transformer` base class. Its only runtime dependency is `activestorage` (no more `turbo-rails` / `isolate_assets`).
+- Moved to the UI gem: `image_tag`/`video_tag` with `async:`/`direct:`, the `<turbo-frame>` state endpoint and partials, the circular progress bar, the filename-bearing placeholder route, the retry affordance, and the `cdn_host` / `parent_controller` / `retry_visible_if` configuration. A variant's `.url` (serving the original until processed) is unchanged.
+- Migration note: apps that relied on the rendering helpers should add `gem "active_storage-async_variants-ui"`. Apps using `active_storage-crucible` or only the variant pipeline need no change.
+
 ## [0.8.0]
 
 - The processing progress bar now advances smoothly between polls: variants expose a `rate` (percent-per-second, derived from the record's `created_at`, last heartbeat, and reported progress) that the `@botandrose/progress-bar` element uses to optimistically creep forward, instead of only stepping on each refresh. Includes a migration adding a `created_at` column to `active_storage_variant_records`; run it before deploying.

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 `async: true` 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. Naming a `transformer:` on a variant definition opts it into async processing.
 
 ## Commands
 
@@ -19,17 +19,23 @@ 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 (`async:`, `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 `async: true`
+- **`VariationExtension`** → `ActiveStorage::Variation` — extracts the `transformer:` option from variant config before passing the rest to standard Active Storage
+- **`AttachmentExtension`** → `ActiveStorage::Attachment` — hooks into `transform_variants_later` to enqueue `ProcessJob` for async variants whose `preprocessed:` holds for the record, hiding async variants from stock preprocessing
 - **`VariantWithRecordExtension`** → `ActiveStorage::VariantWithRecord` — overrides URL generation to serve the original blob while not ready; adds state query methods (`processed?`, `processing?`, `pending?`, `failed?`)
-- **`ProcessJob`** — background job that determines transformer type (inline vs external) and processes accordingly
+- **`PreviewExtension`** → `ActiveStorage::Preview` — blocks the synchronous preview transform for async variants and resolves state/URLs through the stock preview graph
+- **`ProcessJob`** — background job that resolves the attachment's representation (variant vs preview), determines transformer type (inline vs external), and processes accordingly
+
+### Preview Structure
+
+Async previews persist the same graph stock Active Storage builds: the extracted frame is attached as the source blob's `preview_image`, and the variant record hangs off the *frame* blob, not the source. External transformers get a frame placeholder (`byte_size: 0, checksum: "0"`) the service writes into; the success callback reconciles both the variant and frame placeholders. Inline/default transformers extract the real frame up front via the stock previewer.
 
 ### Transformer Types
 
-- **Inline**: implements `process(file, **options)` → blocks worker, returns `{ io:, content_type:, filename: }`
-- **External**: implements `initiate(source_url:, destination_url:, callback_url:, **options)` → frees worker immediately, external service POSTs to callback URL when done
+Naming a `transformer:` is the async opt-in; the kind is determined by what the transformer overrides (`Transformer#standard?`/`#inline?`/`#external?`):
 
-The gem detects which type by checking if `process` is overridden on the transformer class.
+- **Standard** (`ActiveStorage::AsyncVariants::Standard`): overrides neither → runs the stock Active Storage variant pipeline in the background. Replaces the old bare `async: true` (no transformer) declaration, which now raises.
+- **Inline**: overrides `process(file, **options)` → blocks worker, returns `{ io:, content_type:, filename: }`
+- **External**: overrides `initiate(source_url:, callback_url:, **options)` → frees worker immediately, external service POSTs to callback URL when done
 
 ### Callback Endpoint
 

data/README.md

@@ -2,6 +2,8 @@
 
 Extends Active Storage with pluggable per-variant transformers, async-safe variant processing, and failure handling.
 
+This gem is the UI-free plumbing. A variant's `.url` serves the original while it is pending/processing/failed, and the processed variant once ready — nothing renders a spinner or progress bar. For the optional turbo-frame UI (`image_tag`/`video_tag` with `async:`/`direct:`, a circular progress bar, and a retry affordance), add the companion gem [`active_storage-async_variants-ui`](https://github.com/botandrose/active_storage-async_variants-ui).
+
 ## The Problem
 
 Active Storage's variant system assumes transformations are fast and reliable -- like generating an image thumbnail. But some transformations are slow (transcoding a 1GB video to 720p VP9) and fallible (the transcode may permanently fail). When you use `process: :later`, Active Storage enqueues a background job, but if the variant is requested before the job finishes, it falls through to synchronous processing -- blocking the request for minutes or timing out entirely. And if the transformation fails, the error bubbles up with no tracking or retry limits.
@@ -19,7 +21,7 @@ bin/rails db:migrate
 
 ## Usage
 
-Add `async: true` to any named variant to opt into the async pipeline:
+Name a `transformer:` on any variant to opt it into the async pipeline:
 
 ```ruby
 class User < ApplicationRecord
@@ -27,102 +29,73 @@ class User < ApplicationRecord
     attachable.variant :web,
       transformer: VideoTranscoder,
       codec: "vp9",
-      resolution: "720p",
-      async: true
+      resolution: "720p"
   end
 end
 ```
 
-The presence of `async: true` 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 a `transformer:` is what opts a variant into async processing. Without it, variants behave exactly as they do in standard Active Storage. The transformer also says *how* the work happens — there are three kinds, distinguished by what they implement:
 
 ```ruby
 has_one_attached :video do |attachable|
-  # Async with custom transformer (video transcode)
+  # External: hands off to a remote service (implements #initiate)
   attachable.variant :web,
     transformer: VideoTranscoder,
-    codec: "vp9",
-    async: true
+    codec: "vp9"
 
-  # Async with default transformer (large image resize that's too slow for inline)
+  # Standard: the stock Active Storage variant pipeline, run in the background
+  # (e.g. a large image resize that's too slow for an inline request)
   attachable.variant :thumbnail,
     resize_to_limit: [200, 200],
-    async: true
+    transformer: ActiveStorage::AsyncVariants::Standard
 
-  # Sync with custom transformer (fast custom processing, no opt-in needed)
+  # Inline: custom processing in the worker (implements #process)
   attachable.variant :watermarked,
     transformer: WatermarkStamper
 end
 ```
 
-In views, use the same Active Storage helpers:
-
-```erb
-<%= video_tag user.video.variant(:web).url %>
-```
-
-While the variant is still processing (or has failed), 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 shows a progress bar 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: a progress bar while pending,
-    polls for completion, swaps to the real image when ready. %>
-<%= image_tag user.avatar.variant(:web), async: true %>
+A variant with no `transformer:` is a plain synchronous Active Storage variant — the gem stays out of the way.
 
-<%# 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 original). %>
-<%= image_tag user.avatar.variant(:web), direct: true %>
+### Processing on attach
 
-<%# Both together: direct URL once processed, progress bar while pending,
-    polling for completion. %>
-<%= image_tag user.avatar.variant(:web), async: true, direct: true %>
+An async variant is processed when a file is attached only if it says so with Active Storage's own `preprocessed:` option. It takes `true`, a method name, or a proc, evaluated against the record — so one attachment that accepts both images and videos can transcode only the videos:
 
-<%# Same for videos. %>
-<%= video_tag user.video.variant(:web), async: true, controls: true %>
+```ruby
+has_one_attached :media do |attachable|
+  attachable.variant :thumb, resize_to_limit: [150, 150], format: "webp",
+    transformer: Crucible, preprocessed: true
+  attachable.variant :transcoded, resize_to_limit: [1280, 720], format: "mp4",
+    transformer: Crucible, preprocessed: :video?
+end
 ```
 
-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
+An async variant without `preprocessed:` is never enqueued on attach; call `enqueue!` on it when you want it. Stock Active Storage never preprocesses an async variant itself — the gem's `ProcessJob` is the only thing that does.
 
-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:
+In views, use the same Active Storage helpers:
 
-```ruby
-# config/initializers/active_storage_async_variants.rb
-ActiveStorage::AsyncVariants.cdn_host = "https://d1234abcd.cloudfront.net"
+```erb
+<%= video_tag user.video.variant(:web).url %>
 ```
 
-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.
+While the variant is still processing (or has failed), this serves the original video. Once processing completes, it serves the transcoded variant.
 
 ## Configuration
 
-Set options in an initializer. The `configure` block groups them (each is also a plain accessor, e.g. `ActiveStorage::AsyncVariants.cdn_host = …`):
+Set options in an initializer. The `configure` block groups them (each is also a plain accessor, e.g. `ActiveStorage::AsyncVariants.heartbeat_interval = …`):
 
 ```ruby
 # config/initializers/active_storage_async_variants.rb
 ActiveStorage::AsyncVariants.configure do |config|
-  config.cdn_host              = "https://d1234abcd.cloudfront.net"
   config.heartbeat_interval    = 5.seconds
   config.heartbeat_stale_after = 60.seconds
-  config.parent_controller     = "ApplicationController"
-  config.retry_visible_if { current_user&.admin? }
 end
 ```
 
 | Option | Default | Purpose |
 |--------|---------|---------|
-| `cdn_host` | `nil` | Host for `direct:` URLs (`"#{cdn_host}/#{variant.key}"`); falls back to the storage service URL. |
-| `heartbeat_interval` | `5.seconds` | Expected cadence of progress heartbeats; the processing `<turbo-frame>` re-polls at this rate. |
+| `heartbeat_interval` | `5.seconds` | Expected cadence of progress heartbeats from external transformers. (The UI gem's processing `<turbo-frame>` re-polls at this rate.) |
 | `heartbeat_stale_after` | `60.seconds` | A processing variant with no heartbeat for this long is marked `failed`. Must exceed `heartbeat_interval`. |
-| `parent_controller` | `"ActionController::Base"` | Base class for the gem's controllers, so the retry view can reach your app's `current_user`. Set as a String. |
-| `retry_visible_if` | off | Block (run in the view context) gating the failed-state retry affordance. |
 
 ## Writing a Transformer
 
@@ -229,7 +202,7 @@ variant.error        # => error message string, or nil
 
 ## Placeholders
 
-There is nothing to configure. A variant's `.url` serves the original while it is pending, processing, or failed, and the processed variant once ready. With `async: true` on `image_tag`/`video_tag`, the gem instead shows a circular progress bar while processing, and a red error glyph -- the same progress bar in its error state -- once the variant has permanently failed.
+There is nothing to configure. A variant's `.url` serves the original while it is pending, processing, or failed, and the processed variant once ready. (For a circular progress bar while processing and a red error glyph once failed, add the [`active_storage-async_variants-ui`](https://github.com/botandrose/active_storage-async_variants-ui) gem.)
 
 ## Failure Handling
 
@@ -248,7 +221,7 @@ variant.error   # => "ffmpeg exited with status 1: ..."
 ### External transformer flow
 
 1. User uploads a file to an attachment that has async variants defined
-2. After attachment, a background job is enqueued for each async variant
+2. After attachment, a background job is enqueued for each async variant whose `preprocessed:` holds for the record
 3. `VariantRecord` is created with state `pending`
 4. The job calls the transformer's `initiate` method with presigned source/destination URLs and a signed callback URL, then exits -- the worker is free
 5. The external service processes the file, uploads the result to the destination URL

data/Rakefile

@@ -5,23 +5,4 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(: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]
-
-namespace :vendor do
-  desc "Pull the latest @botandrose/progress-bar from unpkg.com into app/assets"
-  task :progress_bar do
-    require "open-uri"
-    url = "https://unpkg.com/@botandrose/progress-bar"
-    dest = File.expand_path("app/assets/javascripts/progress-bar.js", __dir__)
-    File.write(dest, URI.open(url).read)
-    puts "Vendored #{url} -> #{dest}"
-  end
-end
-
-task default: :all
+task default: :spec

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

@@ -4,9 +4,6 @@ module ActiveStorage
   module AsyncVariants
     class CallbacksController < ActionController::API
       def create
-        variant_record_id = ActiveStorage.verifier.verify(params[:token], purpose: :async_variant_callback)
-        variant_record = ActiveStorage::VariantRecord.find(variant_record_id)
-
         case params[:status]
         when "success"
           variant_record.update!(state: "processed")
@@ -29,33 +26,45 @@ module ActiveStorage
 
       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 variant_record
+        @variant_record ||= begin
+          variant_record_id = ActiveStorage.verifier.verify(params[:token], purpose: :async_variant_callback)
+          ActiveStorage::VariantRecord.find(variant_record_id)
+        end
+      end
+
       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])
+        if frame?(variant_record.blob)
+          reconcile(variant_record.blob, params[:preview_image_byte_size], params[:preview_image_checksum])
+        end
       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.
+      # A re-render writes over a reused blob, so the reported values describe the object now stored.
       def reconcile(blob, byte_size, checksum)
         return unless blob
 
-        attrs = {}
-        if (bytes = positive_int(byte_size)) && blob.byte_size.zero?
-          attrs[:byte_size] = bytes
+        if positive_int?(byte_size)
+          blob.byte_size = byte_size
         end
-        if checksum.present? && checksum != "0" && blob.checksum == "0"
-          attrs[:checksum] = checksum
+        if checksum.present?
+          blob.checksum = checksum
         end
-        blob.update!(attrs) if attrs.any?
+        blob.save!
+
+        if blob.checksum != "0"
+          blob.mirror_later
+        end
+      end
+
+      # preview_image_* must never land on a variant's source blob.
+      def frame?(blob)
+        blob.checksum == "0" ||
+          ActiveStorage::Attachment.exists?(record_type: "ActiveStorage::Blob", name: "preview_image", blob_id: blob.id)
       end
 
-      def positive_int(value)
-        int = value.to_i
-        int.positive? ? int : nil
+      def positive_int?(value)
+        value.to_i.positive?
       end
     end
   end

data/config/routes.rb

@@ -4,21 +4,4 @@ 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
-  post "/active_storage/async_variants/states/:signed_blob_id/:variation_key/retry",
-    to: "active_storage/async_variants/states#retry",
-    as: :async_variant_state_retry
-
-  # Tiny 1x1 GIF whose URL carries the media's filename, so the processing/failed
-  # box reserves layout without fetching the original through a representation.
-  get "/active_storage/async_variants/placeholder/:filename",
-    to: "active_storage/async_variants/states#placeholder",
-    as: :async_variant_placeholder,
-    constraints: { filename: %r{[^/]+} },
-    format: false
-
-  ActiveStorage::AsyncVariants::Assets.draw(self, "/active_storage/async_variants/assets")
 end

data/db/migrate/20260304000001_add_state_columns_to_variant_records.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class AddStateColumnsToVariantRecords < ActiveRecord::Migration[7.2]
+  def change
+    add_column :active_storage_variant_records, :state, :string, default: "pending", if_not_exists: true
+    add_column :active_storage_variant_records, :error, :text, if_not_exists: true
+    add_column :active_storage_variant_records, :attempts, :integer, default: 0, if_not_exists: true
+  end
+end

data/gemfiles/rails_7.2.gemfile

@@ -10,9 +10,5 @@ gem "simplecov", require: false
 gem "rspec-rails"
 gem "rails", "~> 7.2.0"
 gem "sqlite3"
-gem "cucumber"
-gem "capybara"
-gem "cuprite"
-gem "puma"
 
 gemspec path: "../"

data/gemfiles/rails_8.0.gemfile

@@ -10,9 +10,5 @@ gem "simplecov", require: false
 gem "rspec-rails"
 gem "rails", "~> 8.0.0"
 gem "sqlite3"
-gem "cucumber"
-gem "capybara"
-gem "cuprite"
-gem "puma"
 
 gemspec path: "../"

data/gemfiles/rails_8.1.gemfile

@@ -10,9 +10,5 @@ gem "simplecov", require: false
 gem "rspec-rails"
 gem "rails", "~> 8.1.0"
 gem "sqlite3"
-gem "cucumber"
-gem "capybara"
-gem "cuprite"
-gem "puma"
 
 gemspec path: "../"

data/lib/active_storage/async_variants/attachment_extension.rb

@@ -5,22 +5,39 @@ module ActiveStorage
     module AttachmentExtension
       private
 
+      # Stock would also preprocess an async variant: a TransformJob, or a PreviewImageJob that runs the local previewer.
       def transform_variants_later
-        super
+        without_async_variants { super }
         enqueue_async_variant_jobs
       end
 
+      def named_variants
+        return super unless @without_async_variants
+        super.reject { |_name, named_variant| async_variant?(named_variant) }
+      end
+
+      def without_async_variants
+        @without_async_variants = true
+        yield
+      ensure
+        @without_async_variants = false
+      end
+
       def enqueue_async_variant_jobs
         return unless blob.bucket_backed?
 
         named_variants.each do |name, named_variant|
-          next unless named_variant.transformations.key?(:async)
+          next unless async_variant?(named_variant) && named_variant.preprocessed?(record)
 
           ActiveStorage::AsyncVariants::ProcessJob.perform_later(
             record, self.name, name.to_s,
           )
         end
       end
+
+      def async_variant?(named_variant)
+        named_variant.transformations.key?(:transformer)
+      end
     end
   end
 end

data/lib/active_storage/async_variants/blob_extension.rb

@@ -7,8 +7,10 @@ module ActiveStorage
       # processing workers (Crucible, etc.) can reach via presigned URLs. The
       # Disk and Test services return false; the gem then defers to vanilla
       # ActiveStorage rather than trying to enqueue jobs or serve fallbacks.
+      # MirrorService doesn't delegate :bucket, so resolve through its primary.
       def bucket_backed?
-        service.respond_to?(:bucket)
+        resolved = service.respond_to?(:primary) ? service.primary : service
+        resolved.respond_to?(:bucket)
       end
     end
   end

data/lib/active_storage/async_variants/named_variant_scan.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    # Finds the async named-variant declaration whose transformations match a
+    # variation, starting from a blob's attachments. Used to recover the
+    # :transformer option when the Registry is cold, and by
+    # Preview/VariantWithRecord enqueue paths to locate the attachment to
+    # dispatch ProcessJob against.
+    #
+    # Walks one level up through a preview_image attachment so a lookup from a
+    # video's extracted frame still finds the named variant declared on the
+    # parent record's source-video field.
+    #
+    # Candidates are compared structurally (order-insensitive, JSON-normalized)
+    # against the declared transformations, never by instantiating
+    # attachment.variant -- which raises InvariableError for previewable blobs.
+    module NamedVariantScan
+      module_function
+
+      def find(blob, variation, depth: 0)
+        blob.attachments.each do |attachment|
+          if attachment.name == "preview_image" && attachment.record_type == "ActiveStorage::Blob" && depth < 1
+            source = ActiveStorage::Blob.find_by(id: attachment.record_id)
+            result = source && find(source, variation, depth: depth + 1)
+            return result if result
+            next
+          end
+
+          attachment.send(:named_variants).each do |name, named_variant|
+            candidate = ActiveStorage::Variation.wrap(named_variant.transformations)
+            next unless candidate.async_options[:transformer]
+            return [attachment, name, candidate.async_options] if matches?(candidate, variation)
+          end
+        end
+        nil
+      end
+
+      # A format-less declaration matches any target format, because runtime
+      # resolution (Blob#variant's default_to) adds a blob-dependent format:
+      # the declaration never carries.
+      def matches?(candidate, variation)
+        declared = normalize(candidate.transformations)
+        target = normalize(variation.transformations)
+        declared_format = declared.delete("format")
+        target_format = target.delete("format")
+        declared == target && (declared_format.nil? || declared_format == target_format)
+      end
+
+      def normalize(transformations)
+        JSON.parse(transformations.to_json)
+      end
+    end
+  end
+end