plutonium 0.49.1 → 0.51.0

data/docs/superpowers/plans/2026-05-07-ui-layout-overhaul.md.tasks.json

@@ -0,0 +1,103 @@
+{
+  "planPath": "docs/superpowers/plans/2026-05-07-ui-layout-overhaul.md",
+  "tasks": [
+    {
+      "id": 7,
+      "subject": "Task 0: Density tokens",
+      "status": "pending",
+      "description": "**Goal:** Codify balanced density scale.\n\n```json:metadata\n{\"files\":[\"src/css/tokens.css\",\"src/css/components.css\",\"lib/plutonium/ui/component/tokens.rb\"],\"verifyCommand\":\"yarn build && bundle exec appraisal rails-8.1 rake test\",\"acceptanceCriteria\":[\"density vars defined\",\"button/input sizes updated\",\"card padding 16px\",\"tests pass\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 8,
+      "subject": "Task 1: PageHeader redesign (Stripe-style)",
+      "status": "pending",
+      "blockedBy": [7],
+      "description": "**Goal:** Tighter Stripe-style PageHeader.\n\n```json:metadata\n{\"files\":[\"lib/plutonium/ui/page_header.rb\",\"lib/plutonium/ui/page/base.rb\",\"test/plutonium/ui/page_header_test.rb\"],\"verifyCommand\":\"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/ui/page_header_test.rb -v\",\"acceptanceCriteria\":[\"title 18-20px\",\"description muted\",\"actions right-aligned\",\"tabs flush\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 9,
+      "subject": "Task 2: IconRail component",
+      "status": "pending",
+      "blockedBy": [7],
+      "description": "**Goal:** 56px icon-only nav.\n\n```json:metadata\n{\"files\":[\"lib/plutonium/ui/layout/icon_rail.rb\",\"test/plutonium/ui/layout/icon_rail_test.rb\",\"src/css/components.css\"],\"verifyCommand\":\"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/ui/layout/icon_rail_test.rb -v\",\"acceptanceCriteria\":[\"aside 56px\",\"slots present\",\"active styling\",\"mobile-hidden\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 10,
+      "subject": "Task 3: Topbar component",
+      "status": "pending",
+      "blockedBy": [7],
+      "description": "**Goal:** Sticky 48px topbar.\n\n```json:metadata\n{\"files\":[\"lib/plutonium/ui/layout/topbar.rb\",\"lib/plutonium/ui/breadcrumbs.rb\",\"test/plutonium/ui/layout/topbar_test.rb\"],\"verifyCommand\":\"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/ui/layout/topbar_test.rb -v\",\"acceptanceCriteria\":[\"48px height\",\"breadcrumbs/search/actions slots\",\"hamburger wired\",\"empty-breadcrumbs handled\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 11,
+      "subject": "Task 4: Wire ResourceLayout to new shell",
+      "status": "pending",
+      "blockedBy": [9, 10],
+      "description": "**Goal:** Replace partials with IconRail+Topbar; drop legacy.\n\n```json:metadata\n{\"files\":[\"lib/plutonium/ui/layout/resource_layout.rb\",\"lib/plutonium/ui/layout/base.rb\",\"lib/plutonium/ui/layout/header.rb\",\"lib/plutonium/ui/layout/sidebar.rb\"],\"verifyCommand\":\"bundle exec appraisal rails-8.1 rake test\",\"acceptanceCriteria\":[\"new shell wired\",\"old partials removed\",\"tests pass\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 12,
+      "subject": "Task 5: Index toolbar",
+      "status": "pending",
+      "blockedBy": [7, 8],
+      "description": "**Goal:** New Toolbar component (view switcher, filter, group, search, column-config, overflow).\n\n```json:metadata\n{\"files\":[\"lib/plutonium/ui/table/components/toolbar.rb\",\"lib/plutonium/ui/table/components/view_switcher.rb\",\"lib/plutonium/ui/table/resource.rb\",\"test/plutonium/ui/table/components/toolbar_test.rb\"],\"verifyCommand\":\"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/ui/table/components/toolbar_test.rb -v\",\"acceptanceCriteria\":[\"toolbar order\",\"search wired\",\"filter popover\",\"disabled segments\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 13,
+      "subject": "Task 6: Active filter pills + result count",
+      "status": "pending",
+      "blockedBy": [12],
+      "description": "**Goal:** Removable filter pills + result count strip.\n\n```json:metadata\n{\"files\":[\"lib/plutonium/ui/table/components/filter_pills.rb\",\"lib/plutonium/ui/table/resource.rb\",\"lib/plutonium/resource/query_object.rb\",\"test/plutonium/ui/table/components/filter_pills_test.rb\"],\"verifyCommand\":\"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/ui/table/components/filter_pills_test.rb -v\",\"acceptanceCriteria\":[\"pill per filter\",\"add-filter pill\",\"clear URL\",\"result count\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 14,
+      "subject": "Task 7: Column-header sort with multi-sort + ⋯ menu",
+      "status": "pending",
+      "blockedBy": [12],
+      "description": "**Goal:** Sort in column headers, shift-click multi-sort, per-column ⋯ menu.\n\n```json:metadata\n{\"files\":[\"lib/plutonium/resource/query_object.rb\",\"lib/plutonium/ui/table/resource.rb\",\"lib/plutonium/ui/table/theme.rb\",\"src/js/controllers/table_controller.js\",\"test/plutonium/resource/query_object_test.rb\"],\"verifyCommand\":\"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/resource/query_object_test.rb -v\",\"acceptanceCriteria\":[\"sort_params_for has multi_url\",\"click vs shift-click\",\"priority badges\",\"column menu\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 15,
+      "subject": "Task 8: Floating bulk action bar",
+      "status": "pending",
+      "blockedBy": [13],
+      "description": "**Goal:** Bulk action bar replaces pills strip when rows selected.\n\n```json:metadata\n{\"files\":[\"lib/plutonium/ui/table/components/bulk_action_bar.rb\",\"lib/plutonium/ui/table/resource.rb\",\"src/js/controllers/bulk_actions_controller.js\",\"test/plutonium/ui/table/components/bulk_action_bar_test.rb\"],\"verifyCommand\":\"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/ui/table/components/bulk_action_bar_test.rb -v\",\"acceptanceCriteria\":[\"bar/pills mutual exclusion\",\"selection count\",\"danger tone\",\"clear deselect\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 16,
+      "subject": "Task 9: Show page redesign",
+      "status": "pending",
+      "blockedBy": [8],
+      "description": "**Goal:** Single-column show + reserved aside slot.\n\n```json:metadata\n{\"files\":[\"lib/plutonium/ui/page/show.rb\",\"lib/plutonium/ui/page/base.rb\",\"lib/plutonium/ui/display/resource.rb\",\"lib/plutonium/ui/panel.rb\",\"test/plutonium/ui/page/show_test.rb\"],\"verifyCommand\":\"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/ui/page/show_test.rb -v\",\"acceptanceCriteria\":[\"max-width 960\",\"card panels\",\"aside slot reserved\",\"tabs flush\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 17,
+      "subject": "Task 10: Form page redesign + sticky footer",
+      "status": "pending",
+      "blockedBy": [8],
+      "description": "**Goal:** Centered narrow form column + sticky footer + inline validation.\n\n```json:metadata\n{\"files\":[\"lib/plutonium/ui/page/new.rb\",\"lib/plutonium/ui/page/edit.rb\",\"lib/plutonium/ui/page/interactive_action.rb\",\"lib/plutonium/ui/form/resource.rb\",\"lib/plutonium/ui/form/interaction.rb\",\"lib/plutonium/ui/form/theme.rb\",\"lib/plutonium/ui/form/components/sticky_footer.rb\",\"test/plutonium/ui/form/sticky_footer_test.rb\"],\"verifyCommand\":\"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/ui/form -v\",\"acceptanceCriteria\":[\"580px centered\",\"sticky footer\",\"inline validation\",\"modal mode skips footer\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 18,
+      "subject": "Task 11: Slideover modal mode + per-interaction option",
+      "status": "pending",
+      "blockedBy": [17],
+      "description": "**Goal:** Add slideover mode; opt-in via interactive_action :name, modal: :slideover.\n\n```json:metadata\n{\"files\":[\"lib/plutonium/resource/interaction.rb\",\"lib/plutonium/interaction/base.rb\",\"src/js/controllers/remote_modal_controller.js\"],\"verifyCommand\":\"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/interaction -v\",\"acceptanceCriteria\":[\"modal: kwarg accepted\",\"two outer containers\",\"slideover transition\",\"mobile full-screen\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 19,
+      "subject": "Task 12: Per-resource modal declaration",
+      "status": "pending",
+      "blockedBy": [18],
+      "description": "**Goal:** modal :slideover on resource definition for new/edit modal mode.\n\n```json:metadata\n{\"files\":[\"lib/plutonium/resource/definition.rb\",\"test/plutonium/resource/definition_test.rb\"],\"verifyCommand\":\"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/resource/definition_test.rb -v\",\"acceptanceCriteria\":[\"modal DSL on definition\",\"invalid raises\",\"modal frame uses declared mode\",\"page URLs unchanged\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 20,
+      "subject": "Task 13: Documentation + changelog",
+      "status": "pending",
+      "blockedBy": [16, 19],
+      "description": "**Goal:** Document overhaul; update skills.\n\n```json:metadata\n{\"files\":[\"docs/guides/ui-overhaul-2026.md\",\"CHANGELOG.md\",\".claude/skills/plutonium-views.md\"],\"verifyCommand\":\"yarn docs:build\",\"acceptanceCriteria\":[\"upgrade guide written\",\"skills updated\",\"changelog entry\",\"docs build passes\"],\"requiresUserVerification\":false}\n```"
+    }
+  ],
+  "lastUpdated": "2026-05-07"
+}

