ruact 0.0.13 → 0.0.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 962dae09686957b84e9e34d12809714978e95e6392265b7fd7f64a7028dd86f5
-  data.tar.gz: ecad09e13bcc52fe30bff4ece70e14527e0c501166d2d487625c9a92ada3a2fd
+  metadata.gz: ab61a580bf64e964d0356fae822cc80a83d31eaaa38fdfb5398e6534158772f0
+  data.tar.gz: c66021ed18cba60a650a6f1f4e77fc60b848079e2c125aa4f34f2868f6af2101
 SHA512:
-  metadata.gz: 87a00a254896d68831e62bb892932c29b0668628232757f692b22c00f1a188de0db7d2ba9600e199e6f46aa1997b73ebe7fed0e6ef193a6d4b060b7fc410b2cf
-  data.tar.gz: f90d5ba0da42e90e7031cff6d93ce648229655a5eea726a8572664354291aa974254f5696596a339942dedf7630506292618c48323a70cf7302c247eae7cb6b3
+  metadata.gz: 053037bfb91205f625613499e5b98c14da4e886be7a94ef60239a1da934d44a35dbf104208494cc951eb7048c9bedbf1b8792c46ed9428e2a455f18d6141f729
+  data.tar.gz: '0800f0c8d28ea88c91b7d40b488ac6931b7548811cbfa0bd56458dbc9d0d4a09ab8f2db5a0884217045072b9a3889fa168cd83d969cb9f778bf22aab0ddc1cc8'

