plutonium 0.50.0 → 0.51.0

data/docs/superpowers/specs/2026-05-13-docs-restructure-design.md

@@ -0,0 +1,186 @@
+# Docs Restructure & Compaction Design
+
+**Date:** 2026-05-13
+**Status:** Draft — awaiting approval
+
+## Problem
+
+Following the skill consolidation (19 → 8 skills, ~37% volume cut), the `docs/` site is misaligned in two ways:
+
+1. **Reference structure** mirrors the OLD skill structure (separate `model/`, `definition/`, `policy/`, `controller/`, `interaction/`, `views/`, `assets/`, `portal/`, `generators/`). It should mirror the new 7 functional areas.
+2. **Concept/task split is muddled.** Some "guides" are really concept explanations (e.g. `guides/authorization.md` overlaps `reference/policy/`). Some concepts have NO reference home (auth, tenancy, testing — they live in `guides/` only).
+
+## Goals
+
+**Primary goal: quality.** Volume reduction is incidental.
+
+1. Restructure `reference/` to mirror the 7 functional areas from the skill consolidation — so readers can predict where to look.
+2. Establish a clean role split: **guides = task recipes ("how do I X")**, **reference = concept lookup ("what does X do")**. Some duplication is fine when framed as different entry points; tables of options live in ONE place.
+3. Improve every page on these axes:
+   - **Right place** — concepts in reference, recipes in guides.
+   - **Right structure** — 🚨 callouts at top for "you'll regret this" rules; option/decision tables for scannability; decision rules over generic exhortations.
+   - **Right content** — keep WHY explanations that help reason about edge cases; cut marketing copy and empty "best practices" exhortations; verify technical accuracy as we go (the skill work caught real bugs — same energy).
+4. Light pass on the tutorial — preserve narrative flow; improve clarity where prose is unclear.
+
+## Non-Goals
+
+- Restructuring `getting-started/` navigation (the tutorial arc stays).
+- Changing VitePress theme, search provider, or build pipeline.
+- Adding new content beyond reorganizing what exists.
+
+## Current state
+
+40 markdown files, ~13,222 lines.
+
+| Area | Files | Notes |
+|---|---|---|
+| `getting-started/` | 11 | Index + installation + 8-step tutorial. Narrative learning arc. |
+| `guides/` | 14 | Task-oriented but inconsistent — some concept-heavy. |
+| `reference/` | 16 | Concept-by-concept, mirrors the OLD skill structure. |
+
+## Target reference structure (mirrors 7 skill areas)
+
+```
+reference/
+├── index.md          ← rewritten overview, links to the 7 areas
+├── app/
+│   ├── index.md      ← installation, configuration
+│   ├── packages.md   ← feature + portal packages
+│   ├── portals.md    ← portal engines, mounting, route registration
+│   └── generators.md ← full generator catalog
+├── resource/
+│   ├── index.md      ← overview, the 4 layers
+│   ├── model.md      ← `Plutonium::Resource::Record`, has_cents, SGID, routing (merges current model/)
+│   ├── definition.md ← field/input/display/column, page chrome (merges current definition/index + fields)
+│   ├── query.md      ← search, filters, scopes, sort
+│   └── actions.md    ← custom + bulk actions
+├── behavior/
+│   ├── index.md      ← overview, the controller/policy/interaction trio
+│   ├── controllers.md ← hooks, key methods, presentation
+│   ├── policies.md   ← actions, permitted attributes, associations, relation_scope
+│   └── interactions.md ← structure, outcomes, chaining, URL generation
+├── ui/
+│   ├── index.md      ← overview
+│   ├── pages.md      ← IndexPage/ShowPage/NewPage/EditPage, hooks
+│   ├── forms.md      ← field builder, layouts, theming, association inputs (current views/forms.md)
+│   ├── displays.md   ← Display class, custom rendering
+│   ├── tables.md     ← Table class, customization
+│   ├── components.md ← component kit, custom Phlex components
+│   ├── layouts.md    ← shell, eject, ResourceLayout
+│   └── assets.md     ← Tailwind config, Stimulus, design tokens, .pu-* classes (current assets/)
+├── auth/             ← NEW (currently only in guides/)
+│   ├── index.md      ← Rodauth overview
+│   ├── accounts.md   ← basic, admin, SaaS account types
+│   └── profile.md    ← profile resource, SecuritySection
+├── tenancy/          ← NEW (currently spread across guides/)
+│   ├── index.md      ← overview, three pieces (portal/policy/model)
+│   ├── entity-scoping.md ← associated_with, three model shapes
+│   ├── nested-resources.md ← parent/child routes, scoping
+│   └── invites.md    ← invitation system
+└── testing/          ← NEW (currently only in guides/)
+    ├── index.md
+    ├── crud.md
+    ├── policy.md
+    ├── nested.md
+    ├── portal-access.md
+    └── auth-helpers.md
+```
+
+### Content migrations
+
+| Current file | Goes to |
+|---|---|
+| `reference/model/index.md` + `features.md` | `reference/resource/model.md` |
+| `reference/definition/index.md` + `fields.md` | `reference/resource/definition.md` |
+| `reference/definition/query.md` | `reference/resource/query.md` |
+| `reference/definition/actions.md` | `reference/resource/actions.md` |
+| `reference/controller/index.md` | `reference/behavior/controllers.md` |
+| `reference/policy/index.md` | `reference/behavior/policies.md` |
+| `reference/interaction/index.md` | `reference/behavior/interactions.md` |
+| `reference/views/index.md` | split → `pages.md`, `displays.md`, `tables.md`, `components.md`, `layouts.md` |
+| `reference/views/forms.md` | `reference/ui/forms.md` |
+| `reference/assets/index.md` | `reference/ui/assets.md` |
+| `reference/portal/index.md` | `reference/app/portals.md` |
+| `reference/generators/index.md` | `reference/app/generators.md` |
+| `getting-started/installation.md` | concept part → `reference/app/index.md`; task part stays |
+| `guides/authentication.md` | concept part → `reference/auth/index.md` + `accounts.md`; recipe stays |
+| `guides/user-profile.md` | concept part → `reference/auth/profile.md`; recipe stays |
+| `guides/multi-tenancy.md` | concept part → `reference/tenancy/entity-scoping.md`; recipe stays |
+| `guides/nested-resources.md` | concept part → `reference/tenancy/nested-resources.md`; recipe stays |
+| `guides/user-invites.md` | concept part → `reference/tenancy/invites.md`; recipe stays |
+| `guides/testing.md` | concept part → `reference/testing/*`; recipe stays |
+| `guides/creating-packages.md` | concept part → `reference/app/packages.md`; recipe stays |
+
+## Guides restructure
+
+Each guide becomes a clean **task recipe**:
+
+- Single goal stated at the top ("Add authentication to your app")
+- Numbered step-by-step
+- Each step links to the relevant reference page for "why" and "what else"
+- No exhaustive option tables (those live in reference)
+- ~50-150 lines each, down from ~300-600
+
+Keep the 14 guides at their current paths so external links don't break.
+
+## Editing principles (quality-first)
+
+Not "cut everything"; cut what doesn't earn its keep. Specifically:
+
+**Cut:**
+- Marketing copy ("Plutonium is awesome because…").
+- Empty "best practices" exhortations ("write clean code", "test your code").
+- Content duplicated across pages — one canonical home + cross-link.
+- Verbose prose where a 10-line snippet shows the same thing.
+- Rails-101 explanations that don't set up a Plutonium twist.
+
+**Keep — and add more of:**
+- **WHY explanations** that help readers reason about edge cases.
+- **Non-obvious gotchas** — the dangerous-default stuff that bites people.
+- **Decision rules** ("use X when you need Y") over generic exhortations.
+- **Option / field / DSL tables** — readers scan them, they don't read prose.
+- **Inline code examples** that work — copy-pasteable, no `...` stand-ins.
+- **🚨 callouts at top of each page** for the "you'll regret this" rules.
+
+**Verify as we go.** The skill work caught real bugs (auto-detection rules, association input behavior, action visibility flags, `views` DSL naming). Same energy here — when prose claims X, check the source.
+
+## Tutorial compaction pass
+
+Same cuts as above, but preserve:
+
+- Step structure (1-8 stays)
+- Narrative flow (one step builds on the next)
+- Frequent "expected output" / "verify" callouts
+- Screenshots and visuals (keep all references)
+
+Target: 10-20% volume reduction without losing pedagogical value.
+
+## VitePress sidebar rewrite
+
+`.vitepress/config.ts` sidebar rewritten for the new structure. Three sidebars:
+
+- `/getting-started/` — unchanged
+- `/guides/` — same 14 entries, reorganized into the 7 functional groups
+- `/reference/` — new 7-area structure
+
+## Rollout
+
+1. **Pilot one reference area** — pick `reference/resource/` (largest, most-read). Build it from scratch using the merged skills as the template. Get user feedback on shape.
+2. **Build out the other 6 areas** — one at a time or in parallel, your call.
+3. **Move concept content** from guides into reference. Hollow guides become recipes.
+4. **Tutorial compaction pass** — minimal, last.
+5. **Rewrite VitePress sidebar** — once all paths exist.
+6. **Delete old reference directories** — `model/`, `definition/`, `policy/`, etc. — in one sweep after everything's in place.
+7. **Build the site locally** — verify no dead links, search index regenerates cleanly.
+
+## Risks
+
+- **External links break.** GitHub PRs, blog posts, Stack Overflow answers may link to `reference/model/`, `reference/definition/actions`, etc. Mitigation: VitePress supports redirects, OR keep stub pages that redirect via meta refresh. Cheap to add.
+- **Guides ↔ reference duplication drifts.** If a recipe and its reference page describe the same option differently, readers get confused. Mitigation: linting (no duplicate DSL/option tables across guide + reference).
+- **Volume isn't the metric.** Some pages will get longer (currently underdeveloped topics: tenancy, testing, profile). Some will get shorter. The win is navigability and clarity, not line count.
+
+## Open questions
+
+- Add `.vitepress` redirect configuration for old reference paths? (Recommended: yes, low cost.)
+- Should `reference/app/generators.md` be the full catalog or a per-area split? (Recommended: full catalog — it's reference, scannability matters.)
+- Are there guides that should be **deleted entirely** because they're 100% concept overlap with reference? (Decide after pilot.)

data/gemfiles/rails_7.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.49.0)
+    plutonium (0.50.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 43.0)

