plutonium 0.60.5 → 0.61.0

data/lib/plutonium/ui/wizard/review.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module UI
+    module Wizard
+      # The terminal review step's body (§2.5), a small state machine (see
+      # {#render_mode}):
+      #
+      #   - INCOMPLETE (a visible step is unvisited/invalid) → a "fix this" jump
+      #     link per outstanding step + an auto-summary of what's entered so far.
+      #   - COMPLETE + custom block → the author's block, rendered bare.
+      #   - COMPLETE + no block, `summary: true` (default) → the auto-summary of
+      #     every visible step's collected `data` (via SummaryDisplay).
+      #   - COMPLETE + no block, `summary: false` → the built-in "ready to
+      #     complete" panel (for a fully author-owned / chromeless review).
+      #
+      # The Finish button is rendered by the page (gated: disabled while any
+      # visible step is incomplete); this component only renders the body.
+      class Review < Plutonium::UI::Component::Base
+        # @param runner  [Plutonium::Wizard::Runner]
+        # @param step_url [Proc] step_key → GET url, for the fix-this links.
+        def initialize(runner:, step_url:)
+          @runner = runner
+          @step_url = step_url
+        end
+
+        def view_template
+          render_outstanding if show_outstanding?
+          render_summary if show_summary?
+          render_custom_block if show_custom?
+          render_ready if show_ready?
+        end
+
+        private
+
+        # The review body composes from these pieces (see the `review summary:`
+        # macro). Order of render: outstanding → summary → custom → ready.
+        #
+        #   - outstanding banner — while any visible step is incomplete.
+        #   - summary cards      — whenever the auto-summary is on: the
+        #     review-and-fix view when incomplete, the check-before-finish view
+        #     when complete.
+        #   - custom block       — author content, ONLY once complete; sits BELOW
+        #     the summary when summary is on, and REPLACES it when summary is off.
+        #   - ready panel        — complete + summary off + no custom block: the
+        #     built-in "ready to complete" confirmation (chromeless finish).
+        def show_outstanding? = !complete?
+
+        def show_summary? = summary?
+
+        def show_custom? = complete? && !custom_block.nil?
+
+        def show_ready? = complete? && !summary? && custom_block.nil?
+
+        def complete? = @runner.incomplete_visible_steps.empty?
+
+        def summary? = @runner.current_step.summary?
+
+        def custom_block = @runner.current_step.block
+
+        def steps = @runner.visible_path.reject(&:review?)
+
+        # The step's typed `data` sub-object (`data.<step>`), the summary's source.
+        def step_data(step) = @runner.wizard.data[step.key]
+
+        def render_outstanding
+          incomplete = @runner.incomplete_visible_steps
+          return if incomplete.empty?
+
+          div(class: "pu-wizard-review-outstanding rounded-lg border border-warning-300 bg-warning-50 dark:border-warning-800 dark:bg-warning-950/30 p-4 mb-6", role: "alert") do
+            p(class: "text-sm font-medium text-[var(--pu-text)] mb-2") do
+              "Some steps still need attention before you can finish:"
+            end
+            ul(class: "space-y-1") do
+              incomplete.each do |step|
+                li do
+                  a(
+                    href: @step_url.call(step.key),
+                    class: "text-sm font-medium text-primary-600 dark:text-primary-400 hover:underline",
+                    data: {wizard_review_fix: step.key}
+                  ) { "Fix #{step.label}" }
+                end
+              end
+            end
+          end
+        end
+
+        def render_summary
+          div(class: "space-y-4") do
+            steps.each do |step|
+              fields = summary_fields(step)
+              structured = step.structured_inputs
+              next if fields.empty? && structured.empty?
+
+              render_step_card(step, fields, structured)
+            end
+          end
+        end
+
+        # One step rendered as a card: a titled header strip (label + Edit) over a
+        # body that holds the scalar summary and any structured collections.
+        def render_step_card(step, fields, structured)
+          section(
+            class: "pu-wizard-review-step overflow-hidden rounded-[var(--pu-radius-lg)] border border-[var(--pu-border)] bg-[var(--pu-surface)] shadow-[var(--pu-shadow-sm)]",
+            data: {wizard_review_step: step.key}
+          ) do
+            div(class: "flex items-center justify-between gap-3 border-b border-[var(--pu-border)] bg-[var(--pu-surface-alt)] px-5 py-3") do
+              h3(class: "text-sm font-semibold text-[var(--pu-text)]") { step.label.to_s }
+              a(
+                href: @step_url.call(step.key),
+                class: "shrink-0 text-xs font-medium text-primary-600 dark:text-primary-400 hover:underline"
+              ) { "Edit" }
+            end
+            div(class: "px-5 py-4") do
+              # Decorate so attachment fields resolve to displayable attachments —
+              # the SummaryDisplay then renders them through the normal attachment
+              # display component, not the raw token string.
+              if fields.any?
+                render SummaryDisplay.new(
+                  Plutonium::Wizard::AttachmentData.wrap(step_data(step), step),
+                  fields:, inputs: step.inputs
+                )
+              end
+              render_structured(step) if structured.any?
+            end
+          end
+        end
+
+        def summary_fields(step)
+          step.attribute_schema.keys.map(&:to_sym)
+        end
+
+        # Repeatable `structured_input` collections aren't scalar `data` attributes,
+        # so the SummaryDisplay can't render them — summarise each collection as a
+        # labelled list of its non-empty rows (blank trailing rows are dropped).
+        def render_structured(step)
+          data = step_data(step)
+          step.structured_inputs.each_key do |name|
+            rows = Array(data.public_send(name))
+              .map(&:to_h)
+              .reject { |row| row.values.all?(&:blank?) }
+
+            div(class: "pu-wizard-review-collection mt-4 first:mt-0", data: {wizard_review_collection: name}) do
+              h4(class: "mb-2 text-xs font-semibold uppercase tracking-wide text-[var(--pu-text-muted)]") do
+                name.to_s.humanize
+              end
+              if rows.empty?
+                p(class: "text-sm text-[var(--pu-text-subtle)]") { "None" }
+              else
+                ul(class: "space-y-1.5") do
+                  rows.each do |row|
+                    li(class: "flex flex-wrap items-center gap-x-2 gap-y-0.5 rounded-[var(--pu-radius-md)] bg-[var(--pu-surface-alt)] px-3 py-2 text-sm text-[var(--pu-text)]") do
+                      row.each do |key, value|
+                        span do
+                          span(class: "text-[var(--pu-text-muted)]") { "#{key.to_s.humanize}: " }
+                          plain value.to_s
+                        end
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+
+        # The review step's custom block, rendered BARE — just a spacing + targeting
+        # wrapper, no surface/border/typography of its own — so the author has full
+        # control over the body's look.
+        def render_custom_block
+          div(class: "pu-wizard-review-custom", data: {wizard_review_custom: true}) do
+            instance_exec(@runner.wizard, &custom_block)
+          end
+        end
+
+        # The built-in "ready to complete" panel: shown when everything is valid,
+        # there's no custom block, and the auto-summary is turned off (`summary:
+        # false`). A clean confirmation so a chromeless review still reads as done.
+        def render_ready
+          div(
+            class: "pu-wizard-review-ready flex flex-col items-center text-center py-6",
+            data: {wizard_review_ready: true}
+          ) do
+            div(class: "mb-4 flex h-14 w-14 items-center justify-center rounded-full bg-success-100 text-success-600 dark:bg-success-900/30 dark:text-success-400") do
+              render Phlex::TablerIcons::Check.new(class: "h-7 w-7")
+            end
+            h3(class: "text-lg font-semibold tracking-tight text-[var(--pu-text)]") { "You're all set" }
+            p(class: "mt-1.5 max-w-prose text-sm text-[var(--pu-text-muted)]") do
+              "Everything looks good. Click Finish to complete."
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/ui/wizard/stepper.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module UI
+    module Wizard
+      # The horizontal step indicator (§7). Renders the visible step path with a
+      # completed / current / upcoming state per step. Navigation mode gates which
+      # steps are clickable:
+      #
+      #   - :linear → only already-visited steps link back (no forward jumps).
+      #   - :free   → any visited step links (still no forward jumps to unvisited).
+      #
+      # Branch-hidden steps are simply absent from `visible_path`, so they never
+      # appear here.
+      class Stepper < Plutonium::UI::Component::Base
+        # @param steps     [Array<Step>] the visible path.
+        # @param current   [Step] the current step.
+        # @param visited   [Array<String>] visited (reached) step keys.
+        # @param complete  [Array<String>] keys of steps that are actually complete
+        #   (submitted AND valid) — distinct from `visited`. A step can be reached
+        #   (e.g. the cursor landed on a branch step) without being completed.
+        # @param navigation [Symbol] :linear or :free.
+        # @param step_url   [Proc] step_key → GET url.
+        def initialize(steps:, current:, visited:, navigation:, step_url:, complete: [])
+          @steps = steps
+          @current = current
+          @visited = visited.map(&:to_s)
+          @complete = complete.map(&:to_s).to_set
+          @navigation = navigation
+          @step_url = step_url
+        end
+
+        def view_template
+          nav(class: "pu-wizard-stepper mb-7", aria_label: "Progress") do
+            ol(class: "pu-wizard-steps") do
+              @steps.each_with_index do |step, index|
+                render_step(step, index)
+              end
+            end
+          end
+        end
+
+        private
+
+        # One step: a numbered node on the connector track + a label beneath. Both
+        # are wrapped in a link when the step is reachable (CSS draws the track,
+        # node states, and the done check via [data-state]).
+        def render_step(step, index)
+          state = step_state(step)
+          # `data-terminal` marks the review node so the CSS suppresses the
+          # "completed" checkmark for it — it's the finish flag, never a done-check.
+          li(data: {state:, wizard_stepper_state: state, terminal: step.review? ? "true" : nil}) do
+            if clickable?(step, state)
+              a(href: @step_url.call(step.key), class: "pu-step-link",
+                aria_current: (state == :current) ? "step" : nil) do
+                render_node(step, index)
+                span(class: "pu-step-label") { step.label.to_s }
+              end
+            else
+              span(class: "pu-step-link") do
+                render_node(step, index)
+                span(class: "pu-step-label",
+                  aria_current: (state == :current) ? "step" : nil) { step.label.to_s }
+              end
+            end
+          end
+        end
+
+        # The node: a numbered badge for a real step. The terminal review step isn't
+        # a numbered step (it's the "finish line"), so it shows a flag icon instead —
+        # no step number, here or in the card header (see Page::Wizard).
+        def render_node(step, index)
+          span(class: "pu-step-node") do
+            if step.review?
+              render_review_icon
+            else
+              # Review is always last, so a real step's index in the full path is
+              # also its position among real steps → a clean 1-based badge.
+              span(class: "pu-step-number") { (index + 1).to_s }
+            end
+          end
+        end
+
+        def render_review_icon
+          render Phlex::TablerIcons::Flag.new(class: "pu-step-flag w-4 h-4")
+        end
+
+        # A step's visual state. `:completed` (the done-check) means actually
+        # complete — submitted AND valid — NOT merely reached: a branch step the
+        # cursor landed on but that was never submitted (or is now invalid) is
+        # `:incomplete`, so the rail never claims a step is done when the review
+        # still lists it under "needs attention". The terminal review node is the
+        # finish flag, so it reads `:completed` once reached (its check is suppressed
+        # by `data-terminal`).
+        def step_state(step)
+          return :current if step.key.to_s == @current&.key.to_s
+          if @visited.include?(step.key.to_s)
+            return :completed if step.review? || @complete.include?(step.key.to_s)
+            return :incomplete
+          end
+          :upcoming
+        end
+
+        # Which step headers link. Mirrors the engine's `Runner#go_to` reachability
+        # so the stepper never offers (or withholds) a jump the engine would reject:
+        #
+        #   - the current step never links to itself;
+        #   - the terminal review step links once the flow has started (any step
+        #     visited) — it's never itself "visited" (you Finish from it, you don't
+        #     advance past it), so without this it would be permanently unclickable,
+        #     stranding a user who navigated back from it;
+        #   - every other step links once visited. Forward jumps to unvisited steps
+        #     stay disallowed.
+        def clickable?(step, state)
+          return false if state == :current
+          return @visited.any? if step.review?
+          @visited.include?(step.key.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/ui/wizard/summary_display.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module UI
+    module Wizard
+      # A tiny read-only display over the wizard's typed `data` snapshot, used by
+      # the review step's auto-summary (§2.5). Reuses the Plutonium display
+      # pipeline (`Display::Base` + its inferred-type builder + `field(...).wrapped`)
+      # so each field's label and value formatting match the rest of the app,
+      # rather than re-implementing value rendering.
+      class SummaryDisplay < Plutonium::UI::Display::Base
+        # @param object [Object] the wizard `data` snapshot.
+        # @param fields [Array<Symbol>] scalar field names to summarize.
+        # @param inputs [Hash] the step's input config ({name => {options:}}), so a
+        #   field's declared `as:` informs the display component (e.g. a `:text`
+        #   input renders via the markdown/text display tag).
+        def initialize(object, fields:, inputs: {}, **options)
+          options[:key] = :wizard
+          @summary_fields = fields
+          @summary_inputs = inputs
+          super(object, **options)
+        end
+
+        def display_template
+          dl(class: "grid grid-cols-1 sm:grid-cols-2 gap-x-6 gap-y-3") do
+            @summary_fields.each { |name| render_summary_field(name) }
+          end
+        end
+
+        private
+
+        def render_summary_field(name)
+          input_options = @summary_inputs[name]&.dig(:options) || {}
+          field_options = input_options[:label] ? {label: input_options[:label]} : {}
+
+          render field(name, **field_options).wrapped do |f|
+            render instance_exec(f, &summary_tag_block(name))
+          end
+        end
+
+        # Pick the display component the same way a resource display does — infer it
+        # from the value's TYPE (date, boolean, number, currency, …) instead of
+        # stringifying everything. The one override: an attachment field stages a
+        # string TOKEN, so inference can't tell it's an attachment — force it (the
+        # data object is decorated upstream to resolve the token to an attachment).
+        def summary_tag_block(name)
+          ->(f) {
+            tag = Plutonium::Wizard::Attachments.field?(@summary_inputs[name]) ? :attachment : f.inferred_field_component
+            if tag.is_a?(Class)
+              f.send(:create_component, tag, tag.name.demodulize.underscore.sub(/component$/, "").to_sym)
+            else
+              f.send(:"#{tag}_tag")
+            end
+          }
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/version.rb

@@ -1,5 +1,5 @@
 module Plutonium
-  VERSION = "0.60.5"
+  VERSION = "0.61.0"
   NEXT_MAJOR_VERSION = VERSION.split(".").tap { |v|
     v[1] = v[1].to_i + 1
     v[2] = 0

data/lib/plutonium/wizard/attachment_data.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # Decorates a step's typed `data` so ATTACHMENT fields READ as resolved,
+    # displayable attachments ({Attachments::Resolved}) rather than the raw staged
+    # token string — so the step form's `Uppy` preview rehydrates on Back/resume
+    # (it calls `.url`/`.signed_id`/`.filename`, which a bare token string can't
+    # answer). Every other field delegates unchanged.
+    #
+    # Read-only: the SUBMITTED value is still the token the hidden preview field
+    # re-posts (`Resolved#signed_id` == the original token), so staging is
+    # unaffected.
+    class AttachmentData < SimpleDelegator
+      # Wrap only when the step actually has an attachment field — otherwise return
+      # the data untouched, so the overwhelming majority of steps are unaffected.
+      def self.wrap(data, step)
+        attachment_fields = step.inputs.select { |_name, config| Attachments.field?(config) }
+        attachment_fields.any? ? new(data, attachment_fields) : data
+      end
+
+      def initialize(data, attachment_fields)
+        super(data)
+        attachment_fields.each do |name, config|
+          multiple = config.dig(:options, :multiple)
+          define_singleton_method(name) do
+            resolved = Attachments.resolve(__getobj__.public_send(name))
+            multiple ? resolved : resolved.first
+          end
+        end
+      end
+
+      # Masquerade as the wrapped object's class so phlexi still infers field
+      # affordances (required marker, maxlength, …) from its validators — it reads
+      # `object.class.validators_on(...)`, and a `SimpleDelegator` would otherwise
+      # report its own class and drop every marker on the step.
+      def class
+        __getobj__.class
+      end
+    end
+  end
+end

data/lib/plutonium/wizard/attachments.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # Bridges a wizard's staged attachment value to the displayable attachment the
+    # `Uppy` input and `Display::Components::Attachment` render — **model-free and
+    # backend-agnostic**, for a bare `attribute :photo, :string` + `input :photo,
+    # as: :uppy, direct_upload: true` field (no `using:` model needed).
+    #
+    # A wizard stages plain strings, so an attachment field holds its backend's own
+    # direct-upload token: ActiveStorage's **signed_id** (an opaque signed string)
+    # or active_shrine/Shrine's **cached-file data** (a JSON object). Those are the
+    # only two shapes, and they're distinguishable — a Shrine token parses as JSON,
+    # an AS signed_id doesn't — so we revive each through its own backend with no
+    # model and no per-field configuration.
+    #
+    # Resolution is **display-only**: staging and `execute` (which assigns the token
+    # straight to a model attachment — both AS and active_shrine accept it) never
+    # call it. The two backends' native objects answer DIFFERENT method names
+    # (`filename`/`content_type` vs `original_filename`/`mime_type`), so a resolved
+    # token is wrapped in {Resolved}, a uniform view exposing exactly what the
+    # display + preview components call. See the wizard-attachments design spec.
+    module Attachments
+      module_function
+
+      # Resolve a staged attachment token (or array of them) into uniform
+      # {Resolved} view(s).
+      #
+      # @param value [String, Array, nil] the staged token(s).
+      # @return [Array<Resolved>] resolved attachments; blank, tampered, or
+      #   unrecognized tokens are dropped (never raised), so a bad token can't 500
+      #   the form or the review.
+      def resolve(value)
+        Array(value).filter_map { |token| resolve_token(token) }
+      end
+
+      # Whether a step input renders as an attachment (its `as:` is a file alias),
+      # so its staged token should be resolved for display. Keys off the form's
+      # canonical file-input alias set, so the two never drift.
+      def field?(input_options)
+        as = input_options&.dig(:options, :as) || input_options&.dig(:as)
+        Plutonium::UI::Form::Base::Builder::FILE_INPUT_TYPES.include?(as&.to_sym)
+      end
+
+      # SERVER-SIDE staging: turn a submitted attachment value into a token string
+      # to stage in `data`, minting one from an uploaded file when needed.
+      #
+      # Handles every shape a step POST can carry for an attachment field:
+      # - an already-minted token String (direct upload, or the hidden preview field
+      #   on re-submit) → kept verbatim;
+      # - an uploaded file (IO-like) → uploaded to the backend's cache, returning its
+      #   token (an AS signed_id, or Shrine cached-file JSON);
+      # - blank / no selection → nil (the caller drops the key so the previously
+      #   staged token survives a Back/re-submit);
+      # - an Array (multiple) → each element mapped, blanks dropped.
+      #
+      # @param backend [Symbol, nil] per-field override; nil → the configured default.
+      # @param uploader [Class, String, nil] a Shrine uploader to cache through
+      #   (`:shrine` backend only) — its cache-stage plugins (mime/dimension
+      #   extraction, `generate_location`, validations) run instead of base Shrine's.
+      #   The minted token stays uploader-agnostic, so display + `execute` promotion
+      #   are unaffected. Ignored shape for ActiveStorage (raises if given).
+      def stage_upload(value, backend: nil, uploader: nil)
+        if value.is_a?(Array)
+          value.filter_map { |v| stage_upload(v, backend:, uploader:) }.presence
+        elsif value.is_a?(String)
+          value.presence
+        elsif value.respond_to?(:read)
+          upload_to_cache(value, backend || attachment_backend, uploader:)
+        end
+      end
+
+      # The default server-side staging backend: the configured one, else
+      # auto-detected (active_shrine loaded → Shrine, else ActiveStorage).
+      def attachment_backend
+        Plutonium.configuration.wizards.attachment_backend ||
+          (defined?(ActiveShrine) ? :shrine : :active_storage)
+      end
+
+      # Run the EFFECTIVE Shrine uploader's attacher validations against a staged
+      # token (or array of them), returning the validation messages — so a file that
+      # violates the uploader's `validate_*` rules is rejected at the STEP (stage
+      # phase), not deferred to `execute`'s model assignment.
+      #
+      # The effective uploader is the field's `uploader:` if given, else base
+      # `Shrine` — both of which may carry `Attacher.validate` rules. Returns `[]`
+      # when the field isn't Shrine-backed (ActiveStorage has no attacher here), when
+      # nothing is staged, or when the effective uploader declares no validations.
+      #
+      # @param value [String, Array, nil] the staged token(s).
+      # @param backend [Symbol, nil] per-field override; nil → the configured default.
+      # @param uploader [Class, String, nil] the field's `uploader:` option.
+      # @return [Array<String>] validation messages (empty ⇒ valid).
+      def validation_errors(value, backend: nil, uploader: nil)
+        return [] unless (backend || attachment_backend).to_sym == :shrine
+
+        klass = shrine_uploader(uploader)
+        # Shrine's `validation` plugin is OPTIONAL — without it (or `validation_helpers`)
+        # the Attacher has no `#errors` and nothing to enforce. Detect it up front so a
+        # plugin-less app is a clean no-op, not a per-step rescued NoMethodError.
+        return [] unless klass::Attacher.method_defined?(:errors)
+
+        Array(value).flat_map { |token| token_validation_errors(klass, token) }
+      end
+
+      # Validate one cached token through an uploader's attacher. A broad rescue
+      # (like {resolve_token}) — a tampered/expired token shouldn't 500 the step; it
+      # surfaces at `execute` instead, where it's caught as a RecordInvalid.
+      def token_validation_errors(uploader_class, token)
+        return [] if token.blank?
+
+        attacher = uploader_class::Attacher.new
+        attacher.assign(token)
+        Array(attacher.errors)
+      rescue => e
+        Rails.logger.warn { "[Plutonium::Wizard] attachment validation skipped: #{e.class}: #{e.message}" }
+        []
+      end
+      private_class_method :token_validation_errors
+
+      # Upload a file to the backend's CACHE and return its re-postable token. The
+      # file lives in cache until `execute` assigns the token to a real attachment
+      # (which promotes it); an abandoned upload is reaped by the backend's own
+      # unattached-cache cleanup.
+      def upload_to_cache(file, backend, uploader: nil)
+        case backend.to_sym
+        when :shrine
+          shrine_uploader(uploader).upload(file, :cache).to_json
+        when :active_storage
+          raise ArgumentError, "input `uploader:` is only supported for the :shrine backend" if uploader
+          ActiveStorage::Blob.create_and_upload!(
+            io: file, filename: file.original_filename, content_type: file.content_type
+          ).signed_id
+        else
+          raise ArgumentError, "unknown wizard attachment backend: #{backend.inspect}"
+        end
+      end
+      private_class_method :upload_to_cache
+
+      # Resolve an `uploader:` option to the Shrine uploader class to cache through.
+      # nil → base `Shrine`; a class is used as-is; a String/Symbol is constantized.
+      # Anything that isn't a Shrine subclass is a configuration error (fail loud).
+      def shrine_uploader(uploader)
+        return Shrine if uploader.nil?
+
+        klass = uploader.is_a?(Class) ? uploader : uploader.to_s.safe_constantize
+        unless klass.is_a?(Class) && klass <= Shrine
+          raise ArgumentError, "input `uploader:` must be a Shrine uploader class, got #{uploader.inspect}"
+        end
+        klass
+      end
+      private_class_method :shrine_uploader
+
+      # Revive one token through whichever backend owns it, wrapped in {Resolved}. A
+      # broad rescue is warranted here (unlike elsewhere): the token is arbitrary,
+      # user-supplied input reconstituted at a render boundary, and the two backends
+      # raise different error classes for a tampered/expired token — none of which
+      # should take down the page.
+      def resolve_token(token)
+        return if token.blank?
+
+        source = shrine_uploaded_file(token) || active_storage_blob(token)
+        source && Resolved.new(source, token)
+      rescue => e
+        Rails.logger.warn { "[Plutonium::Wizard] could not resolve attachment token: #{e.class}: #{e.message}" }
+        nil
+      end
+      private_class_method :resolve_token
+
+      # A Shrine cached-file token is JSON (`{"id":…,"storage":"cache",…}`); an AS
+      # signed_id isn't. Parse-success → Shrine materializes it from the globally
+      # registered storages (no model, no per-field uploader needed for a `.url`).
+      def shrine_uploaded_file(token)
+        return unless defined?(Shrine)
+
+        data = begin
+          JSON.parse(token)
+        rescue JSON::ParserError, TypeError
+          nil
+        end
+        return unless data.is_a?(Hash)
+
+        Shrine.uploaded_file(data)
+      end
+      private_class_method :shrine_uploaded_file
+
+      def active_storage_blob(token)
+        ActiveStorage::Blob.find_signed(token) if defined?(ActiveStorage::Blob)
+      end
+      private_class_method :active_storage_blob
+
+      # A uniform view over a resolved attachment so the review display + the uppy
+      # preview don't care whether the source is an ActiveStorage `Blob`
+      # (`filename`/`content_type`/`representable?`) or a Shrine `UploadedFile`
+      # (`original_filename`/`mime_type`, none of the AS-only methods). Exposes
+      # exactly what those components call.
+      class Resolved
+        # @param source the backend object (AS Blob or Shrine UploadedFile).
+        # @param token  [String] the ORIGINAL staged token — what the hidden preview
+        #   field re-posts to preserve the upload across a Back/re-submit, and what
+        #   `execute` assigns to the model attachment.
+        def initialize(source, token)
+          @source = source
+          @token = token
+        end
+
+        # `url` is lazy (called at render, inside a request, where AS url options
+        # exist) — never eager at resolve time.
+        def url(*args) = @source.url(*args)
+
+        # The re-postable token, surfaced under the name the uppy input reads.
+        def signed_id = @token
+
+        def filename = (@source.try(:filename) || @source.try(:original_filename)).to_s
+
+        def content_type = @source.try(:content_type) || @source.try(:mime_type)
+
+        def representable? = @source.try(:representable?) || content_type.to_s.start_with?("image/")
+
+        def extension = @source.try(:extension).presence || File.extname(filename).delete(".").presence
+
+        def present? = true
+      end
+    end
+  end
+end