plutonium 0.64.0 → 0.65.0

data/lib/plutonium/resource/controller.rb

@@ -188,14 +188,19 @@ module Plutonium
         end
       end
 
-      # Attachment/file input names (as Strings) declared on the current
-      # definition — inputs whose `as:` is a file type (`:file`/`:uppy`/
-      # `:attachment`). Excluded from the extraction-record pre-assignment so a
-      # single-read Rack upload isn't consumed before create/update reads it.
+      # Attachment/file input names (as Strings) for the current resource —
+      # inputs declared with a file `as:` (`:file`/`:uppy`/`:attachment`)
+      # unioned with the attachments reflected on the model, so auto-detected
+      # attachments (no `input` declaration) are covered too. Excluded from the
+      # extraction-record pre-assignment so a single-read Rack upload isn't
+      # consumed before create/update reads it.
       def attachment_input_keys
-        current_definition.defined_inputs.filter_map { |name, config|
+        declared = current_definition.defined_inputs.filter_map { |name, config|
           name.to_s if Plutonium::Definition::InputAliases.file_input?(config.dig(:options, :as))
         }
+        reflected = (resource_class.has_one_attached_field_names + resource_class.has_many_attached_field_names)
+          .map(&:to_s)
+        declared | reflected
       end
 
       # Returns the resource parameters, including scoped and parent parameters

data/lib/plutonium/resource/controllers/crud_actions.rb

@@ -36,7 +36,7 @@ module Plutonium
         # GET /resources/new
         def new
           authorize_current! resource_class
-          set_page_title "Create #{resource_class.model_name.human.titleize}"
+          set_page_title t("plutonium.resource.titles.new", resource: resource_class.model_name.human)
 
           @resource_record = build_resource_record
           maybe_apply_submitted_resource_params!
@@ -47,7 +47,7 @@ module Plutonium
         # POST /resources(.{format})
         def create
           authorize_current! resource_class
-          set_page_title "Create #{resource_class.model_name.human.titleize}"
+          set_page_title t("plutonium.resource.titles.new", resource: resource_class.model_name.human)
 
           @resource_record = build_resource_record resource_params
 
@@ -57,13 +57,13 @@ module Plutonium
               format.html { render :new, status: :unprocessable_content }
             elsif resource_record!.save
               after_create_persisted
+              notice = t("plutonium.resource.created", resource: resource_class.model_name.human)
               format.turbo_stream do
-                flash.notice = "#{resource_class.model_name.human} was successfully created."
+                flash.notice = notice
                 render turbo_stream: stacked_modal_create_streams
               end
               format.html do
-                redirect_to redirect_url_after_submit,
-                  notice: "#{resource_class.model_name.human} was successfully created."
+                redirect_to redirect_url_after_submit, notice:
               end
               format.any do
                 @current_policy = nil # Reset cached policy so it uses the instance instead of class
@@ -85,7 +85,7 @@ module Plutonium
         # GET /resources/1/edit
         def edit
           authorize_current! resource_record!
-          set_page_title "Update #{resource_record!.to_label.titleize}"
+          set_page_title t("plutonium.resource.titles.edit", record: resource_record!.to_label.titleize)
 
           maybe_apply_submitted_resource_params!
 
@@ -95,7 +95,7 @@ module Plutonium
         # PATCH/PUT /resources/1(.{format})
         def update
           authorize_current! resource_record!
-          set_page_title "Update #{resource_record!.to_label.titleize}"
+          set_page_title t("plutonium.resource.titles.edit", record: resource_record!.to_label.titleize)
 
           resource_record!.attributes = resource_params
 
@@ -104,14 +104,13 @@ module Plutonium
               format.turbo_stream { render turbo_stream: turbo_stream.replace(helpers.turbo_scoped_dom_id("resource-form"), view_context.render(build_form(action: :edit))) }
               format.html { render :edit, status: :unprocessable_content }
             elsif resource_record!.save
+              notice = t("plutonium.resource.updated", resource: resource_class.model_name.human)
               format.turbo_stream do
-                flash.notice = "#{resource_class.model_name.human} was successfully updated."
+                flash.notice = notice
                 render turbo_stream: helpers.turbo_stream_redirect(redirect_url_after_submit)
               end
               format.html do
-                redirect_to redirect_url_after_submit,
-                  notice: "#{resource_class.model_name.human} was successfully updated.",
-                  status: :see_other
+                redirect_to redirect_url_after_submit, notice:, status: :see_other
               end
               format.any do
                 render :show, status: :ok, location: redirect_url_after_submit
@@ -134,29 +133,27 @@ module Plutonium
           respond_to do |format|
             resource_record!.destroy
 
+            notice = t("plutonium.resource.deleted", resource: resource_class.model_name.human)
             format.turbo_stream do
-              flash.notice = "#{resource_class.model_name.human} was successfully deleted."
+              flash.notice = notice
               render turbo_stream: helpers.turbo_stream_redirect(redirect_url_after_destroy)
             end
             format.html do
-              redirect_to redirect_url_after_destroy,
-                notice: "#{resource_class.model_name.human} was successfully deleted."
+              redirect_to redirect_url_after_destroy, notice:
             end
             format.json { head :no_content }
           rescue ActiveRecord::InvalidForeignKey, ActiveRecord::DeleteRestrictionError
+            alert = t("plutonium.resource.referenced", resource: resource_class.model_name.human)
             format.turbo_stream do
-              flash.alert = "#{resource_class.model_name.human} is referenced by other records."
+              flash.alert = alert
               render turbo_stream: helpers.turbo_stream_redirect(resource_url_for(resource_record!))
             end
             format.html do
-              redirect_to resource_url_for(resource_record!),
-                alert: "#{resource_class.model_name.human} is referenced by other records."
+              redirect_to resource_url_for(resource_record!), alert:
             end
             format.any do
               @errors = ActiveModel::Errors.new resource_record!
-              @errors.add :base,
-                :existing_references,
-                message: "is referenced by other records"
+              @errors.add :base, :existing_references
 
               render "errors", status: :unprocessable_content
             end

data/lib/plutonium/resource/controllers/export_csv.rb

@@ -37,12 +37,6 @@ module Plutonium
         # Collections rendered here preload what they are about to show.
         include Plutonium::Resource::Controllers::EagerLoading
 
-        # Placeholder written when a column is neither an `export` block nor a
-        # real attribute on the record, so the export degrades to a usable file
-        # instead of a mid-stream NoMethodError (which would truncate the
-        # already-committed download).
-        INVALID_COLUMN = "<<invalid column>>"
-
         included do
           before_action :authorize_export_csv!, only: :export_csv
           # Row-level authorization is the scope itself
@@ -121,9 +115,17 @@ module Plutonium
         # A cell beginning with = + - @ (or a leading tab/CR) is executed as a
         # formula by Excel/Sheets. Prefix it with a single quote so the value
         # imports as literal text (CSV/formula injection).
+        #
+        # The leading-character check runs against the NFKC-normalized string so
+        # that full-width (double-byte) variants — ＝ ＋ － ＠ (U+FF1D/FF0B/FF0D/FF20) —
+        # which East Asian locales (e.g. Japanese Excel) treat as formula
+        # initiators, are also neutralized. The *original* string is prefixed
+        # (not the normalized one), so legitimate full-width content is preserved
+        # verbatim and only gains a defensive leading quote.
         def neutralize_csv_formula(value)
           string = value.to_s
-          /\A[=+\-@\t\r]/.match?(string) ? "'#{string}" : string
+          normalized = string.unicode_normalize(:nfkc)
+          /\A[=+\-@\t\r]/.match?(normalized) ? "'#{string}" : string
         end
 
         # The primary key is always the first column, followed by the
@@ -143,7 +145,7 @@ module Plutonium
         # Associations render as their display label — the same as the index —
         # instead of "#<User:0x…>"; scalars pass through untouched. A name that
         # is neither an `export` block nor a real attribute renders the
-        # INVALID_COLUMN placeholder rather than aborting the stream.
+        # invalid-column placeholder rather than aborting the stream.
         def export_csv_value(record, name)
           definition = current_definition.defined_exports[name]
           return definition[:block].call(record) if definition && definition[:block]
@@ -151,7 +153,7 @@ module Plutonium
           begin
             value = record.public_send(name)
           rescue NoMethodError
-            return INVALID_COLUMN
+            return invalid_column_placeholder
           end
 
           case value
@@ -165,6 +167,14 @@ module Plutonium
           definition = current_definition.defined_exports[name]
           definition&.dig(:options, :label) || name.to_s.humanize
         end
+
+        # Placeholder written when a column is neither an `export` block nor a
+        # real attribute on the record, so the export degrades to a usable file
+        # instead of a mid-stream NoMethodError (which would truncate the
+        # already-committed download).
+        def invalid_column_placeholder
+          @invalid_column_placeholder ||= I18n.t("plutonium.resource.export_csv.invalid_column")
+        end
       end
     end
   end

data/lib/plutonium/resource/controllers/kanban_actions.rb

@@ -114,7 +114,7 @@ module Plutonium
           if from && !record_in_kanban_column?(record, from)
             return render_kanban_rejection(
               params[:from_column],
-              reason: "This card is no longer in “#{from.label}”."
+              reason: t("plutonium.kanban.move.not_in_column", column: from.label)
             )
           end
 
@@ -123,11 +123,11 @@ module Plutonium
           unless from && to&.accepts?(from.key) && !from.locked?
             reason =
               if from&.locked?
-                "Cards can't be moved out of “#{from.label}”."
+                t("plutonium.kanban.move.locked_source", column: from.label)
               elsif to
-                "Cards can't be moved into “#{to.label}”."
+                t("plutonium.kanban.move.not_accepted", column: to.label)
               else
-                "This card can't be moved there."
+                t("plutonium.kanban.move.not_allowed")
               end
             return render_kanban_rejection(params[:from_column], reason:)
           end
@@ -151,7 +151,7 @@ module Plutonium
           if to.wip && from.key != to.key && dest_cards.size + 1 > to.wip
             return render_kanban_rejection(
               params[:from_column],
-              reason: "“#{to.label}” is at its WIP limit (#{to.wip})."
+              reason: t("plutonium.kanban.move.wip_limit_reached", column: to.label, wip: to.wip)
             )
           end
 
@@ -180,7 +180,7 @@ module Plutonium
           # board. (Static boards always register — see Definition::IndexViews.)
           if run_enter_interaction && current_definition.defined_actions[to.enter_interaction_key].nil?
             Rails.logger.warn { "[plutonium] kanban enter_interaction on column `#{to.key}` is not registered — enter_interaction is unsupported on dynamic (`columns do…end`) boards; rejecting the drop." }
-            return render_kanban_rejection(params[:from_column], reason: "This drop can’t be completed.")
+            return render_kanban_rejection(params[:from_column], reason: t("plutonium.kanban.move.drop_incomplete"))
           end
 
           # An input-less drop interaction is `immediate` — the client commits it
@@ -304,7 +304,7 @@ module Plutonium
             # fix the input and resubmit.
             if drop_immediate
               reason = @interaction.errors.full_messages.to_sentence.presence ||
-                "“#{to.label}” could not be applied."
+                t("plutonium.kanban.move.enter_interaction_failed", column: to.label)
               return render_kanban_rejection(from.key, reason:)
             end
             return render :kanban_move_form, formats: [:html], **modal_render_options, status: :unprocessable_content
@@ -373,7 +373,7 @@ module Plutonium
           skip_verify_authorize_current!
           render_kanban_rejection(
             params[:from_column],
-            reason: "You are not authorized to move this card there.",
+            reason: t("plutonium.kanban.move.unauthorized"),
             status: :forbidden
           )
         rescue ActiveRecord::RecordNotFound
@@ -384,13 +384,13 @@ module Plutonium
           # `find` raised before authorize_current!, so satisfy that verifier; the
           # scope verifier is already satisfied by kanban_base_relation.
           skip_verify_authorize_current!
-          render_kanban_rejection(params[:from_column], reason: "This card no longer exists.")
+          render_kanban_rejection(params[:from_column], reason: t("plutonium.kanban.move.record_missing"))
         rescue ActiveRecord::RecordInvalid => e
           # An on_exit/on_enter hook (or the interaction) left the record invalid,
           # so save! raised and the transaction rolled back. Snap back with the
           # validation reason rather than let a 500 HTML page morph into the board.
           reason = e.record.errors.full_messages.to_sentence.presence ||
-            "This card could not be moved."
+            t("plutonium.kanban.move.record_invalid")
           render_kanban_rejection(params[:from_column], reason:)
         end
 
@@ -437,15 +437,15 @@ module Plutonium
           if from && !record_in_kanban_column?(record, from)
             return render_kanban_rejection(
               params[:from_column],
-              reason: "This card is no longer in “#{from.label}”."
+              reason: t("plutonium.kanban.move.not_in_column", column: from.label)
             )
           end
           unless from && to.accepts?(from.key) && !from.locked?
             reason =
               if from&.locked?
-                "Cards can't be moved out of “#{from.label}”."
+                t("plutonium.kanban.move.locked_source", column: from.label)
               else
-                "Cards can't be moved into “#{to.label}”."
+                t("plutonium.kanban.move.not_accepted", column: to.label)
               end
             return render_kanban_rejection(params[:from_column], reason:)
           end
@@ -473,7 +473,7 @@ module Plutonium
           skip_verify_authorize_current!
           render_kanban_rejection(
             params[:from_column],
-            reason: "You are not authorized to move this card there.",
+            reason: t("plutonium.kanban.move.unauthorized"),
             status: :forbidden
           )
         rescue ActiveRecord::RecordNotFound
@@ -527,7 +527,7 @@ module Plutonium
         # from the block for safety and dynamic edge cases.
         def current_kanban_board
           @current_kanban_board ||= current_definition.defined_kanban_board ||
-            Plutonium::Kanban::DSL.build(&current_definition.defined_kanban_block)
+            Plutonium::Kanban::DSL.build(resource_class: resource_class, &current_definition.defined_kanban_block)
         end
 
         # Authorized + query-applied UN-paginated relation.
@@ -799,7 +799,7 @@ module Plutonium
           apply_kanban_column_enter!(resource_record!, column)
         rescue => e
           Rails.logger.error { "[plutonium] kanban quick-add on_enter failed for column #{params[:kanban_column].inspect}: #{e.class}: #{e.message}\n#{e.backtrace&.join("\n")}" }
-          flash[:alert] = "Couldn’t place it in “#{column&.label || params[:kanban_column]}” — it stayed in its default column."
+          flash[:alert] = t("plutonium.kanban.quick_add.default_column_fallback", column: column&.label || params[:kanban_column])
         end
 
         # Applies a column's on_enter to an already-persisted record, then appends

data/lib/plutonium/resource/controllers/position_actions.rb

@@ -91,7 +91,7 @@ module Plutonium
           # writing a position derived from neighbours that never implied one.
           if config.delegate? && !current_query_object.sorted_ascending_only_by?(config.attribute)
             return render_position_reconciliation(
-              reason: "Reordering is only available while the list is sorted by #{config.attribute.to_s.humanize.downcase}."
+              reason: t("plutonium.positioning.reposition.foreign_sort", attribute: config.attribute.to_s.humanize.downcase)
             )
           end
 
@@ -168,17 +168,17 @@ module Plutonium
           end
 
           render_position_reconciliation(
-            reason: "You are not authorized to reorder this.",
+            reason: t("plutonium.positioning.reposition.unauthorized"),
             status: :forbidden
           )
         rescue ActiveRecord::RecordNotFound
           # The row was destroyed between render and drop. `find` raised before
           # authorize_current!, so satisfy that verifier explicitly.
           skip_verify_authorize_current!
-          render_position_reconciliation(reason: "This record no longer exists.")
+          render_position_reconciliation(reason: t("plutonium.positioning.reposition.record_missing"))
         rescue ActiveRecord::RecordInvalid => e
           reason = e.record.errors.full_messages.to_sentence.presence ||
-            "This record could not be moved."
+            t("plutonium.positioning.reposition.record_invalid")
           render_position_reconciliation(reason:)
         end
 
@@ -223,7 +223,7 @@ module Plutonium
         # says "the same product" rather than restating the column.
         def position_foreign_group_reason(record)
           scope = record.class.positioning_scope_attr.to_s.delete_suffix("_id").humanize.downcase
-          "Reordering only works within the same #{scope}."
+          t("plutonium.positioning.reposition.foreign_group", group: scope)
         end
 
         # Fills in a neighbour the CLIENT could not see.

data/lib/plutonium/resource/controllers/typeahead.rb

@@ -140,8 +140,14 @@ module Plutonium
         # gets useful typeahead without declaring `search`). If neither
         # search block nor fallback column is available, the relation is
         # returned unfiltered (capped).
+        #
+        # The input's `scope:` (set on the Association filter) narrows the
+        # relation BEFORE authorization — mirroring ResourceSelect so the
+        # dropdown and typeahead present the same candidate set (a
+        # filtered subset rather than all policy-permitted records).
         def filter_association(klass, query, options)
-          relation = options[:skip_authorization] ? klass.all : authorized_resource_scope(klass)
+          relation = apply_scope(klass.all, options[:scope])
+          relation = options[:skip_authorization] ? relation : authorized_resource_scope(klass, relation: relation)
           if query.present?
             if (search_block = associated_definition_search_block(klass))
               relation = search_block.call(relation, query)
@@ -154,6 +160,23 @@ module Plutonium
           relation.limit(Typeahead::TYPEAHEAD_LIMIT + 1).to_a
         end
 
+        # Applies an optional association scope to a relation. Identical to
+        # ResourceSelect#apply_scope so dropdown and typeahead agree.
+        #   Symbol → relation.public_send(sym)   (named scope, e.g. :verified)
+        #   Proc   → arity 0  → relation.instance_exec(&scope) (kanban form: -> { where(...) })
+        #          → arity ≥1 → scope.call(relation)             (documented form: ->(s) { s.verified })
+        #   nil    → relation unchanged
+        # The arity dispatch matches call_option_proc (Form::Resource). Unsupported
+        # types fail loud rather than silently doing nothing.
+        def apply_scope(relation, scope)
+          case scope
+          when Symbol then relation.public_send(scope)
+          when Proc then scope.arity.zero? ? relation.instance_exec(&scope) : scope.call(relation)
+          when nil then relation
+          else raise ArgumentError, "Unsupported association scope: #{scope.inspect} (expected Symbol, Proc, or nil)"
+          end
+        end
+
         # Resolves the associated resource's `search` block, if declared.
         # Goes through `resource_definition` so portal/package namespacing
         # is honored (same fallback chain as the rest of the controller).

data/lib/plutonium/resource/query_object.rb

@@ -13,10 +13,29 @@ module Plutonium
 
       attr_accessor :default_sort_config, :default_scope_name
 
+      # Keys the query object reserves under the `q` namespace for built-in
+      # controls (e.g. `q[scope]`, `q[sort_fields]`). A filter sharing one of
+      # these names would collide with the control in the URL and in the filter
+      # form's hidden state, so defining one is rejected — see #define_filter.
+      RESERVED_FILTER_NAMES = %i[search scope sort_fields sort_directions].freeze
+
       # Initializes a QueryObject with the given resource_class and parameters.
       #
       # @param resource_class [Object] The resource class.
       # @param params [Hash] The parameters for initialization.
+      # The model this query object filters, for label conventions keyed by model.
+      attr_reader :resource_class
+
+      # Display label for a filter: its own `label` when it is a Filter (an
+      # explicit `label:` or the plutonium.filters.<model>.<name> convention),
+      # else the convention, else the humanized name.
+      def filter_label(name)
+        filter = filter_definitions[name]
+        return filter.label if filter.is_a?(Plutonium::Query::Filter)
+
+        Plutonium::Translation.label_for(:filter, resource_class, name) || name.to_s.humanize
+      end
+
       def initialize(resource_class, params, request_path, &)
         @resource_class = resource_class
         @params = params
@@ -32,7 +51,13 @@ module Plutonium
       #
       # @param name [Symbol] The name of the filter.
       # @param body [Proc, nil] The body of the filter.
+      # @raise [ArgumentError] if the name collides with a reserved query control.
       def define_filter(name, body, &)
+        if RESERVED_FILTER_NAMES.include?(name.to_sym)
+          raise ArgumentError,
+            "filter name :#{name} is reserved — the query string uses q[#{name}] as a " \
+            "built-in control (one of: #{RESERVED_FILTER_NAMES.join(", ")}). Rename the filter."
+        end
         filter_definitions[name] = build_query(body, &)
       end
 
@@ -170,7 +195,9 @@ module Plutonium
               next if humanized.blank?
               humanized
             else
-              entries.map { |k, v| "#{k.to_s.humanize.downcase} #{v}" }.join(", ")
+              entries.map { |k, v|
+                Plutonium::Translation.t("plutonium.query.active_filter.input_value", input: k.to_s.humanize.downcase, value: v)
+              }.join(", ")
             end
           when Array
             entries = filter_params.reject(&:blank?)
@@ -187,7 +214,7 @@ module Plutonium
 
           {
             name: name,
-            label: name.to_s.humanize,
+            label: filter_label(name),
             value_label: value_label,
             clear_url: build_url(name => nil)
           }
@@ -242,7 +269,7 @@ module Plutonium
 
       private
 
-      attr_reader :resource_class, :params, :selected_sort_fields, :selected_sort_directions, :selected_scope_filter
+      attr_reader :params, :selected_sort_fields, :selected_sort_directions, :selected_scope_filter
 
       # Defines standard queries for search and scope.
       def define_standard_queries

data/lib/plutonium/routing/dashboard_registration.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Routing
+    # Adds `register_dashboard` to the routing mapper, mirroring
+    # `register_wizard`. A dashboard is portal-hosted: its routes are drawn
+    # inside the engine's `routes.draw` block, so they inherit the portal's
+    # scope, auth and layout, and dispatch to a synthesized portal-namespaced
+    # `DashboardsController` that includes {Plutonium::Dashboard::Controller}.
+    #
+    # @example inside a portal engine's routes
+    #   AdminPortal::Engine.routes.draw do
+    #     register_dashboard HomeDashboard, at: "/"        # the portal root
+    #     register_dashboard SalesDashboard, at: "sales"   # /dashboards/sales
+    #   end
+    #
+    # Draws (portal-relative):
+    #   GET /dashboards/sales             → DashboardsController#show   (sales_dashboard_path)
+    #   GET /dashboards/sales/cards/:card → DashboardsController#card   (sales_dashboard_card_path)
+    #
+    # Every path sits under the `dashboards/` segment, so a dashboard can never
+    # shadow (or be shadowed by) a `register_resource` route of the same name:
+    # `at: "sales"` and a `Sale` resource would otherwise both claim `/sales`.
+    # `prefix: nil` turns the segment off for a mount (`/sales`), and a string
+    # swaps it (`prefix: "reports"` → `/reports/sales`).
+    #
+    # A root mount draws `root` for the page and `/dashboards/<name>/cards/:card`
+    # for the cards, where `<name>` is `as:` or the class slug
+    # (`HomeDashboard` → `home`).
+    module DashboardRegistration
+      DASHBOARD_CONTROLLER_NAME = "dashboards"
+      DASHBOARD_PATH_SEGMENT = "dashboards"
+
+      # @param dashboard_class [Class] a Plutonium::Dashboard::Base subclass
+      # @param at [String] the path under the prefix; "/" (or "") mounts at the root
+      # @param as [String, Symbol, nil] override the route helper prefix
+      # @param prefix [String, nil] the leading path segment, "dashboards" by
+      #   default; nil (or "") draws the mount at the bare `at:` path
+      def register_dashboard(dashboard_class, at:, as: nil, prefix: DASHBOARD_PATH_SEGMENT)
+        unless dashboard_class.is_a?(Class) && dashboard_class < Plutonium::Dashboard::Base
+          raise ArgumentError, "register_dashboard: #{dashboard_class.inspect} must subclass Plutonium::Dashboard::Base"
+        end
+
+        engine = dashboard_route_engine
+        raise ArgumentError, "register_dashboard: routes must be drawn on a Plutonium engine or the application" if engine.nil?
+
+        mount_path = strip_slashes(at)
+        prefix = strip_slashes(prefix)
+        root = mount_path.empty?
+        helper_name = (as || mount_path.presence || dashboard_class.route_name).to_s.tr("/", "_")
+        defaults = {dashboard_class: dashboard_class.name}
+
+        ensure_dashboard_controller!(engine)
+        engine.dashboard_register.register(dashboard_class)
+
+        controller = DASHBOARD_CONTROLLER_NAME
+        if root
+          get "/", to: "#{controller}#show", as: :root, defaults: defaults
+        else
+          get File.join(prefix, mount_path), to: "#{controller}#show", as: :"#{helper_name}_dashboard", defaults: defaults
+        end
+
+        cards_path = File.join(prefix, root ? helper_name : mount_path, "cards/:card")
+        get cards_path, to: "#{controller}#card", as: :"#{helper_name}_dashboard_card", defaults: defaults
+      end
+
+      private
+
+      # Possessive quantifiers (`/++`) so stripping the slashes can't backtrack:
+      # a plain `/+\z` is O(n²) on a string of many slashes (rb/polynomial-redos).
+      def strip_slashes(path)
+        path.to_s.sub(%r{\A/++}, "").sub(%r{/++\z}, "")
+      end
+
+      # Resolve (creating if needed) the controller the routes dispatch to:
+      # `<Portal>::DashboardsController` on a portal, `::DashboardsController`
+      # on the main app. An app-defined class of that name wins.
+      def ensure_dashboard_controller!(engine)
+        portal_module = dashboard_portal_module(engine)
+        if portal_module.nil?
+          define_dashboard_controller(Object, "DashboardsController", "ApplicationController", nil)
+        else
+          define_dashboard_controller(
+            portal_module,
+            "DashboardsController",
+            "#{portal_module.name}::PlutoniumController",
+            "#{portal_module.name}::Concerns::Controller"
+          )
+        end
+      end
+
+      # Synthesize the controller unless the app defines one. A controller this
+      # module synthesized earlier is rebuilt when its parent has been reloaded
+      # (development), so it never keeps serving a stale `PlutoniumController`.
+      def define_dashboard_controller(namespace, const_name, parent_name, concern_name)
+        parent = parent_name.safe_constantize || ActionController::Base
+
+        if namespace.const_defined?(const_name, false)
+          existing = namespace.const_get(const_name, false)
+          return existing unless existing.instance_variable_get(:@plutonium_synthesized) && existing.superclass != parent
+
+          namespace.send(:remove_const, const_name)
+        end
+
+        klass = Class.new(parent) do
+          include Plutonium::Dashboard::Controller
+        end
+        klass.instance_variable_set(:@plutonium_synthesized, true)
+        namespace.const_set(const_name, klass)
+
+        # `Class.new(parent)` fires Rails' `inherited` hook while the class is
+        # still anonymous, so `module_parents` finds no engine and the hook
+        # includes the *application's* URL helpers over the portal's. Include
+        # the portal's again, last, so bare helpers (`root_path` in the
+        # sidebar) resolve against the engine like a source-defined controller.
+        klass.include(namespace.railtie_routes_url_helpers) if namespace != Object
+
+        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 dashboard_route_engine
+        rs = respond_to?(:route_set) ? route_set : @set
+        rs.respond_to?(:engine) ? rs.engine : nil
+      end
+
+      def dashboard_portal_module(engine)
+        return nil if engine == Rails.application.class
+
+        engine.module_parent
+      end
+    end
+  end
+end

data/lib/plutonium/routing/resource_registration.rb

@@ -10,6 +10,11 @@ module Plutonium
         def resource_register
           @resource_register ||= Plutonium::Resource::Register.new
         end
+
+        # Dashboards mounted on this engine with `register_dashboard`.
+        def dashboard_register
+          @dashboard_register ||= Plutonium::Dashboard::Register.new
+        end
       end
     end
   end

data/lib/plutonium/routing/route_set_extensions.rb

@@ -25,6 +25,7 @@ module Plutonium
         if engine
           resource_route_config_lookup.clear
           engine.resource_register.clear
+          engine.dashboard_register.clear
         end
 
         super
@@ -36,7 +37,7 @@ module Plutonium
       # @return [void]
       # @yield Executes the given block in the context of route drawing.
       def draw(&block)
-        if self.class.supported_engine?(engine)
+        if engine && self.class.supported_engine?(engine)
           scope_params = entity_scope_params_for_path_strategy
           ActiveSupport::Notifications.instrument("plutonium.resource_routes.draw", app: engine.to_s) do
             super do