data/gemfiles/rails_8.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.49.0)
+    plutonium (0.50.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 43.0)

data/gemfiles/rails_8.1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.49.1)
+    plutonium (0.50.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 43.0)

data/lib/generators/pu/core/update/update_generator.rb

@@ -9,14 +9,10 @@ module Pu
 
       desc "Update Plutonium gem and npm package to the latest version"
 
-      SHELL_PIN_THRESHOLD = "0.49.1"
-
       def start
-        @previous_gem_version = installed_gem_version
         update_gem
         update_npm_package
         sync_skills_if_present
-        pin_shell_to_classic
       rescue => e
         exception "#{self.class} failed:", e
       end
@@ -30,22 +26,6 @@ module Pu
         Rails::Generators.invoke("pu:skills:sync", [], destination_root: Rails.root)
       end
 
-      # Pin the shell config to :classic on apps upgrading from a version
-      # that predates the shell change so the upgrade is invisible. Newer
-      # apps installed after the shell change get :modern from the install
-      # template and shouldn't be flipped.
-      def pin_shell_to_classic
-        return unless @previous_gem_version
-        return unless SemanticRange.satisfies?(@previous_gem_version, "<=#{SHELL_PIN_THRESHOLD}")
-
-        initializer = Rails.root.join("config", "initializers", "plutonium.rb")
-        return unless File.file?(initializer)
-        return if File.read(initializer).match?(/^\s*config\.shell\s*=/)
-
-        say_status :update, "Pinning Plutonium shell to :classic...", :green
-        configure_plutonium "config.shell = :classic"
-      end
-
       def update_gem
         say_status :update, "Updating plutonium gem...", :green
         run "bundle update plutonium"

