active_storage-async_variants 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 003cbfe68ded6c238669546679e76b7d0c8e856842450181ceb8497a9e452361
-  data.tar.gz: 0b41dad0aa8a59e81e9b2e384d6d04e55ee479c0c35822d71e3a06a46b0c64cd
+  metadata.gz: f3d828692f86ff7b409b93f3198daae20c5c6821a0cce10da31b625abe7c04be
+  data.tar.gz: '0319ea7873525ea5d76a930e195687b3ba28bebd58922e3fc4aa821238241f28'
 SHA512:
-  metadata.gz: e5eb0728baf9f4d9cfc591625f6035d362d9df192c2c64fb7cef4e397fcef9817a460dbfba24210f01d777360a1d2e73e4dabf7d00306f8c9685ff1df4641b0e
-  data.tar.gz: 4c87c749a9dad93f251fcddf5830996f53d7c054becabdd529ea89000eb75e5f2360b6332aea764fc615931b0c350a15bfe8610d4b5efa1561a22ffd3d966ee6
+  metadata.gz: 9e80ebc6059bf84853cf7bf05d824ed5d25d5b195a4702d86495cdb29366eb02ee390558768fa66a1f5ea85e8e86987a46f9c7a2492de59e1a7287b25ef7074a
+  data.tar.gz: 23dc024c9a1ceaa334580d32af52f20e4e327f3d40d22e438616bdc0077f5b62f95deb50670ee5a30b3a1e72716e2ef9604bd6eabe2fc3a699aaa21142518ad8

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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`).
+
 ## [0.4.0]
 
 - **Breaking:** Replaced the polling-`<img>` architecture with a `<turbo-frame>` for unprocessed variants. `image_tag`/`video_tag` with `async: true` now emits a normal `<img>`/`<video>` when the variant is already processed, and a `<turbo-frame src="…">` otherwise. The frame hits a new gem-shipped endpoint (`GET /active_storage/async_variants/states/:signed_blob_id/:variation_key`) that renders one of `_processing`/`_failed`/`_processed` partials. Non-terminal renders include an inline `<script>` that schedules the frame's next reload, so the state polls itself until it terminates.

data/README.md

@@ -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).

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,269 @@
+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);
+  }
+
+  :host([error]) .progress-ring {
+    stroke: var(--error-color);
+  }
+
+  .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); }
+  }
+`;
+
+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>
+    </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/javascripts/retry.js

@@ -0,0 +1,11 @@
+// Declarative shadow roots are only attached by the initial HTML parser, not by
+// fragment insertion (innerHTML / Turbo frame swaps), so promote them on connect.
+customElements.define("async-variant-retry", class extends HTMLElement {
+  connectedCallback() {
+    if (this.shadowRoot) return
+    const template = this.querySelector(":scope > template[shadowrootmode]")
+    if (!template) return
+    this.attachShadow({ mode: template.getAttribute("shadowrootmode") }).append(template.content)
+    template.remove()
+  }
+})

data/app/assets/stylesheets/progress.css

@@ -0,0 +1,30 @@
+/* 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) {
+  display: block;
+}
+.async-variant-processing {
+  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. */
+.async-variant-processing img,
+.async-variant-processing 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);
+}

data/app/assets/stylesheets/retry.css

