plutonium 0.60.5 → 0.62.0

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

data/lib/plutonium/wizard/base.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module Plutonium
+  module Wizard
+    # Author-facing base class for wizards (§2). A wizard declares ordered `step`s
+    # (with their own field surface, branching `condition:`, and optional per-step
+    # `on_submit`/`on_rollback`), an optional terminal `review` step, and commits
+    # at the end via `execute`.
+    #
+    # This class is pure object behaviour — declaring the DSL, exposing the
+    # ordered steps, the union `data` snapshot, and the `anchor`/`fail!`
+    # accessors. HTTP/runner/store wiring lives elsewhere.
+    #
+    # @example
+    #   class CompanyOnboardingWizard < Plutonium::Wizard::Base
+    #     step :company do
+    #       attribute :name, :string
+    #       input :name
+    #       validates :name, presence: true
+    #     end
+    #     review label: "Review"
+    #
+    #     def execute
+    #       succeed(Company.create!(name: data.name))
+    #     end
+    #   end
+    class Base
+      include ActiveModel::Model
+      include Plutonium::Definition::Presentable
+      include DSL
+
+      attr_reader :data_attributes
+      attr_accessor :view_context
+      attr_writer :anchor, :scope, :token
+
+      # Identity/concurrency context (§4.5), supplied by the runner/driving layer
+      # so `concurrency_key` resolvers and the tenancy fold can reach them.
+      # `wizard_token` is the per-run id (the identity for guest/repeatable runs,
+      # available inside `concurrency_key`) — NOT a pre-auth principal that
+      # survives login.
+      attr_accessor :current_user, :current_scoped_entity, :wizard_token
+
+      # The runner reuses a single wizard instance across a request, reassigning
+      # `data_attributes` between reads, so invalidate the memoized `data` snapshot
+      # whenever the staged attributes change. Only rebuild when the value actually
+      # CHANGES: the runner calls this on every `visible_path` (via `sync_data`),
+      # and an unconditional reset would discard a `data` snapshot the view layer
+      # has since mutated — e.g. validation errors `seed_errors!` added before the
+      # form reads them back (they'd silently vanish).
+      def data_attributes=(attrs)
+        return if @data && attrs == @data_attributes
+        @data_attributes = attrs
+        @data = nil
+      end
+
+      def initialize(view_context: nil, **)
+        @view_context = view_context
+        @data_attributes = {}
+        super()
+      end
+
+      class << self
+        # Per-step data spec ({step_key => {schema:, options:, structured:}}), used
+        # to build the step-keyed `data` container (§2.6). Each step contributes its
+        # OWN schema/options/structured — no cross-step union, so two steps may share
+        # a field name without colliding. `using:` imports are already composed into
+        # each step's `attribute_schema`.
+        def data_steps_spec
+          steps.reject(&:review?).each_with_object({}) do |step, acc|
+            acc[step.key.to_sym] = {
+              schema: step.attribute_schema,
+              options: step.attribute_options,
+              structured: step_structured_schema(step),
+              validations: step.validations + step.imported_form_validators
+            }
+          end
+        end
+
+        # The per-step typed sub-object classes ({step_key => Class}), built once
+        # per wizard class from {data_steps_spec} and reused for every `data`
+        # snapshot (the container is cheap to instantiate; the classes aren't).
+        def data_step_classes
+          @data_step_classes ||= data_steps_spec.transform_values do |spec|
+            Data.class_for(spec[:schema], options: spec[:options], structured: spec[:structured], validations: spec[:validations])
+          end
+        end
+
+        # Per-step typed classes carrying ONLY the step's INLINE `validates` (no
+        # imported form validators — those are validated separately via the
+        # transient model, so folding them in here would double-report). Built once
+        # per wizard class and reused by the runner's inline validation, which
+        # otherwise recompiles an equivalent anonymous class on every `validate`
+        # call (and `validate` runs many times per render). `{step_key => Class}`,
+        # omitting steps with no inline validations.
+        def inline_validation_classes
+          @inline_validation_classes ||= steps.reject(&:review?).each_with_object({}) do |step, acc|
+            next if step.validations.blank?
+            acc[step.key.to_sym] = Data.class_for(step.attribute_schema, validations: step.validations)
+          end
+        end
+
+        private
+
+        # One step's structured collections, as {name => [sub-field names]}, so
+        # `data.<step>.<name>` exposes typed sub-objects (§2.6 / §7.2).
+        def step_structured_schema(step)
+          step.structured_inputs.each_with_object({}) do |(name, entry), acc|
+            acc[name.to_sym] = structured_sub_fields(entry)
+          end
+        end
+
+        # Resolve the declared sub-field names of a structured_input entry by
+        # evaluating its block (or `using:` holder) against a FieldsDefinition.
+        def structured_sub_fields(entry)
+          options = entry[:options] || {}
+          return Array(options[:fields]).map(&:to_sym) if options[:fields]
+
+          holder =
+            if options[:using]
+              options[:using].is_a?(Class) ? options[:using].new : options[:using]
+            else
+              h = Plutonium::Definition::StructuredInputs::FieldsDefinition.new
+              entry[:block]&.call(h)
+              h
+            end
+          holder.defined_inputs.keys.map(&:to_sym)
+        end
+      end
+
+      # The step-keyed `data` snapshot (§2.6), reconstituted from the nested staged
+      # `data_attributes` ({step_key => {field => value}}). Addressed as
+      # `data.<step>.<field>`; `data[:step]` for dynamic access.
+      def data
+        @data ||= Data::Container.new(self.class.data_step_classes, data_attributes)
+      end
+
+      # The record this wizard was launched against (§3). Raises when the wizard
+      # was not declared `anchored` — never returns nil.
+      def anchor
+        unless self.class.anchored?
+          raise NotAnchoredError, "#{self.class} is not declared `anchored`"
+        end
+        @anchor
+      end
+
+      # Resolve this wizard's concurrency_key VALUE(S) in the wizard context
+      # (§4.2), with the tenant ALWAYS folded in (§4.4). Returns nil when no
+      # `concurrency_key` is declared (→ tokened identity). The returned value is
+      # an array `[*key_values, tenant_gid]`; {InstanceKey.concurrency} serializes
+      # it. The tenant is appended even when nil so the digest is stable.
+      def concurrency_key_value
+        resolver = self.class.concurrency_key_resolver
+        return nil unless resolver
+
+        key = instance_exec(&resolver)
+        [*Array.wrap(key), current_scoped_entity]
+      end
+
+      # The `{ "step_key" => [gids] }` source the runner injects from the stored
+      # state, backing the lazy `persisted` view. Reassigning it resets the memo.
+      def persisted_gid_source=(source)
+        @persisted = LazyPersisted.new(source)
+      end
+
+      # Records the per-step `on_submit`/`persist` macro registers (§2.2), as a
+      # LAZY view over the stored GIDs: a key is located on first read and
+      # memoized, so a request that never reads `persisted` issues zero locates
+      # (§4.5). Records set this request (the `persist` macro) are live already.
+      def persisted
+        @persisted ||= LazyPersisted.new
+      end
+
+      # The at-end commit hook (§2.3). Authors override it.
+      def execute
+        raise NotImplementedError, "#{self.class} must implement #execute"
+      end
+
+      # Entry authorization (§5.2/§6.5). Authors override it; false → 403. Default
+      # allow — resource-mounted surfaces additionally gate via the action policy.
+      def authorize? = true
+
+      private
+
+      # Raise a StepError from `on_submit`/`execute` (§6.1).
+      #
+      #   fail!("message")        → base (form-level) error
+      #   fail!(:field, "message") → field-level error
+      def fail!(attribute_or_message, message = nil)
+        if message.nil?
+          raise StepError.new(attribute_or_message, attribute: :base)
+        else
+          raise StepError.new(message, attribute: attribute_or_message)
+        end
+      end
+
+      # @return [Plutonium::Interaction::Outcome::Success]
+      def succeed(value = nil)
+        Plutonium::Interaction::Outcome::Success.new(value)
+      end
+      alias_method :success, :succeed
+
+      # @return [Plutonium::Interaction::Outcome::Failure]
+      def failed(errors = nil, attribute = :base)
+        case errors
+        when Hash
+          errors.each { |attr, error| self.errors.add(attr, error) }
+        else
+          Array(errors).each { |error| self.errors.add(attribute, error) }
+        end
+        Plutonium::Interaction::Outcome::Failure.new
+      end
+    end
+  end
+end