data/lib/generators/pu/invites/install_generator.rb

@@ -70,6 +70,7 @@ module Pu
       end
 
       def create_package
+        return if File.exist?(File.join(destination_root, "packages/invites"))
         generate "pu:pkg:package", "invites"
       end
 

data/lib/plutonium/definition/base.rb

@@ -33,7 +33,7 @@ module Plutonium
       include Scoping
       include Search
       include NestedInputs
-      include Views
+      include IndexViews
       include Metadata
 
       class IndexPage < Plutonium::UI::Page::Index; end

data/lib/plutonium/definition/{views.rb → index_views.rb}

@@ -7,17 +7,15 @@ module Plutonium
     #
     # @example Enable both views, default to Grid
     #   class UserDefinition < Plutonium::Resource::Definition
-    #     views :table, :grid
-    #     default_view :grid
-    #
     #     grid_fields(
     #       image:     :avatar,
     #       header:    :name,
     #       subheader: :email,
     #       meta:      [:role, :status]
     #     )
+    #     default_index_view :grid
     #   end
-    module Views
+    module IndexViews
       extend ActiveSupport::Concern
 
       KNOWN_VIEWS = %i[table grid].freeze
@@ -25,8 +23,8 @@ module Plutonium
       GRID_LAYOUTS = %i[compact media].freeze
 
       included do
