active_storage-async_variants 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3d828692f86ff7b409b93f3198daae20c5c6821a0cce10da31b625abe7c04be
-  data.tar.gz: '0319ea7873525ea5d76a930e195687b3ba28bebd58922e3fc4aa821238241f28'
+  metadata.gz: 34c672d7d6d989bb7c633aa1e57e081d6879a8ea9695ffd65997b9df9cf8f8ab
+  data.tar.gz: aca54bb9b2ae6af16016f1e96e6e3f221bc7029b8eca9c145535eadefeb57d66
 SHA512:
-  metadata.gz: 9e80ebc6059bf84853cf7bf05d824ed5d25d5b195a4702d86495cdb29366eb02ee390558768fa66a1f5ea85e8e86987a46f9c7a2492de59e1a7287b25ef7074a
-  data.tar.gz: 23dc024c9a1ceaa334580d32af52f20e4e327f3d40d22e438616bdc0077f5b62f95deb50670ee5a30b3a1e72716e2ef9604bd6eabe2fc3a699aaa21142518ad8
+  metadata.gz: e86b3777c71d70d2014fe439fb91f395f1711cce40efefa3c5e5291a22bd2fc6d1933aad3a1c095557726e45547d7112f9e2f2bbd24fece75726adebddd6f686
+  data.tar.gz: 591deb4316c685316084ebb26904e5fe5b2ecbea0328cc832469ae4185388239511e35507b53264e137cf85153bfe1a846e7bd0491ba023bb991333653cfb532

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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.
+- Fix: the processing/failed placeholder image now points at a tiny gem-served 1x1 GIF whose URL ends in the media's filename, instead of a `data:` URI. Restores filename-based identification of the placeholder (e.g. for media-table diff assertions) without fetching the original through a representation. Video placeholders remain a source-less `<video>`.
+
+## [0.7.0]
+
+- **Breaking:** A variant now opts into async processing with `async: true` instead of `processing:`. The `processing:` and `failed:` placeholder options are removed entirely — there is nothing to configure. A variant's `.url` serves the original while pending/processing/failed, and the processed variant once ready.
+- The `async:`-helper UI no longer fetches a placeholder through the representations path on every poll. The processing/failed states render a zero-network sized box with the progress bar floating over it.
+- The failed state now renders the progress bar in its error state (a static red ring with an X, via `@botandrose/progress-bar`'s `error` attribute) rather than a configurable failed SVG. The retry affordance is unchanged.
+- Migration note: replace `processing: <anything>` with `async: true` on each async variant and drop any `failed:` option. Any `:original`/`:blank`/String/Proc placeholder values no longer have an effect.
+
 ## [0.6.0]
 
 - External transforms can now report progress: a `progress` callback records the percent complete and a heartbeat, readable via `#progress` / `#progress_known?` on variants and previews.

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 `processing:` 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 `async: true` 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 (`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?`)
+- **`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`
+- **`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
 
 ### Transformer Types

data/README.md

@@ -19,7 +19,7 @@ bin/rails db:migrate
 
 ## Usage
 
-Add `processing:` to any named variant to opt into the async pipeline. The value is what to serve while the variant is being processed:
+Add `async: true` to any named variant to opt into the async pipeline:
 
 ```ruby
 class User < ApplicationRecord
@@ -28,12 +28,12 @@ class User < ApplicationRecord
       transformer: VideoTranscoder,
       codec: "vp9",
       resolution: "720p",
-      processing: :original
+      async: true
   end
 end
 ```
 
-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:
+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:
 
 ```ruby
 has_one_attached :video do |attachable|
@@ -41,12 +41,12 @@ has_one_attached :video do |attachable|
   attachable.variant :web,
     transformer: VideoTranscoder,
     codec: "vp9",
-    processing: :original
+    async: true
 
   # Async with default transformer (large image resize that's too slow for inline)
   attachable.variant :thumbnail,
     resize_to_limit: [200, 200],
-    processing: :original
+    async: true
 
   # Sync with custom transformer (fast custom processing, no opt-in needed)
   attachable.variant :watermarked,
@@ -60,23 +60,23 @@ In views, use the same Active Storage helpers:
 <%= video_tag user.video.variant(:web).url %>
 ```
 
-If the variant is still processing, this serves the original video. Once processing completes, it serves the transcoded variant.
+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 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`:
+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: spinner while pending,
+<%# 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 %>
 
 <%# 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). %>
+    Rails representation URL (which serves the original). %>
 <%= image_tag user.avatar.variant(:web), direct: true %>
 
-<%# Both together: direct URL once processed, placeholder while pending,
+<%# Both together: direct URL once processed, progress bar while pending,
     polling for completion. %>
 <%= image_tag user.avatar.variant(:web), async: true, direct: true %>
 
@@ -227,31 +227,9 @@ variant.failed?      # => true if permanently failed
 variant.error        # => error message string, or nil
 ```
 
-## Placeholder Options
+## Placeholders
 
-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 while processing
-attachable.variant :web, processing: :original
-
-# Return nil -- let the view handle it
-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" }
-
-# Distinct placeholder when permanently failed
-attachable.variant :web,
-  processing: :original,
-  failed: "/icons/broken.svg"
-```
-
-Both options accept the same set of values: `:original`, `:blank`, a String URL, or a Proc that receives the blob.
+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.
 
 ## Failure Handling
 
@@ -276,7 +254,7 @@ 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 `processing:`/`failed:` placeholder
+8. When a view requests the variant URL, the gem checks state and serves the processed variant or, while pending/processing/failed, the original
 
 ### Inline transformer flow
 
@@ -284,7 +262,7 @@ variant.error   # => "ffmpeg exited with status 1: ..."
 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 3 attempts)
