ruact 0.0.12 → 0.0.14

data/lib/generators/ruact/install/templates/AGENTS.md.tt

@@ -15,7 +15,10 @@ truth" below) instead of guessing.
 
 ## Mental model
 
-- A page is a normal Rails controller action rendering a normal `.html.erb`.
+- A page is an action rendering a `.html.erb` in a controller with `include Ruact::Controller`
+  (install adds it to none — `--app` puts it on ApplicationController; `ruact:scaffold`
+  adds it; `ruact_pages only:` narrows it). The page's renderer owns navigation:
+  going between a ruact page and a plain Rails/Turbo page is a full page load.
 - Interactive components live in `app/javascript/components/` as `"use client"`
   files, mounted from ERB with a PascalCase self-closing tag:
   `<LikeButton postId={@post.id} />`.
@@ -66,10 +69,9 @@ object is instantiated.
 
 ## Ground truth — read the generated file
 
-`app/javascript/.ruact/server-functions.ts` is regenerated from the route
-table (it is gitignored). It is the authoritative list of every accessor and
-its typed params — READ THAT FILE instead of simulating the name generation.
-Regenerate it after changing routes or queries:
+`app/javascript/.ruact/server-functions.ts` (gitignored, regenerated from the
+route table) is the authoritative list of every accessor and its typed params —
+READ IT instead of simulating the name generation. Regenerate after routes/queries change:
 
     bin/rails ruact:server_functions:generate
 
@@ -92,12 +94,12 @@ Regenerate it after changing routes or queries:
    (a Flight stream for client-side navigation, an HTML page otherwise). You
    cannot infer the response shape from the controller body alone — the
    caller picks it.
-4. **`ruact_errors` requires fall-through.** On the `if @post.save ... else`
-   path, call `ruact_errors(@post)` and let the action END there — ruact's
-   implicit render injects `errors: { attribute: [messages] }` into the JSON.
-   An explicit `render` on that branch opts out of the injection. In the
-   redirect-back flow, `ruact_errors(@post)` then `redirect_to` carries the
-   errors through flash to the next render.
+4. **`ruact_errors` requires fall-through.** On a function call's failed-save
+   branch, call `ruact_errors(@post)` and let the action END — the implicit
+   render injects `errors: { attribute: [messages] }` into the JSON (an explicit
+   `render` opts out). On a page form, `ruact_errors(@post)` then
+   `render :new, status: :unprocessable_entity` re-renders the page through ruact
+   (view: `errors={ruact_errors}`); `redirect_to` instead carries them via flash.
 5. **Accessor names are derived, not declared.** `posts#create` → `createPost`,
    `posts#publish_all` → `publishAllPosts`; query methods camelCase the same
    way (`search_users` → `searchUsers`). Collisions fail loudly at boot;
@@ -146,8 +148,7 @@ duration, or a deliberate `expires_in: nil` for a non-expiring token.
   `schema_version` field (currently `0`), do not treat it as a stable contract.
 - `bin/rails ruact:server_functions:generate` — regenerates the TS module;
   exits 1 on a naming collision or an invalid name.
-- `bin/dev` — boots Rails AND Vite (both are required: Vite serves the client
-  components and writes the client manifest).
+- `bin/dev` — boots Rails AND Vite (both required: Vite serves the client components).
 - If your app has TypeScript tooling configured, `npx tsc --noEmit`
   type-checks call sites against the generated accessor types (a fresh
   install does not ship a tsconfig).

data/lib/generators/ruact/install/templates/Procfile.dev.tt

@@ -1,5 +1,5 @@
 web: bin/rails server -p 3000
 vite: npm run dev
 <% if shadcn? -%>
-css: npx @tailwindcss/cli -i app/javascript/styles/globals.css -o app/assets/builds/tailwind.css --watch
+<%= SHADCN_CSS_PROCESS %>
 <% end -%>

data/lib/generators/ruact/install/templates/initializer.rb.tt

@@ -1,14 +1,36 @@
 # frozen_string_literal: true
 
 Ruact.configure do |config|
