plutonium 0.62.2 → 0.63.0

data/lib/plutonium/wizard/driving.rb

@@ -170,20 +170,48 @@ module Plutonium
         respond_to_wizard_result(runner, result)
       end
 
-      # Advance the current step; if the POSTed step is the last visible step,
-      # finalize. The last visible step is the terminal `review` (no fields), so
-      # finalize runs directly; otherwise validate + stage + move the cursor.
-      def advance_or_finalize(runner)
-        return runner.finalize if wizard_posting_last_step?(runner)
+      # DELETE (/:token) — abandon a run. Same entry gauntlet as every other wizard
+      # action (auth → ownership → policy) before anything is destroyed.
+      def wizard_cancel
+        require_wizard_authentication!
+        runner = build_wizard_runner
+        deny_wizard_resume_for_other_user!(runner)
+        authorize_wizard_entry!(runner)
 
-        runner.advance(params[:step], wizard_params(runner), goto: params[:_goto].presence)
+        # No stored row at this key — nothing to abandon, so bail BEFORE `cancel`,
+        # which is destructive: `run_cleanup` fires every declared `on_rollback`,
+        # then `clear` deletes the row.
+        #
+        # A DELETE carrying a stale or forged token mints an EMPTY runner, and
+        # `rollback_step` only no-ops when the step ALSO declares no `on_rollback` —
+        # so a side-effect-only compensator (refund the charge, call the external
+        # API) runs for a run that never existed. The token is the only thing
+        # identifying a run and a caller can simply make one up, which puts this in
+        # reach of anyone allowed to LAUNCH the wizard.
+        #
+        # PRG to the launch path: the chooser over any runs the user still has, or
+        # a fresh run. A finished one-time run lands here too (it resumes no row)
+        # and gets its completed page.
+        unless runner.resumed?
+          return redirect_to wizard_launch_url, status: :see_other, allow_other_host: false
+        end
+
+        runner.cancel
+        clear_wizard_session_token
+        clear_wizard_return_to
+
+        # PRG to the bare launch path: with this run gone, that re-renders the
+        # chooser over the user's remaining runs, or mints a fresh one if it was
+        # their last.
+        redirect_to wizard_launch_url, status: :see_other, allow_other_host: false
       end
 
-      # Whether the step being POSTed is the last visible step (so Next → Finish).
-      # Computed BEFORE advancing, since advance moves the cursor past it.
-      def wizard_posting_last_step?(runner)
-        last = runner.visible_path.last
-        last && last.key.to_s == params[:step].to_s
+      # Advance the POSTed step, finalizing when it turns out to end the flow. The
+      # advance-or-finalize decision lives in the runner because it can only be made
+      # AFTER the submission is staged — a step's `condition:` may be gated on an
+      # answer from the very step being submitted. See {Runner#submit}.
+      def advance_or_finalize(runner)
+        runner.submit(params[:step], wizard_params(runner), goto: params[:_goto].presence)
       end
 
       def respond_to_wizard_result(runner, result)
@@ -214,8 +242,26 @@ module Plutonium
         # `:return_to` (the page the user was bounced FROM into a one-time wizard)
         # still wins, so they resume where they were headed.
         clear_wizard_return_to
+        flash_wizard_messages(result.messages)
         target = session.delete(:return_to).presence || wizard_completion_url(result.value)
-        redirect_to target, status: :see_other, allow_other_host: false
+
+        respond_to do |format|
+          format.turbo_stream do
+            render turbo_stream: helpers.turbo_stream_redirect(target)
+          end
+          format.html do
+            redirect_to target, status: :see_other, allow_other_host: false
+          end
+        end
+      end
+
+      # Carry the outcome's `with_message` entries ([message, type] pairs) into the
+      # flash so the page we land on shows them. Several messages of one type are
+      # joined — writing them in a loop would leave only the last one standing.
+      def flash_wizard_messages(messages)
+        messages.group_by(&:last).each do |type, group|
+          flash[type] = group.map(&:first).join(" ")
+        end
       end
 
       # Drop a guest run's token from the Rails session (on completion). A no-op
@@ -274,6 +320,12 @@ module Plutonium
       # the step form; otherwise re-render the whole page. Mirrors interactive
       # actions, where conditional inputs depend on sibling values.
       def render_wizard_pre_submit(runner)