-        class_attribute :defined_views, default: [:table], instance_accessor: false
-        class_attribute :defined_default_view, default: nil, instance_accessor: false
+        class_attribute :defined_index_views, default: [:table], instance_accessor: false
+        class_attribute :defined_default_index_view, default: nil, instance_accessor: false
         class_attribute :defined_grid_fields, default: {}, instance_accessor: false
         class_attribute :defined_grid_layout, default: :compact, instance_accessor: false
         class_attribute :defined_grid_columns, default: nil, instance_accessor: false
@@ -34,37 +32,40 @@ module Plutonium
 
       class_methods do
         # Declares the index views this resource supports.
+        # Usually unnecessary — declaring `grid_fields` auto-enables :grid
+        # alongside the default :table. Use `index_views` only to disable
+        # one (e.g. `index_views :grid` to drop the table view).
         # @param list [Array<Symbol>] one or more of {KNOWN_VIEWS}
-        def views(*list)
+        def index_views(*list)
           list = list.flatten.map(&:to_sym)
           invalid = list - KNOWN_VIEWS
-          raise ArgumentError, "Unknown views: #{invalid.inspect}. Valid: #{KNOWN_VIEWS}" if invalid.any?
-          self.defined_views = list.empty? ? [:table] : list
+          raise ArgumentError, "Unknown index_views: #{invalid.inspect}. Valid: #{KNOWN_VIEWS}" if invalid.any?
+          self.defined_index_views = list.empty? ? [:table] : list
         end
 
-        # Declares the default index view. Must be one of {.views}.
+        # Declares the default index view. Must be one of {.index_views}.
         # Falls back to the first declared view if unset.
-        def default_view(name = nil)
+        def default_index_view(name = nil)
           if name.nil?
-            defined_default_view || defined_views.first
+            defined_default_index_view || defined_index_views.first
           else
             name = name.to_sym
-            unless defined_views.include?(name)
-              raise ArgumentError, "default_view #{name.inspect} not in views #{defined_views.inspect}"
+            unless defined_index_views.include?(name)
+              raise ArgumentError, "default_index_view #{name.inspect} not in index_views #{defined_index_views.inspect}"
             end
-            self.defined_default_view = name
+            self.defined_default_index_view = name
           end
         end
 
         # Maps grid slots to fields. Each slot is optional. Implicitly