-  # Render ruact pages through your app's own layout, so the document `<head>`
-  # is yours: `stylesheet_link_tag`, favicons, fonts, analytics and any gem that
-  # writes into `<head>` all reach a ruact page. Requires the layout to call
-  # `<%%= ruact_js_assets %>` (this generator adds it next to the React root).
-  #
-  # Set to false to use ruact's built-in minimal shell instead — it has no
-  # stylesheet slot, so your app's CSS will NOT reach a ruact-rendered page.
+<% if whole_app? -%>
+  # Whole-app mode (`rails generate ruact:install --app`, or an app installed
+  # before island mode was the default): ApplicationController
+  # includes Ruact::Controller, so every action with an .html.erb template
+  # renders through ruact, into your own layout. That layout needs
+  # `<%%= ruact_head_assets %>` in <head> and `<%%= ruact_js_assets %>` next to a
+  # `<div id="root"></div>` (`rails ruact:doctor` checks).
   config.layout = true
+<% else -%>
+  # Island mode: nothing in your controllers changed. A page renders through
+  # ruact when its controller has `include Ruact::Controller` — narrow it to
+  # some actions with `ruact_pages only: %i[show]`.
+  #
+  # Ruact pages render through the layout ruact ships (layouts/ruact). It links
+  # the CSS your client components import, then the stylesheets below — yours
+  # load last, so they win ties — and it edits none of your layouts. What it
+  # does NOT bring is the rest of your own layout's <head> or your app's
+  # JavaScript; to own that document, copy it into your app with
+  # `rails generate ruact:layout`.
+  #
+  # Set to true to render through your app's own layout instead (it then needs
+  # `<%%= ruact_head_assets %>` in <head> and `<%%= ruact_js_assets %>` next to a
+  # `<div id="root"></div>`; `rails ruact:doctor` checks), or false for ruact's
+  # minimal built-in shell, which carries none of your stylesheets.
+  config.layout = "ruact"
+
+  # The app stylesheets ruact's layout links, as you would pass them to
+  # stylesheet_link_tag. [:app] under Propshaft is every stylesheet you have.
+  config.layout_stylesheets = <%= detected_layout_stylesheets %>
+<% end -%>
 
   # Path to the react-client-manifest.json generated by the Vite plugin.
   # Defaults to Rails.root.join("public/react-client-manifest.json").

data/lib/generators/ruact/install/templates/package.json.tt