+        # Seed the re-render from the JUST-SUBMITTED values, so an input conditional
+        # on the changed field appears/disappears and the user's other typed values
+        # survive the swap. In-memory only — `stage_inputs` never persists, so an
+        # abandoned refresh leaves nothing durable.
+        runner.stage_inputs(runner.current_step.key, wizard_pre_submit_inputs(runner))
+
         form = wizard_step_form(runner)
         respond_to do |format|
           format.turbo_stream do
@@ -488,12 +540,38 @@ module Plutonium
       def wizard_params(runner)
         return {} if params[:wizard].blank?
 
+        cleaned = wizard_extracted_inputs(runner)
+        stage_wizard_uploads!(runner.current_step, cleaned)
+        cleaned.stringify_keys
+      end
+
+      # Like {#wizard_params} but WITHOUT staging uploads — shared with the
+      # `pre_submit` re-render, which must not stage them, or every `change` event
+      # would push the selected file to the backend cache.
+      def wizard_extracted_inputs(runner)
+        return {} if params[:wizard].blank?
+
         step = runner.current_step
         form = wizard_step_form(runner)
         extracted = form.extract_input(params, view_context:)[:wizard] || {}
-        cleaned = clean_structured_inputs(Plutonium::Wizard::StepAdapter.new(step), extracted.dup)
-        stage_wizard_uploads!(step, cleaned)
-        cleaned.stringify_keys
+        clean_structured_inputs(Plutonium::Wizard::StepAdapter.new(step), extracted.dup)
+      end
+
+      # The submitted values a `pre_submit` re-render may seed itself from.
+      #
+      # Attachment fields are EXCLUDED. Their extracted value is a raw upload — or,
+      # far more often, nothing at all, since a file input doesn't re-post on an
+      # unrelated field's `change`. Merging either over the token already staged in
+      # `data` would blank the file out of the re-rendered form, losing an upload the
+      # user had already made. Uploads only ever stage on a real submit
+      # ({#stage_wizard_uploads!}); a pre_submit leaves them exactly as they were.
+      def wizard_pre_submit_inputs(runner)
+        step = runner.current_step
+        inputs = wizard_extracted_inputs(runner).stringify_keys
+        step.inputs.each do |name, config|
+          inputs.delete(name.to_s) if Plutonium::Wizard::Attachments.field?(config)
+        end
+        inputs
       end
 
       # Replace each attachment field's value with a staged TOKEN, minting one from
@@ -528,6 +606,7 @@ module Plutonium
         step = runner.current_step
         Plutonium::UI::Form::Wizard.new(
           step:,
+          wizard: runner.wizard,
           data: Plutonium::Wizard::AttachmentData.wrap(runner.wizard.data[step.key], step),
           action: wizard_step_url(step&.key),
           fields: step.attribute_schema.keys.map(&:to_sym) + step.structured_inputs.keys.map(&:to_sym)
@@ -634,6 +713,11 @@ module Plutonium
       def wizard_step_url(step_key)
         raise NotImplementedError
       end
+
+      # @return [String] the GET URL for launching this wizard.
+      def wizard_launch_url
+        raise NotImplementedError
+      end
     end
   end
 end

data/lib/plutonium/wizard/dsl.rb

@@ -152,6 +152,29 @@ module Plutonium
           @cleanup_after = (ttl == :never) ? nil : ttl
         end
 
+        # --- presentation ---
+
+        # Width of THIS wizard's step pages, one of
+        # {Plutonium::UI::PageWidth::VALID_SIZES}. Unset inherits
+        # `config.wizards.width`, and stops there — the wizard chain does NOT
+        # reach `config.default_page_width`. A wizard is a focused,
+        # self-contained flow rather than a resource detail page, so an app
+        # that widens its resource pages should not silently drag its wizards
+        # along with them.
+        #
+        # Mirrors what a resource definition gets from `page_width`: a wizard
+        # with a wide review table or a two-column step can widen itself
+        # without the app having to move every wizard.
+        #
+        #   class CheckoutWizard < Plutonium::Wizard::Base
+        #     width :lg
+        #   end
+        def width(value = UNSET)
+          return @width || Plutonium.configuration.wizards.width if value.equal?(UNSET)
+
+          @width = Plutonium::UI::PageWidth.validate!(value)
+        end
+
         # --- concurrency (§4.2) ---
 
         # Declare the run's CONCURRENCY KEY — the value(s) a run is keyed by

data/lib/plutonium/wizard/resume.rb

@@ -36,6 +36,9 @@ module Plutonium
         :current_step_label,
         :updated_at,
         :resume_url,
+        # The DELETE target that abandons this run, resolved from the same mount as
+        # `resume_url`. nil when the mount exposes no cancel route.
+        :cancel_url,
         :resume_unresolved_reason,
         :session
       )
