plutonium 0.60.5 → 0.61.0

data/lib/plutonium/routing/mapper_extensions.rb

@@ -43,6 +43,8 @@ module Plutonium
           define_collection_interactive_actions
           define_collection_typeahead_actions
           define_collection_export_actions
+          define_member_wizard_actions
+          define_collection_wizard_actions
         end
       end
 
@@ -149,6 +151,7 @@ module Plutonium
             as: :interactive_record_action
           post "record_actions/:interactive_action", action: :commit_interactive_record_action,
             as: :commit_interactive_record_action
+          post "kanban_move", action: :kanban_move, as: :kanban_move
         end
       end
 
@@ -183,6 +186,47 @@ module Plutonium
         end
       end
 
+      # Defines member-level wizard launch actions (§5.1 / Fix A). Auto-mounted on
+      # every Plutonium resource alongside record_actions — the action 404s unless
+      # `:wizard_name` is a wizard registered (anchored → record) on the resource's
+      # definition, mirroring how `:interactive_action` gates record_actions. The
+      # anchor is the scoped, policy-gated `resource_record!` (IDOR-safe).
+      #
+      # @return [void]
+      def define_member_wizard_actions
+        return unless Plutonium.configuration.wizards.enabled
+
+        member do
+          # Bare launch (no :step): resolve/mint the run and redirect to its step.
+          get "wizards/:wizard_name", action: :launch_wizard_record_action,
+            as: :launch_wizard_record_action
+          get "wizards/:wizard_name(/:token)/:step", action: :wizard_record_action,
+            as: :wizard_record_action
+          post "wizards/:wizard_name(/:token)/:step", action: :commit_wizard_record_action,
+            as: :commit_wizard_record_action
+        end
+      end
+
+      # Defines collection-level wizard launch actions (§5.1 / Fix A) for
+      # non-anchored (create) wizards. Auto-mounted alongside resource_actions;
+      # the action 404s unless `:wizard_name` is a collection wizard registered on
+      # the resource's definition.
+      #
+      # @return [void]
+      def define_collection_wizard_actions
+        return unless Plutonium.configuration.wizards.enabled
+
+        collection do
+          # Bare launch (no :step): resolve/mint the run and redirect to its step.
+          get "wizards/:wizard_name", action: :launch_wizard_resource_action,
+            as: :launch_wizard_resource_action
+          get "wizards/:wizard_name(/:token)/:step", action: :wizard_resource_action,
+            as: :wizard_resource_action
+          post "wizards/:wizard_name(/:token)/:step", action: :commit_wizard_resource_action,
+            as: :commit_wizard_resource_action
+        end
+      end
+
       # Defines the collection-level CSV export action. Auto-mounted on
       # every Plutonium resource alongside typeahead and bulk actions.
       # The action itself is gated by the `export_csv?` policy (default