-7. When a view requests the variant URL, the gem checks state and serves the variant or the `processing:`/`failed:` placeholder
+7. When a view requests the variant URL, the gem checks state and serves the processed variant or, while pending/processing/failed, the original
 
 ## License
 

data/app/assets/javascripts/progress-bar.js

@@ -1,5 +1,6 @@
 const CIRCLE_RADIUS = 40; // fallback r attribute; CSS shrinks it to fit the stroke
 const PATH_LENGTH = 100;  // normalize the arc so dash math is independent of the radius
+const RATE_HZ = 30;       // optimistic auto-advance tick frequency
 
 const STYLES = `
   :host {
@@ -98,8 +99,13 @@ const STYLES = `
     stroke: var(--indeterminate-color);
   }
 
-  :host([error]) .progress-ring {
+  /* The X of the error glyph; revealed by [error]. */
+  .error-mark {
+    display: none;
+    fill: none;
     stroke: var(--error-color);
+    stroke-width: var(--circular-thickness);
+    stroke-linecap: round;
   }
 
   .label {
@@ -132,6 +138,12 @@ const STYLES = `
     0%   { transform: rotate(-90deg); }
     100% { transform: rotate(270deg); }
   }
+
+  /* Error (circular): static full ring + X. Last so it beats the indeterminate rules. */
+  :host([error]) .track { stroke: var(--error-color); }
+  :host([error]) .progress-ring { display: none; }
+  :host([error]) .ring { animation: none; }
+  :host([error]) .error-mark { display: block; }
 `;
 
 const LINEAR_HTML = `
@@ -144,6 +156,7 @@ const CIRCULAR_HTML = `
     <svg class="ring" viewBox="0 0 100 100">
       <circle class="track" cx="50" cy="50" r="${CIRCLE_RADIUS}"></circle>
       <circle class="progress-ring" cx="50" cy="50" r="${CIRCLE_RADIUS}" pathLength="${PATH_LENGTH}"></circle>
+      <path class="error-mark" d="M37 37 L63 63 M63 37 L37 63"></path>
     </svg>
     <span class="label"><slot></slot></span>
   </div>
@@ -166,12 +179,21 @@ function clampPercent(value) {
   return Math.min(100, Math.max(0, number));
 }
 
+function parseRate(value) {
+  const number = Number(value);
+  if (Number.isNaN(number)) {
+    throw new TypeError(`progress-bar: rate must be numeric, got ${JSON.stringify(value)}`);
+  }
+  return number;
+}
+
 class ProgressBar extends HTMLElement {
   constructor() {
     super();
     this.attachShadow({ mode: 'open' });
     this._percent = null;
     this._renderedMode = null;
+    this._rateTimer = null;
   }
 
   connectedCallback() {
@@ -180,6 +202,11 @@ class ProgressBar extends HTMLElement {
     this.setAttribute('aria-valuemin', '0');
     this.setAttribute('aria-valuemax', '100');
     this.updateBar();
+    this._syncTicker();
+  }
+
+  disconnectedCallback() {
+    this._stopTicker();
   }
 
   get percent() {
@@ -202,6 +229,19 @@ class ProgressBar extends HTMLElement {
     this.toggleAttribute('error', Boolean(value));
   }
 
+  get rate() {
+    const value = this.getAttribute('rate');
+    return value === null ? null : Number(value);
+  }
+
+  set rate(value) {
+    if (value === null || value === undefined) {
+      this.removeAttribute('rate');
+    } else {
+      this.setAttribute('rate', parseRate(value));
+    }
+  }
+
   get indeterminate() {
     return !this.hasAttribute('percent');
   }
@@ -215,16 +255,22 @@ class ProgressBar extends HTMLElement {
   }
 
   static get observedAttributes() {
-    return ['percent', 'mode'];
+    return ['percent', 'mode', 'rate'];
   }
 
   attributeChangedCallback(name, oldValue, newValue) {
     if (name === 'percent') {
       this._percent = newValue === null ? null : clampPercent(newValue);
     }
+    if (name === 'rate' && newValue !== null) {
+      parseRate(newValue);
+    }
     if (name === 'mode') {
       this.render();
     }
+    if (name === 'percent' || name === 'rate') {
+      this._syncTicker();
+    }
     this.updateBar();
   }
 
@@ -251,6 +297,38 @@ class ProgressBar extends HTMLElement {
     }
   }
 
+  // Optimistic auto-advance: while a nonzero rate is set on a determinate bar,
+  // creep percent forward on its own. Indeterminate bars ignore rate entirely.
+  _syncTicker() {
+    const rate = Number(this.getAttribute('rate'));
+    const shouldRun = this.isConnected && !this.indeterminate && Number.isFinite(rate) && rate !== 0;
+    if (shouldRun && this._rateTimer === null) {
+      this._rateTimer = setInterval(() => this._tick(), 1000 / RATE_HZ);
+    } else if (!shouldRun) {
+      this._stopTicker();
+    }
+  }
+
+  _stopTicker() {
+    if (this._rateTimer !== null) {
+      clearInterval(this._rateTimer);
+      this._rateTimer = null;
+    }
+  }
+
+  _tick() {
+    const rate = Number(this.getAttribute('rate'));
+    const next = clampPercent(this._percent + rate / RATE_HZ);
+    if (next !== this._percent) {
+      this.percent = next;
+    }
+    // Hitting the bound it's heading toward retires the rate; a later percent
+    // change can re-arm it.
+    if (next === 0 || next === 100) {
+      this.removeAttribute('rate');
+    }
+  }
+
   render() {
     const mode = this.mode;
     if (this._renderedMode === mode) {

data/app/assets/stylesheets/progress.css

@@ -2,19 +2,23 @@
    media box (and the progress bar centered on it) coincides with the parent
    figure box, instead of sitting in a taller line box from the baseline gap --
    otherwise an overlay centered on the figure lands off-center from the ring. */
-turbo-frame:has(> .async-variant-processing) {
+turbo-frame:has(> .async-variant-processing),
+turbo-frame:has(> .async-variant-failed) {
   display: block;
 }
-.async-variant-processing {
+.async-variant-processing,
+.async-variant-failed {
   position: relative;
   display: block;
 }
-/* Present to reserve the processed media's box, but rendered invisible via
-   opacity rather than visibility/display -- so it still has layout and stays
-   queryable by Capybara. The spinner floats over it. block drops the baseline
-   descender so the ring centers on the media, not a few px below it. */
+/* Present to reserve the variant's box, but rendered invisible via opacity
+   rather than visibility/display -- so it still has layout and stays queryable
+   by Capybara. The progress bar floats over it. block drops the baseline
+   descender so the ring centers on the box, not a few px below it. */
 .async-variant-processing img,
-.async-variant-processing video {
+.async-variant-processing video,
+.async-variant-failed img,
+.async-variant-failed video {
   opacity: 0.001;
   display: block;
 }
@@ -27,4 +31,5 @@ turbo-frame:has(> .async-variant-processing) {
   --progress-color: #2E7D32;
   --indeterminate-color: #2E7D32;
   --track-color: rgba(0, 0, 0, 0.25);
+  --error-color: #ff7c81;
 }

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

@@ -11,11 +11,20 @@ module ActiveStorage
 
       layout false
 
-      before_action :set_variant
+      # 1x1 transparent GIF served at a filename-bearing URL, so the
+      # processing/failed <img> identifies its media without fetching anything.
+      TRANSPARENT_GIF = "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7".unpack1("m").freeze
+
+      before_action :set_variant, only: %i[show retry]
 
       def show
       end
 
+      def placeholder
+        expires_in 1.year, public: true
+        send_data TRANSPARENT_GIF, type: "image/gif", disposition: "inline"
+      end
+
       def retry
         @variant.blob.variant_records.where(
           variation_digest: @variant.variation.digest,

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

@@ -1,16 +1,17 @@
 <div class="async-variant-state async-variant-failed">
-  <%= image_tag async_variant_representation_path(variant), **html_options.symbolize_keys.except(:controls, :autoplay, :preload) %>
+  <%= async_variant_placeholder_tag(variant, html_options, kind: kind) %>
+
+  <%= content_tag "progress-bar", "", mode: "circular", error: "", class: "async-variant-progress" %>
+
+  <%= ActiveStorage::AsyncVariants.stylesheet_link_tag "progress" %>
+  <%= ActiveStorage::AsyncVariants.javascript_include_tag "progress-bar", type: "module" %>
 
   <% if ActiveStorage::AsyncVariants.retry_visible?(self) %>
     <% dialog_id = "#{async_variant_frame_id(variant)}-error" %>
     <% form_id = "#{dialog_id}-form" %>
     <%# Light DOM, so the custom property inherits into the shadow root. %>
     <style>
-      .async-variant-failed {
-        position: relative;
-        display: inline-block;
-        --retry-opener-display: none;
-      }
+      .async-variant-failed { --retry-opener-display: none; }
       .async-variant-failed:hover { --retry-opener-display: inline-flex; }
     </style>
     <%# In the light DOM so its submit reaches Turbo, and so preventDefault on the

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

@@ -1,8 +1,7 @@
 <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 %>
+  <%= async_variant_placeholder_tag(variant, html_options, kind: kind) %>
 
-  <%= content_tag "progress-bar", "", mode: "circular", class: "async-variant-progress", percent: variant.progress %>
+  <%= content_tag "progress-bar", "", mode: "circular", class: "async-variant-progress", percent: variant.progress, rate: variant.progress_rate %>
 </div>
 
 <%= ActiveStorage::AsyncVariants.stylesheet_link_tag "progress" %>

data/config/routes.rb

@@ -12,5 +12,13 @@ Rails.application.routes.draw do
     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/20260608000001_add_created_at_to_variant_records.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddCreatedAtToVariantRecords < ActiveRecord::Migration[7.2]
+  def change
+    add_column :active_storage_variant_records, :created_at, :datetime, if_not_exists: true
+  end
+end

data/features/state_rendering.feature

@@ -37,3 +37,4 @@ Feature: image_tag with async: true emits the right markup per variant 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 failed state
+    And the frame should render an error progress bar

data/features/step_definitions/dummy_steps.rb

@@ -24,6 +24,10 @@ Then /^the frame should render a progress bar$/ do
   expect(page).to have_css("turbo-frame progress-bar", visible: :all)
 end
 
+Then /^the frame should render an error progress bar$/ do
+  expect(page).to have_css("turbo-frame progress-bar[error]", visible: :all)
+end
+
 Then /^the progress bar should be indeterminate$/ do
   expect(page).to have_css("turbo-frame progress-bar:not([percent])", visible: :all)
 end

data/lib/active_storage/async_variants/attachment_extension.rb

@@ -14,7 +14,7 @@ module ActiveStorage
         return unless blob.bucket_backed?
 
         named_variants.each do |name, named_variant|
-          next unless named_variant.transformations.key?(:processing)
+          next unless named_variant.transformations.key?(:async)
 
           ActiveStorage::AsyncVariants::ProcessJob.perform_later(
             record, self.name, name.to_s,

data/lib/active_storage/async_variants/helper.rb

@@ -7,6 +7,27 @@ module ActiveStorage
     # `helper ActiveStorage::AsyncVariants::Helper` (so the state partials can
     # use them).
     module Helper
+      # Invisible box reserving layout for the progress bar. The image src is a
+      # tiny gem GIF whose URL ends in the media filename (no original fetched);
+      # the video placeholder carries no <source>.
+      def async_variant_placeholder_tag(variant, html_options = {}, kind: :image)
+        opts = async_variant_box_dimensions(variant)
+          .merge(html_options.symbolize_keys.except(:src, :controls, :autoplay, :preload, :poster))
+        if kind == :video
+          content_tag(:video, "", opts)
+        else
+          src = Rails.application.routes.url_helpers.async_variant_placeholder_path(variant.blob.filename.to_s)
+          image_tag(src, opts)
+        end
+      end
+
+      def async_variant_box_dimensions(variant)
+        resize = variant.variation.transformations
+          .values_at(:resize_to_limit, :resize_to_fit, :resize_to_fill)
+          .compact.first
+        resize.is_a?(Array) ? { width: resize[0], height: resize[1] } : {}
+      end
+
       # In test with non-bucket-backed services, the gem defers to vanilla
       # ActiveStorage (synchronous vips transform) -- inline rendering keeps
       # those environments simple. Otherwise, only inline a normal <img> when

data/lib/active_storage/async_variants/preview_extension.rb

@@ -67,15 +67,15 @@ module ActiveStorage
       private
 
       def async_preview?
-        resolved_async_options[:transformer].present?
+        resolved_async_options[:async].present?
       end
 
       # Variations rebuilt from the redirect URL only carry transformations --
-      # :transformer / :processing / :failed are stripped at Variation#initialize
-      # and not embedded in the URL key. Recover them via the digest-keyed
-      # registry that VariationExtension warms on every view-side variant call,
-      # or fall back to scanning attached named variants when the registry is
-      # cold (autoloader hasn't touched the consumer model yet).
+      # :async / :transformer are stripped at Variation#initialize and not
+      # embedded in the URL key. Recover them via the digest-keyed registry that
+      # VariationExtension warms on every view-side variant call, or fall back to
+      # scanning attached named variants when the registry is cold (autoloader
+      # hasn't touched the consumer model yet).
       def resolved_async_options
         @resolved_async_options ||=
           variation.async_options.presence ||
@@ -90,7 +90,7 @@ module ActiveStorage
           attachment.send(:named_variants).each do |name, _|
             candidate = attachment.variant(name.to_sym)
             next unless candidate.variation.transformations.to_json == target
-            return [attachment, name, candidate.variation.async_options] if candidate.variation.async_options[:transformer].present?
+            return [attachment, name, candidate.variation.async_options] if candidate.variation.async_options[:async]
           end
         end
         nil
@@ -107,25 +107,9 @@ module ActiveStorage
         blob.variant_records.find_by(variation_digest: variation.digest)
       end
 
+      # Serve the original until the preview variant is processed.
       def fallback_preview_url(...)
-        case active_fallback
-        when :original then blob.url(...)
-        when :blank then nil
-        when Proc then active_fallback.call(blob)
-        when String then active_fallback
-        end
-      end
-
-      def active_fallback
-        if failed?
-          resolved_async_options.fetch(:failed) { resolved_async_options[:processing] }
-        else
-          resolved_async_options[:processing]
-        end
-      end
-
-      def failed?
-        find_preview_variant_record&.state == "failed"
+        blob.url(...)
       end
     end
   end

data/lib/active_storage/async_variants/reflection_extension.rb

@@ -7,7 +7,7 @@ module ActiveStorage
     #
     #   has_one_attached :avatar do |attachable|
     #     attachable.variant :thumb, resize_to_limit: [150, 150], format: "webp",
-    #       transformer: Crucible, processing: "/spinner.svg"
+    #       transformer: Crucible, async: true
     #   end
     #
     # Without this, the Registry only warms when view-side code calls

data/lib/active_storage/async_variants/registry.rb

@@ -7,7 +7,7 @@ module ActiveStorage
     # Process-wide lookup of async_options keyed by Variation#digest.
     #
     # Populated lazily by VariationExtension#initialize whenever a Variation is
-    # constructed with :transformer in its async_options -- which happens on
+    # constructed with :async in its async_options -- which happens on
     # every view-side `attachment.variant(:name)` call. The redirect controller
     # then resolves async_options by digest without scanning blob.attachments
     # for a transformations-match.

data/lib/active_storage/async_variants/variant_record_extension.rb

@@ -13,8 +13,8 @@ module ActiveStorage
 
       # processed and failed are terminal states: cache fragments built when
       # state was pending/processing need to be invalidated so the next
-      # render sees the new state (and serves the failed: fallback URL,
-      # swaps src to the direct CDN URL, etc.).
+      # render sees the new state (swaps the processing box for the failed
+      # error state, swaps src to the direct CDN URL, etc.).
       def reached_terminal_state?
         saved_change_to_state? && %w[processed failed].include?(state)
       end

data/lib/active_storage/async_variants/variant_with_record_extension.rb

@@ -27,15 +27,8 @@ module ActiveStorage
       end
 
       def url(...)
-        if blob.bucket_backed? && !processed?
-          fallback = active_fallback
-          case fallback
-          when :original then blob.url(...)
-          when :blank then nil
-          when Proc then fallback.call(blob)
-          when String then fallback
-          else super
-          end
+        if blob.bucket_backed? && async_variant? && !processed?
+          blob.url(...)
         else
           super
         end
@@ -82,8 +75,21 @@ module ActiveStorage
         async_record&.last_heartbeat_at
       end
 
+      # Percent-per-second observed so far (progress over elapsed processing
+      # time); drives the progress-bar's optimistic creep between reloads.
+      def progress_rate
+        record = async_record
+        return nil unless record&.created_at && record.last_heartbeat_at && record.progress&.positive?
+        elapsed = record.last_heartbeat_at - record.created_at
+        elapsed.positive? ? (record.progress / elapsed).round(4) : nil
+      end
+
       private
 
+      def async_variant?
+        resolved_async_options[:async].present?
+      end
+
       def resolved_async_options
         @resolved_async_options ||=
           variation.async_options.presence ||
@@ -92,14 +98,6 @@ module ActiveStorage
           {}
       end
 
-      def active_fallback
-        if failed?
-          resolved_async_options.fetch(:failed) { resolved_async_options[:processing] }
-        else
-          resolved_async_options[:processing]
-        end
-      end
-
       # Cold-path scan: used by enqueue! (which needs the attachment +
       # variant_name to dispatch ProcessJob) and by resolved_async_options as
       # a fallback when the Registry is cold (e.g. in dev, when a
@@ -126,7 +124,7 @@ module ActiveStorage
           attachment.send(:named_variants).each do |name, _|
             candidate = attachment.variant(name.to_sym)
             if candidate.variation.transformations.to_json == target
-              return [attachment, name, candidate.variation.async_options] if candidate.variation.async_options[:processing].present?
+              return [attachment, name, candidate.variation.async_options] if candidate.variation.async_options[:async]
             end
           end
         end

data/lib/active_storage/async_variants/variation_extension.rb

@@ -3,7 +3,7 @@
 module ActiveStorage
   module AsyncVariants
     module VariationExtension
-      ASYNC_KEYS = %i[processing failed transformer].freeze
+      ASYNC_KEYS = %i[async transformer].freeze
 
       def initialize(transformations)
         if transformations.is_a?(Hash)
@@ -13,7 +13,7 @@ module ActiveStorage
           @async_options = {}
           super
         end
-        ActiveStorage::AsyncVariants::Registry.register(digest, @async_options) if @async_options[:processing].present?
+        ActiveStorage::AsyncVariants::Registry.register(digest, @async_options) if @async_options[:async]
       end
 
       def async_options

data/lib/active_storage/async_variants/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveStorage
   module AsyncVariants
-    VERSION = "0.6.0"
+    VERSION = "0.8.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_storage-async_variants
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Micah Geisel
 bindir: exe
 cert_chain: []
-date: 2026-06-07 00:00:00.000000000 Z
+date: 2026-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activestorage
@@ -79,6 +79,7 @@ files:
 - app/views/active_storage/async_variants/states/show.html.erb
 - config/routes.rb
 - db/migrate/20260607000001_add_heartbeat_columns_to_variant_records.rb
+- db/migrate/20260608000001_add_created_at_to_variant_records.rb
 - features/retry_flow.feature
 - features/retry_visibility.feature
 - features/state_rendering.feature