@@ -100,6 +103,7 @@ module Plutonium
           current_step_label: step&.label,
           updated_at: row.updated_at,
           resume_url: resolved[:url],
+          cancel_url: resolved[:cancel_url],
           resume_unresolved_reason: resolved[:reason],
           session: row
         )
@@ -111,71 +115,114 @@ module Plutonium
         wizard_class.steps.find { |s| s.key.to_s == key.to_s }
       end
 
-      # Resolves a single row to its resume URL in the current portal.
+      # Resolves a single row to its resume + cancel URLs in the current portal.
+      #
+      # Both URLs come from the SAME resolved mount, through named route helpers —
+      # the cancel target is never derived by string-surgery on the resume URL,
+      # which would drop query params and break for a run whose `current_step` is
+      # still nil (there the resume URL is the bare launch path, so lopping off its
+      # last segment yields a non-route).
       class ResumeUrl
+        # How this row's wizard is reachable in the current portal.
+        #
+        # - +:register_wizard+ — a standalone `register_wizard` mount. `subject` is
+        #   the GET route's name, resolved within `route_set`.
+        # - +:member+ — a resource-mounted ANCHORED wizard. `subject` is the anchor
+        #   record.
+        # - +:collection+ — a resource-mounted non-anchored wizard. `subject` is the
+        #   resource class whose definition registers it.
+        Mount = Struct.new(:kind, :subject, :wizard_name, :route_set)
+
         def initialize(row, wizard_class, view_context)
           @row = row
           @wizard_class = wizard_class
           @view_context = view_context
         end
 
-        # @return [Hash] {url:, reason:} — exactly one of the two is non-nil.
+        # @return [Hash] {url:, cancel_url:, reason:} — `reason` is non-nil exactly
+        #   when no resume URL could be built. The two URLs resolve INDEPENDENTLY:
+        #   a run with no `current_step` has no stepped resume URL, but is still
+        #   perfectly cancellable, and leaving the user no way to clear it would
+        #   strand the row in their chooser forever.
         def resolve
-          if (named = register_wizard_url)
-            return {url: named, reason: nil}
-          end
-
-          if (member = resource_member_url)
-            return {url: member, reason: nil}
-          end
+          return {url: nil, cancel_url: nil, reason: unresolved_reason} if mount.nil?
 
-          {url: nil, reason: unresolved_reason}
+          url = build_step_url(mount)
+          {url: url, cancel_url: build_cancel_url(mount), reason: url.nil? ? unresolved_reason : nil}
         end
 
         private
 
-        # A `register_wizard` route is named and carries `defaults[:wizard_class]`.
-        def register_wizard_url
-          route_sets.each do |route_set|
-            name = Plutonium::Wizard::RouteResolution.route_name(route_set, @wizard_class, action: "show")
-            next unless name
+        # The first mount that claims this row, in precedence order: a standalone
+        # `register_wizard` route, then the row's anchor, then a resource definition
+        # that registers this wizard as a collection (non-anchored) mount.
+        def mount
+          return @mount if defined?(@mount)
 
-            return build_url(route_set, name, register_wizard_params)
-          end
-          nil
+          @mount = register_wizard_mount || resource_member_mount || resource_collection_mount
         end
 
-        # Params for a `register_wizard` named helper: the current step, the tenant
-        # scope path segment (when the run is scoped), and the URL token for a
-        # tokened (no concurrency_key) run.
-        def register_wizard_params
-          {step: @row.current_step}.merge(scope_param).merge(token_param)
+        # A `register_wizard` route is named and carries `defaults[:wizard_class]`.
+        def register_wizard_mount
+          return @register_wizard_mount if defined?(@register_wizard_mount)
+
+          @register_wizard_mount = route_sets.filter_map { |route_set|
+            name = Plutonium::Wizard::RouteResolution.route_name(route_set, @wizard_class, action: "show")
+            Mount.new(:register_wizard, name, nil, route_set) if name
+          }.first
         end
 