-        # adds `:grid` to {.views} so a resource can opt into the Grid
-        # view simply by declaring its slots.
+        # adds `:grid` to {.index_views} so a resource can opt into the
+        # Grid view simply by declaring its slots.
         # @param slots [Hash{Symbol => Symbol, Array<Symbol>}]
         def grid_fields(**slots)
           invalid = slots.keys - GRID_SLOTS
           raise ArgumentError, "Unknown grid slots: #{invalid.inspect}. Valid: #{GRID_SLOTS}" if invalid.any?
           self.defined_grid_fields = slots
-          self.defined_views = defined_views + [:grid] unless defined_views.include?(:grid)
+          self.defined_index_views = defined_index_views + [:grid] unless defined_index_views.include?(:grid)
         end
 
         # Layout shape for grid cards. :compact (default) places the image
@@ -84,8 +85,8 @@ module Plutonium
         end
       end
 
-      def defined_views = self.class.defined_views
-      def default_view = self.class.default_view
+      def defined_index_views = self.class.defined_index_views
+      def default_index_view = self.class.default_index_view
       def defined_grid_fields = self.class.defined_grid_fields
       def defined_grid_layout = self.class.defined_grid_layout
       def defined_grid_columns = self.class.defined_grid_columns

data/lib/plutonium/helpers/turbo_helper.rb

@@ -5,6 +5,17 @@ module Plutonium
         request.headers["Turbo-Frame"]
       end
 
+      # True when the request is rendered inside any turbo frame.
+      def in_frame? = current_turbo_frame.present?
+
+      # True when the request is rendered inside either modal frame
+      # (primary or secondary).
+      def in_modal? = Plutonium::MODAL_FRAMES.include?(current_turbo_frame)
+
+      # True when the request is rendered inside the secondary (stacked)
+      # modal frame specifically.
+      def in_secondary_modal? = current_turbo_frame == Plutonium::REMOTE_MODAL_SECONDARY_FRAME
+
       def remote_modal_frame_tag(&)
         turbo_frame_tag(Plutonium::REMOTE_MODAL_FRAME, &)
       end

data/lib/plutonium/helpers/turbo_stream_actions_helper.rb

@@ -9,6 +9,20 @@ module Plutonium
         end
       end
 
+      # Closes the <dialog> inside the targeted frame and empties the
+      # frame. Used to dismiss a stacked modal without affecting the
+      # rest of the page.
+      def turbo_stream_close_frame(frame_id)
+        turbo_stream_action_tag :close_frame, target: frame_id
+      end
+
+      # Reloads the targeted frame from its current src. Used to refresh
+      # the primary modal after a secondary-modal action mutates data
+      # the primary depends on.
+      def turbo_stream_reload_frame(frame_id)
+        turbo_stream_action_tag :reload_frame, target: frame_id
+      end
+
       private
 
       def turbo_stream_redirect_same_page?(url)

data/lib/plutonium/resource/controller.rb

@@ -15,6 +15,7 @@ module Plutonium
       include Plutonium::Resource::Controllers::Queryable
       include Plutonium::Resource::Controllers::CrudActions
       include Plutonium::Resource::Controllers::InteractiveActions
+      include Plutonium::Resource::Controllers::Typeahead
 
       included do
         after_action { response.headers.merge!(@pagy.headers_hash) if @pagy }

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

@@ -58,7 +58,7 @@ module Plutonium
             elsif resource_record!.save
               format.turbo_stream do
                 flash.notice = "#{resource_class.model_name.human} was successfully created."
-                render turbo_stream: helpers.turbo_stream_redirect(redirect_url_after_submit)
+                render turbo_stream: stacked_modal_create_streams
               end
               format.html do
                 redirect_to redirect_url_after_submit,
@@ -164,6 +164,24 @@ module Plutonium
 
         private
 