data/docs/superpowers/specs/2026-05-07-ui-layout-overhaul-design.md

@@ -0,0 +1,270 @@
+# Plutonium UI Layout Overhaul — Design Spec
+
+**Date:** 2026-05-07
+**Scope:** Visual + structural redesign of Plutonium's app shell, page header, index/show/form pages. Code-level component refactoring (slot APIs, hook reduction, partial-to-Phlex conversion) is intentionally out of scope here — this spec captures the *target UI* only. A separate refactor pass can re-architect the Phlex internals to deliver this target.
+
+## Goals
+
+1. Modernize the look and feel to match contemporary admin tools (Linear, Stripe Dashboard, Vercel, Plane).
+2. Increase information density without sacrificing scannability.
+3. Establish a coherent visual vocabulary across all four page types (index / show / form / interactive-action).
+4. Leave clean extension points for upcoming features (metadata side panel, view switchers).
+
+## Non-Goals
+
+- Theming / token rebuild (deferred — current `--pu-*` token system stays).
+- Component API consolidation (separate effort).
+- Mobile-first redesign (mobile must work, but desktop is the optimization target).
+- New colors / typography (use existing tokens unless a decision below requires a new one).
+
+---
+
+## 1. App Shell — Icon Rail + Topbar
+
+A narrow icon-only left rail plus a topbar replaces the current expanded sidebar.
+
+**Left rail**
+- Width: ~56px, fixed.
+- Icon-only nav items with tooltips on hover.
+- Top: brand mark / portal switcher.
+- Middle: primary nav (resources grouped by section, dividers between groups).
+- Bottom: settings, theme toggle.
+- Active item: filled background, primary tone.
+- Mobile (<lg breakpoint): rail collapses to hamburger drawer.
+
+**Topbar**
+- Height: ~48px, sticky.
+- Left: breadcrumbs (resource path; replaces in-content breadcrumbs).
+- Center: global search input (filled, ~360px max).
+- Right: notifications, user menu.
+
+**Removed**
+- Current expanded sidebar (240px) — labels now live in tooltips and breadcrumbs.
+- In-page breadcrumbs above title — moved to topbar.
+
+---
+
+## 2. Page Header — Stripe-Style
+
+Every page renders a unified header below the topbar.
+
+```
+┌────────────────────────────────────────────────────┐
+│ Customers                              [Cancel] [Save] │
+│ Manage customer accounts and contact details        │
+├────────────────────────────────────────────────────┤
+│ Overview │ Orders │ Invoices │ Activity            │
+└────────────────────────────────────────────────────┘
+```
+
+- Title: 18–20px, semibold.
+- Description: 13px, muted, optional, sits directly below title.
+- Actions: right-aligned at title's vertical level. Primary as filled button, secondary as outline. Overflow into a `⋯` dropdown after 2 visible actions.
+- Tabs: connected strip directly under header (no gap), 1px bottom border becomes the active-tab indicator's baseline.
+
+The header is uniform across index / show / form / interactive-action.
+
+---
+
+## 3. Index Page — Hybrid Toolbar + Pills + Column Sort
+
+### Toolbar (single 36-40px row above the table)
+
+Order, left to right:
+1. **View switcher** — segmented control (Grid / Cards / Kanban — Cards/Kanban are placeholders for now; only Grid is wired initially).
+2. Vertical divider.
+3. **Filter** button (popover).
+4. **Group** button (popover).
+5. Spacer (`flex-grow`).
+6. **Search input** — visible, ~220px wide, expands on focus.
+7. Vertical divider.
+8. **Column config** icon button (`⊞`).
+9. **Overflow** icon button (`⋯`) — exports, advanced options.
+
+The "Sort" button is intentionally absent — sort is column-driven (see below).
+
+### Active Filter Strip (below toolbar, only when filters are active)
+
+- Each active filter renders as a removable pill: `<field> <op> <value>` with `✕`.
+- After the last pill: `+ Filter` dashed pill that opens the same popover as the toolbar Filter button.
+- Right-aligned: result count (e.g., "147 results").
+
+### Table — Column-Header Sort
+
+- Click a column header: sorts asc → desc → none (cycles).
+- Shift-click: adds a secondary/tertiary sort (multi-sort).
+- Active sort columns show: arrow (↑/↓) + small priority badge (1, 2, 3) when more than one column is active.
+- Each header has a `⋯` menu: Sort asc / Sort desc / Clear sort / Group by / Filter by / Hide column.
+- Row height: 32px (balanced density). Header height: 32px.
+- Selection: leftmost column is a 12px checkbox.
+
+### Bulk Action Bar
+
+- Appears as a 36px strip *replacing* the active-filter strip when ≥1 row is selected.
+- Tinted background (primary-50 light / primary-950/30 dark).
+- Left: count + "Clear selection".
+- After spacer: action buttons (Export, Archive, Delete) — Delete uses danger tone.
+
+### Pagination Footer
+
+- Sticky-ish strip below the table.
+- Left: "Showing N–M of Total".
+- Right: prev / page indicator / next.
+
+---
+
+## 4. Show Page — Single Column + Tabs
+
+A single content column under the page header. Nested resources render as tabs.
+
+### Structure
+
+```
+PageHeader (title, description, actions, tab strip)
+└── content
+    ├── [Aside slot — empty by default; reserved]
+    └── Main column
+        ├── Field panel: Details
+        ├── Field panel: Address
+        └── ...
+```
+
+- Field panels: card-styled (1px border, radius-md, white surface) with uppercase 9px section labels.
+- Default content max-width: ~960px, centered if rail+topbar leaves wider area.
+- Tabs render nested resources (the existing tab strip mechanism).
+
+### Reserved Aside Slot (Future Hook)
+
+The page layout reserves a `render_aside` slot that is empty by default. A future `metadata` DSL on resource definitions will populate this slot:
+
+```ruby
+class CustomerDefinition < Plutonium::Resource::Definition
+  metadata do
+    field :status, badge: true
+    field :owner
+    field :created_at
+  end
+end
+```
+
+When populated, the aside renders as a 200–240px right side panel with a sticky 16px-padded background-`surface-alt` column. Implementation of the DSL itself is a separate task — this spec only requires the layout to leave room.
+
+---
+
+## 5. Form Page — Centered Narrow + Sticky Footer
+
+For new / edit / interactive-action.
+
+### Structure
+
+```
+PageHeader (title, description; no actions in header)
+└── content (max-width ~580px, centered)
+    ├── Card: Section 1 (uppercase 9px label + fields)
+    ├── Card: Section 2
+    └── ...
+StickyFooter (full width, right-aligned [Cancel] [Save])
+```
+
+- Form column max-width: 580px.
+- Card-style sections, same chrome as show-page panels.
+- Inline validation: errors render as 12px danger text directly under each field. No toasts for field-level errors. Toast/flash only for form-level outcomes.
+- Sticky footer: 56px tall, white surface, top border, sticks to viewport bottom when form scrolls.
+- Cancel: outline button. Save: primary filled button. Right-aligned.
+
+### Modal Variant
+
+The same form can render in a modal when triggered as a quick-create / quick-edit (e.g., `+ New` from an index toolbar that targets the remote modal frame, or a row-edit action):
+- No sticky footer; the modal's own footer bar holds Cancel / Save.
+- Internal layout otherwise identical (card sections, inline validation).
+- Modal mode (`:centered` vs `:slideover`) is configurable per resource definition — see §7.
+- Page-level new/edit URLs always render the full page form (§5); modal rendering is invoked via the modal turbo frame.
+
+---
+
+## 6. Density
+
+**Balanced (Stripe / Vercel-class)** as the framework default.
+
+| Token            | Value         |
+|------------------|---------------|
+| Table row height | 32px          |
+| Body text        | 14px          |
+| Section gap      | 16px          |
+| Field gap        | 12px          |
+| Button (md)      | 32px height, 14px text, 12px horizontal padding |
+| Button (sm)      | 28px, 13px, 10px |
+| Input height     | 36px (forms), 32px (toolbars) |
+| Card padding     | 16px          |
+| Page side padding | 24px         |
+
+These values become the canonical scale; spot-deviations are allowed but should be rare.
+
+---
+
+## 7. Modals — Both Modes, Per-Action Opt-In
+
+Two modal modes ship as siblings.
+
+### Default: Centered Dialog
+- Max-width 520px, max-height 80vh, centered, dimmed backdrop.
+- Header: dialog title + close (✕).
+- Body: form / content with internal scroll.
+- Footer: 56px strip, right-aligned [Cancel] [Confirm].
+- Use cases: short forms, confirmations, most interactive actions.
+
+### Opt-In: Right Slide-Over Panel
+- Slides in from right, full height, 480px wide on desktop, full-screen on mobile.
+- Header / body / footer same as centered.
+- Underlying list visible (dimmed); user keeps context.
+### Configuration
+
+**Per interaction** — defaults to `:centered`, opt into `:slideover`:
+```ruby
+interactive_action :reschedule, modal: :slideover
+interactive_action :archive   # implicit modal: :centered
+```
+
+**Per resource (for quick-create / quick-edit modals)** — definition declares the mode used when new/edit is rendered through the modal turbo frame:
+```ruby
+class CustomerDefinition < Plutonium::Resource::Definition
+  modal :slideover   # default :centered
+end
+```
+
+The page-level new/edit URLs always render the full §5 page layout. Whether `+ New` opens a modal or navigates to the page is a per-context call-site choice (e.g., index toolbar can target the modal frame for quick-create; a "Create customer" landing CTA navigates to the full page).
+
+Both modal modes share the same Phlex modal component; only the outer container varies.
+
+---
+
+## 8. Compatibility & Migration Notes
+
+- **`Layout::ResourceLayout`** currently uses Rails partials for `resource_header` / `resource_sidebar`. Conversion to Phlex is implicit in this work — the icon rail and topbar must be Phlex components.
+- **`Page::Base` hook explosion** (~12 before/after hooks) — most apps don't use these. The redesign assumes apps that override `render_breadcrumbs` etc. continue to work; new slot APIs are additive. Hook deprecation is a future cleanup.
+- **Existing CSS classes** — `.pu-input`, `.pu-btn`, `.pu-card` keep their names; sizes shift to the density table above. Apps that hard-code Tailwind utilities on top will need cosmetic touch-ups but no breakage.
+- **Breadcrumbs** — moving from in-page to topbar means `Plutonium::UI::Breadcrumbs` becomes a topbar component. The definition-level `breadcrumbs` toggle stays; "off" means hidden in topbar (or replaced with title only).
+
+---
+
+## 9. Out-of-Scope Followups (referenced, not designed here)
+
+- **Metadata DSL** for show-page side panel (§4).
+- **View switcher** wiring beyond Grid (Cards, Kanban) — placeholders in toolbar; implementation deferred.
+- **Code-level Phlex refactor** — slot API, hook reduction, asset registry — separate spec.
+- **Token / theme rebuild** — separate spec.
+
+---
+
+## 10. Acceptance Checklist
+
+- [ ] Icon rail (56px) replaces expanded sidebar; topbar adds breadcrumbs + search + user.
+- [ ] Page header is a single component (`PageHeader`) used by every page type, supporting title / description / actions / tabs.
+- [ ] Index page renders the toolbar in the order of §3 with no Sort button.
+- [ ] Active filters render as removable pills below the toolbar with a result count.
+- [ ] Column headers sort on click (asc/desc/none) with shift-click multi-sort and priority badges.
+- [ ] Bulk action bar replaces the filter strip when rows are selected.
+- [ ] Show page is single-column with tab strip; an empty aside slot is reserved.
+- [ ] Form pages use a 580px centered column with sticky footer; modal variant uses dialog footer.
+- [ ] Density tokens (§6) are codified in CSS / Phlex constants and used consistently.
+- [ ] Modal component supports both `:centered` (default) and `:slideover` via per-action / per-form opt-in.