data/lib/plutonium/routing/wizard_registration.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Routing
+    # Adds `register_wizard` to the routing mapper, mirroring `register_resource`
+    # (see {MapperExtensions}). A wizard is **portal-hosted** (§5.2): the routes are
+    # drawn inside the portal engine's `routes.draw` block, so they inherit the
+    # portal's scope/auth/layout, and they dispatch to a portal-namespaced wizard
+    # controller that includes {Plutonium::Wizard::Controller} + the portal's own
+    # controller concern.
+    #
+    # @example inside a portal engine's routes
+    #   AdminPortal::Engine.routes.draw do
+    #     register_wizard OnboardingWizard, at: "onboarding"
+    #     register_resource ::User
+    #   end
+    #
+    # Draws (portal-relative):
+    #   GET  /onboarding(/:token)/:step  → <Portal>::WizardsController#show
+    #   POST /onboarding(/:token)/:step  → <Portal>::WizardsController#update
+    #
+    # with `onboarding_wizard_path` / `_url` helpers.
+    module WizardRegistration
+      WIZARD_CONTROLLER_NAME = "wizards"
+
+      # Tracks public wizard mounts already appended to the main app route set, so
+      # re-draws (boot, reload, multiple portals) don't stack duplicate named
+      # routes. Keyed by the wizard CLASS NAME (not the helper name) so two distinct
+      # anonymous wizards never collapse into one entry — a helper-name collision
+      # between different wizards is a hard error (see {#register_public_wizard}),
+      # not a silent drop. Maps `wizard_class.name => helper_name`.
+      class << self
+        attr_accessor :appended_public_wizards
+      end
+
+      # @param wizard_class [Class] a Plutonium::Wizard::Base subclass
+      # @param at [String] the portal-relative base path for the wizard's steps
+      # @param as [String, Symbol, nil] override the route helper name prefix
+      # @param public [Boolean, nil] mount on a PUBLIC (unauthenticated) route
+      #   outside the portal's auth constraint, for an `anonymous` (guest) wizard.
+      #   Defaults to the wizard's own `anonymous?` flag. A non-`anonymous` wizard
+      #   may not be mounted public; an `anonymous` wizard may not be mounted
+      #   authenticated (its whole point is pre-login access). See §4.5.
+      # @param layout [Symbol, String, nil] the Rails layout this mount renders in —
+      #   a layout NAME, exactly like the controller `layout` macro: `:basic` (the
+      #   bare `BasicLayout`, e.g. an onboarding screen), `:resource` (the standard
+      #   shell), or any app layout. Only meaningful for `register_wizard` mounts;
+      #   resource-defined (`wizard` macro) wizards are always embedded. Defaults by
+      #   context (portal → the resource shell, main-app → `:basic`); turbo-frame
+      #   requests are always layout-less regardless.
+      def register_wizard(wizard_class, at:, as: nil, public: nil, layout: nil)
+        # The wizard subsystem is opt-in (`config.wizards.enabled`). When disabled,
+        # draw no routes — its tables/migrations are skipped too, so a mounted route
+        # couldn't work anyway. Warn rather than fail silently, so a
+        # registered-but-disabled wizard is discoverable instead of a mystery 404.
+        unless Plutonium.configuration.wizards.enabled
+          Rails.logger.warn { "[Plutonium::Wizard] not registering routes for #{wizard_class} — config.wizards.enabled is false" }
+          return
+        end
+
+        # A CONTEXT anchor (`anchored via: :method`) is portal-level: the anchor is
+        # resolved by calling a controller method, needs no URL `:id`, and is
+        # IDOR-safe (trusted context) — so it CAN mount here. Only a TYPE anchor
+        # (`with:`-only, resolved from the URL `:id`) is rejected, because it needs
+        # the resource controller's scoped, policy-gated `resource_record!`.
+        if wizard_class.anchored? && !wizard_class.anchored_via?
+          raise ArgumentError,
+            "register_wizard #{wizard_class.name} — `with:`-anchored wizards are not " \
+            "mounted portal-level. Register them on the anchored resource's definition " \
+            "with the `wizard` macro, which auto-mounts a record action whose anchor is " \
+            "resolved through the resource controller's scoped, policy-gated " \
+            "`resource_record!`. (A `via:`-anchored wizard mounts here fine.)"
+        end
+
+        # Default the mount kind to the wizard's `anonymous?` flag, and reject
+        # contradictions (§4.5): an `anonymous` wizard NEEDS a public route
+        # (pre-login); a non-`anonymous` wizard MUST stay behind portal auth.
+        is_public = public.nil? ? wizard_class.anonymous? : !!public
+        if is_public && !wizard_class.anonymous?
+          raise ArgumentError,
+            "register_wizard #{wizard_class.name}, public: true — only an `anonymous` " \
+            "wizard may be mounted public. Add the `anonymous` macro to the wizard, or " \
+            "drop `public:`."
+        end
+        if !is_public && wizard_class.anonymous?
+          raise ArgumentError,
+            "register_wizard #{wizard_class.name} — an `anonymous` wizard must be mounted " \
+            "public (it runs pre-login). Pass `public: true` (it is the default for " \
+            "`anonymous` wizards)."
+        end
+
+        return register_public_wizard(wizard_class, at:, as:, layout:) if is_public
+
+        ensure_wizard_controller!(wizard_class)
+
+        # The helper name defaults to the mount path (`at:`), so
+        # `register_wizard W, at: "onboarding"` yields `onboarding_wizard_path`.
+        # `as:` overrides it; the wizard's own route name is the final fallback.
+        helper_name = (as || at.presence || wizard_route_name(wizard_class)).to_s.tr("/", "_")
+        defaults = wizard_route_defaults(wizard_class, layout)
+
+        scope path: at do
+          # Canonical launch: GET the bare mount → resolve/mint the run and PRG to
+          # its first (or resumed) step, with the token already in the URL. This is
+          # the shareable entry point; `wizard_step_url` builds the stepped URLs.
+          get "/", to: "#{WIZARD_CONTROLLER_NAME}#launch",
+            as: :"#{helper_name}_wizard_launch", defaults: defaults
+          get "(/:token)/:step", to: "#{WIZARD_CONTROLLER_NAME}#show",
+            as: :"#{helper_name}_wizard", defaults: defaults
+          post "(/:token)/:step", to: "#{WIZARD_CONTROLLER_NAME}#update",
+            defaults: defaults
+        end
+      end
+
+      private
+
+      # Route defaults carried on every wizard route: the wizard class (resolves the
+      # wizard at request time) and, when explicitly set, the `layout`
+      # (a layout name). An unset layout is omitted — the driving layer then
+      # defaults it by context (portal → the resource shell, main-app → `:basic`). The
+      # layout rides the route (not a controller-class setting) because one
+      # synthesized controller serves many mounts, so the per-mount value can't live
+      # on the controller.
+      def wizard_route_defaults(wizard_class, layout)
+        defaults = {wizard_class: wizard_class.name}
+        defaults[:wizard_layout] = layout.to_s if layout
+        defaults
+      end
+
+      # Mount an `anonymous` wizard on a PUBLIC (unauthenticated) route (§4.5).
+      #
+      # Portal engines are mounted INSIDE the host's auth constraint
+      # (`constraints Rodauth::Rails.authenticate(:user) { mount ... }`), so a
+      # route drawn in the engine is unreachable pre-login. A guest wizard must
+      # therefore be drawn on the MAIN application's route set, OUTSIDE that
+      # constraint. We append to `Rails.application.routes` so the public route is
+      # added after (and independent of) the engine mount.
+      #
+      # The route dispatches to a synthesized top-level `WizardsController` that
+      # includes the full Plutonium controller stack + `Plutonium::Auth::Public`
+      # (so `current_user` is the guest sentinel) + {Plutonium::Wizard::Controller}.
+      def register_public_wizard(wizard_class, at:, as:, layout: nil)
+        ensure_public_wizard_controller!
+
+        helper_name = (as || at.presence || wizard_route_name(wizard_class)).to_s.tr("/", "_")
+        defaults = wizard_route_defaults(wizard_class, layout)
+        mount_path = at.to_s.sub(%r{\A/}, "")
+
+        # `Rails.application.routes.append` blocks are RETAINED and re-run on every
+        # route reload — so append a given wizard's block at most once. Key by the
+        # wizard CLASS (not the helper name) so re-drawing the SAME wizard is a no-op
+        # while two DIFFERENT wizards are never silently collapsed.
+        registered = (Plutonium::Routing::WizardRegistration.appended_public_wizards ||= {})
+
+        # Two distinct public wizards sharing a helper name (same `at:`/`as:`) would
+        # draw the same route name → Rails "route name already in use", or worse, a
+        # silent drop. Fail loudly with a fix instead.
+        clash = registered.find { |klass_name, helper| helper == helper_name && klass_name != wizard_class.name }
+        if clash
+          raise ArgumentError,
+            "register_wizard #{wizard_class.name}, at: #{at.inspect} — the route helper " \
+            "`#{helper_name}_wizard` is already used by #{clash.first}. Give one of them a " \
+            "distinct `at:` or `as:`."
+        end
+
+        return unless registered[wizard_class.name].nil?
+        registered[wizard_class.name] = helper_name
+
+        Rails.application.routes.append do
+          scope path: mount_path do
+            get "/", to: "public_wizards#launch",
+              as: :"#{helper_name}_wizard_launch", defaults: defaults
+            get "(/:token)/:step", to: "public_wizards#show",
+              as: :"#{helper_name}_wizard", defaults: defaults
+            post "(/:token)/:step", to: "public_wizards#update",
+              defaults: defaults
+          end
+        end
+      end
+
+      # Synthesize the top-level public `PublicWizardsController` once. Unlike the
+      # portal controller (built on the portal's authenticated `PlutoniumController`),
+      # the public one is built directly on the Plutonium controller stack with
+      # `Plutonium::Auth::Public`, so it has the rendering/scoping infra a wizard
+      # needs WITHOUT requiring a login.
+      #
+      # It is a DISTINCT const from the authenticated main-app `::WizardsController`
+      # (see {#ensure_wizard_controller!}): the two must not share a controller, or a
+      # public (guest) and an authenticated main-app wizard in the same app would
+      # collapse onto whichever was synthesized first — an authenticated main-app
+      # wizard would then run through `Auth::Public` and reject every logged-in user.
+      def ensure_public_wizard_controller!
+        return if Object.const_defined?(:PublicWizardsController, false)
+
+        # Build on a BARE base, decoupled from the app's `::PlutoniumController`
+        # (which portals inherit and may carry auth). `Plutonium::Wizard::Controller`
+        # brings the full rendering stack — including `Core::Controller`'s gem
+        # view-path, which resolves the shared partials (`plutonium/_flash`, etc.) —
+        # so no PlutoniumController inheritance is needed for that.
+        base = "ApplicationController".safe_constantize || ActionController::Base
+        klass = Class.new(base) do
+          # `Auth::Public` provides the guest `current_user`; an `anonymous` wizard
+          # ignores it for identity (session-token keyed) but the host still needs a
+          # `current_user` defined.
+          include Plutonium::Auth::Public
+          include Plutonium::Wizard::Controller
+        end
+        Object.const_set(:PublicWizardsController, klass)
+      end
+
+      def wizard_route_name(wizard_class)
+        wizard_class.name.demodulize.underscore.sub(/_wizard\z/, "")
+      end
+
+      # Resolve (creating if needed) the portal-namespaced wizard controller the
+      # routes dispatch to. The portal engine isolates its namespace, so a route
+      # `controller: "wizards"` resolves to `<PortalModule>::WizardsController`.
+      # There is no hand-written file for it (unlike resource controllers, which
+      # are scaffolded), so we synthesize it here — the same idea as
+      # {Plutonium::Portal::DynamicControllers}, but triggered explicitly at route
+      # draw time rather than via `const_missing`.
+      def ensure_wizard_controller!(wizard_class)
+        engine = wizard_route_engine
+        return if engine.nil?
+
+        portal_module = wizard_portal_module(engine)
+        if portal_module.nil?
+          # Main-app / non-namespaced mount. Synthesize a BARE top-level
+          # WizardsController (ApplicationController + the wizard module) — it is NOT
+          # rooted in the app's `::PlutoniumController` (portals inherit that, so auth
+          # there would leak). A bare synthesized controller has NO auth, so a
+          # public/`anonymous` wizard works as-is; an AUTHENTICATED main-app wizard
+          # requires the app to define its own `::WizardsController` (with its auth
+          # concern), which the const-check below picks up instead of synthesizing.
+          #
+          # This rhymes with `register_resource` ("the app owns the controller") but
+          # isn't identical: `register_resource` never synthesizes a fallback, so a
+          # missing controller is a loud routing/constant error; here the fallback is
+          # auth-less, so a missing override for an authenticated wizard fails QUIETER
+          # — every user is bounced to login rather than erroring. Covered by the
+          # skill docs + main_app_wizard_test so it's an explicit, tested edge.
+          define_wizard_controller(Object, "WizardsController", "ApplicationController", nil)
+          return
+        end
+
+        define_wizard_controller(
+          portal_module,
+          "WizardsController",
+          "#{portal_module.name}::PlutoniumController",
+          "#{portal_module.name}::Concerns::Controller"
+        )
+      end
+
+      # Synthesize a wizard controller unless one is already defined (the app's
+      # override wins — define `<Portal>::WizardsController` / `::WizardsController`
+      # to take over). `Plutonium::Wizard::Controller` brings the full rendering
+      # stack, so the parent only needs to supply auth/scope (a portal's
+      # PlutoniumController) or nothing (a bare main-app base).
+      def define_wizard_controller(namespace, const_name, parent_name, concern_name)
+        return if namespace.const_defined?(const_name, false)
+
+        parent = parent_name.safe_constantize || ActionController::Base
+        klass = Class.new(parent) do
+          include Plutonium::Wizard::Controller
+        end
+        namespace.const_set(const_name, klass)
+
+        if concern_name && (concern = concern_name.safe_constantize)
+          klass.include concern
+        end
+        klass
+      end
+
+      # The Plutonium engine owning this route set (mirrors RouteSetExtensions#engine).
+      def wizard_route_engine
+        rs = respond_to?(:route_set) ? route_set : @set
+        rs.respond_to?(:engine) ? rs.engine : nil
+      end
+
+      # The portal module (e.g. AdminPortal) for a `SomePortal::Engine`, or nil for
+      # the main application.
+      def wizard_portal_module(engine)
+        return nil if engine == Rails.application.class
+
+        engine.module_parent
+      end
+    end
+  end
+end