@@ -5,7 +5,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build"<% if shadcn? %>,
-    "build:css": "@tailwindcss/cli -i app/javascript/styles/globals.css -o app/assets/builds/tailwind.css --minify"<% end %>
+    "build:css": "<%= SHADCN_BUILD_CSS_SCRIPT %>"<% end %>
   },
   "dependencies": {
     "react": "^19.0.0",
@@ -14,9 +14,9 @@
   "devDependencies": {
     "@vitejs/plugin-react": "^4.3.4",
 <% if shadcn? -%>
-    "@tailwindcss/cli": "^4.0.0",
-    "tailwindcss": "^4.0.0",
-    "tw-animate-css": "^1.0.0",
+<% SHADCN_DEV_DEPENDENCIES.each do |name, version| -%>
+    "<%= name %>": "<%= version %>",
+<% end -%>
 <% end -%>
     "vite": "^6.0.7"
   }

data/lib/generators/ruact/install/templates/tsconfig.json.tt

@@ -9,6 +9,9 @@
     "noEmit": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
+    // Vite's client types. Without them a client component importing a
+    // stylesheet for its side effect has no declaration to resolve against.
+    "types": ["vite/client"],
     "baseUrl": ".",
     "paths": {
       "@/*": ["app/javascript/*"]

data/lib/generators/ruact/layout/layout_generator.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "ruact"
+
+module Ruact
+  module Generators
+    # Copies the layout ruact pages render into (`layouts/ruact`, shipped with
+    # the gem) into the app, so the app owns it.
+    #
+    # Nothing needs configuring afterwards: the gem's view path is APPENDED by
+    # the Railtie, behind the app's, so `app/views/layouts/ruact.html.erb` wins
+    # by view-path order the moment it exists. That is the point of the ejected
+    # copy — add the app's JavaScript, fonts, meta tags or anything else
+    # `config.layout_stylesheets` cannot express.
+    #
+    # The cost, said once here and again when the command runs: an ejected
+    # layout no longer changes when the gem does.
+    #
+    # Run: rails generate ruact:layout
+    class LayoutGenerator < Rails::Generators::Base
+      source_root Ruact.views_path
+
+      desc "Copies ruact's layout into app/views/layouts/ruact.html.erb so your app owns it"
+
+      DESTINATION = "app/views/layouts/ruact.html.erb"
+
+      # `copy_file` already refuses to overwrite silently: an existing file
+      # prompts, or is skipped/overwritten under `--skip`/`--force`, which is
+      # the Rails convention every other generator follows.
+      def copy_layout
+        copy_file "layouts/ruact.html.erb", DESTINATION
+      end
+
+      # Only on `generate` (not `destroy`), and phrased for what is true: the copy
+      # renders ruact pages while `config.layout` is "ruact" — under `true` or
+      # `false` it is not used at all.
+      def explain
+        return unless behavior == :invoke
+
+        say ""
+        say "  #{DESTINATION} renders ruact pages in place of the one ruact ships,"
+        say "  as long as config.layout is \"ruact\". It will no longer change when you upgrade the gem —"
+        say "  compare it with #{File.join(Ruact.views_path, 'layouts/ruact.html.erb')}"
+        say "  after an upgrade. Keep `<%= ruact_head_assets %>` in <head>, and"
+        say "  `<div id=\"root\"></div>` with `<%= ruact_js_assets %>` in <body>:"
+        say "  `rails ruact:doctor` checks all three."
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/ruact/scaffold/scaffold_generator.rb

@@ -107,7 +107,7 @@ module Ruact
 
       SUPPORTED_TYPES = TYPE_MAP.keys.freeze
 
-      # Column types the `search` query's case-insensitive LIKE scope spans —
+      # Column types the search query's case-insensitive LIKE scope spans —
       # matching numeric/date/boolean columns by substring is meaningless.
       SEARCHABLE_COLUMN_TYPES = %w[string text].freeze
 
@@ -121,7 +121,7 @@ module Ruact
       REFERENCE_OPTIONS_LIMIT = 100
 
       # Documentation anchor referenced by the unknown-type error message (AC4).
-      DOCS_POINTER = "https://github.com/luizcg/ruact/blob/main/website/docs/api/scaffold.md#attribute-types"
+      DOCS_POINTER = "https://ruact.dev/docs/api/scaffold.html#attribute-types"
 
       # Story 10.5 (AC1, AC2, AC4) — the shadcn/ui dependency PRE-FLIGHT: detect
       # the host's shadcn state (complete / missing / partial) and either proceed
@@ -191,7 +191,7 @@ module Ruact
       end
 
       # AC5 — the client-driven read path. Emits the resource query
-      # (`<Plural>Query < ApplicationQuery` with a `search(q:)` method) in BOTH
+      # (`<Plural>Query < ApplicationQuery` with a `search_<plural>(q:)` method) in BOTH
       # `.tsx` and `.jsx` modes (the query is server-side Ruby; the language flag
       # only governs the React component). The `ApplicationQuery` base is created
       # idempotently — `ruact:install` does NOT ship it, and a second scaffold in
@@ -205,13 +205,13 @@ module Ruact
         template "queries/application_query.rb.tt", application_query
       end
 
-      # AC5 — mount the resource query so its `search` method becomes the named
-      # GET route the codegen exports as `search` (consumed by `useQuery`).
+      # AC5 — mount the resource query so its `search_<plural>` method becomes the
+      # named GET route the codegen exports as `search<Plural>` (consumed by `useQuery`).
       # Idempotent on re-run: guard on the drawn `ruact_queries <Plural>Query`
       # line first (sibling of {#add_resource_route}'s `resources :posts` guard).
       def add_query_route
         routes_file = Pathname(destination_root).join("config/routes.rb")
-        if routes_file.exist? && routes_file.read.match?(/^\s*ruact_queries\s+#{Regexp.escape(query_class_name)}\b/)
+        if routes_file.exist? && query_already_mounted?(routes_file.read)
           say_status "skip", "ruact_queries #{query_class_name} already routed", :yellow
           return
         end
@@ -406,17 +406,44 @@ module Ruact
 
         # The read-side query class — PLURAL, mirroring the golden `PostsQuery`
         # (file `posts_query.rb`) and Zeitwerk's path↔constant rule. Mounted via
-        # `ruact_queries <Plural>Query`; its `search` method becomes `GET /q/search`.
+        # `ruact_queries <Plural>Query`; its search method becomes `GET /q/searchPosts`.
         def query_class_name
           "#{class_name.pluralize}Query"
         end
 
-        # The JS import alias for the query's `search` accessor. The codegen
-        # exports a generic `search` (from `<Plural>Query#search`); the component
-        # aliases it `search<Plural>` to avoid a bare-`search` collision — exactly
-        # as the golden does (`search as searchPosts`).
+        # True when a `ruact_queries` line already lists this exact class —
+        # alone or among others, ignoring a trailing comment and not mistaking
+        # `Legacy::PostsQuery` or `BlogPostsQuery` for `PostsQuery`.
+        def query_already_mounted?(routes)
+          class_ref = /(?<![:\w])#{Regexp.escape(query_class_name)}\b/
+          routes.each_line.any? do |line|
+            code = line.sub(/#.*/, "")
+            code.match?(/\A\s*ruact_queries\b/) && code.match?(class_ref)
+          end
+        end
+
+        # The query's search method, named after the resource (`search_posts`).
+        # Query names share ONE namespace — one `GET /q/<name>` route and one
+        # export of `@/.ruact/server-functions` per name — so a bare `search`
+        # was free for the first resource and broke the boot on the second
+        # (`ruact_query_search` drawn twice).
+        def query_search_method
+          "search_#{plural_table_name}"
+        end
+
+        # The accessor the codegen exports for {#query_search_method}
+        # (`searchPosts`); the List imports it under this name, unaliased.
         def js_search_alias
-          "search#{class_name.pluralize}"
+          Ruact::ServerFunctions::NameBridge.to_js_identifier(query_search_method)
+        end
+
+        # The List's collection prop, named after the resource (`posts`,
+        # `comments`, `blogPosts`) rather than fixed to the golden's `posts`.
+        # The List binds it to a fixed local (`initialRows`), so a model whose
+        # plural matches one of the List's own names (`Row` → `rows`) or one a
+        # module cannot declare (`Argument` → `arguments`) still compiles.
+        def js_collection_prop
+          plural_table_name.camelize(:lower)
         end
 
         # The columns the search `LIKE` scope spans — string/text only (a

data/lib/generators/ruact/scaffold/scaffold_shadcn_preflight.rb

@@ -20,7 +20,7 @@ module Ruact
         # Documentation anchor for the shadcn dependency pre-flight: how to set
         # up shadcn, and how to override the version-compat warning.
         SHADCN_DOCS_POINTER =
-          "https://github.com/luizcg/ruact/blob/main/website/docs/api/scaffold.md#shadcnui-setup"
+          "https://ruact.dev/docs/guides/shadcn-ui.html#shadcn-versions"
 
         # The pre-flight body (the {ScaffoldGenerator#check_shadcn_setup} Thor
         # command delegates here). Detect the host's shadcn state, surface the
@@ -141,9 +141,10 @@ module Ruact
           <<~MSG.chomp
             ruact:scaffold — shadcn/ui is not set up in this app yet.
             The generated components import from @/components/ui/*, which does not exist.
-            Set up shadcn/ui first, then re-run this generator:
+            Set up shadcn/ui first (--base radix: the components import Radix primitives,
+            and shadcn now defaults to Base UI), then re-run this generator:
 
-              npx shadcn@latest init
+              npx shadcn@latest init --base radix
               #{shadcn_add_command(required_shadcn_components)}
 
             No files were written (no partial state). Advanced: pass --skip-shadcn-check

data/lib/generators/ruact/scaffold/templates/components/List.tsx.tt

@@ -16,7 +16,7 @@
 // small GENERATED client-side sort. There is NO table-engine dependency: the
 // scaffold stays dep-free (no react-table runtime), matching the dep-free
 // Form and the native date inputs. The collection arrives as a SERVER-RENDERED
-// prop (`posts`); there is no client query for the initial render. A query only
+// prop (`<%= js_collection_prop %>`); there is no client query for the initial render. A query only
 // enters when the *client* drives the read: the search box calls
 // useQuery(<%= js_search_alias %>, { q }) and swaps in filtered rows as you type.
 // Per-row delete drives a controlled <%= class_name %>DeleteDialog (DELETE
@@ -30,7 +30,7 @@
 // freshly scaffolded app will not resolve these until 10.5 lands; that is
 // expected (the end-to-end live demo is Story 10.7).
 import { useState } from "react";
-import { search as <%= js_search_alias %>, destroy<%= class_name %>, useQuery } from "@/.ruact/server-functions";
+import { <%= js_search_alias %>, destroy<%= class_name %>, useQuery } from "@/.ruact/server-functions";
 import { <%= class_name %>DeleteDialog } from "./<%= class_name %>DeleteDialog";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
@@ -52,11 +52,11 @@ import {
 
 type <%= class_name %>Row = { <%= ts_row_fields %> };
 
-// FR100 — opt-in call-site contract: `posts` is required. The index view passes
-// `<<%= class_name %>List posts={rows} />` (satisfied); a call site that omits it
+// FR100 — opt-in call-site contract: `<%= js_collection_prop %>` is required. The index view passes
+// `<<%= class_name %>List <%= js_collection_prop %>={rows} />` (satisfied); a call site that omits it
 // fails at preprocess time, not as a silent `undefined` in the browser.
 export const __ruactContract = {
-  props: { posts: "required" },
+  props: { <%= js_collection_prop %>: "required" },
 };
 <% end -%>
 
@@ -208,9 +208,9 @@ function RowActions({ record, onDeleted }<% if typescript? %>: {
 }
 
 export function <%= class_name %>List({
-  posts = [],
+  <%= js_collection_prop %>: initialRows = [],
   emptyLabel = "No <%= plural_name %> yet — create one.",
-}<% if typescript? %>: { posts?: <%= class_name %>Row[]; emptyLabel?: string }<% end %>) {
+}<% if typescript? %>: { <%= js_collection_prop %>?: <%= class_name %>Row[]; emptyLabel?: string }<% end %>) {
   const [q, setQ] = useState("");
   const searching = q.trim().length > 0;
 
@@ -229,7 +229,7 @@ export function <%= class_name %>List({
   // the box is idle and we fall back to the server-rendered rows.
   const { data: searchData, loading: searchLoading } = useQuery<% if typescript? %><<%= class_name %>Row[]><% end %>(<%= js_search_alias %>, { q: q.trim() });
 
-  const source = searching ? searchData ?? [] : posts;
+  const source = searching ? searchData ?? [] : initialRows;
   const rows = removedIds.length === 0 ? source : source.filter((row) => !removedIds.includes(row.id));
   // Always sort a COPY — never mutate the prop/source array.
   const sortedRows = sort ? [...rows].sort((a, b) => compareRows(a, b, sort)) : rows;

data/lib/generators/ruact/scaffold/templates/components/agnostic/List.tsx.tt

@@ -8,7 +8,7 @@
 // <%= class_name %> list — a DESIGN-SYSTEM-AGNOSTIC table (Story 14.4 / FR103). The
 // default scaffold ships plain, native HTML elements styled by the browser /
 // Rails-default CSS — NO shadcn/ui, NO Tailwind, NO table-engine dependency. The
-// collection arrives as a SERVER-RENDERED prop (`posts`); there is no client query
+// collection arrives as a SERVER-RENDERED prop (`<%= js_collection_prop %>`); there is no client query
 // for the initial render. A query only enters when the *client* drives the read:
 // the search box calls useQuery(<%= js_search_alias %>, { q }) and swaps in filtered rows as
 // you type. Per-row delete drives a controlled <%= class_name %>DeleteDialog (DELETE
@@ -18,17 +18,17 @@
 // sort/pagination is Phase-3 territory. (The richer shadcn DataTable styling is
 // the opt-in `--shadcn` path — Story 14.5.)
 import { useState } from "react";
-import { search as <%= js_search_alias %>, destroy<%= class_name %>, useQuery } from "@/.ruact/server-functions";
+import { <%= js_search_alias %>, destroy<%= class_name %>, useQuery } from "@/.ruact/server-functions";
 import { <%= class_name %>DeleteDialog } from "./<%= class_name %>DeleteDialog";
 <% if typescript? -%>
 
 type <%= class_name %>Row = { <%= ts_row_fields %> };
 
-// FR100 — opt-in call-site contract: `posts` is required. The index view passes
-// `<<%= class_name %>List posts={rows} />` (satisfied); a call site that omits it
+// FR100 — opt-in call-site contract: `<%= js_collection_prop %>` is required. The index view passes
+// `<<%= class_name %>List <%= js_collection_prop %>={rows} />` (satisfied); a call site that omits it
 // fails at preprocess time, not as a silent `undefined` in the browser.
 export const __ruactContract = {
-  props: { posts: "required" },
+  props: { <%= js_collection_prop %>: "required" },
 };
 <% end -%>
 
@@ -146,9 +146,9 @@ function RowActions({ record, onDeleted }<% if typescript? %>: {
 }
 
 export function <%= class_name %>List({
-  posts = [],
+  <%= js_collection_prop %>: initialRows = [],
   emptyLabel = "No <%= plural_name %> yet — create one.",
-}<% if typescript? %>: { posts?: <%= class_name %>Row[]; emptyLabel?: string }<% end %>) {
+}<% if typescript? %>: { <%= js_collection_prop %>?: <%= class_name %>Row[]; emptyLabel?: string }<% end %>) {
   const [q, setQ] = useState("");
   const searching = q.trim().length > 0;
 
@@ -167,7 +167,7 @@ export function <%= class_name %>List({
   // the box is idle and we fall back to the server-rendered rows.
   const { data: searchData, loading: searchLoading } = useQuery<% if typescript? %><<%= class_name %>Row[]><% end %>(<%= js_search_alias %>, { q: q.trim() });
 
-  const source = searching ? searchData ?? [] : posts;
+  const source = searching ? searchData ?? [] : initialRows;
   const rows = removedIds.length === 0 ? source : source.filter((row) => !removedIds.includes(row.id));
   // Always sort a COPY — never mutate the prop/source array.
   const sortedRows = sort ? [...rows].sort((a, b) => compareRows(a, b, sort)) : rows;

data/lib/generators/ruact/scaffold/templates/controller.rb.tt

@@ -2,9 +2,10 @@
 
 # <%= controller_class_name %>Controller — a complete CRUD on the v2 route-driven contract.
 #
-# `include Ruact::Server` (sibling of the Ruact::Controller already on
-# ApplicationController via `ruact:install`) gives this controller two
-# behaviours at once:
+# `include Ruact::Controller` makes this controller's pages ruact pages — the
+# install no longer puts it on ApplicationController (Story 17.0g: island mode
+# is the default; in whole-app mode, `ruact:install --app`, including it again
+# here is a no-op). `include Ruact::Server` then gives it two behaviours:
 #
 #   - GET actions (index/show/new/edit) need NO explicit `ruact_render` —
 #     Ruact::Controller#default_render activates the RSC pipeline implicitly
@@ -22,6 +23,7 @@
 # NOTE: `include Ruact::Server` must come AFTER `protect_from_forgery` (inherited
 # from ApplicationController) so the CSRF check precedes these actions.
 class <%= controller_class_name %>Controller < ApplicationController
+  include Ruact::Controller
   include Ruact::Server
 
   # --- GET pages (rendered as RSC) -----------------------------------------

data/lib/generators/ruact/scaffold/templates/queries/query.rb.tt

@@ -3,7 +3,7 @@
 # Read side of the CRUD. Each public instance method becomes one named GET
 # route when mounted with `ruact_queries <%= query_class_name %>`:
 #
-#   GET /q/search  → <%= query_class_name %>#search(q:)  → useQuery(<%= js_search_alias %>, { q })  (list search box)
+#   GET /q/<%= js_search_alias %>  → <%= query_class_name %>#<%= query_search_method %>(q:)  → useQuery(<%= js_search_alias %>, { q })  (list search box)
 #
 # NOTE: there is deliberately NO whole-list query — the index list is
 # server-rendered as props (see <%= controller_class_name %>Controller#index). A query is only the
@@ -14,7 +14,7 @@ class <%= query_class_name %> < ApplicationQuery
   # is what justifies a query — the result depends on live client input, not on
   # what the server already had. Rows are the SAME shape the index serializes, so
   # the search results and the server-rendered props are interchangeable.
-  def search(q:)
+  def <%= query_search_method %>(q:)
     term = q.to_s.strip
     scope =
 <% if searchable_attributes.empty? -%>

data/lib/generators/ruact/scaffold/templates/views/index.html.erb.tt

@@ -3,4 +3,4 @@
     Flight payload: no client query, no loading flash. The ivar is serialized to
     plain row hashes here in the view (no as_json on the model). %>
 <%% rows = @<%= plural_name %>.map { |<%= singular_name %>| <%= serialized_row(singular_name) %> } %>
-<<%= class_name %>List posts={rows} />
+<<%= class_name %>List <%= js_collection_prop %>={rows} />

data/lib/ruact/configuration.rb

@@ -9,7 +9,7 @@ module Ruact
   # `Ruact::ConfigurationError` with the offending attribute, the caller's
   # file:line, and the suggested fix. Re-calling `Ruact.configure` after boot
   # replaces the configuration atomically and emits a `[ruact]` warning.
-  class Configuration
+  class Configuration # rubocop:disable Metrics/ClassLength -- an attribute list with a validator per attribute; Doctor and InstallGenerator carry the same disable
     # The set of public attributes; new attributes added here automatically
     # inherit the freeze contract via the `define_method` writer below.
     ATTRIBUTES = %i[
@@ -25,6 +25,7 @@ module Ruact
       signed_global_id_default_expires_in
       shadcn_compatible_versions
       layout
+      layout_stylesheets
     ].freeze
 
     # @!attribute [r] manifest_path
@@ -72,7 +73,7 @@ module Ruact
     #     a stream-safety guarantee — Rack's multipart parser will still buffer
     #     bodies up to its own limits before the guard rejects. For very large
     #     uploads route through Active Storage Direct Upload or a presigned S3
-    #     URL; see `website/docs/api/server-actions.md` "File uploads" section.
+    #     URL; see https://ruact.dev/docs/api/server-actions.html, "File uploads".
     #   @example Raise the limit to 25 MB
     #     Ruact.configure { |c| c.max_upload_bytes = 25 * 1024 * 1024 }
     #   @example Disable the gem-side guard (reverse proxy owns the cap)
@@ -131,11 +132,13 @@ module Ruact
     #     host `package.json`) that is NOT in this list, it emits a warning
     #     (never a hard stop) that the generated components may import from
     #     outdated `@/components/ui/*` paths. Must be a non-empty Array of
-    #     Integers. Default `[1, 2]` (the majors tested at gem-release time).
+    #     Integers. Default `[1, 2, 4]` (the majors tested at gem-release time;
+    #     4 was run end to end on 2026-10-01: init --base radix, the full add
+    #     list, scaffold --shadcn, form/table/dialog in a browser).
     #     A dev who has manually verified a newer major adds it here to
     #     suppress the warning — the documented "override" path.
     #   @example Allow shadcn v3 once you have verified it
-    #     Ruact.configure { |c| c.shadcn_compatible_versions = [1, 2, 3] }
+    #     Ruact.configure { |c| c.shadcn_compatible_versions = [1, 2, 3, 4] }
     #
     # @!attribute [r] layout
     #   @return [Boolean, String] Which document wrapper a ruact page's HTML
@@ -144,17 +147,21 @@ module Ruact
     #     full-document render a browser gets on a normal navigation.
     #
     #     - `false` (default) — render the gem's built-in minimal shell.
+    #     - `"ruact"` — render through the layout the gem ships
+    #       (`lib/ruact/views/layouts/ruact.html.erb`, Story 17.0b): CSRF, CSP,
+    #       the client-component CSS, then the app stylesheets named in
+    #       {#layout_stylesheets}. What `rails generate ruact:install` writes.
+    #       It edits no layout of the app; an app that puts its own
+    #       `app/views/layouts/ruact.html.erb` in place (`rails generate
+    #       ruact:layout` copies the gem's) wins by view-path order.
     #     - `true` — render through the controller's normal Rails layout.
-    #     - a String — render through that named layout (e.g. `"ruact"`).
+    #     - another String — render through that named layout.
     #
-    #     The layout path exists because the document `<head>` belongs to the
-    #     host app: `stylesheet_link_tag`, favicons, fonts, analytics and any
-    #     `<head>`-writing gem only reach the page when Rails' own layout owns
-    #     the document. The built-in shell carries no stylesheet slot, so under
-    #     the `false` default a ruact page renders with no app CSS at all —
-    #     which is why `rails generate ruact:install` writes `config.layout =
-    #     true` into the generated initializer and adds `<%= ruact_js_assets %>`
-    #     to your layout in the same run.
+    #     The trade-off between the last two and `"ruact"`: the app's own layout
+    #     brings its whole `<head>` (favicons, fonts, analytics, `<head>`-writing
+    #     gems) but has to be wired by hand; the gem's layout needs no wiring but
+    #     brings only the stylesheets. The built-in shell carries neither — under
+    #     the `false` default a ruact page renders with no app CSS at all.
     #
     #     **This setting is deliberately explicit — there is no auto-detection.**
     #     ruact used to try to infer whether your layout was ready by inspecting
@@ -173,10 +180,26 @@ module Ruact
     #   @note A ruact view is rendered in its own pass (it produces the component
     #     tree), so `content_for` declared inside the view does NOT reach the
     #     layout. Set document metadata from the controller instead.
-    #   @example Let your layout own the document (what ruact:install writes)
-    #     Ruact.configure { |c| c.layout = true }
-    #   @example Use a dedicated layout for ruact pages only
+    #   @example Render through the layout ruact ships (what ruact:install writes)
     #     Ruact.configure { |c| c.layout = "ruact" }
+    #   @example Let your own application layout own the document
+    #     Ruact.configure { |c| c.layout = true }
+    #
+    # @!attribute [r] layout_stylesheets
+    #   @return [Array<Symbol, String>] The app stylesheets the gem's layout
+    #     (`layouts/ruact`, used when `layout` is `"ruact"`) links, passed as-is
+    #     to `stylesheet_link_tag`. They come AFTER the client-component CSS
+    #     (`ruact_head_assets`), so the app's own CSS loads last and wins ties.
+    #
+    #     Defaults to `[:app]`, what `rails new` 8.x puts in its layout: under
+    #     Propshaft it expands to every stylesheet on the load path, including a
+    #     Tailwind build. Under Sprockets `:app` means a file called `app.css`,
+    #     which is why `rails generate ruact:install` writes `["application"]`
+    #     there instead. `[]` links none. Anything more than a list of names —
+    #     a media attribute, fonts, other `<head>` tags — is what ejecting the
+    #     layout is for: `rails generate ruact:layout`.
+    #   @example A Sprockets app
+    #     Ruact.configure { |c| c.layout_stylesheets = ["application"] }
     ATTRIBUTES.each do |attr|
       attr_reader attr
 
@@ -229,8 +252,9 @@ module Ruact
         @query_parent_controller = "ApplicationController"
         @signed_global_id_default_purpose = nil
         @signed_global_id_default_expires_in = nil
-        @shadcn_compatible_versions = [1, 2]
+        @shadcn_compatible_versions = [1, 2, 4]
         @layout = false
+        @layout_stylesheets = [:app]
       end
     end
 
@@ -266,6 +290,10 @@ module Ruact
         # reference, but a caller probing `frozen?` would see the right answer.
         if value.is_a?(Proc)
           value.freeze
+        elsif value.is_a?(Array)
+          # Story 17.0b — `layout_stylesheets` holds Strings; freezing only the
+          # Array would leave `Ruact.config.layout_stylesheets.first << "x"` open.
+          instance_variable_set("@#{attr}", value.map { |item| item.frozen? ? item : item.dup.freeze }.freeze)
         else
           instance_variable_set("@#{attr}", value.dup.freeze)
         end
@@ -293,6 +321,7 @@ module Ruact
       when :query_parent_controller then validate_query_parent_controller!(value)
       when :shadcn_compatible_versions then validate_shadcn_compatible_versions!(value)
       when :layout                     then validate_layout!(value)
+      when :layout_stylesheets         then validate_layout_stylesheets!(value)
       end
     end
 
@@ -325,6 +354,31 @@ module Ruact
             "false uses ruact's built-in shell."
     end
 
+    # Story 17.0b — the arguments `layouts/ruact` passes to `stylesheet_link_tag`.
+    # Checked at boot because the layout splats them straight into a Rails
+    # helper, where a stray nil or Hash would surface as a first-render error
+    # instead of a legible configuration one.
+    #
+    # Propshaft reads `:app` / `:all` ONLY as the first item, and then ignores
+    # every other one (`case sources.first when :app then sources = …`): so
+    # `[:app, "theme"]` silently drops "theme", and `["reset", :app]` looks for
+    # a file named app.css and raises. Either is allowed only on its own.
+    def validate_layout_stylesheets!(value)
+      if value.is_a?(Array) && value.length > 1 && value.intersect?(%i[app all])
+        raise Ruact::ConfigurationError,
+              "Ruact::Configuration#layout_stylesheets: :app and :all stand alone — Propshaft reads " \
+              "them only as the whole list and drops anything next to them; got #{value.inspect}. " \
+              "Use [:app], or list the stylesheets by name."
+      end
+      return if value.is_a?(Array) && value.all? { |name| name.is_a?(Symbol) || (name.is_a?(String) && !name.empty?) }
+
+      raise Ruact::ConfigurationError,
+            "Ruact::Configuration#layout_stylesheets must be an Array of stylesheet names " \
+            "(Symbols or non-empty Strings, as you would pass to stylesheet_link_tag), " \
+            "e.g. [:app] or [\"application\"]; got #{value.inspect} (#{value.class.name}). " \
+            "Use [] to link none of your app's stylesheets."
+    end
+
     def validate_max_upload_bytes!(value)
       return if value.nil?
       return if value.is_a?(Integer) && value >= 0