data/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.15] - 2026-10-03
+
+### Security
+
+- **Text in a prop could run as script on the page (stored XSS).** On a plain browser load, the page's Flight payload is inlined in a `<script>` element. It was embedded as a Ruby string literal with only a lowercase `</script>` escaped. A value containing `</SCRIPT>`, `</script >` or another casing closed the element, and the rest ran as HTML. A post titled `</SCRIPT><img src=x onerror=…>` executed its handler for everyone who opened the list. Any string a ruact page passes as a prop, such as user-written record content, could do it. The payload is now embedded as a JSON string literal with `<`, `>`, `&`, U+2028 and U+2029 escaped, so no character of it can end the element. Control characters such as `\e`, which the Ruby literal also delivered wrongly to JavaScript, now arrive intact. **Affects every version up to and including 0.0.14; upgrade.** `Ruact::Testing`'s matchers read both forms.
+
+- **A same-origin redirect could send the browser to another site.** `redirect_to "#{root_url}#{params[:path]}"` with `path=/evil.com` gives `https://your.app//evil.com`, which is your own host, so Rails' open-redirect check accepts it. ruact then shortened every same-origin URL to its path, `//evil.com`, and a browser reads that as a URL to `evil.com`. A server function answered `{"$redirect":"//evil.com"}` and the runtime navigated there. A page redirect produced a Flight row the router refused, so the navigation silently did nothing. A path that a browser would read as another host now keeps its absolute, same-origin URL.
+
+### Fixed
+
+- **Any text of 1 KB or more blanked the page.** The server sends every string of 1024 bytes or more as a separate row framed by its byte length, with no newline after it. The browser read the payload line by line, so it lost the row that holds the page and showed nothing: `[flight-client] No root row (id=0) found in payload`. A scaffolded post whose body was one long paragraph made the whole list disappear. The first load and the router now read the payload with one parser that works on bytes, so text arrives exactly as it left, including multibyte characters and newlines, wherever the network splits it. A truncated or malformed payload, or a reference to text that never arrived, is now an error that says so instead of a blank page. Long text inside Suspense content was also never sent at all; it is now, before the row that uses it. `Ruact::Testing`'s matchers compare a long prop by its text.
+
+- **Dates and large integers reached React as marker strings.** A Ruby `Time`, `DateTime` or `ActiveSupport::TimeWithZone` prop arrived as `"$D2026-09-08T12:30:45.123Z"`, and an integer beyond JavaScript's safe range (±(2^53 − 1)) as `"$n9007199254740993"`. A component had to know ruact's transport to use them. They now arrive as a `Date`, with the same instant and millisecond precision, and as a `BigInt`; integers inside the safe range stay numbers. This holds on the first load and after a navigation. A `BigInt` is not a `number`: `JSON.stringify` refuses it and some libraries expect numbers, so format it where you use it (`String(id)`). A `Date` is not text, so `{createdAt}` as a child now raises "Objects are not valid as a React child"; format it (`createdAt.toLocaleDateString()`). Both can go back: a server function sends a `BigInt` argument as its decimal string, and `useQuery` takes a `BigInt` or `Date` param (the generated query accessors' TypeScript parameter types do not list them yet). Years outside 0–9999 are written in the form JavaScript reads (`+010000`). A calendar `Date` (`Date.today`) arrives as `"YYYY-MM-DD"`; it used to raise `Ruact::SerializationError` in production, where `strict_serialization` is on. A symbol whose name starts with `$` is escaped like a string.
+
+- **`respond_to` answered 406 to every navigation and form submit of the client router.** The router asks for a page with `Accept: text/x-component`, which is not a Rails MIME type, so the request negotiated no format and `respond_to { |format| format.html { … } }` raised `ActionController::UnknownFormat`. That is the controller Rails' own scaffold writes: with `include Ruact::Controller`, its `create`, `update` and `destroy` failed whenever the router submitted the form. A router request now negotiates `format.html`, the same page a browser asks for: the `format.html` branch runs, and its render, status or redirect reaches the browser as a ruact answer. A URL that names a format (`/posts/1.json`) and an `Accept: application/json` request still get `format.json`. The format is negotiated before every callback, so an authentication `before_action` that answers with `respond_to` gets it too. A `respond_to` with no `format.html` still answers 406, now with a message naming the missing branch and the `data-ruact="false"` way out. A partial that exists only in another format (`.text.erb`) is no longer found by a ruact page during a router request.
+
+- **`bin/rails server` without Vite showed an empty page and no error.** Once Vite has run once, the component manifest is on disk, so a page renders without the dev server, but its JavaScript is not served: the page answered 200 with nothing in it, and the only clue was a 404 in the browser's network tab. In development, when the Vite dev server is not running and there is no build to serve, the page now shows a banner that says so and to start the app with `bin/dev`, and the Rails log gets the same `[ruact]` line. The banner is plain HTML, so it does not need the JavaScript that failed to load. Nothing changes with Vite running, with a build present, or outside development.
+
+- **Text that is not valid UTF-8 broke the page.** A string holding Latin-1 bytes, or bytes that are not text at all, made the page answer 500 for every viewer, because JSON refuses invalid UTF-8. A long one, 1024 bytes or more, was sent with a byte count that did not match what the browser decoded. Strings now leave as valid UTF-8: text in another encoding is transcoded, binary-tagged UTF-8 (`File.binread`, an HTTP body) is read as the text it is, and bytes that are not text become U+FFFD, as a browser shows them.
+
+## [0.0.14] - 2026-10-02
+
+### Fixed
+
+- **Scaffolding a second resource stopped the app from booting.** Every `rails generate ruact:scaffold` wrote a query with a method named `search`. Query names share one namespace: each name gets one `GET /q/<name>` route and one export of `@/.ruact/server-functions`. So the second resource drew `ruact_query_search` again, and Rails refused to load the routes with "Invalid route name, already in use: 'ruact_query_search'", a route the app never wrote. The scaffold now names the method after the resource: `PostsQuery#search_posts`, served at `GET /q/searchPosts` and imported as `searchPosts`. Two query classes that define the same method — or one query class mounted twice — now raise `Ruact::ConfigurationError` naming the query, the path and the fix. The new name can meet one thing the bare `search` could not: a custom collection action named `search` on the same controller (`post :search, on: :collection`) also derives `searchPosts`, and boot stops with ruact's name-collision error, which points to `ruact_function_name` to rename one. Apps scaffolded before this release keep their `search` and work as they are. The first scaffold of a *new* resource in such an app no longer collides with it.
+
+- **`rails generate ruact:install --shadcn` on an app that already had ruact installed left Tailwind out, then said the setup was in place.** That is the order Getting Started gives: install ruact first, add shadcn later. On the second run `package.json` and `Procfile.dev` already existed, so the generator skipped both. Tailwind was never declared and the `css` process was never added. `npx shadcn@latest init` then stopped with "No Tailwind CSS configuration found", right after the generator had printed that the prerequisites were in place. Under `--shadcn` the generator now adds what is missing to both files: the Tailwind `devDependencies` and the `build:css` script in `package.json`, the `css` process in `Procfile.dev`. It keeps every version and script you already declare; `package.json` is rewritten as 2-space JSON when something is added. When it cannot complete the setup, it says the setup is not in place and names what to do: a `package.json` it cannot parse, a Tailwind older than 4, or a `Procfile.dev` that already runs a `css` process or another Tailwind watcher — such as tailwindcss-rails' `bin/rails tailwindcss:watch`, which compiles its own entry rather than the `globals.css` shadcn writes its theme into. Without `--force`, `rails destroy ruact:install --shadcn` leaves an existing `package.json` in place.
+
+- **Under `--shadcn`, `bin/dev` stopped as soon as it started when no terminal was attached.** The `css` process ran `@tailwindcss/cli --watch`, which stops watching and exits 0 when its input closes. Foreman then stops Rails and Vite as well. A coding agent, CI, Docker or an IDE task runner starts `bin/dev` without a terminal, so the app was gone before its first request, with no error in the output. The process now runs with `--watch=always`. To fix an app generated before this release, change `--watch` to `--watch=always` on the `css:` line of `Procfile.dev`.
+
+- **The `ruact:scaffold --shadcn` pre-flight printed `npx shadcn@latest init` without `--base radix`.** The current shadcn defaults to Base UI, but the components the scaffold generates import Radix. An app set up from that message got components whose imports do not resolve. The message now prints `--base radix`, as the install generator already did.
+
+- **Two generator messages linked to pages that do not exist.** The unknown-attribute-type error and the shadcn version warning pointed at a documentation path inside this repository, where no such file exists. They now link to ruact.dev.
+
+### Changed
+
+- **The scaffold's list prop is named after the resource.** `<CommentList posts={rows} />` was a leftover from the reference app the templates came from, and every resource got a `posts` prop. It is now `<CommentList comments={rows} />`, `<BlogPostList blogPosts={rows} />`, and so on. Inside the component the prop is bound to a fixed local, so a model whose plural is one of the List's own names (`Row`) or one a module cannot declare (`Argument`) still compiles. A `Post` scaffold's view is unchanged.
+
+- **shadcn 4 is in the default `shadcn_compatible_versions`** (now `[1, 2, 4]`). It is the current major, so every app that followed the setup steps saw `ruact:scaffold --shadcn` warn that its shadcn was not tested. shadcn 4 was run end to end with this release: `init --base radix`, the full `add` list, `ruact:scaffold --shadcn`, and the form, table and delete dialog checked in a browser.
+
 ## [0.0.13] - 2026-09-27
 
 ### Added
@@ -84,7 +124,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 - **The README no longer claims props are an allowlist.** It said *"Props are an allowlist — other columns never cross"*, describing the opt-in rather than the default. The default is `as_json`: every attribute of a model prop crosses to the client, and the gem says so in the log (`ALL attributes exposed to client`). A reader who took the bullet at face value would have believed the safe behaviour was already on. The bullet now leads with what actually happens, then names `ruact_props` as the thing that makes it an allowlist and `strict_serialization` as what turns the permissive path into an error in production.
+
 - **The server-functions bullet no longer calls the whole generated module "typed".** Only queries carry an exact signature (one property per declared keyword, since 0.0.5). An action's accessor is typed to be callable and to satisfy `<form action>`, but its arguments and resolved value are `Record<string, unknown>` and `unknown` — useful, and not the autocomplete the word "typed" promises. Both are now described as what they are.
+
 - **The mechanism is stated where the reader meets it.** "Capitalized tag means React. Lowercase stays HTML." now sits directly under the ERB/TSX pair, and the paragraph that follows explains the wire in plain terms — the view renders server-side as it always did, the result travels as a React tree in the format React uses for Server Components, the data is inlined so React renders without a fetch, and Node builds the bundle and does nothing else.
 
 ### Fixed
@@ -124,6 +166,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   It is referenced by absolute URL and **nothing binary is committed here** — so neither `gem install ruact` nor a clone of this repository carries a multi-megabyte file, permanently, for a picture. Two things keep it from aging into a lie: the URL belongs to the site's URL contract, and `spec/readme_demo_message_spec.rb` pins the message the recording shows against a fixture the gem itself produced. If the wording changes, that spec goes red and names the recording as the thing to redo.
 
 - **`LICENSE.txt`** — the gemspec has declared `spec.license = "MIT"` since the first commit while the repository contained no licence file, so both GitHub and the packaged gem shipped a promise with nothing behind it.
+
 - **`spec.description` and `metadata["documentation_uri"]` in the gemspec** — RubyGems rendered the one-line `summary` as the whole description and fell through to rubydoc.info for documentation.
 
 ### Fixed
@@ -280,6 +323,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Tooling
 
 - **Code coverage instrumentation** (Story 6.7). Added `simplecov` and `simplecov-lcov` as development dependencies; gem CI uploads coverage from the canonical matrix cell (Ruby 3.3 × Rails 7.2) to Codecov on every push and PR with the `gem` flag. **Baseline at merge: 88.30% line (581/658), 72.25% branch (239 specs).** (Corrects the earlier 87.89% figure recorded at story-merge time, which was a typo of the SimpleCov output for 567/644 = 88.04%; the current numbers reflect the post-review state after Story 6.7 review F1 refactored `html_converter.rb#convert_element` into helpers, which added a few lines and one new spec.) Coverage is informativo (not a CI gate); see Codecov PR comments for diff coverage on individual changes. Diff coverage target per project DoD: ≥ 90% line / ≥ 80% branch on new code.
+
 - **Spec `rails_stub.rb` fix.** The previous `$LOADED_FEATURES.any? { |f| f.end_with?("/rails.rb") }` heuristic for skipping the `LOADED_FEATURES` insertion was unreliable — unrelated gems ship files at `*/rails.rb` (e.g. SimpleCov's `simplecov/profiles/rails.rb`). Replaced with an unconditional insertion guarded only by the existing `return if defined?(Rails)` early-exit, which is the correct invariant.
 
 ### Renamed
@@ -307,6 +351,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Rake task descriptions and internal `require` statements migrated from `rails_rsc` to `ruact`. Public API is unchanged; this is a documentation and tooling rename only.
 - **Render context now passed explicitly** (Story 7.1). `Ruact::ComponentRegistry` (which used `Thread.current`) has been removed; the per-render component list is now an instance of `Ruact::RenderContext` passed explicitly through `Controller#ruact_render → RenderPipeline → HtmlConverter`. The `Ruact/NoSharedState` cop now passes with no exceptions in `lib/ruact/`. **No public API change.** Note: `Ruact::Flight::*`, `Ruact::Internal::*`, and `Ruact::RenderContext` are not part of the public API and may change between minors. Hosts upgrading need no application code changes. See decision note for rationale and contributor guidance.
+
 - **`RenderPipeline` entry points consolidated** (Story 7.2). `RenderPipeline#call`, `#stream`, and `#from_html` have been removed and replaced with a single `#render(input, mode:)` entry point. `input` selects the source — `{ erb: String, binding: Binding }` for ERB templates or `{ html: String, render_context: Ruact::RenderContext }` for pre-rendered HTML; `mode:` selects the output shape — `:string` returns a `String` (deferred chunks inlined eagerly), `:stream` returns an `Enumerator` of Flight rows (deferred chunks delay). Conflicting input keys, missing siblings, and unknown modes raise `ArgumentError` with the offending input named. **No public API change** — `Ruact::Controller#ruact_render` is unchanged. Note: `Ruact::Flight::*`, `Ruact::Internal::*`, and `Ruact::RenderPipeline` are not part of the public API and may change between minors. See decision note for rationale and contributor guidance.
 
   _Migration for any external code that may have reached into `Ruact::RenderPipeline`:_ `pipeline.call(erb, binding)` → `pipeline.render({ erb: erb, binding: binding }, mode: :string)`; `pipeline.stream(erb, binding)` → `pipeline.render({ erb: erb, binding: binding }, mode: :stream)`; `pipeline.from_html(html, render_context: ctx)` → `pipeline.render({ html: html, render_context: ctx }, mode: :string)`; `pipeline.from_html(html, render_context: ctx, streaming: true)` → `pipeline.render({ html: html, render_context: ctx }, mode: :stream)`.
@@ -340,23 +385,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **ERB preprocessor** — PascalCase RSC component tags (`<Button />`, `<LikeButton postId={@post.id} />`) are transformed to Flight placeholders in ERB templates before Ruby evaluation.
+
 - **`<Suspense>` support** — `<Suspense fallback="Loading...">` in ERB templates maps to React Suspense boundaries in the Flight payload.
+
 - **React Flight wire format serializer** — Full Ruby-to-Flight protocol implementation covering: nil, booleans, integers, floats (NaN/Infinity/-0), strings (with `$` escaping), arrays, hashes, `Time`/`DateTime`, large strings (T rows), `ReactElement`, `SuspenseElement`, and `ClientReference`.
+
 - **`Ruact::Controller` concern** — Include in `ApplicationController` to enable RSC rendering. Provides `ruact_render`, RSC request detection (`text/x-component` / `Ruact-Request: 1` header), HTML shell generation with inline `__FLIGHT_DATA`, and Flight-aware `redirect_to`.
+
 - **Streaming mode** — When `ActionController::Live` is included, Flight rows are streamed to the client as they are produced (Suspense-aware).
+
 - **Client component resolution** — `Ruact::ClientManifest` reads `public/react-client-manifest.json` (generated by the Vite plugin) and resolves component names to `ClientReference` objects via a dual-path resolver.
+
 - **`Ruact::Serializable` mixin** — `ruact_props` DSL for declaring safe prop attributes on Ruby model objects.
+
 - **Install generator** — `rails generate ruact:install` scaffolds the initializer, Vite config patch, and JavaScript entry point.
+
 - **`ruact:doctor` Rake task** — Checks manifest presence, Vite server accessibility, controller setup, and streaming mode configuration.
+
 - **`vite-plugin-ruact`** — Vite plugin (npm package, co-versioned) that scans `"use client"` components and emits `public/react-client-manifest.json`.
+
 - **Client-side navigation** — JavaScript `ruact-router.js` intercepts same-origin link clicks and form submissions, fetches Flight payloads, and updates the React tree without full-page reloads.
+
 - **Error overlay** — Development-mode React error boundary with dismissible overlay for Flight parse and rendering errors.
+
 - **RSpec test suite** — 223 examples covering all modules: Flight serializer, ERB preprocessor, HTML converter, render pipeline, controller, client manifest, serializable, install generator, and `ruact:doctor`.
+
 - **Memory benchmark** — `rake benchmark:memory` enforces a 120% allocation regression gate against `spec/benchmarks/baseline.json`.
+
 - **CI matrix** — GitHub Actions: RSpec across Ruby 3.2 × 3.3 × Rails 7.0 × 7.1 × 7.2 × 8.0; RuboCop; YARD docs; memory benchmark; E2E system tests against React 19.0.0 and 19.x (Capybara + Cuprite); non-blocking React@next job with auto-issue on failure.
+
 - **E2E test app** — `e2e/` Rails app (no DB, in-memory Post model) with full CRUD system tests validating the complete request cycle.
 
-[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.13...HEAD
+[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.15...HEAD
+[0.0.15]: https://github.com/luizcg/ruact/releases/tag/v0.0.15
+[0.0.14]: https://github.com/luizcg/ruact/releases/tag/v0.0.14
 [0.0.13]: https://github.com/luizcg/ruact/releases/tag/v0.0.13
 [0.0.12]: https://github.com/luizcg/ruact/releases/tag/v0.0.12
 [0.0.11]: https://github.com/luizcg/ruact/releases/tag/v0.0.11

data/lib/generators/ruact/install/install_generator.rb

@@ -152,6 +152,24 @@ module Ruact
         say ""
       end
 
+      # What `--shadcn` adds to package.json and Procfile.dev. One source for the
+      # templates (fresh install) and the merge below (an app that already has
+      # both files), so the two paths cannot drift.
+      SHADCN_DEV_DEPENDENCIES = {
+        "@tailwindcss/cli" => "^4.0.0",
+        "tailwindcss" => "^4.0.0",
+        "tw-animate-css" => "^1.0.0"
+      }.freeze
+      SHADCN_BUILD_CSS_SCRIPT =
+        "@tailwindcss/cli -i app/javascript/styles/globals.css -o app/assets/builds/tailwind.css --minify"
+      # `--watch=always`, not `--watch`: Tailwind stops watching when stdin
+      # closes, and it does exit 0, so foreman then stops Rails and Vite with it.
+      # stdin is closed whenever bin/dev runs without a terminal (a coding agent,
+      # CI, Docker, an IDE task runner), which made the whole app go down in silence.
+      SHADCN_CSS_PROCESS =
+        "css: npx @tailwindcss/cli -i app/javascript/styles/globals.css " \
+        "-o app/assets/builds/tailwind.css --watch=always"
+
       # `--shadcn` only. Two files, both of them things shadcn's CLI checks for
       # and refuses to proceed without ("No Tailwind CSS configuration found" /
       # "Could not find valid path aliases"), verified against shadcn 4.x:
@@ -256,10 +274,18 @@ module Ruact
       # imports it by the absolute `Ruact.vite_plugin_path` and it uses only
       # `node:` builtins. Guarded like vite.config.js: an existing package.json
       # is left untouched (the app may already have one) unless --force.
+      #
+      # Under `--shadcn` an existing package.json is not skipped but COMPLETED:
+      # adding shadcn to an app that already ran the install is the documented
+      # path (Getting Started step 7 onward), and skipping here left Tailwind
+      # undeclared, so `shadcn init` aborted with "No Tailwind CSS configuration
+      # found" right after this generator said the prerequisites were in place.
       def create_package_json
         package_json_file = Pathname(destination_root).join("package.json")
 
         if package_json_file.exist? && !options[:force]
+          return merge_shadcn_package_json(package_json_file) if shadcn?
+
           say_status "skip", "package.json already exists — ensure it has react, react-dom, " \
                              "vite and @vitejs/plugin-react (re-run with --force to overwrite)", :yellow
           return
@@ -279,7 +305,12 @@ module Ruact
       # OWNED by ruact: see `install_foreman_launcher`. `bin/dev` is made
       # executable.
       def create_launch_files
-        create_guarded_file "Procfile.dev", "Procfile.dev.tt"
+        procfile = Pathname(destination_root).join("Procfile.dev")
+        if procfile.exist? && !options[:force] && shadcn?
+          append_shadcn_css_process(procfile)
+        else
+          create_guarded_file "Procfile.dev", "Procfile.dev.tt"
+        end
         install_foreman_launcher
         # Ensure bin/dev is executable whether we just wrote it or it pre-existed
         # (a skipped, already-foreman launcher should still be runnable).
@@ -612,7 +643,13 @@ module Ruact
       # templates' imports, so the two generators cannot drift.
       def show_shadcn_next_steps
         say ""
-        say "shadcn prerequisites are in place (Tailwind entry, tsconfig alias, css process)."
+        if shadcn_gaps.empty?
+          say "shadcn prerequisites are in place (Tailwind entry, tsconfig alias, css process)."
+        else
+          say_status "attention", "shadcn prerequisites are NOT all in place:", :red
+          shadcn_gaps.each { |gap| say "  - #{gap}" }
+          say "Fix these first, then run the two commands below."
+        end
         say "Two commands remain — they are interactive and hit the network, so run them yourself:"
         say ""
         say "  npx shadcn@latest init --base radix"
@@ -890,6 +927,12 @@ module Ruact
         options[:shadcn]
       end
 
+      # Prerequisites `--shadcn` could not put in place. Non-empty means
+      # show_shadcn_next_steps must not say "in place".
+      def shadcn_gaps
+        @shadcn_gaps ||= []
+      end
+
       # The superset the scaffold generator narrows per resource. Loaded lazily
       # (and only under `--shadcn`) so a plain install never pays for the
       # scaffold generator's load, and so a failure to reach it degrades to the
@@ -901,6 +944,74 @@ module Ruact
         "button input textarea switch select label badge table alert-dialog dropdown-menu"
       end
 
+      # Adds the shadcn devDependencies and the build:css script to an existing
+      # package.json. Never overwrites a key the app already has (its own
+      # Tailwind version wins). The file is re-serialized with 2-space JSON
+      # when something is added. An unparseable file is left alone, loudly.
+      def merge_shadcn_package_json(path)
+        # `create_file … force: true` would DELETE the whole file under
+        # `rails destroy`; this merge has nothing to undo.
+        return if behavior == :revoke
+
+        pkg = JSON.parse(path.read.delete_prefix("\uFEFF"))
+        raise JSON::ParserError, "top level is #{pkg.class}, not an object" unless pkg.is_a?(Hash)
+
+        dev = (pkg["devDependencies"] ||= {})
+        scripts = (pkg["scripts"] ||= {})
+        flag_tailwind_below_v4(dev["tailwindcss"] || pkg.dig("dependencies", "tailwindcss"))
+        added = SHADCN_DEV_DEPENDENCIES.reject { |name, _| dev.key?(name) || pkg.dig("dependencies", name) }
+        dev.merge!(added)
+        add_script = !scripts.key?("build:css")
+        scripts["build:css"] = SHADCN_BUILD_CSS_SCRIPT if add_script
+
+        if added.empty? && !add_script
+          say_status "identical", "package.json (Tailwind already declared)", :blue
+          return
+        end
+
+        create_file "package.json", "#{JSON.pretty_generate(pkg)}\n", force: true, verbose: false
+        say_status "update", "package.json (+ #{(added.keys + (add_script ? ['build:css'] : [])).join(', ')})", :green
+      rescue JSON::ParserError => e
+        shadcn_gaps << "package.json could not be parsed (#{e.message.lines.first.strip}) — add " \
+                       "#{SHADCN_DEV_DEPENDENCIES.keys.join(', ')} to devDependencies and a " \
+                       "\"build:css\" script (#{SHADCN_BUILD_CSS_SCRIPT}) yourself"
+      end
+
+      # globals.css is written for Tailwind 4 (`@import "tailwindcss"`). An app
+      # pinned to an older major keeps its version, and the setup is not in place.
+      def flag_tailwind_below_v4(version)
+        major = version.to_s[/\d+/]
+        return if major.nil? || major.to_i >= 4
+
+        shadcn_gaps << "package.json pins tailwindcss #{version}; app/javascript/styles/globals.css " \
+                       "and shadcn's current components need Tailwind 4"
+      end
+
+      # Appends the Tailwind watch process to an existing Procfile.dev, unless a
+      # process already builds globals.css. A different `css:` process, or
+      # another Tailwind watcher (tailwindcss-rails' compiles its own entry into
+      # the same app/assets/builds/tailwind.css), cannot be appended next to: it
+      # is reported as a gap, never silently accepted. Comment lines are ignored.
+      def append_shadcn_css_process(path)
+        content = path.read
+        code = content.lines.reject { |line| line.lstrip.start_with?("#") }
+
+        if code.any? { |line| line.include?("app/javascript/styles/globals.css") }
+          say_status "identical", "Procfile.dev (already builds globals.css)", :blue
+          return
+        end
+
+        if (clash = code.find { |line| line.match?(/\A\s*css\s*:/) || line.include?("tailwind") })
+          shadcn_gaps << "Procfile.dev already runs `#{clash.strip}`, which does not build " \
+                         "app/javascript/styles/globals.css — replace it with: #{SHADCN_CSS_PROCESS}"
+          return
+        end
+
+        separator = content.empty? || content.end_with?("\n") ? "" : "\n"
+        append_to_file "Procfile.dev", "#{separator}#{SHADCN_CSS_PROCESS}\n", verbose: false
+        say_status "update", "Procfile.dev (+ css process)", :green
+      end
+
       def app_package_name
         base = File.basename(File.expand_path(destination_root))
         sanitized = base.downcase.gsub(/[^a-z0-9._-]/, "-").squeeze("-").gsub(/\A-+|-+\z/, "")

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/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/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/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

@@ -73,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)
@@ -132,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
@@ -250,7 +252,7 @@ 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