+        # When the create came in through the secondary (stacked) modal
+        # frame — i.e. the user clicked "+" next to an association field
+        # while the parent form was already in a modal — we don't want to
+        # navigate anywhere. Close the secondary dialog and reload the
+        # primary modal frame so the just-created record appears in the
+        # association select. Outside that case fall back to the normal
+        # post-submit redirect.
+        def stacked_modal_create_streams
+          if helpers.in_secondary_modal?
+            [
+              helpers.turbo_stream_close_frame(Plutonium::REMOTE_MODAL_SECONDARY_FRAME),
+              helpers.turbo_stream_reload_frame(Plutonium::REMOTE_MODAL_FRAME)
+            ]
+          else
+            helpers.turbo_stream_redirect(redirect_url_after_submit)
+          end
+        end
+
         def redirect_url_after_submit
           if (return_to = url_from(params[:return_to]))
             return return_to

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

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Resource
+    module Controllers
+      # Backend dispatch for typeahead/autocomplete queries against
+      # resource form inputs and index filter inputs. Auto-mounted on
+      # every Plutonium resource via the `interactive_resource_actions`
+      # routing concern (see Plutonium::Routing::MapperExtensions).
+      #
+      # The controller resolves what to query directly from the input
+      # definition + the model's association reflection — no widget
+      # indirection. Two source kinds are supported:
+      #
+      #   1. Static `choices: [...]` — case-insensitive substring filter.
+      #   2. Association — either `association_class:` set on the input,
+      #      or inferred from `resource_class.reflect_on_association(name)`.
+      #
+      # Association queries route through the associated resource's
+      # `policy.relation_scope` so users only see records they can read.
+      module Typeahead
+        extend ActiveSupport::Concern
+
+        TYPEAHEAD_LIMIT = 50
+
+        # Priority list tried when the input doesn't tell us which
+        # column carries its label. Aligns with what `to_label` usually
+        # wraps. Used only as a last resort.
+        FALLBACK_SEARCH_COLUMNS = %w[name title label slug display_name email].freeze
+
+        # Returns the column to LIKE against when no `search` block is
+        # defined. Used by both the server (to build the WHERE clause)
+        # and the input component (to decide whether to attach the
+        # typeahead URL).
+        #
+        # Resolution order:
+        # 1. The input's `label_method` if it names a real column (so
+        #    `input :user, label_method: :email` just works).
+        # 2. The first match from FALLBACK_SEARCH_COLUMNS.
+        # 3. nil — no usable column, server returns unfiltered.
+        #
+        # The fallback is fine for moderate tables but uses a leading-
+        # wildcard LIKE which can't be served by a b-tree index. For
+        # large tables, declare a `search` block that uses a trigram or
+        # full-text index instead.
+        def self.searchable_column_for(klass, label_method: nil)
+          cols = klass.column_names
+          if label_method && cols.include?(label_method.to_s)
+            return label_method.to_s
+          end
+          FALLBACK_SEARCH_COLUMNS.find { |c| cols.include?(c) }
+        end
+
+        # Escapes the SQL LIKE wildcards `%` and `_` (plus the escape
+        # char itself) so a user searching for "100%" doesn't match
+        # everything. The literal `!` is used as the ESCAPE character —
+        # unambiguous across sqlite/postgres/mysql, no backslash-quoting
+        # surprises.
+        LIKE_ESCAPE_CHAR = "!"
+        def self.escape_like(value)
+          value.to_s.gsub(/[!%_]/) { |c| "#{LIKE_ESCAPE_CHAR}#{c}" }
+        end
+
+        included do
+          before_action :authorize_typeahead!, only: %i[typeahead_input typeahead_filter]
+          # Read-only JSON; row-level auth is enforced inline through
+          # authorized_resource_scope, so the after_action verifier is
+          # redundant.
+          skip_verify_current_authorized_scope only: %i[typeahead_input typeahead_filter]
+        end
+
+        # GET /<resource>/typeahead/input/:name?q=...
+        def typeahead_input
+          field_name = params[:name].to_sym
+          defn = current_definition.defined_inputs[field_name]
+          # Inputs are often inferred from the model (no explicit
+          # `input :foo` in the definition). Accept the request when the
+          # field name maps to a real association even without an entry.
+          unless defn || resource_class.reflect_on_association(field_name)
+            return head(:not_found)
+          end
+
+          render_typeahead_response(defn || {}, field_name)
+        end
+
+        # GET /<resource>/typeahead/filter/:name?q=...
+        def typeahead_filter
+          filter = current_query_object.filter_definitions[params[:name].to_sym]
+          return head(:not_found) unless filter
+
+          defn = filter.defined_inputs[:value]
+          return head(:not_found) unless defn
+
+          render_typeahead_response(defn, params[:name].to_sym)
+        end
+
+        private
+
+        def render_typeahead_response(defn, field_name)
+          options = defn[:options] || {}
+          query = params[:q].to_s
+          candidates = collect_typeahead_candidates(options, field_name, query)
+
+          if candidates.nil?
+            return render(json: {error: "input has no typeahead source"}, status: :bad_request)
+          end
+
+          has_more = candidates.length > TYPEAHEAD_LIMIT
+          results = candidates.first(TYPEAHEAD_LIMIT).map { |row| serialize_typeahead_row(row) }
+          render json: {results: results, has_more: has_more}
+        end
+
+        # Returns the candidate list, or nil if the input has neither
+        # static choices nor a resolvable association class.
+        def collect_typeahead_candidates(options, field_name, query)
+          if options[:choices]
+            filter_static_choices(options[:choices], query)
+          elsif (klass = typeahead_association_class(options, field_name))
+            filter_association(klass, query, options)
+          end
+        end
+
+        def typeahead_association_class(options, field_name)
+          options[:association_class] ||
+            resource_class.reflect_on_association(field_name)&.klass
+        end
+
+        def filter_static_choices(choices, query)
+          return choices if query.blank?
+          q = query.downcase
+          choices.select { |label, _| label.to_s.downcase.include?(q) }
+        end
+
+        # Routes through the associated resource's policy.relation_scope
+        # so typeahead never surfaces records the user can't read, then
+        # narrows via the associated resource definition's `search` block
+        # when present. Without a search block, fall back to a case-
+        # insensitive LIKE on the first column in FALLBACK_SEARCH_COLUMNS
+        # that exists on the model (so a resource with a `name` column
+        # gets useful typeahead without declaring `search`). If neither
+        # search block nor fallback column is available, the relation is
+        # returned unfiltered (capped).
+        def filter_association(klass, query, options)
+          relation = options[:skip_authorization] ? klass.all : authorized_resource_scope(klass)
+          if query.present?
+            if (search_block = associated_definition_search_block(klass))
+              relation = search_block.call(relation, query)
+            elsif (col = Typeahead.searchable_column_for(klass, label_method: options[:label_method]))
+              quoted = klass.connection.quote_column_name(col)
+              pattern = "%#{Typeahead.escape_like(query.downcase)}%"
+              relation = relation.where("LOWER(#{quoted}) LIKE ? ESCAPE '#{Typeahead::LIKE_ESCAPE_CHAR}'", pattern)
+            end
+          end
+          relation.limit(Typeahead::TYPEAHEAD_LIMIT + 1).to_a
+        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).
+        def associated_definition_search_block(klass)
+          resource_definition(klass).class._search_definition
+        rescue NameError
+          nil
+        end
+
+        def serialize_typeahead_row(row)
+          if row.is_a?(Array)
+            {value: row[1].to_s, label: row[0].to_s}
+          else
+            {value: row.to_signed_global_id.to_s, label: row.to_label}
+          end
+        end
+
+        def authorize_typeahead!
+          authorize_current! resource_class, to: :typeahead?
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/resource/policy.rb

@@ -179,6 +179,13 @@ module Plutonium
         index?
       end
 
+      # Checks if typeahead/autocomplete queries are permitted.
+      #
+      # @return [Boolean] Delegates to index?.
+      def typeahead?
+        index?
+      end
+
       # Core attributes
 
       # Returns the permitted attributes for the create action.