data/lib/plutonium/wizard/base_controller.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # Convenience base for a standalone wizard controller that needs NO custom auth
+    # base: a plain `ActionController::Base` plus the wizard module. Use it when you
+    # want to drop in your own controller without an auth concern:
+    #
+    #   class WizardsController < Plutonium::Wizard::BaseController; end
+    #
+    # For an AUTHENTICATED standalone wizard, don't use this — inherit your own
+    # authenticated base and `include Plutonium::Wizard::Controller` instead, so the
+    # controller carries `current_user`:
+    #
+    #   class WizardsController < ApplicationController
+    #     include Plutonium::Wizard::Controller
+    #     include Plutonium::Auth::Rodauth(:user)
+    #   end
+    #
+    # The module is the mechanism; this class is only sugar.
+    class BaseController < ActionController::Base
+      # A bare `ActionController::Base` host normally inherits forgery protection
+      # from the app's `default_protect_from_forgery`, but make it explicit here so
+      # a standalone wizard mount is CSRF-protected regardless of app config (the
+      # wizard `update` is a state-changing POST).
+      protect_from_forgery with: :exception
+
+      include Plutonium::Wizard::Controller
+    end
+  end
+end

data/lib/plutonium/wizard/configuration.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # Configuration for the Plutonium wizard subsystem.
+    #
+    # Exposed via {Plutonium::Configuration#wizards}.
+    class Configuration
+      # @return [Boolean] whether the wizard subsystem (and its migrations) is enabled
+      attr_accessor :enabled
+
+      # @return [ActiveSupport::Duration] how long completed/abandoned sessions are kept
+      attr_accessor :cleanup_after
+
+      # @return [Symbol] which database wizard tables live in
+      attr_accessor :database
+
+      # @return [Boolean] encrypt every wizard's staged `data` at rest by default.
+      #   Off by default because it needs ActiveRecord encryption keys configured;
+      #   a wizard may still opt in (`encrypt_data`) or out (`encrypt_data false`)
+      #   individually regardless of this default.
+      attr_accessor :encrypt_data
+
+      # @return [Symbol, nil] the storage backend used to SERVER-SIDE-stage a plain
+      #   (non-direct-upload) wizard attachment field — `:active_storage` or
+      #   `:shrine`. `nil` auto-detects (active_shrine loaded → `:shrine`, else
+      #   `:active_storage`). A field may override with `input …, backend:`. Only
+      #   relevant when a file rides the step POST; direct-upload fields already
+      #   arrive as a token and ignore this.
+      attr_accessor :attachment_backend
+
+      # Initialize a new wizard Configuration instance with default values.
+      def initialize
+        @enabled = false
+        @cleanup_after = 14.days
+        @database = :primary
+        @encrypt_data = false
+        @attachment_backend = nil
+      end
+    end
+  end
+end