-        # A resource-mounted ANCHORED wizard's member URL is built by the SAME
-        # `resource_url_for(record, wizard:, step:)` machinery the launch button uses
-        # (§5.1) — so it's portal- and scope-correct by construction (it resolves on
-        # the current portal's `current_engine`, threads the entity segment when the
-        # portal is path-scoped, and singularizes the member helper). We pass the
-        # row's anchor as the record, the registering definition's wizard name, and
-        # the resumed step; a tokened (non-keyed) run also carries its run token.
-        def resource_member_url
+        # A resource-mounted ANCHORED wizard resolves against the row's anchor and
+        # the registering definition's wizard name.
+        def resource_member_mount
           anchor = @row.anchor
           return nil if anchor.nil?
 
-          wizard_name = registered_wizard_name
+          wizard_name = registered_wizard_name_for(anchor.class)
           return nil if wizard_name.nil?
 
-          @view_context.resource_url_for(anchor, wizard: wizard_name, step: @row.current_step, **token_param)
+          Mount.new(:member, anchor, wizard_name, nil)
+        end
+
+        # A resource-mounted non-anchored (collection) wizard carries no resource
+        # identity on the row, so find it the other way round: scan this portal's
+        # registered resources for the definition that registers this wizard class.
+        #
+        # Rescued as a whole — `current_engine` is nil (or a plain Rails app with no
+        # resource register) outside a portal, and `resolve`'s contract is to report
+        # a reason rather than raise.
+        def resource_collection_mount
+          return nil unless @row.anchor.nil?
+
+          engine = @view_context.current_engine
+          return nil if engine.nil?
+
+          candidates = engine.resource_register.resources.filter_map { |resource_class|
+            name = registered_wizard_name_for(resource_class)
+            [resource_class, name] if name
+          }.sort_by { |resource_class, _name| resource_class.name }
+          return nil if candidates.empty?
+
+          if candidates.size > 1
+            Rails.logger.warn do
+              "[Plutonium::Wizard] #{@wizard_class.name} is registered on more than one resource " \
+                "definition in #{engine.name} (#{candidates.map { |klass, _| klass.name }.join(", ")}); " \
+                "resolving its resume URL against #{candidates.first.first.name}"
+            end
+          end
+
+          resource_class, wizard_name = candidates.first
+          Mount.new(:collection, resource_class, wizard_name, nil)
         rescue => e
-          Rails.logger.warn { "[Plutonium::Wizard] resume url build failed for #{@wizard_class.name}: #{e.message}" }
+          Rails.logger.warn { "[Plutonium::Wizard] collection mount lookup failed for #{@wizard_class.name}: #{e.message}" }
           nil
         end
 
         # Reverse-lookup the `wizard`-macro name registered for this wizard class on
-        # the anchor's resource definition. nil when not found.
-        def registered_wizard_name
-          definition = definition_for(@row.anchor)
+        # a resource's definition. nil when the definition can't be loaded or doesn't
+        # register this wizard.
+        def registered_wizard_name_for(resource_class)
+          definition = "#{resource_class.name}Definition".safe_constantize
           return nil unless definition.respond_to?(:registered_wizards)
 
           definition.registered_wizards.find do |_name, reg|
@@ -183,8 +230,45 @@ module Plutonium
           end&.first
         end
 
-        def definition_for(record)
-          "#{record.class.name}Definition".safe_constantize
+        # The GET URL that resumes the run at its current step.
+        #
+        # For a resource mount this is the SAME `resource_url_for(subject, wizard:,
+        # step:)` machinery the launch button uses (§5.1) — portal- and scope-correct
+        # by construction (it resolves on the current portal's `current_engine`,
+        # threads the entity segment when the portal is path-scoped, and singularizes
+        # the member helper).
+        def build_step_url(mount)
+          if mount.kind == :register_wizard
+            build_url(mount.route_set, mount.subject, register_wizard_params)
+          else
+            resource_wizard_url(mount, step: @row.current_step)
+          end
+        end
+
+        # The DELETE target that abandons the run, from the same mount's named cancel
+        # route. nil when the mount predates the cancel route (or generation fails) —
+        # the caller then renders no cancel affordance.
+        def build_cancel_url(mount)
+          if mount.kind == :register_wizard
+            name = Plutonium::Wizard::RouteResolution.route_name(mount.route_set, @wizard_class, action: "cancel")
+            name && build_url(mount.route_set, name, scope_param.merge(token_param))
+          else
+            resource_wizard_url(mount, wizard_action: :cancel)
+          end
+        end
+
+        def resource_wizard_url(mount, **extra)
+          @view_context.resource_url_for(mount.subject, wizard: mount.wizard_name, **token_param, **extra)
+        rescue => e
+          Rails.logger.warn { "[Plutonium::Wizard] url build failed for #{@wizard_class.name}: #{e.message}" }
+          nil
+        end
+
+        # Params for a `register_wizard` named helper: the current step, the tenant
+        # scope path segment (when the run is scoped), and the URL token for a
+        # tokened (no concurrency_key) run.
+        def register_wizard_params
+          {step: @row.current_step}.merge(scope_param).merge(token_param)
         end
 
         # The scope path segment for an entity-scoped portal, keyed by the portal