data/lib/plutonium/ui/display/resource.rb

@@ -74,18 +74,23 @@ module Plutonium
         def render_tablist_with_details
           tablist = BuildTabList()
 
-          # Build an inner display component for the Details tab.
-          # It must be a standalone Phlex component so that TabList can call
-          # `render(details_display)` from within its own context. Phlex propagates
-          # @_state through render calls, so the inner component writes to the same
-          # buffer as the outer Resource display even though self changes.
-          details_display = build_details_display
-
-          tablist.with_tab(
-            identifier: "details",
-            title: -> { plain "Details" }
-          ) do
-            render details_display
+          # Only render the Details tab when the user is permitted to see at
+          # least one field. With no permitted fields the tab would be empty,
+          # so we drop it and let the first association tab lead instead.
+          if resource_fields.present?
+            # Build an inner display component for the Details tab.
+            # It must be a standalone Phlex component so that TabList can call
+            # `render(details_display)` from within its own context. Phlex propagates
+            # @_state through render calls, so the inner component writes to the same
+            # buffer as the outer Resource display even though self changes.
+            details_display = build_details_display
+
+            tablist.with_tab(
+              identifier: "details",
+              title: -> { plain "Details" }
+            ) do
+              render details_display
+            end
           end
 
           resource_associations.each do |name|