data/lib/plutonium/wizard/controller.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # The standalone portal-hosted controller concern for portal-level wizards
+    # registered with `register_wizard` (§5.2). It is mixed into a portal-
+    # namespaced controller (see {Plutonium::Routing::WizardRegistration}), so it
+    # inherits the portal's auth, tenant scoping entity, layout, and Phlex
+    # rendering exactly like a resource controller.
+    #
+    # All runner-driving logic lives in {Plutonium::Wizard::Driving} (shared with
+    # the resource-mounted {Plutonium::Resource::Controllers::WizardActions}). This
+    # concern only adapts that logic to the standalone surface: the `show`/`update`
+    # actions, the wizard class carried as a route default, no anchor (portal-level
+    # wizards are non-anchored — anchored wizards mount on the resource controller),
+    # and the per-step URL built from the named route helper `register_wizard` draws.
+    #
+    # Identity (§4): a guest (`anonymous`) run's per-run id lives in the Rails
+    # session, namespaced per wizard (no cookie, no TTL); it is cleared on
+    # completion and auto-cleared on login/logout (Rodauth `reset_session`). An
+    # authenticated repeatable run carries its per-run id in the URL `:token`
+    # segment, guarded by owner-scoping; neither crosses the auth boundary
+    # mid-flow (§4.5).
+    module Controller
+      extend ActiveSupport::Concern
+      # The complete include surface for a standalone wizard controller: the
+      # Plutonium rendering/scoping stack PLUS the wizard driving. Including this
+      # one module yields a fully renderable wizard controller, so the synthesizer
+      # and any app override (`class WizardsController < MyAuthBase; include
+      # Plutonium::Wizard::Controller; end`) both get everything. Re-including Core
+      # on a host that already has it (a portal controller) is a harmless no-op.
+      include Plutonium::Core::Controller
+      include Plutonium::Wizard::Driving
+
+      included do
+        helper_method :current_user
+      end
+
+      class_methods do
+        # The gem's shared partials (`plutonium/_flash`, …) are looked up by a
+        # "plutonium" view prefix, which normally comes from inheriting a controller
+        # whose `controller_path` is "plutonium" (the app's `PlutoniumController`). A
+        # bare host (a main-app / public wizard rooted in `ActionController::Base`)
+        # has no such ancestor, so contribute the prefix here — making the module
+        # self-sufficient and the "main-app can be bare" path actually work.
+        def _prefixes
+          @_wizard_view_prefixes ||= (super | ["plutonium"])
+        end
+      end
+
+      # GET the bare mount — resolve/mint the run and redirect to its step.
+      def launch
+        wizard_launch
+      end
+
+      # GET .../:step — render the current step.
+      def show
+        wizard_show
+      end
+
+      # POST .../:step — advance / back / cancel.
+      def update
+        wizard_update
+      end
+
+      private
+
+      # Identity for a standalone wizard host. Defers to the host's own auth
+      # concern when present — a portal controller's `Rodauth(:account)`, or an
+      # app-defined `::WizardsController`'s — and is `nil` on a bare host (a public
+      # mount, or a misconfigured authenticated main-app wizard with no auth
+      # controller). An `anonymous` wizard never consults this; a non-anonymous
+      # wizard on a bare host resolves `nil` and is rejected by
+      # `require_wizard_authentication!`.
+      def current_user
+        defined?(super) ? super : nil
+      end
+
+      # The wizard class is carried as a route default (see WizardRegistration),
+      # so it is a server-set path parameter. Resolve it through an ALLOWLIST of
+      # the loaded wizard classes rather than `constantize`-ing the raw value:
+      # every standalone wizard route is drawn by handing `register_wizard` the
+      # class object, so by the time its route matches the class is loaded and
+      # registered as a `Base` descendant. Matching by name can therefore only
+      # ever return an actual wizard — it never triggers resolution of an
+      # arbitrary constant (the `constantize`-on-params code-execution surface).
+      def current_wizard_class
+        @current_wizard_class ||= begin
+          name = params.fetch(:wizard_class).to_s
+          Plutonium::Wizard::Base.descendants.find { |klass| klass.name == name } ||
+            raise(Plutonium::Wizard::UnknownWizardError, "unknown wizard #{name.inspect}")
+        end
+      end
+
+      # Portal-level wizards are either non-anchored or CONTEXT-anchored
+      # (`anchored via: :method`, §3). A `with:`-only (TYPE) anchor mounts on the
+      # resource controller instead (see {WizardActions}), where the anchor is
+      # resolved through the scoped, policy-gated `resource_record!` — never an
+      # unscoped `find_by`, which would be a cross-tenant IDOR.
+      #
+      # For a CONTEXT anchor we call the declared method on this controller; a nil
+      # result is a programming error (the wizard declared itself anchored).
+      def resolved_wizard_anchor
+        klass = current_wizard_class
+        return nil unless klass.anchored_via?
+
+        record = send(klass.anchor_via)
+        if record.nil?
+          raise Plutonium::Wizard::NotAnchoredError,
+            "#{klass.name} resolves its anchor via `#{klass.anchor_via}`, which returned nil"
+        end
+        assert_anchor_type!(klass, record)
+        record
+      end
+
+      # When a CONTEXT anchor also declares `with:` types, type-assert the result.
+      def assert_anchor_type!(klass, record)
+        types = klass.anchor_types
+        return if types.nil?
+        return if types.any? { |t| record.is_a?(t) }
+
+        raise Plutonium::Wizard::NotAnchoredError,
+          "#{klass.name} anchor resolved to #{record.class} but expects one of " \
+          "#{types.join(", ")}"
+      end
+
+      # Build the GET URL for a given step of this wizard, preserving the
+      # `:token` segment. Built through the named route helper that
+      # `register_wizard` draws (resolved from the current engine's route set by
+      # the wizard class, so `at:`/`as:` overrides are honored) — never
+      # string-surgery on `request.path`, so the URL is always a same-host,
+      # route-validated path.
+      def wizard_step_url(step_key)
+        url_options = {step: step_key}
+        token = wizard_url_token
+        url_options[:token] = token if token.present?
+        # An entity-scoped portal's wizard routes carry the scope path segment
+        # (e.g. `:organization_scoped`); thread it through from the request so the
+        # generated URL stays inside the tenant.
+        if scoped_to_entity?
+          url_options[scoped_entity_param_key] = params[scoped_entity_param_key]
+        end
+        current_engine.routes.url_helpers.public_send(wizard_step_url_helper, **url_options)
+      end
+
+      # The `<name>_wizard_path` helper for this wizard's standalone mount. Found
+      # by the GET route `register_wizard` draws (named `:"#{helper}_wizard"`,
+      # carrying the `wizard_class` route default) so the lookup tracks the actual
+      # `at:`/`as:` used at registration rather than re-deriving a slug.
+      def wizard_step_url_helper
+        @wizard_step_url_helper ||= begin
+          name = Plutonium::Wizard::RouteResolution.route_name(
+            current_engine.routes, current_wizard_class, action: "show"
+          )
+          raise "no register_wizard route found for #{current_wizard_class.name}" unless name
+
+          :"#{name}_path"
+        end
+      end
+    end
+  end
+end