@@ -220,24 +304,18 @@ module Plutonium
         end
 
         def unresolved_reason
-          if @row.anchor && registered_wizard_name.nil?
+          if @row.anchor && registered_wizard_name_for(@row.anchor.class).nil?
             "no `wizard` macro registration found for #{@wizard_class.name} " \
               "on #{@row.anchor.class.name}Definition"
-          elsif @row.anchor.nil? && resource_mounted_candidate?
-            "non-anchored resource-mounted wizard — the row carries no resource " \
-              "identity to rebuild its collection URL"
+          elsif @row.anchor.nil? && register_wizard_mount.nil?
+            "non-anchored wizard — no `register_wizard` route in this portal, and no " \
+              "resource definition here registers #{@wizard_class.name}"
           else
             "no route found for #{@wizard_class.name} (not registered via " \
               "register_wizard or a `wizard` macro mount this resolver can reach)"
           end
         end
 
-        # Heuristic for the reason text only: the wizard isn't a register_wizard
-        # mount (no named route) and has no anchor on the row.
-        def resource_mounted_candidate?
-          register_wizard_url.nil?
-        end
-
         # The CURRENT portal's route set, plus the main app's (for `public:` mounts).
         # Scoped to this portal so a `register_wizard` wizard mounted in several
         # portals resolves here, not in whichever engine happens to be scanned first.

data/lib/plutonium/wizard/runner.rb

@@ -18,7 +18,7 @@ module Plutonium
       # - +completed+ — finalize ran `execute` to completion.
       # - +redirect_step+ — finalize found a completeness gap; the step to bounce to.
       # - +value+ — the successful `execute` outcome's value.
-      Result = Struct.new(:ok, :errors, :completed, :redirect_step, :value) do
+      Result = Struct.new(:ok, :errors, :completed, :redirect_step, :value, :messages) do
         def ok? = !!ok
 
         def completed? = !!completed
@@ -147,6 +147,43 @@ module Plutonium
         end
       end
 
+      # Submit the posted step: advance through it, then finalize if it turns out
+      # to be the end of the flow (§6.3). This is the driving layer's single entry
+      # point for a forward POST.
+      #
+      # "Is this the last step?" CANNOT be answered before the submission is
+      # staged. Every `condition:` is evaluated against `data`, so a step gated on
+      # an answer from the step being submitted is still hidden at POST time.
+      # Deciding first broke two shapes:
+      #
+      # - a wizard whose later steps are all revealed BY its first step saw a
+      #   visible path of just `[first]`, called it terminal, and finalized — which
+      #   found `first` unsubmitted and bounced back to it, forever. The revealed
+      #   steps were unreachable and no state was ever written.
+      # - a wizard with no `review` step finalized its last step WITHOUT staging
+      #   it, silently dropping that step's params before `execute`.
+      #
+      # So the order is stage, then look: after `advance` the cursor holds the next
+      # visible step, recomputed against the freshly staged data, and a nil cursor
+      # means nothing follows — finish. This also matches what the user sees: the
+      # nav strip renders Finish only on the review step (§7), never on a field
+      # step that merely happens to be last right now.
+      #
+      # The terminal `review` step short-circuits: it declares no fields, so there
+      # is nothing to stage and Finish runs `execute` directly.
+      def submit(step_key, params, goto: nil)
+        step = step_for(step_key)
+        return finalize if step&.review?
+
+        result = advance(step_key, params, goto:)
+        return result unless result.ok?
+        # A cursor target survives → the flow continues (including the `goto:`
+        # "Save & review" shortcut). Nil → `advance` found no next visible step.
+        return result if @state.current_step.present?
+
+        finalize
+      end
+
       # Validate + stage a step, run its `on_submit` (in a transaction), then move
       # the cursor to the next visible step. On validation/`on_submit` failure the
       # cursor does not move and the errors are returned.
@@ -243,6 +280,13 @@ module Plutonium
         true
       end
 
