active_storage-async_variants 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc926d64601c238db11edd005f220c0842cbf4316f405d43c23d08a99ff874de
-  data.tar.gz: 177a3d4a3647e41ac5e23db1908265c556a8c4c006b5497cbb802b2cf9ebb02e
+  metadata.gz: 259c11526314988d60e78e9e176dc16105c6aeb578b1774693a666fc1e277a21
+  data.tar.gz: 92fc3546ed708ed709ad4fedc2d7e6258d765719fad75571844671a902f1b485
 SHA512:
-  metadata.gz: 25f4d2430ce2547c9a4109bd648f338914e92cacdb38bf2e651cdfff21a9a045e90480c10e6170f0723dbcb5e675a35370cda7c91ced43ec41c5bfa3f112f2a1
-  data.tar.gz: c02fac50058fd3465435bf194e09ffb0732deda2c61316b8e960b1179e4ee8e9eb417e1dd192fdf564c0e059d87a674fe76aa852f99a385592ddfcd71fb1a453
+  metadata.gz: ebfe0839de2603c91a5705f3942b30b3db7685d20ce5d3d2425f98472a191d559ac9103bab5a59972e09f18385b8829283fe0323f2de4810e8619cb57e028ab2
+  data.tar.gz: 165f5796f098a3f40194a9d893ba07b98bd7b3a7ac8601fda744f5dcb1e4a98c0d69e1514e788f612ea8fa1dbf4bca6c44cbb7ee5ef072fcf5fa13fe03ce5b56

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [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.
+- Processing variants render a progress bar — indeterminate until progress is reported, then a determinate percentage — served as a cached asset. The turbo-frame poll interval now follows `heartbeat_interval` (default 5s) so each refresh lands on fresh progress.
+- A stalled external transform (no heartbeat within `heartbeat_stale_after`, default 60s) is now marked failed automatically — and therefore retryable — instead of hanging in "processing" forever.
+- Added an `ActiveStorage::AsyncVariants.configure { |config| … }` block for setting all options in one place (see the README's Configuration section).
+- Includes a migration adding the `progress` and `last_heartbeat_at` columns; run it before deploying.
+
 ## [0.5.0]
 
 - Added an opt-in retry affordance to the failed state: hovering a failed variant reveals a control that opens a dialog with the error and a "Retry processing" button that re-runs the transform. Disabled by default; enable it with `ActiveStorage::AsyncVariants.retry_visible_if { … }` (the block runs in the view context, so it can check `current_user`).

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 %>
 
@@ -101,6 +101,29 @@ The resulting URL is `"#{cdn_host}/#{variant.key}"`.
 
 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.
 
+## Configuration
+
+Set options in an initializer. The `configure` block groups them (each is also a plain accessor, e.g. `ActiveStorage::AsyncVariants.cdn_host = …`):
+
+```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_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
 
 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).
@@ -204,31 +227,9 @@ variant.failed?      # => true if permanently failed
 variant.error        # => error message string, or nil
 ```
 
-## Placeholder Options
-
-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"
-```
+## Placeholders
 
-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
 
@@ -253,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
 
@@ -261,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/Rakefile

@@ -13,4 +13,15 @@ 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

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

@@ -0,0 +1,281 @@
+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 STYLES = `
+  :host {
+    --progress-color: #2E7D32;
+    --error-color: #7a242f;
+    --indeterminate-color: #999;
+    --track-color: #333333;
+    --progress-duration: 120ms;
+    --indeterminate-duration: 1.5s;
+    --bar-height: 32px;
+    --bar-padding: 8px;
+    --circular-size: 64px;
+    --circular-thickness: 16;
+    display: block;
+    overflow: hidden;
+    background: var(--track-color);
+    border: 1px solid #999;
+    border-radius: 4px;
+    min-height: var(--bar-height);
+    padding: var(--bar-padding);
+    font-size: 13px;
+    align-content: center;
+    box-sizing: border-box;
+    position: relative;
+  }
+  .bar {
+    position: absolute;
+    top: 0;
+    left: 0;
+    height: 100%;
+    width: 0%;
+    background: var(--progress-color);
+    transition: width var(--progress-duration) ease;
+    z-index: 1;
+  }
+  .text{position: relative; z-index: 2;}
+  :host([error]) .bar {
+    background: var(--error-color);
+  }
+
+  /* Indeterminate (linear): no percent set — a fixed-width segment sweeping across the track. */
+  :host(:not([percent])) .bar {
+    background: var(--indeterminate-color);
+    width: 40%;
+    animation: indeterminate-linear var(--indeterminate-duration) infinite linear;
+  }
+
+  @keyframes indeterminate-linear {
+    0%   { transform: translateX(-100%); }
+    100% { transform: translateX(250%); }
+  }
+
+  /* Circular mode: the host box styling is for the linear track, so drop it. */
+  :host([mode="circular"]) {
+    background: transparent;
+    border: none;
+    overflow: visible;
+    padding: 0;
+    min-height: 0;
+  }
+
+  .circular {
+    position: relative;
+    display: inline-flex;
+    width: var(--circular-size);
+    height: var(--circular-size);
+  }
+
+  .ring {
+    width: 100%;
+    height: 100%;
+    transform: rotate(-90deg);
+  }
+
+  .ring circle {
+    fill: none;
+    stroke-width: var(--circular-thickness);
+    /* Shrink the radius so the stroke's outer edge always lands inside the
+       100x100 viewBox, no matter how thick --circular-thickness is. */
+    r: calc(49px - var(--circular-thickness) * 0.5px);
+  }
+
+  .track {
+    stroke: var(--track-color);
+  }
+
+  .progress-ring {
+    stroke: var(--progress-color);
+    stroke-linecap: round;
+    stroke-dasharray: ${PATH_LENGTH};
+    stroke-dashoffset: ${PATH_LENGTH};
+    transition: stroke-dashoffset var(--progress-duration) ease;
+  }
+
+  :host(:not([percent])) .progress-ring {
+    stroke: var(--indeterminate-color);
+  }
+
+  /* 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 {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: #fff;
+    mix-blend-mode: difference;
+  }
+
+  /* When the host carries its own inline styling (e.g. a color override), opt
+     out of the blend trick and just inherit, so the override wins predictably. */
+  :host([style]) .label {
+    mix-blend-mode: initial;
+    color: inherit;
+  }
+
+  /* Indeterminate (circular): no percent set — spin a fixed arc around the ring. */
+  :host(:not([percent])) .ring {
+    animation: indeterminate-rotate var(--indeterminate-duration) infinite linear;
+  }
+
+  :host(:not([percent])) .progress-ring {
+    stroke-dashoffset: ${PATH_LENGTH * 0.75};
+  }
+
+  @keyframes indeterminate-rotate {
+    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 = `
+  <div class="bar"></div>
+  <div class="text"><slot></slot></div>
+`;
+
+const CIRCULAR_HTML = `
+  <div class="circular">
+    <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>
+`;
+
+let styleSheet = null;
+function getStyleSheet() {
+  if (!styleSheet) {
+    styleSheet = new CSSStyleSheet();
+    styleSheet.replaceSync(STYLES);
+  }
+  return styleSheet;
+}
+
+function clampPercent(value) {
+  const number = Number(value);
+  if (Number.isNaN(number)) {
+    throw new TypeError(`progress-bar: percent must be numeric, got ${JSON.stringify(value)}`);
+  }
+  return Math.min(100, Math.max(0, number));
+}
+
+class ProgressBar extends HTMLElement {
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    this._percent = null;
+    this._renderedMode = null;
+  }
+
+  connectedCallback() {
+    this.render();
+    this.setAttribute('role', 'progressbar');
+    this.setAttribute('aria-valuemin', '0');
+    this.setAttribute('aria-valuemax', '100');
+    this.updateBar();
+  }
+
+  get percent() {
+    return this._percent;
+  }
+
+  set percent(value) {
+    if (value === null || value === undefined) {
+      this.removeAttribute('percent');
+    } else {
+      this.setAttribute('percent', clampPercent(value));
+    }
+  }
+
+  get error() {
+    return this.hasAttribute('error');
+  }
+
+  set error(value) {
+    this.toggleAttribute('error', Boolean(value));
+  }
+
+  get indeterminate() {
+    return !this.hasAttribute('percent');
+  }
+
+  get mode() {
+    return this.getAttribute('mode') === 'circular' ? 'circular' : 'linear';
+  }
+
+  set mode(value) {
+    this.setAttribute('mode', value);
+  }
+
+  static get observedAttributes() {
+    return ['percent', 'mode'];
+  }
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (name === 'percent') {
+      this._percent = newValue === null ? null : clampPercent(newValue);
+    }
+    if (name === 'mode') {
+      this.render();
+    }
+    this.updateBar();
+  }
+
+  updateBar() {
+    if (this.mode === 'circular') {
+      const ring = this.shadowRoot?.querySelector('.progress-ring');
+      if (ring) {
+        ring.style.strokeDashoffset = this.indeterminate
+          ? ''
+          : String(PATH_LENGTH * (1 - this._percent / 100));
+      }
+    } else {
+      const bar = this.shadowRoot?.querySelector('.bar');
+      if (bar) {
+        // Leave width to the indeterminate CSS animation when unknown.
+        bar.style.width = this.indeterminate ? '' : `${this._percent}%`;
+      }
+    }
+
+    if (this.indeterminate) {
+      this.removeAttribute('aria-valuenow');
+    } else {
+      this.setAttribute('aria-valuenow', String(this._percent));
+    }
+  }
+
+  render() {
+    const mode = this.mode;
+    if (this._renderedMode === mode) {
+      return;
+    }
+    this._renderedMode = mode;
+    this.shadowRoot.adoptedStyleSheets = [getStyleSheet()];
+    this.shadowRoot.innerHTML = mode === 'circular' ? CIRCULAR_HTML : LINEAR_HTML;
+  }
+}
+
+if (!customElements.get('progress-bar')) {
+  customElements.define('progress-bar', ProgressBar);
+}
+
+export default ProgressBar;

data/app/assets/stylesheets/progress.css

@@ -0,0 +1,35 @@
+/* turbo-frame is inline by default; make it and the wrapper block-level so the
+   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-failed) {
+  display: block;
+}
+.async-variant-processing,
+.async-variant-failed {
+  position: relative;
+  display: block;
+}
+/* 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-failed img,
+.async-variant-failed video {
+  opacity: 0.001;
+  display: block;
+}
+.async-variant-progress {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  --circular-size: 80px;
+  --progress-color: #2E7D32;
+  --indeterminate-color: #2E7D32;
+  --track-color: rgba(0, 0, 0, 0.25);
+  --error-color: #ff7c81;
+}

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

@@ -11,6 +11,10 @@ module ActiveStorage
         when "success"
           variant_record.update!(state: "processed")
           apply_reported_metadata(variant_record, params)
+        when "progress"
+          ActiveStorage::VariantRecord
+            .where(id: variant_record.id, state: %w[pending processing])
+            .update_all(progress: params[:percent].to_i.clamp(0, 100), last_heartbeat_at: Time.current)
         when "failed"
           # 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))

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,9 +1,15 @@
 <div class="async-variant-state async-variant-processing">
-  <%= 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", class: "async-variant-progress", percent: variant.progress %>
 </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. %>
+
+<%= ActiveStorage::AsyncVariants.stylesheet_link_tag "progress" %>
+<%= ActiveStorage::AsyncVariants.javascript_include_tag "progress-bar", type: "module" %>
+<% interval_ms = ActiveStorage::AsyncVariants.heartbeat_interval.in_seconds * 1000 %>
 <script>
-  setTimeout(() => document.getElementById("<%= async_variant_frame_id(variant) %>")?.reload(), 3000)
+  (() => {
+    const frame = document.currentScript?.closest("turbo-frame")
+    setTimeout(() => frame?.reload(), <%= interval_ms %>)
+  })()
 </script>

data/db/migrate/20260607000001_add_heartbeat_columns_to_variant_records.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class AddHeartbeatColumnsToVariantRecords < ActiveRecord::Migration[7.2]
+  def change
+    add_column :active_storage_variant_records, :progress, :integer, if_not_exists: true
+    add_column :active_storage_variant_records, :last_heartbeat_at, :datetime, if_not_exists: true
+  end
+end

data/features/state_rendering.feature

@@ -13,6 +13,23 @@ Feature: image_tag with async: true emits the right markup per variant state
     Then the page should contain a turbo-frame
     And the frame should render the processing state
 
+  Scenario: A processing variant renders an indeterminate progress bar before any heartbeat
+    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 a progress bar
+    And the progress bar should be indeterminate
+    And the placeholder image should reserve layout
+
+  Scenario: A processing variant with reported progress renders a determinate progress bar
+    Given a user with an attached avatar
+    And the avatar's :thumb_proc variant is in processing state
+    And the avatar's :thumb_proc variant has reported 42% progress
+    When I visit the avatar page for the :thumb_proc variant
+    Then the page should contain a turbo-frame
+    And the progress bar should show 42%
+
   Scenario: A failed variant renders the failed partial inside the frame
     Given a user with an attached avatar
     And the retry affordance is visible to everyone
@@ -20,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

@@ -14,6 +14,34 @@ Given /^the avatar's :(\w+) variant is in (pending|processing|processed|failed)
   end
 end
 
+Given /^the avatar's :(\w+) variant has reported (\d+)% progress$/ do |variant_name, percent|
+  variant = @user.avatar.variant(variant_name.to_sym)
+  record = variant.blob.variant_records.find_by(variation_digest: variant.variation.digest)
+  record.update!(progress: percent.to_i)
+end
+
+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
+
+Then /^the progress bar should show (\d+)%$/ do |percent|
+  expect(page).to have_css(%(turbo-frame progress-bar[percent="#{percent}"]), visible: :all)
+end
+
+# Default (visible-only) matcher: passes only because the placeholder is hidden
+# via opacity (not visibility/display), so Capybara still sees it.
+Then /^the placeholder image should reserve layout$/ do
+  expect(page).to have_css("turbo-frame .async-variant-processing img")
+end
+
 Given /^the retry affordance is visible to everyone$/ do
   ActiveStorage::AsyncVariants.retry_visible_if { true }
 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/heartbeat_watchdog_job.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    # External transforms free the worker at `initiate` and report progress via
+    # heartbeats; if the service dies, no terminal callback arrives and the
+    # record would sit in "processing" forever. This flips it to "failed" once
+    # the heartbeats go stale, re-arming itself each tick until then.
+    class HeartbeatWatchdogJob < ActiveJob::Base
+      # A retry destroys the record, so a re-armed job has nothing left to watch.
+      discard_on ActiveJob::DeserializationError
+
+      def perform(variant_record)
+        stale_after = ActiveStorage::AsyncVariants.heartbeat_stale_after
+        active = ActiveStorage::VariantRecord.where(id: variant_record.id, state: %w[pending processing])
+        stale = active.where("last_heartbeat_at < ?", Time.current - stale_after)
+
+        # Atomic check-and-set: a success/progress callback landing in the same
+        # instant moves the row out of `stale` and wins, instead of being clobbered.
+        marked_failed_count = stale.update_all(
+          state: "failed",
+          error: "Transcoding stalled: no heartbeat for over #{stale_after.to_i}s",
+        )
+
+        if marked_failed_count.positive?
+          touch_consumers(variant_record)
+        elsif active.any?
+          self.class.set(wait: stale_after).perform_later(variant_record)
+        end
+      end
+
+      private
+
+      # update_all skips the terminal-state touch, so invalidate consumer caches by hand.
+      def touch_consumers(variant_record)
+        variant_record.blob.attachments.includes(:record).each { |a| a.record&.touch }
+      end
+    end
+  end
+end

data/lib/active_storage/async_variants/helper.rb

@@ -7,6 +7,25 @@ module ActiveStorage
     # `helper ActiveStorage::AsyncVariants::Helper` (so the state partials can
     # use them).
     module Helper
+      # 1x1 transparent GIF: reserves the variant's box without fetching the
+      # original through the representations path on every poll.
+      PLACEHOLDER_SRC = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
+
+      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))
+        # A video placeholder carries no <source>, so it reserves the box
+        # without loading anything -- same zero-network intent as the GIF.
+        kind == :video ? content_tag(:video, "", opts) : image_tag(PLACEHOLDER_SRC, opts)
+      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

@@ -52,18 +52,30 @@ module ActiveStorage
         find_preview_variant_record&.state || "pending"
       end
 
+      def progress
+        find_preview_variant_record&.progress
+      end
+
+      def progress_known?
+        !find_preview_variant_record&.progress.nil?
+      end
+
+      def last_heartbeat_at
+        find_preview_variant_record&.last_heartbeat_at
+      end
+
       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 ||
@@ -78,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
@@ -95,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/process_job.rb

@@ -79,6 +79,13 @@ module ActiveStorage
           variant_record_id: variant_record.id,
           **options,
         )
+
+        # Seed the heartbeat so a transform that dies before its first heartbeat
+        # still goes stale, then arm the watchdog.
+        variant_record.touch(:last_heartbeat_at)
+        ActiveStorage::AsyncVariants::HeartbeatWatchdogJob
+          .set(wait: ActiveStorage::AsyncVariants.heartbeat_stale_after)
+          .perform_later(variant_record)
       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
@@ -70,8 +63,24 @@ module ActiveStorage
         async_record&.state || "pending"
       end
 
+      def progress
+        async_record&.progress
+      end
+
+      def progress_known?
+        !async_record&.progress.nil?
+      end
+
+      def last_heartbeat_at
+        async_record&.last_heartbeat_at
+      end
+
       private
 
+      def async_variant?
+        resolved_async_options[:async].present?
+      end
+
       def resolved_async_options
         @resolved_async_options ||=
           variation.async_options.presence ||
@@ -80,14 +89,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
@@ -114,7 +115,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.5.0"
+    VERSION = "0.7.0"
   end
 end

data/lib/active_storage/async_variants.rb

@@ -14,6 +14,7 @@ require_relative "async_variants/preview_extension"
 require_relative "async_variants/attachment_extension"
 require_relative "async_variants/reflection_extension"
 require_relative "async_variants/process_job"
+require_relative "async_variants/heartbeat_watchdog_job"
 require_relative "async_variants/asset_tag_helper_extension"
 
 module ActiveStorage
@@ -30,6 +31,14 @@ module ActiveStorage
     # the host's class is autoloadable. Defaults to ActionController::Base.
     mattr_accessor :parent_controller, default: "ActionController::Base"
 
+    # How long an external transform may go without a heartbeat before the
+    # watchdog fails it. Must exceed the transformer's heartbeat interval.
+    mattr_accessor :heartbeat_stale_after, default: 60.seconds
+
+    # The transformer's heartbeat cadence. The turbo-frame poll matches it so
+    # each reload lands on fresh progress; keep heartbeat_stale_after well above it.
+    mattr_accessor :heartbeat_interval, default: 5.seconds
+
     # Gates the failed-state retry affordance; the block runs in the view context.
     def self.retry_visible_if(&block)
       self.retry_visible_proc = block
@@ -41,6 +50,10 @@ module ActiveStorage
       false
     end
 
+    def self.configure
+      yield self
+    end
+
     class Engine < ::Rails::Engine
       # Prepend the core model/reflection extensions before eager_load runs
       # so that models' has_X_attached blocks (and the Variation.wrap calls

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_storage-async_variants
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.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
@@ -66,7 +66,9 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- app/assets/javascripts/progress-bar.js
 - app/assets/javascripts/retry.js
+- app/assets/stylesheets/progress.css
 - app/assets/stylesheets/retry.css
 - app/controllers/active_storage/async_variants/callbacks_controller.rb
 - app/controllers/active_storage/async_variants/states_controller.rb
@@ -76,6 +78,7 @@ files:
 - app/views/active_storage/async_variants/states/_processing.html.erb
 - app/views/active_storage/async_variants/states/show.html.erb
 - config/routes.rb
+- db/migrate/20260607000001_add_heartbeat_columns_to_variant_records.rb
 - features/retry_flow.feature
 - features/retry_visibility.feature
 - features/state_rendering.feature
@@ -88,6 +91,7 @@ files:
 - lib/active_storage/async_variants/asset_tag_helper_extension.rb
 - lib/active_storage/async_variants/attachment_extension.rb
 - lib/active_storage/async_variants/blob_extension.rb
+- lib/active_storage/async_variants/heartbeat_watchdog_job.rb
 - lib/active_storage/async_variants/helper.rb
 - lib/active_storage/async_variants/preview_extension.rb
 - lib/active_storage/async_variants/process_job.rb