data/lib/plutonium/ui/form/base.rb

@@ -47,6 +47,13 @@ module Plutonium
           end
           alias_method :switch_tag, :toggle_tag
 
+          # Password / secret input that never renders the stored value.
+          # Routed to here for both explicit `as: :password` and every field
+          # inferred as a password (see Options::InferredTypes#infer_field_component).
+          def password_tag(**, &)
+            create_component(Components::Password, :password, **, &)
+          end
+
           def slim_select_tag(**attributes, &)
             attributes[:data_controller] = tokens(attributes[:data_controller], "slim-select")
             select_tag(**attributes, required: false, class!: "", &)
@@ -61,11 +68,16 @@ module Plutonium
           end
           alias_method :phone_tag, :int_tel_input_tag
 
+          # The `as:` values that render through the Uppy file-upload component —
+          # the single source of truth, also consulted by
+          # {Plutonium::Wizard::Attachments.field?} so a wizard can detect an
+          # attachment field model-free without re-listing the aliases.
+          FILE_INPUT_TYPES = %i[uppy file attachment].freeze
+
           def uppy_tag(**, &)
             create_component(Components::Uppy, :uppy, **, &)
           end
-          alias_method :file_tag, :uppy_tag
-          alias_method :attachment_tag, :uppy_tag
+          (FILE_INPUT_TYPES - [:uppy]).each { |name| alias_method :"#{name}_tag", :uppy_tag }
 
           def key_value_store_tag(**, &)
             create_component(Components::KeyValueStore, :key_value_store, **, &)