+      # Stage a step's params for a render-only refresh (the pre_submit re-render).
+      # Unlike `advance` it never persists, so the step isn't marked submitted and
+      # an abandoned refresh leaves nothing durable.
+      def stage_inputs(step_key, params)
+        stage(step_key, params)
+      end
+
       # Move the cursor to the previous visible step. No validation; never discards
       # staged data (§6 — back is navigation, not submission).
       def back
@@ -301,7 +345,7 @@ module Plutonium
           else
             @store.clear(@instance_key)
           end
-          Result.new(ok: true, completed: true, value: outcome.value)
+          Result.new(ok: true, completed: true, value: outcome.value, messages: outcome.messages)
         else
           revert_completing!
           Result.new(ok: false, errors: wizard_errors)

data/lib/plutonium/wizard/step_adapter.rb

@@ -26,7 +26,7 @@ module Plutonium
       # `uploader:` as an attribute, and `backend:` would otherwise leak as a stray
       # attribute. Driving reads them off `step.inputs` directly, so removing them
       # here is invisible to staging.
-      STAGING_ONLY_INPUT_OPTIONS = %i[backend uploader].freeze
+      STAGING_ONLY_INPUT_OPTIONS = Plutonium::Attachments::STAGING_ONLY_INPUT_OPTIONS
 
       def initialize(step)
         @step = step

data/lib/plutonium/wizard/sweep_job.rb

@@ -19,6 +19,22 @@ module Plutonium
     # and an unconstantizable wizard class is skipped while the row is still reaped.
     # +completed+ rows are never touched (the +sweepable+ scope excludes them).
     class SweepJob < ActiveJob::Base
+      # One sweep at a time, when the host's queue offers a semaphore.
+      #
+      # A sweep that outlives its own interval would otherwise overlap the next
+      # tick and walk the same rows. That is not merely wasteful here: two
+      # sweepers can pick up the same session and both build a Runner for it, so
+      # a step's on_rollback compensator — refund the charge, call the external
+      # API — runs twice for one abandoned run.
+      #
+      # A constant key: every sweep is the same sweep, so they queue behind each
+      # other globally rather than per row. Only +key+ and +to+ are passed;
+      # +on_conflict+ arrived in Solid Queue 1.2 and passing it would turn an
+      # older host's boot into an ArgumentError.
+      if respond_to?(:limits_concurrency)
+        limits_concurrency to: 1, key: ->(*) { "sweep" }
+      end
+
       def perform(now: Time.current)
         store = Store::ActiveRecord.new
 

data/lib/plutonium.rb

@@ -26,6 +26,15 @@ module Plutonium
   # Custom error class for Plutonium-specific exceptions
   class Error < StandardError; end
 
+  # Raised when a resource registered `singular: true` has an authorized scope
+  # that resolves to more than one record.
+  #
+  # A singular route carries no :id — the scope IS the identification — so the
+  # promise `singular: true` makes is "exactly one record here". A scope that
+  # returns several silently nests (or shows) an arbitrary row, so it fails
+  # instead. Always a registration/policy mismatch, never user input.
+  class SingularScopeError < Error; end
+
   # Turbo frame id used by the modal/slideover renderer. The layout wraps
   # itself in this frame, in_modal? checks against it, and Action and
   # Definition default to targeting it. Kept as a single constant so the
@@ -40,6 +49,18 @@ module Plutonium
 
   MODAL_FRAMES = [REMOTE_MODAL_FRAME, REMOTE_MODAL_SECONDARY_FRAME].freeze
 
+  # DOM id of the page's toast region (Layout::Base#render_flash). An action
+  # that answers a turbo_stream never renders the layout, so it never gets to
+  # consume `flash` — it appends a rendered toast to this region instead.
+  FLASH_REGION = "pu-flash"
+
+  # Query param a kanban card appends to its show URL when the board opens the
+  # card in the shared remote-modal frame. Since a kanban modal and a regular
+  # show modal both target REMOTE_MODAL_FRAME, `in_modal?` can't tell them apart
+  # — this flag lets `in_kanban_modal?` distinguish the two so the show page can
+  # render a compact detail (no metadata rail) for kanban cards only.
+  KANBAN_MODAL_PARAM = "kanban_modal"
+
   # Set up Zeitwerk loader for the Plutonium gem
   # @return [Zeitwerk::Loader] configured Zeitwerk loader instance
   Loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false).tap do |loader|