data/docs/superpowers/specs/2026-05-09-typeahead-endpoint-design.md

@@ -0,0 +1,203 @@
+# Typeahead Endpoint Design
+
+**Status:** Approved (2026-05-09)
+**Author:** stefan
+**Scope:** New backend-driven typeahead/autocomplete primitive for resource form inputs and index filter inputs.
+
+## Goal
+
+Add an async typeahead endpoint to every Plutonium resource so association-backed selects (and any future typeahead-capable input) can fetch matching records from the server instead of materialising up to `DEFAULT_CHOICE_LIMIT` options into the page at render time. This unblocks association pickers over large tables (where the existing 100-row cap silently truncates) without forcing every input into a custom JS solution.
+
+## Non-goals
+
+- Pagination of typeahead results (we use a hard cap with an overflow indicator; pagination can be added later if a real need surfaces).
+- Rich result rows (subtitle, icon, avatar). MVP returns minimal `{value, label}` per row; richer payloads are a separate iteration.
+- Replacing the existing eager-list ResourceSelect; the eager path stays as the fallback / small-table mode.
+
+## Architecture
+
+Three layers, mirroring how `Plutonium::Resource::Controllers::InteractiveActions` is composed today.
+
+### 1. Routing — `Plutonium::Routing::MapperExtensions`
+
+Two routes are added to the existing `interactive_resource_actions` concern (auto-mounted on every Plutonium resource alongside `record_actions`, `bulk_actions`, etc.):
+
+```
+GET /<resource>/typeahead/input/:name?q=…   → typeahead_input
+GET /<resource>/typeahead/filter/:name?q=…  → typeahead_filter
+```
+
+Both collection-level. **No member variant** — authorization on the parent resource class is sufficient (see "Authorization" below).
+
+### 2. Controller concern — `Plutonium::Resource::Controllers::Typeahead`
+
+Two thin actions plus a single `before_action` for auth.
+
+```ruby
+module Plutonium::Resource::Controllers::Typeahead
+  extend ActiveSupport::Concern
+
+  included do
+    before_action :authorize_typeahead!, only: %i[typeahead_input typeahead_filter]
+  end
+
+  def typeahead_input
+    name = params[:name].to_sym
+    defn = current_definition.defined_inputs[name]
+    return head(:not_found) unless defn
+
+    render_typeahead_response(defn)
+  end
+
+  def typeahead_filter
+    name = params[:name].to_sym
+    filter = current_query_object.filter_definitions[name]
+    return head(:not_found) unless filter
+
+    defn = filter.defined_inputs[:value]
+    return head(:not_found) unless defn
+
+    render_typeahead_response(defn)
+  end
+
+  private
+
+  def render_typeahead_response(defn)
+    klass = lookup_input_class(defn)
+    return render(json: { error: "input is not typeahead-capable" }, status: :bad_request) unless klass < Plutonium::UI::Form::Components::Searchable
+
+    widget = klass.build_for_typeahead(defn[:options] || {})
+    results, has_more = widget.typeahead(
+      query: params[:q].to_s,
+      limit: TYPEAHEAD_LIMIT,
+      controller: self
+    )
+    render json: { results: results, has_more: has_more }
+  end
+
+  def authorize_typeahead!
+    authorize! resource_class, to: :typeahead?
+  end
+
+  # Maps the input definition's :as symbol (e.g. :resource_select) to a
+  # component class. Backed by an explicit registry — only inputs that
+  # opted in by including Searchable register here, so anything not in
+  # the registry falls through to the 400 branch.
+  def lookup_input_class(defn)
+    Plutonium::UI::Form::Components::Searchable.registry[defn[:options]&.[](:as)&.to_sym]
+  end
+end
+```
+
+`TYPEAHEAD_LIMIT` is a module-level constant (default `50`). Easy to tune.
+
+### 3. Search behavior — `Plutonium::UI::Form::Components::Searchable`
+
+A small mixin. Mixed into `ResourceSelect` (and into any future input that wants typeahead). Two-method public surface:
+
+```ruby
+module Plutonium::UI::Form::Components::Searchable
+  extend ActiveSupport::Concern
+
+  # Maps :as symbol -> component class. Each typeahead-capable widget
+  # populates this when it includes Searchable so the controller can
+  # dispatch by name without a brittle inflection convention.
+  def self.registry
+    @registry ||= {}
+  end
+
+  class_methods do
+    # Subclasses call this to claim their :as symbol in the registry.
+    def typeahead_input_name(name)
+      Plutonium::UI::Form::Components::Searchable.registry[name.to_sym] = self
+    end
+
+    # Allocates the widget and assigns just the ivars #typeahead needs.
+    # Bypasses Phlex's render-time build_attributes pipeline so we don't
+    # need a field/form context to run the search.
+    def build_for_typeahead(options)
+      allocate.tap { |w| w.send(:apply_typeahead_options, options) }
+    end
+  end
+
+  # Returns [results_array, has_more_bool]. results entries are { value:, label: }.
+  def typeahead(query:, limit:, controller:)
+    raw = collect_typeahead_candidates(query, controller: controller)
+    over = raw.length > limit
+    [raw.first(limit).map { |r| serialize_typeahead_row(r) }, over]
+  end
+end
+```
+
+`ResourceSelect` implements `apply_typeahead_options`, `collect_typeahead_candidates`, and `serialize_typeahead_row`:
+
+- `apply_typeahead_options(options)` reads `@association_class`, `@raw_choices`, `@choice_limit`, `@skip_authorization` from the input definition's options hash — the same keys the existing `build_attributes` consumes at render time.
+- `collect_typeahead_candidates` branches:
+  - if `@raw_choices` (static list) — `@raw_choices.select { |label, _| label.to_s.downcase.include?(query.downcase) }`. No auth: choices are static, definition-author-controlled.
+  - elsif `@association_class` — runs the search through `controller.send(:authorized_resource_scope, @association_class)` so the associated resource's `policy.relation_scope` enforces row-level auth, then applies the associated resource definition's `search` block if present, else `LIKE` on the column backing `to_label` (or skips filtering when query is blank).
+- `serialize_typeahead_row(row)` returns `{ value: row.to_signed_global_id.to_s, label: row.to_label }` for records, or `{ value: raw_value, label: raw_label }` for static choices.
+
+The cap is **`limit + 1`** at the SQL level (`LIMIT 51` for a `limit: 50` request) so we can detect overflow without a separate `COUNT`.
+
+## Authorization
+
+Two gates, layered:
+
+1. **Parent gate** — `policy.typeahead?` on the resource hosting the endpoint. Defaults to `index?` (collection-shaped — typeahead is "list/search records of this class", not "show one record"). Override per-resource if needed (e.g. `def typeahead? = create? || update?` to require write intent).
+2. **Row gate** — when the input is association-backed, results are scoped through the *associated* resource's `policy.relation_scope` via the existing `authorized_resource_scope` helper. So a user can typeahead Authors only if they're allowed to read Authors, regardless of whether they can edit Posts.
+
+Static `choices` lists bypass the row gate (they're not records, they're definition-author-controlled enumerations).
+
+## Data flow
+
+```
+Browser (Stimulus controller)
+  fetch GET /widgets/typeahead/input/author?q=ali
+    ↓
+Typeahead#typeahead_input
+  authorize_typeahead! → policy.typeahead? on Widget       [parent gate]
+  defn = current_definition.defined_inputs[:author]
+  widget = ResourceSelect.build_for_typeahead(defn[:options])
+  widget.typeahead(query: "ali", limit: 50, controller: self)
+    authorized_resource_scope(User).where("name LIKE ?", "%ali%").limit(51)   [row gate]
+    serialize each → { value: sgid, label: to_label }
+  render json: { results: [...], has_more: false }
+```
+
+## Components
+
+| File | Responsibility |
+|---|---|
+| `lib/plutonium/routing/mapper_extensions.rb` | Add 2 routes to the `interactive_resource_actions` concern. |
+| `lib/plutonium/resource/controllers/typeahead.rb` | **New.** Controller concern with `typeahead_input`/`typeahead_filter` actions, auth, dispatch, JSON serialization. |
+| `lib/plutonium/resource/controller.rb` | Include `Controllers::Typeahead`. |
+| `lib/plutonium/resource/policy.rb` | Add `typeahead?` defaulting to `index?`. |
+| `lib/plutonium/ui/form/components/searchable.rb` | **New.** `Searchable` mixin (class-level `build_for_typeahead`, instance-level `typeahead`). |
+| `lib/plutonium/ui/form/components/resource_select.rb` | Include `Searchable`, call `typeahead_input_name :resource_select` to register. Implement `apply_typeahead_options`, `collect_typeahead_candidates`, `serialize_typeahead_row`. Wire Stimulus controller + remote URL data attrs into the rendered `<select>`. |
+| `src/js/controllers/resource_select_controller.js` | **New.** Stimulus controller: debounced fetch, populates options on the underlying `<select>`, surfaces overflow hint, handles network errors. |
+
+## Error handling
+
+- Unknown input/filter name → `404 Not Found`.
+- Input class registered but doesn't include `Searchable` → `400 Bad Request` with `{error: "input is not typeahead-capable"}`.
+- Authorization failure → existing `ActionPolicy::Unauthorized` flow → `403`.
+- Empty/blank `q` → return all candidates within the cap (so initial dropdown open shows something useful, mirroring the eager mode).
+- Network/parse errors on the JS side → controller leaves the existing `<select>` options intact and shows a small "couldn't search" inline notice; user can retry.
+
+## Testing
+
+- **Unit — `Searchable#typeahead` (ResourceSelect):** static choices filter case-insensitively; association case routes through `authorized_resource_scope`; overflow detection (`limit+1` rows in DB → `has_more: true`); blank query returns top-N.
+- **Controller — `Typeahead#typeahead_input` / `typeahead_filter`:** happy path renders correct JSON envelope; unknown name → 404; non-searchable input class → 400; auth denied → 403.
+- **Integration:** full request through `admin_portal` hitting a registered resource, verifying SGID round-trip (the value in the response is accepted by ResourceSelect on form submit).
+- **JS — Stimulus controller:** debounces input, handles `has_more`, handles network errors. Lightweight, behavior-focused.
+
+## Migration & rollout
+
+- Existing eager `ResourceSelect` keeps working — typeahead is opt-in per render via a flag on the input definition (e.g. `as: :resource_select, typeahead: true`). When unset, the component renders today's eager list. The Stimulus controller only attaches when `data-resource-select-typeahead-url-value` is present.
+- Filter inputs default to typeahead when the underlying input class supports it (filters are the worst pain point for the 100-row cap).
+
+## Open questions / deferred
+
+- Server-driven sort order beyond what `relation_scope` returns (e.g. recency, fuzzy-rank). Out of scope for MVP.
+- Multi-select typeahead UX (chips, paste-multiple). MVP supports `multiple: true` mechanically (the array of SGIDs round-trips fine), but the dropdown UX is single-select-shaped. Iteration.
+- Caching/coalescing repeated queries client-side. Defer.