@@ -165,9 +177,11 @@ module Plutonium
           attributes["data-controller"] = form_data_controller
         end
 
-        # `dirty-form-guard` is attached unconditionally — it self-disables
-        # outside a <dialog>. Branching on `in_modal?` here would fail:
-        # Phlex forbids view-context access before rendering begins.
+        # `dirty-form-guard` is attached unconditionally — it is inert until it has
+        # something to guard: a modal (Esc/close/cancel) or a control marked
+        # `data-dirty-form-guard-leave` posting without this form's fields. With
+        # neither it never prompts. Branching on `in_modal?` here would fail: Phlex
+        # forbids view-context access before rendering begins.
         def form_data_controller
           "form dirty-form-guard"
         end

data/lib/plutonium/ui/form/components/password.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module UI
+    module Form
+      module Components
+        # Password / secret input that never emits the stored value into the DOM.
+        #
+        # The generic Phlexi input renders `value=field.dom.value`, leaking the
+        # server-side secret (and its length) into the page source. This component
+        # instead renders a fixed SENTINEL whenever an *untouched* secret is
+        # stored, masking both the secret and its length, and renders an empty
+        # field otherwise.
+        #
+        # On submit the sentinel maps back to `nil`, which Plutonium's param
+        # extraction (`submitted_resource_params`) compacts away — leaving the
+        # stored value untouched. An empty field passes through as "":
+        #
+        #   untouched field → sentinel submitted → nil   → keep existing
+        #   emptied field   → "" submitted       → ""    → explicit clear (clear-by-blank)
+        #   typed value     → value submitted    → value → set new value
+        #
+        # On a failed re-render of an *edited* secret the field comes back blank
+        # (we never echo a submitted secret). When the edit set a new value it is
+        # also marked `required`, so the browser forces a re-type rather than a
+        # silent blank resubmit clearing the stored secret. When the edit *cleared*
+        # the value we leave it blank and not required — the clear may be intended
+        # (clear-by-blank). Either guard is client-side UX only.
+        #
+        # The rendered sentinel is guarded client-side by the `password-sentinel`
+        # Stimulus controller: the first edit (keystroke, paste, backspace) wipes
+        # the whole field, so a partial edit can't corrupt the sentinel into a
+        # literal new password.
+        #
+        # New records and interaction forms (set-password, reset-password) render
+        # an honest empty field that invites input and lets password managers
+        # offer to generate a strong password.
+        class Password < Phlexi::Form::Components::Input
+          # Rendered in place of an existing secret. Masked in the UI; only ever
+          # visible (as this constant) in page source — never the real value.
+          SENTINEL = "__plutonium_password_unchanged__"
+
+          protected
+
+          def build_input_attributes
+            super
+            attributes[:type] = :password
+            value = masked_value
+            attributes[:value] = value
+            attributes[:autocomplete] ||= "new-password"
+            # A stored secret edited (to a new value) on a failed submit comes
+            # back blank. Force re-entry so an untouched resubmit can't silently
+            # clear it via the clear-by-blank path. Client-side UX guard only.
+            attributes[:required] = true if reentry_required?
+
+            # When the field renders the sentinel, guard it so the first edit
+            # wipes the whole value — a partial edit would corrupt the sentinel
+            # into a literal new password.
+            if value == SENTINEL
+              attributes[:data_controller] = tokens(attributes[:data_controller], :"password-sentinel")
+              attributes[:data_action] = tokens(attributes[:data_action], "beforeinput->password-sentinel#beforeinput")
+              attributes[:data_password_sentinel_sentinel_value] = SENTINEL
+            end
+
+            apply_default_hint(value)
+          end
+
+          # The masked field is otherwise opaque — the user can't tell what the
+          # dots mean or what a blank submit does. Supply a default hint
+          # explaining it, unless the author already set one (theirs wins). The
+          # wrapper renders the hint after this input, so setting it here is in
+          # time. No hint for a plain empty field (new record) — it speaks for
+          # itself.
+          def apply_default_hint(value)
+            return if field.has_hint?
+            if value == SENTINEL
+              field.hint("Leave blank to keep the current value.")
+            elsif reentry_required?
+              field.hint("Re-enter the new value to save it.")
+            end
+          end
+
+          def masked_value
+            key = field.key.to_s
+            # New records and interaction forms (set-password, reset-password)
+            # have nothing stored — render an empty field that invites input.
+            return nil unless field.object.persisted?
+            # Write-only attributes (e.g. has_secure_password's `password`) are
+            # not real columns, so there is nothing stored to keep.
+            return nil unless field.object.has_attribute?(key)
+            # Nothing stored yet — render blank.
+            return nil unless field.object.attribute_in_database(key).present?
+            # A secret is stored. On a failed re-render of an edit it is dirty:
+            # render blank so the user re-enters it (we never echo a submitted
+            # secret). Otherwise mask it (and its length) behind the sentinel,
+            # which submits back as "leave unchanged".
+            field.object.attribute_changed?(key) ? nil : SENTINEL
+          end
+
+          # True only when a stored secret was edited *to a new value* and
+          # therefore renders blank — the state where an untouched resubmit would
+          # silently clear a secret the user meant to change. We deliberately do
+          # NOT force re-entry when the edit blanked the value: that user may
+          # have intended to clear it (clear-by-blank), so let the blank stand.
+          def reentry_required?
+            key = field.key.to_s
+            field.object.persisted? &&
+              field.object.has_attribute?(key) &&
+              field.object.attribute_in_database(key).present? &&
+              field.object.attribute_changed?(key) &&
+              field.object.read_attribute(key).present?
+          end
+
+          def normalize_input(input_value)
+            # The sentinel means "leave unchanged" → nil, which
+            # `submitted_resource_params` compacts away so the stored secret is
+            # kept. An empty field passes through as "" → an explicit clear
+            # (clear-by-blank); a typed value is set as-is.
+            return nil if input_value == SENTINEL
+            super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/ui/form/components/uppy.rb