@@ -0,0 +1,98 @@
+/* Scoped to the retry dialog's shadow root (linked inside its <template>). */
+:host { display: contents; }
+
+button { font: inherit; cursor: pointer; }
+
+.opener {
+  position: absolute;
+  top: 6px; right: 6px;
+  width: 22px; height: 22px;
+  background: #2b7cd6;
+  color: #fff;
+  border: 2px solid #fff;
+  border-radius: 50%;
+  font-size: 13px;
+  font-weight: bold;
+  line-height: 1;
+  padding: 0;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.35);
+  display: var(--retry-opener-display, none);
+  align-items: center;
+  justify-content: center;
+}
+.opener:hover { background: #1a5fb0; }
+
+dialog {
+  width: 720px;
+  max-width: 90vw;
+  max-height: 80vh;
+  padding: 0;
+  border: 1px solid #999;
+  border-radius: 6px;
+  background: #fff;
+  color: #222;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
+  font: 13px/1.4 system-ui, -apple-system, sans-serif;
+}
+dialog[open] { display: flex; flex-direction: column; }
+dialog::backdrop { background: rgba(0, 0, 0, 0.5); }
+
+dialog > button {
+  position: absolute;
+  top: 10px;
+  right: 12px;
+  width: 32px; height: 32px;
+  background: transparent;
+  border: none;
+  color: #888;
+  font-size: 24px;
+  line-height: 1;
+  padding: 0;
+  border-radius: 4px;
+  z-index: 1;
+}
+dialog > button:hover { color: #000; background: rgba(0, 0, 0, 0.08); }
+
+header { padding: 20px 24px 0 24px; }
+header h3 {
+  margin: 0;
+  font-size: 16px;
+  font-weight: bold;
+  color: #111;
+  padding-right: 32px;
+}
+
+section {
+  flex: 1 1 auto;
+  overflow: auto;
+  padding: 12px 24px 20px 24px;
+  min-height: 0;
+}
+section pre {
+  background: #f5f5f5;
+  color: #222;
+  border: 1px solid #ddd;
+  padding: 8px;
+  font: 11px/1.4 ui-monospace, Menlo, monospace;
+  white-space: pre-wrap;
+  word-break: break-all;
+  margin: 0;
+}
+
+footer {
+  flex: 0 0 auto;
+  border-top: 1px solid #ddd;
+  padding: 12px 20px;
+  display: flex;
+  justify-content: flex-end;
+  background: #fafafa;
+}
+footer button {
+  padding: 8px 16px;
+  background: #2a7;
+  color: #fff;
+  border: none;
+  border-radius: 4px;
+  font-weight: bold;
+}
+footer button:disabled { opacity: 0.5; cursor: wait; }

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/controllers/active_storage/async_variants/states_controller.rb

@@ -16,6 +16,22 @@ module ActiveStorage
       def show
       end
 
+      def retry
+        @variant.blob.variant_records.where(
+          variation_digest: @variant.variation.digest,
+          state: "failed",
+        ).destroy_all
+        @variant.enqueue!
+
+        redirect_to Rails.application.routes.url_helpers.async_variant_state_path(
+          signed_blob_id: params[:signed_blob_id],
+          variation_key: params[:variation_key],
+          kind: params[:kind],
+          direct: params[:direct],
+          opts: async_variant_html_options.presence,
+        ), status: :see_other
+      end
+
       helper_method :async_variant_kind, :async_variant_direct?, :async_variant_html_options
 
       private

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

@@ -1,4 +1,43 @@
 <div class="async-variant-state async-variant-failed">
-  <% method = kind == :video ? :video_tag : :image_tag %>
-  <%= send method, async_variant_representation_path(variant), **html_options.symbolize_keys %>
+  <%= image_tag async_variant_representation_path(variant), **html_options.symbolize_keys.except(:controls, :autoplay, :preload) %>
+
+  <% 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:hover { --retry-opener-display: inline-flex; }
+    </style>
+    <%# In the light DOM so its submit reaches Turbo, and so preventDefault on the
+        buttons doesn't also cancel the submit. %>
+    <form action="<%= Rails.application.routes.url_helpers.async_variant_state_retry_path(signed_blob_id:, variation_key:, kind:, direct:, opts: html_options) %>"
+          method="post"
+          id="<%= form_id %>"
+          data-turbo-frame="<%= async_variant_frame_id(variant) %>"
+          hidden></form>
+    <async-variant-retry>
+      <template shadowrootmode="open">
+        <%= ActiveStorage::AsyncVariants.stylesheet_link_tag "retry" %>
+        <button class="opener" type="button"
+                onclick="event.preventDefault(); event.stopPropagation(); this.getRootNode().getElementById('<%= dialog_id %>').showModal()"
+                title="Variant processing failed — click for details">?</button>
+        <dialog id="<%= dialog_id %>">
+          <button type="button"
+                  onclick="event.preventDefault(); event.stopPropagation(); this.closest('dialog').close()">&times;</button>
+          <header><h3>Variant processing failed</h3></header>
+          <section><pre><%= variant.error %></pre></section>
+          <footer>
+            <button type="button"
+                    onclick="event.preventDefault(); event.stopPropagation(); this.disabled = true; this.textContent = 'Retrying…'; document.getElementById('<%= form_id %>').requestSubmit()">Retry processing</button>
+          </footer>
+        </dialog>
+      </template>
+    </async-variant-retry>
+    <%= ActiveStorage::AsyncVariants.javascript_include_tag "retry", type: "module" %>
+  <% end %>
 </div>

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

@@ -1,10 +1,16 @@
 <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 %>
+
+  <%= 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/app/views/active_storage/async_variants/states/show.html.erb

@@ -4,5 +4,7 @@
     html_options: async_variant_html_options,
     kind: async_variant_kind,
     direct: async_variant_direct?,
+    signed_blob_id: params[:signed_blob_id],
+    variation_key: params[:variation_key],
   } %>
 <% end %>

data/config/routes.rb

@@ -8,4 +8,9 @@ Rails.application.routes.draw do
   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
+
+  ActiveStorage::AsyncVariants::Assets.draw(self, "/active_storage/async_variants/assets")
 end

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/retry_flow.feature

@@ -0,0 +1,20 @@
+Feature: Clicking the retry affordance opens a dialog and resubmits the variant
+
+  Background:
+    Given a user with an attached avatar
+    And the retry affordance is visible to everyone
+
+  Scenario: Clicking the opener reveals the error inside the shadow-DOM dialog
+    Given the avatar's :thumb_proc variant is in failed state with error "boom from upstream"
+    When I visit the avatar page for the :thumb_proc variant
+    And I click the retry opener
+    Then the failure dialog should be open
+    And the failure dialog should contain "boom from upstream"
+
+  Scenario: Submitting Retry destroys the failed record and re-enqueues
+    Given the avatar's :thumb_proc variant is in failed state with error "boom"
+    When I visit the avatar page for the :thumb_proc variant
+    And I click the retry opener
+    And I click "Retry processing"
+    Then the frame should render the processing state
+    And the page should not have navigated away

data/features/retry_visibility.feature

@@ -0,0 +1,23 @@
+Feature: The retry affordance is gated by ActiveStorage::AsyncVariants.retry_visible_if
+
+  Scenario: When retry_visible_if returns true, the retry chrome renders
+    Given a user with an attached avatar
+    And the retry affordance is visible to everyone
+    And the avatar's :thumb_proc variant is in failed state with error "boom"
+    When I visit the avatar page for the :thumb_proc variant
+    Then the retry affordance should be visible
+
+  Scenario: When retry_visible_if returns false, the retry chrome is omitted
+    Given a user with an attached avatar
+    And the retry affordance is hidden
+    And the avatar's :thumb_proc variant is in failed state with error "boom"
+    When I visit the avatar page for the :thumb_proc variant
+    Then the retry affordance should NOT be visible
+
+  Scenario: A proc that consults current_user gates the affordance per-viewer
+    Given a user with an attached avatar
+    And the retry affordance requires a signed-in user
+    And the avatar's :thumb_proc variant is in failed state with error "boom"
+    When I sign in as the user
+    And I visit the avatar page for the :thumb_proc variant
+    Then the retry affordance should be visible

data/features/state_rendering.feature

@@ -13,8 +13,26 @@ 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
     And the avatar's :thumb_proc variant is in failed state with error "boom"
     When I visit the avatar page for the :thumb_proc variant
     Then the page should contain a turbo-frame

data/features/step_definitions/dummy_steps.rb

@@ -14,6 +14,30 @@ 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 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/gemfiles/rails_7.2.gemfile

@@ -10,5 +10,9 @@ 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,5 +10,9 @@ 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,5 +10,9 @@ 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/asset_tag_helper_extension.rb

@@ -33,10 +33,7 @@ module ActiveStorage
         assert_async_variant!(variant)
 
         if async && !async_variant_processed_inline?(variant)
-          async_variant_turbo_frame(variant, kind:, direct:, html_options: options) do
-            # populate TurboFrame with a placeholder image/video, so there's valid markup right away
-            yield [async_variant_representation_path(variant), *rest], options.except(:data)
-          end
+          async_variant_turbo_frame(variant, kind:, direct:, html_options: options)
         else
           yield [async_variant_resolved_src(variant, direct:), *rest], options
         end
@@ -48,13 +45,13 @@ module ActiveStorage
         end
       end
 
-      def async_variant_turbo_frame(variant, kind:, direct:, html_options:, &block)
+      def async_variant_turbo_frame(variant, kind:, direct:, html_options:)
         content_tag(
           :"turbo-frame",
+          "",
           id: async_variant_frame_id(variant),
           src: async_variant_frame_src(variant, kind: kind, direct: direct, html_options: html_options),
           refresh: "morph",
-          &block
         )
       end
     end

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/preview_extension.rb

@@ -52,6 +52,18 @@ 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?

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/variant_with_record_extension.rb

@@ -70,6 +70,18 @@ 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 resolved_async_options

data/lib/active_storage/async_variants/version.rb

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

data/lib/active_storage/async_variants.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "turbo-rails"
+require "isolate_assets"
 require_relative "async_variants/version"
 require_relative "async_variants/helper"
 require_relative "async_variants/transformer"
@@ -13,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
@@ -22,12 +24,36 @@ module ActiveStorage
     PASS_THROUGH_HTML_OPTIONS = %i[alt width height controls autoplay preload].freeze
 
     mattr_accessor :cdn_host
+    mattr_accessor :retry_visible_proc, default: ->(_view) { false }
 
     # Lets the host app plug its auth chain (and thus `current_user`) into the
     # gem's StatesController. Set to a string so resolution is deferred until
     # 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
+    end
+
+    def self.retry_visible?(view)
+      !!view.instance_exec(&retry_visible_proc)
+    rescue StandardError
+      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
@@ -79,6 +105,8 @@ module ActiveStorage
       )
     end
 
+    Assets = IsolateAssets.register(namespace: self, engine: Engine, route_name: :async_variant_asset)
+
     def self.callback_token_for(variant_record)
       ActiveStorage.verifier.generate(variant_record.id, purpose: :async_variant_callback)
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_storage-async_variants
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Micah Geisel
 bindir: exe
 cert_chain: []
-date: 2026-06-06 00:00:00.000000000 Z
+date: 2026-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activestorage
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: isolate_assets
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
 email:
 - micah@botandrose.com
 executables: []
@@ -52,6 +66,10 @@ 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
 - app/views/active_storage/async_variants/states/_failed.html.erb
@@ -60,6 +78,9 @@ 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
 - features/step_definitions/dummy_steps.rb
 - features/support/env.rb
@@ -70,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