@@ -13,13 +13,16 @@ module Plutonium
                 # Hidden field for ensuring removal of esp. has_one_attached attachments
                 input(type: :hidden, name: attributes[:name], multiple: attributes[:multiple], value: nil, autocomplete: "off", hidden: true)
 
-                next if field.value.nil?
-
+                # Always render the preview container — even when empty — so the
+                # `attachment-input` controller's `attachment-preview-container`
+                # OUTLET exists on a fresh (valueless) field. Without it the FIRST
+                # upload can't inject its preview: Stimulus raises on the missing
+                # outlet and the uploaded token never reaches the form.
                 div(
                   class: "attachment-preview-container grid grid-cols-[repeat(auto-fill,minmax(0,180px))] gap-4",
                   data_controller: "attachment-preview-container"
                 ) do
-                  render_existing_attachments
+                  render_existing_attachments unless field.value.nil?
                 end
               end
 

data/lib/plutonium/ui/form/options/inferred_types.rb

@@ -8,6 +8,14 @@ module Plutonium
           private
 
           def infer_field_component
+            # Password detection lives in the string-type inference, not the
+            # component-type inference (a `password` column infers as :string).
+            # Route every inferred password/secret field to the masking Password
+            # component so the stored value never reaches the DOM. We also widen
+            # the heuristic to secret-bearing names Phlexi misses (`*_secret`,
+            # `*_key`, `salt`, ...) — see #secret_field_name?.
+            return :password if inferred_string_field_type == :password || secret_field_name?
+
             case inferred_field_type
             when :rich_text
               return :markdown
@@ -25,6 +33,18 @@ module Plutonium
               inferred_field_component
             end
           end
+
+          # Secret-bearing names Phlexi's `is_password_field?` does not catch
+          # (it only handles `password`, `encrypted_*`, `*_password`, `*_digest`,
+          # `*_hash`, `*_token`). Mask these too so their value never reaches the
+          # DOM. Still a name heuristic, not a guarantee — opt in/out per field
+          # with `as: :password` / `as: :string`.
+          def secret_field_name?
+            name = key.to_s.downcase
+            name == "token" || name == "salt" ||
+              name.include?("secret") ||
+              name.end_with?("_key", "_salt")
+          end
         end
       end
     end

data/lib/plutonium/ui/form/resource.rb

@@ -66,7 +66,7 @@ module Plutonium
               "w-full max-w-md p-0 " \
               "open:flex flex-col " \
               "opacity-0 scale-95 data-[open]:opacity-100 data-[open]:scale-100 " \
-              "transition-[opacity,transform] duration-200 ease-out",
+              "transition-[opacity,scale] duration-200 ease-out",
             data: {"dirty-form-guard-target": "confirmDialog"},
             # Modern Chrome refuses user-agent close requests (Esc, backdrop);
             # older browsers fall back to the JS controller's interception.