ruact 0.0.8 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9a45065af0d01daed8548084a9667fb066f9e8c19a685f99b0f101a8e825ca0
-  data.tar.gz: 99206ecd7d61a44b4cdfe52bb5b40b046f66e2938f7bf060e603b98ef17971b8
+  metadata.gz: eb5572218264cb747d7e6d89f990946c3eb05b4614469f4d96fd69158aece888
+  data.tar.gz: efe3a28deef2028b9470d0d1edbe5770d7289f668b72d842c0a4f4cab8aef47c
 SHA512:
-  metadata.gz: d303e5aa55881c70b88a6a7f132450712c8f35adb7b00f0172d3503784dbe82b1373ae7ecc30db05a98832f2c2154134e49bbba43ba403497cdc61b90401b91a
-  data.tar.gz: 8b8fcc40cca7167dece277333fdd56562a62800d150af0be85a50033fc6a2ea3dc8aeebf7650dbb220891f73a843a80d2b0becd1f1d7483b4a2afa6af8a1404e
+  metadata.gz: 6fd494f658f9e5121f0f2beed2965c6d58926f8c4ec1f4d6b0b3db714d903c9a3a4ecc1492c32e5e3f61dc6bad10ea716e2a9795884cd5319bcc039af4c5dc3b
+  data.tar.gz: bd6ac4fcf1042364845221187cb85d64dd3f299bc6873d1a9d7cd796cbf1ec13e95b07692ef55c5dd4c1e861ad9180639d97c5df19e7d2cc2eb4a0d777972fb1

data/CHANGELOG.md

@@ -7,6 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.10] - 2026-08-25
+
+### Changed
+
+- **`README.md` — the gem's public face is no longer `bundle gem` boilerplate.** The file GitHub renders on `github.com/luizcg/ruact`, the file `spec.files` packages *inside* the built `.gem`, and the destination of `source_code_uri` still said *"TODO: Delete this and the text below"*, told the reader to `bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG`, and pointed contributors at `https://github.com/[USERNAME]/ruact`. It is now a first-contact README for v0.0.9: the four-command greenfield quick start (the same sequence the site's landing puts on the clipboard), the ERB-tag/`"use client"` pair, `include Ruact::Server` with its generated typed accessor, a list where every bullet names a shipped artifact, a compatibility table sourced from the CI matrix rather than from optimism, and links out to `ruact.dev` instead of second copies of the guides.
+
+  It also carries the **AI-tools section deferred here from the docs work** — the one-requirement rule (`"use client"` at the top; a PascalCase *named* export is the thing to check rather than add), the four-step walkthrough, and a pointer to the canonical page — plus one line naming the shipped agent context: the `AGENTS.md` `rails generate ruact:install` writes, `ruact.dev/llms.txt`, and the experimental `-- --json` output of `ruact:doctor` / `ruact:routes`.
+
+  Two gates now watch it, because nothing did before: `spec/readme_spec.rb` runs inside this repo's own `rspec` job (no boilerplate literals, every relative link resolves on disk, no `path:` gem source a reader could copy, and the quick-start block pinned literally), and the monorepo's command-spine check treats `README.md` as a declared artifact of the one canonical greenfield sequence.
+
+### Added
+
+- **A demo at the top of `README.md` — the write→verify loop, recorded rather than described.** The README could argue the mechanism in prose and code but could not show what happens when the boundary is used wrong, which is the part a reader of *"React rendered from Rails templates"* actually doubts. The recording is one loop: an ERB template with `<LikeButton likes={@likes} />` beside the `"use client"` component it resolves to; the component rendering in a browser, its count changing on click; children put inside the tag — the JSX habit — and the next request stopping **server-side, while the template is being processed, before anything reaches the browser**, with `Ruact::ChildrenNotSupportedError` naming the component, the template file and line, and the fix; then the children removed and the page rendering again. Every frame is a capture of the gem running; the loud error is the one shipped in 0.0.9.
+
+  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
+
+- **`SECURITY.md` named a version that has never existed.** Its supported-versions table listed `0.1.x`; the released gem is `0.0.9`. Corrected to `0.0.x`.
+
+## [0.0.9] - 2026-08-12
+
+### Added
+
+- **`rails generate ruact:install --shadcn` — the `--shadcn` scaffold path now has a working setup.** `ruact:scaffold --shadcn` emits components dressed in Tailwind classes, but nothing in ruact ever wired Tailwind, so the generated CRUD rendered **unstyled**: the classes had nothing to resolve against. Worse, the documented next step did not work either — shadcn's own CLI **refuses to initialize** in a ruact app, aborting with *"No Tailwind CSS configuration found"* and *"Could not find valid path aliases"*, because a fresh ruact app ships neither Tailwind nor a `tsconfig.json`.
+
+  The new flag emits exactly those prerequisites, each verified against the real shadcn CLI: `app/javascript/styles/globals.css` (the Tailwind entry shadcn appends its design tokens to, and points `components.json` at), a `tsconfig.json` carrying the `@/*` → `app/javascript/*` alias (the bundled Vite plugin already registers the same alias for the *bundler*; this is what makes it resolve for *TypeScript*, and therefore for shadcn's probe and your editor), `app/assets/builds/` with the compiled stylesheet gitignored, the `build:css` script, and a `css` process in `Procfile.dev` so `bin/dev` rebuilds the stylesheet alongside Rails and Vite.
+
+  It then **prints** the two `npx shadcn` commands instead of running them — they hit the network, and `shadcn init` is interactive, so automating them is neither safe (the scaffold generator's "never auto-run npx/npm" rule) nor possible. The printed `init` line pins **`--base radix`**, which is the part nobody would guess: current shadcn defaults to **Base UI**, while the components `ruact:scaffold --shadcn` generates import **Radix** primitives — accepting the default gets you a component library the scaffold cannot use. The printed `add` list is the complete primitive superset, pinned by a spec as a superset of whatever a given resource narrows to, so the two generators cannot drift.
+
+  **The default (agnostic) path is untouched** — no Tailwind, no `tsconfig.json`, and a byte-identical `package.json` and `Procfile.dev`, all pinned by specs.
+
+  Verified end to end twice from `rails new`: the generated CRUD renders as a styled shadcn table with the `useQuery` search filtering rows live. Note that shadcn's CLI is currently **4.x** while `shadcn_compatible_versions` defaults to `[1, 2]`, so the scaffold's version pre-flight emits its (non-blocking) warning; the generated components do work against 4.x.
+
+### Fixed
+
+- **A ruact page can now carry your app's CSS — the Rails layout owns the document.** `ruact_render` rendered the view with `layout: false` and then wrapped the Flight payload in a hardcoded HTML shell whose `<head>` holds only `charset`, `viewport`, the CSRF meta tag and the title `Rails RSC`. That shell has **no stylesheet slot and never uses your layout**, so `stylesheet_link_tag` — and with it favicons, fonts, analytics and every `<head>`-writing gem — could not reach a ruact-rendered page **at all**. The visible consequence: `rails generate ruact:scaffold --shadcn` emitted components whose Tailwind classes had nothing to resolve against, so the generated CRUD was **unstyled by construction**; the docs' instruction to put shadcn theme variables in `app/assets/stylesheets/application.css` pointed at a file that provably never reached the browser; and Epic 12 (`ruact_meta` → tags in `<head>`) had no surface to write into. The default agnostic scaffold was affected too — it renders plain semantic HTML and only *looked* acceptable because browsers style a bare `<table>`.
+
+  A non-Flight HTML response is now rendered **through the host app's own layout**, with the React root's bootstrap tags supplied by the layout's `<%= ruact_js_assets %>` call (which, called with no argument, picks up the render's Flight payload). The Flight wire shape (`text/x-component`) is untouched — this only changes the full document a browser gets on a normal navigation.
+
+  Controlled by the new **`Ruact.config.layout`** — `false` by default, `true` (or a layout name) to opt in. `rails generate ruact:install` now writes **both halves of that opt-in in the same run**: `config.layout = true` in the generated initializer, and `<%= ruact_js_assets %>` next to the React root in your layout.
+
+  **The default is `false`, so an existing app is untouched until it opts in** — not because ruact detects anything, but because it does not look. An earlier cut of this change tried to infer whether your layout was ready by inspecting it; three review rounds each found another template shape that fooled the inference (a mention in a comment, a commented-out call, a trim-mode comment), and each wrong answer decided how every page in the app rendered. "Does this template call this method?" is not a question pattern-matching can answer reliably, so it is no longer asked. One explicit line beats a clever guess for a setting this load-bearing. (`:auto` is rejected with a message naming its replacement, so an initializer carrying it forward cannot be silently reinterpreted.)
+
+  Once opted in, a layout that cannot mount the app is a configuration error rather than a silent blank page: ruact checks the rendered document for both the assets block and a `<div id="root">`, raising in development/test and logging-and-degrading to the shell in production. A controller with no resolvable layout (API-shaped, or `layout false`) degrades quietly instead — that is a normal Rails choice, not a mistake.
+
+  **To migrate an existing app:** add `<%= ruact_js_assets %>` next to the `<div id="root"></div>` in `app/views/layouts/application.html.erb`, or re-run `rails generate ruact:install` (which now injects both, and adds only the missing call to a layout that already has the root — tolerating single quotes, extra attributes and a same-line marker, and telling you loudly if it cannot find the root div rather than reporting a success it did not perform). `rails ruact:doctor` reports the half-migrated state as a **warning** naming the one-line fix — where it previously reported a root-only layout as a pass.
+
+  **Known limitation:** 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.
+
+  `rails ruact:doctor` reports the two halves separately, because they are different fixes: a layout missing the root or the helper **fails**, and a ready layout with `config.layout = false` **warns** and names the setting.
+
 ## [0.0.8] - 2026-07-11
 
 ### Changed
@@ -192,6 +247,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **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.7...HEAD
+[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.10...HEAD
+[0.0.10]: https://github.com/luizcg/ruact/releases/tag/v0.0.10
+[0.0.9]: https://github.com/luizcg/ruact/releases/tag/v0.0.9
+[0.0.8]: https://github.com/luizcg/ruact/releases/tag/v0.0.8
 [0.0.7]: https://github.com/luizcg/ruact/releases/tag/v0.0.7
 [0.0.6]: https://github.com/luizcg/ruact/releases/tag/v0.0.6

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luiz Garcia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,37 +1,143 @@
-# Ruact
+# ruact
 
-[![codecov](https://codecov.io/gh/luizcg/ruact/branch/main/graph/badge.svg?flag=gem)](https://codecov.io/gh/luizcg/ruact)
+**Real React, right in your Rails views.** Write a PascalCase tag in ERB, pass `@post` as a prop, and a React component renders — no hand-written JSON layer, no Node process in production.
 
-TODO: Delete this and the text below, and describe your gem
+[![CI](https://github.com/luizcg/ruact/actions/workflows/ci.yml/badge.svg)](https://github.com/luizcg/ruact/actions/workflows/ci.yml) [![Gem Version](https://badge.fury.io/rb/ruact.svg)](https://badge.fury.io/rb/ruact) [![codecov](https://codecov.io/gh/luizcg/ruact/branch/main/graph/badge.svg?flag=gem)](https://codecov.io/gh/luizcg/ruact)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/ruact`. To experiment with that code, run `bin/console` for an interactive prompt.
+<!-- Packaging (Story 5.2): the demo is a documentation asset, published with the site
+     rather than committed here — so neither `gem install ruact` nor a clone of this
+     repository carries a multi-megabyte file, permanently, for a picture. The URL belongs
+     to the site's URL contract and cannot quietly start 404ing, the capture sources are
+     scripted and live with the project's other capture harnesses, and the message the demo
+     shows is pinned here by `spec/readme_demo_message_spec.rb`. -->
+<img src="https://ruact.dev/readme-write-verify.gif" width="800"
+     alt="An ERB template holding a &lt;LikeButton likes=&#123;@likes&#125; /&gt; tag, and the &quot;use client&quot; React component that tag resolves to. The component renders in a browser and its count changes when it is clicked. Children are then put inside the tag — the JSX habit — and the next request stops server-side with Ruact::ChildrenNotSupportedError, which names the component, the template file and line, and the fix. The children come out again and the page renders." />
 
-## Installation
+## Quick start
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+```bash
+# 1. A throwaway app to try it in
+rails new myapp --skip-javascript && cd myapp
 
-Install the gem and add to the application's Gemfile by executing:
+# 2. Add the gem
+bundle add ruact
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+# 3. Write the config, the layout wiring and an AGENTS.md — then run npm install
+rails generate ruact:install
+
+# 4. Rails + Vite, one command
+bin/dev
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+That is the whole install. The [Getting Started guide](https://ruact.dev/docs/getting-started) picks it up from here — first component, first scaffold, `ruact:doctor`. Already have an app? Start at step 2, then read [Progressive migration](https://ruact.dev/docs/guides/progressive-migration) — ruact renders one action at a time and leaves the rest of your views alone.
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+## How it works
+
+```erb
+<%# app/views/posts/show.html.erb %>
+<PostCard post={@post} author={@author} />
+```
+
+```tsx
+// app/javascript/components/PostCard.tsx
+"use client"
+
+import { useState } from "react"
+
+export function PostCard({ post, author }) {
+  const [liked, setLiked] = useState(false)
+  return (
+    <article>
+      <h1>{post.title}</h1>
+      <p>by {author.name}</p>
+      <button onClick={() => setLiked(!liked)}>
+        {liked ? "Liked" : "Like"}
+      </button>
+    </article>
+  )
+}
+```
+
+Rails serializes `@post` and `@author` as Ruby values, sends the component tree as a [Flight](https://ruact.dev/docs/concepts/flight-wire-format) payload, and React hydrates it in the browser. No JSON ceremony, no duplicate routes, no Node.js in production.
+
+## Call Rails from React
+
+Add one line to a controller and its routed non-GET actions become callable from React at their real routes:
+
+```ruby
+class PostsController < ApplicationController
+  include Ruact::Server   # ← the only new line
+
+  def create
+    @post = Post.create!(post_params)
+    redirect_to @post
+  end
+  # ...
+end
+```
+
+```tsx
+import { createPost } from "@/.ruact/server-functions";
+
+await createPost({ post: { title: "Hi", body: "…" } });
 ```
 
-## Usage
+The verb decides — there is no per-action DSL and no second endpoint. The export name is derived from the route (`posts#create` → `createPost`), and ruact's Vite plugin regenerates the module whenever your routes change. What the call *resolves* is decided by the action you already wrote: this one redirects, so ruact follows the redirect and the call resolves `null`; an action that assigns `@post` instead resolves `{ post: … }`, through the same `ruact_props` allowlist as everything else. Reading works the same way: a `Ruact::Query` class mounted with `ruact_queries` draws one named `GET` route per public method, and React reads it with `useQuery`. Both are documented in [Server functions & queries](https://ruact.dev/docs/api/server-actions).
+
+## What you get
+
+Every item below is shipped in this gem at v0.0.9:
+
+- **ERB as server components** — `include Ruact::Controller`, then write PascalCase tags in your existing views. [Docs](https://ruact.dev/docs/concepts/erb-as-server-components)
+- **`"use client"`** — the one directive that marks a file as client-side. The bundled Vite plugin scans for it and writes the manifest. [Docs](https://ruact.dev/docs/concepts/use-client)
+- **Server functions and queries** — `include Ruact::Server` and `Ruact::Query` + `useQuery`, both reachable through a typed module generated from your route table. [Docs](https://ruact.dev/docs/api/server-actions)
+- **Props are an allowlist** — `include Ruact::Serializable` + `ruact_props :id, :title`; other columns never cross. [Docs](https://ruact.dev/docs/api/serializable)
+- **Validation errors round-trip** — `ruact_errors(record)` hands React `{ title: ["can't be blank"] }` without a serializer. [Docs](https://ruact.dev/docs/api/server-actions)
+- **Signed record references** — `Ruact.signed_global_id(record, for:, expires_in:)` out, `Ruact.locate_signed(token, for:)` back in; a tampered token is a `400`, not a lookup. [Docs](https://ruact.dev/docs/api/server-actions)
+- **Client-side navigation** — link interception, scroll restoration and redirect-after-POST, derived from your Rails routes. [Docs](https://ruact.dev/docs/concepts/navigation)
+- **A CRUD generator** — `rails generate ruact:scaffold Post title:string body:text` delegates the model, migration and route to Rails' own `resource` generator, then adds the ruact layer. Plain semantic HTML by default; `--shadcn` opts into the Tailwind/shadcn path. It does not run migrations — `rails db:migrate` is still yours. [Docs](https://ruact.dev/docs/api/scaffold)
+- **`bin/rails ruact:doctor`** — eight checks over the manifest, Vite, the layout and streaming; exits `1` when one fails. [Docs](https://ruact.dev/docs/api/ruact-doctor)
+- **One runtime dependency** — `nokogiri`. Rails itself is not a declared dependency of this gem.
+
+## AI tools and coding agents
+
+**The only line you have to add to an AI-generated React component is `"use client"` at the top of the file.** One thing to check rather than add: the component needs a PascalCase *named* export, because that name is the tag you write in ERB.
 
-TODO: Write usage instructions here
+1. Generate the component with whatever AI tool you already use.
+2. Save it as `app/javascript/components/MyComponent.tsx`.
+3. Add `"use client"` at the top if it is not already there.
+4. Call `<MyComponent />` from ERB.
 
-## Development
+That is the whole adaptation, and it holds for any tool that outputs standard React components — nothing here is pinned to one vendor. The worked example, the traps and the real error messages are on [AI Tools & Agents](https://ruact.dev/docs/guides/ai-tools).
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+For agents driving the app rather than writing one component: `rails generate ruact:install` writes an `AGENTS.md` into your app, [ruact.dev/llms.txt](https://ruact.dev/llms.txt) serves the same context to tools that fetch from the web, and `bin/rails ruact:doctor -- --json` / `bin/rails ruact:routes -- --json` emit machine-readable output (experimental — `schema_version: 0`, and the `--` separator is required).
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Compatibility
+
+| | Version | Where that comes from |
+|---|---|---|
+| Ruby | >= 3.2 | the gemspec's `required_ruby_version` |
+| Rails | tested against 7.0, 7.1, 7.2 and 8.0 | every commit runs the full CI matrix; the gemspec sets no Rails bound |
+| React | 19.x | the `package.json` the install generator writes |
+| Node.js | >= 20 | the build only — ruact runs no Node process in production |
+
+## Documentation
+
+Everything lives at [ruact.dev](https://ruact.dev):
+
+- [Getting Started](https://ruact.dev/docs/getting-started) — from `rails new` to a rendered component
+- [Why ruact?](https://ruact.dev/docs/why-ruact) — where it sits next to Hotwire and Inertia
+- [Server functions & queries](https://ruact.dev/docs/api/server-actions) — the full request/response contract
+- [Progressive migration](https://ruact.dev/docs/guides/progressive-migration) — adopting it one action at a time
+- [Testing](https://ruact.dev/docs/guides/testing) — render assertions on the server side
+- [Changelog](CHANGELOG.md) — also published at [ruact.dev/docs/changelog](https://ruact.dev/docs/changelog)
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/ruact.
+Bug reports and pull requests are welcome at [github.com/luizcg/ruact/issues](https://github.com/luizcg/ruact/issues).
+
+Release process: [RELEASING.md](RELEASING.md). Security policy and private reporting: [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/SECURITY.md

@@ -6,7 +6,7 @@ Only the latest patch release of the current minor version is actively maintaine
 
 | Version | Supported |
 |---------|-----------|
-| 0.1.x   | ✅ Yes    |
+| 0.0.x   | ✅ Yes    |
 
 Once a new minor version is released, the previous minor version receives security fixes for **90 days** after the new release, then it is no longer supported.
 

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

@@ -12,7 +12,10 @@ module Ruact
     # Performs the following actions:
     # 1. Creates config/initializers/ruact.rb
     # 2. Injects `include Ruact::Controller` into ApplicationController
-    # 3. Injects the React root div into app/views/layouts/application.html.erb
+    # 3. Injects the React root div AND `ruact_js_assets` into
+    #    app/views/layouts/application.html.erb, so the app's own layout owns
+    #    the document (and its `<head>` — stylesheets, fonts, meta — reaches a
+    #    ruact page). See Ruact::Configuration#layout.
     # 4. Creates app/javascript/components/.keep
     # 5. Creates vite.config.js (or shows manual instructions if one exists)
     # 6. Creates package.json (react/react-dom/vite/@vitejs/plugin-react) so a
@@ -25,6 +28,10 @@ module Ruact
     #    verification commands in context by default (Story 15.1, FR105).
     # 9. Runs `npm install` so JavaScript dependencies are ready (FR101);
     #    skippable via --skip-npm.
+    # 10. With `--shadcn`: also emits the prerequisites shadcn's own CLI refuses
+    #    to initialize without (a Tailwind entry + a `tsconfig.json` import
+    #    alias), wires the `css` build process, and prints the two `npx shadcn`
+    #    commands it deliberately does not run.
     #
     # Story 14.2 (FR104) — the generator no longer writes a bootstrap entry into
     # the user's tree. ruact's React entry is served as the virtual module
@@ -48,8 +55,32 @@ module Ruact
                    default: false,
                    desc: "Skip running npm install (for CI or non-npm package managers)"
 
+      # Prepares the app for the `ruact:scaffold --shadcn` path. shadcn's own
+      # CLI refuses to initialize without BOTH Tailwind and a TypeScript import
+      # alias, and a ruact app has neither — it ships no Tailwind and no
+      # `tsconfig.json` at all. That left `--shadcn` scaffolding into an app
+      # where the generated components' classes resolved to nothing: markup with
+      # no styling. This flag emits exactly the prerequisites (verified against
+      # the real shadcn CLI) and then PRINTS the two `npx shadcn` commands
+      # rather than running them — they hit the network and `shadcn init` is
+      # interactive, so automating them is neither safe nor possible.
+      class_option :shadcn,
+                   type: :boolean,
+                   default: false,
+                   desc: "Also wire Tailwind + a TS import alias, the prerequisites for `ruact:scaffold --shadcn`"
+
+      # A fresh app gets the whole initializer. An app that ALREADY has one gets
+      # a surgical injection instead of `template`'s overwrite prompt, which
+      # offered a bad choice on the one path that matters most — migrating an
+      # existing app: overwrite and lose every setting the app had
+      # (`strict_serialization`, `manifest_path`, the SGID defaults…), or skip
+      # and end up half-migrated, with the layout edited but `config.layout`
+      # still off and nothing saying so except `ruact:doctor`.
       def create_initializer
-        template "initializer.rb.tt", "config/initializers/ruact.rb"
+        path = Pathname(destination_root).join("config/initializers/ruact.rb")
+        return template "initializer.rb.tt", "config/initializers/ruact.rb" unless path.exist?
+
+        inject_layout_setting(path)
       end
 
       def inject_controller_concern
@@ -67,21 +98,93 @@ module Ruact
                          after: /class ApplicationController.*\n/
       end
 
+      # The layout owns the document: `stylesheet_link_tag`, favicons, fonts and
+      # every `<head>`-writing gem only reach a ruact page because Rails' own
+      # layout renders it (see `Ruact::Configuration#layout`). That requires TWO
+      # things in the layout — the React root, and `ruact_js_assets` to emit the
+      # bootstrap entry + this render's Flight payload. The other half of the
+      # opt-in is `config.layout = true`, which the generated initializer
+      # carries — a layout with the helper but the setting off (or the reverse)
+      # keeps rendering through ruact's built-in, CSS-less shell.
       def inject_layout_shell
         layout_file = "app/views/layouts/application.html.erb"
         return unless File.exist?(Pathname(destination_root).join(layout_file))
 
         content = File.read(Pathname(destination_root).join(layout_file))
-        if content.include?("ruact: root")
-          say_status "skip", "Rails RSC root already present in layout", :yellow
+
+        # A CALL, not a mention: `<%# TODO: add ruact_js_assets %>` used to read
+        # as "already present" here and skip the migration, leaving the app on
+        # ruact's CSS-less shell with the generator reporting success. Shared
+        # with the runtime so both agree on what "migrated" means.
+        # BOTH halves, not just the helper. A layout carrying `ruact_js_assets`
+        # with no `<div id="root"></div>` was skipped as "already present" — and
+        # since this generator also turns `config.layout` on, that app then
+        # raised at render time on a document React could not mount into.
+        if Ruact::LayoutSource.wired?(content) && Ruact::LayoutSource.root?(content)
+          say_status "skip", "ruact root + assets already present in layout", :yellow
           return
         end
 
+        # Migration path for an app installed before the layout owned the
+        # document: the root is already there, only the asset call is missing.
+        #
+        # The anchor matches the ROOT DIV itself rather than the marker-then-div
+        # pair, and tolerates the ways a real layout is written — single or
+        # double quotes, extra attributes, any attribute order, CRLF, and the
+        # marker on the same line. The earlier anchor required the exact emitted
+        # formatting, so a hand-edited layout silently matched nothing. The
+        # attribute boundary in `ROOT_ELEMENT` is what keeps `data-id="root"`
+        # from being mistaken for the mount point.
+        if Ruact::LayoutSource.root?(content)
+          return migrate_layout(layout_file,
+                                "\n    <%= ruact_js_assets %>",
+                                after: Ruact::LayoutSource::ROOT_ELEMENT,
+                                success: "added ruact_js_assets to the existing layout root")
+        end
+
+        # The mirror case: the helper is there but the mount target is not, so
+        # the root goes in just BEFORE the call (React needs the node in the
+        # document, and keeping the pair adjacent matches what a fresh install
+        # writes). Injecting the whole block instead would duplicate the helper.
+        if Ruact::LayoutSource.wired?(content)
+          return migrate_layout(layout_file,
+                                "<%# ruact: root %>\n    <div id=\"root\"></div>\n    ",
+                                before: Ruact::LayoutSource::ASSETS_CALL,
+                                success: "added the React root div next to the existing ruact_js_assets")
+        end
+
         inject_into_file layout_file,
-                         "\n    <%# ruact: root %>\n    <div id=\"root\"></div>\n",
+                         "\n    <%# ruact: root %>\n    <div id=\"root\"></div>\n    <%= ruact_js_assets %>\n",
                          before: "  </body>"
       end
 
+      # `--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:
+      #
+      #   app/javascript/styles/globals.css — the Tailwind entry. shadcn appends
+      #     its design tokens here, which is why components.json points at it.
+      #   tsconfig.json — the `@/*` → `app/javascript/*` alias. The Vite plugin
+      #     already registers the same alias for the BUNDLER, so components
+      #     resolve at runtime today; this is what makes it resolve for
+      #     TypeScript (and therefore for shadcn's alias probe and your editor).
+      #
+      # Both are guarded: an app that already has them keeps its own.
+      def create_shadcn_prerequisites
+        return unless shadcn?
+
+        create_guarded_file "app/javascript/styles/globals.css", "globals.css.tt"
+        create_guarded_file "tsconfig.json", "tsconfig.json.tt"
+        # Propshaft only serves directories that exist; the built stylesheet is
+        # generated, so the directory ships with a .keep and the artifact is
+        # gitignored (see append_gitignore_entries).
+        empty_directory "app/assets/builds"
+        create_file "app/assets/builds/.keep" unless
+          File.exist?(Pathname(destination_root).join("app/assets/builds/.keep"))
+
+        warn_unless_layout_links_builds
+      end
+
       def create_components_directory
         empty_directory "app/javascript/components"
         create_file "app/javascript/components/.keep" unless
@@ -106,6 +209,10 @@ module Ruact
           "app/javascript/.ruact/server-functions.ts",
           "tmp/cache/ruact/"
         ]
+        # The compiled stylesheet is a build artifact of globals.css, rebuilt by
+        # the Procfile's `css` process on every boot — same reasoning as the
+        # generated server-functions module above.
+        entries << "app/assets/builds/tailwind.css" if shadcn?
         # Substring matches (`existing.include?(entry)`) were unsafe — they
         # would skip "tmp/cache/ruact/" when the file already contained
         # "tmp/cache/ruact/some-cache.bin", leaving the directory itself
@@ -291,6 +398,8 @@ module Ruact
           say "  2. Start your app:           bin/dev"
         end
 
+        show_shadcn_next_steps if shadcn?
+
         say "\nThen add <MyComponent /> to any ERB view.\n"
         say "Note: re-run this generator after updating the ruact gem to refresh"
         say "the bundled Vite plugin path in vite.config.js."
@@ -299,6 +408,96 @@ module Ruact
 
       private
 
+      # `inject_into_file` prints "File unchanged!" and carries on when its
+      # anchor misses, so reporting success without checking would be a lie —
+      # and the app would keep rendering through ruact's CSS-less shell with no
+      # clue why. Compare the file around the call and only claim what happened.
+      def migrate_layout(layout_file, content, success:, **anchor)
+        path   = Pathname(destination_root).join(layout_file)
+        before = path.read
+        inject_into_file layout_file, content, **anchor
+
+        if path.read == before
+          warn_layout_migration_failed
+        else
+          say_status "update", success, :green
+        end
+      end
+
+      def inject_layout_setting(path)
+        content = path.read
+
+        if content.match?(/^\s*config\.layout\s*=/)
+          say_status "skip", "config.layout already set in config/initializers/ruact.rb", :yellow
+          return
+        end
+
+        unless content.match?(/Ruact\.configure\s+do\s*\|(\w+)\|/)
+          warn_initializer_not_injectable
+          return
+        end
+
+        inject_into_file "config/initializers/ruact.rb",
+                         LAYOUT_SETTING_SNIPPET,
+                         after: /Ruact\.configure\s+do\s*\|\w+\|\n/
+        say_status "update", "set config.layout = true (your layout renders ruact pages)", :green
+      end
+
+      # The compiled stylesheet still has to be REQUESTED. Rails 8's default
+      # layout links `stylesheet_link_tag :app`, which Propshaft expands over
+      # every stylesheet on the load path — so `app/assets/builds/tailwind.css`
+      # is picked up with no further wiring (verified against a generated app:
+      # the rendered `<head>` carries `/assets/tailwind-<digest>.css`).
+      #
+      # A layout that instead links stylesheets BY NAME never asks for it, and
+      # the failure is silent: Tailwind builds fine, Propshaft serves it fine,
+      # and the page is simply unstyled. Warn rather than edit — which
+      # stylesheets a layout links is the app's business.
+      def warn_unless_layout_links_builds
+        layout_path = Pathname(destination_root).join("app/views/layouts/application.html.erb")
+        return unless layout_path.exist?
+
+        content = layout_path.read
+        return unless content.include?("stylesheet_link_tag")
+        return if content.match?(/stylesheet_link_tag\s+:app\b/) || content.include?("tailwind")
+
+        say_status "notice", "your layout links stylesheets by name — add the built one:", :yellow
+        say ""
+        say "      <%= stylesheet_link_tag \"tailwind\" %>"
+        say ""
+        say "  `stylesheet_link_tag :app` (the Rails 8 default) would pick up"
+        say "  app/assets/builds/tailwind.css on its own; a named link does not,"
+        say "  and the page would render unstyled with no error."
+        say ""
+      end
+
+      # The generator does NOT run these: `shadcn init` is interactive (it
+      # prompts for a component library and a preset) and both commands hit the
+      # network. What it CAN do is spell them exactly, which is the part nobody
+      # guesses: current shadcn defaults to **Base UI**, while ruact's generated
+      # components import **Radix** primitives — accepting the default gives you
+      # a component library the scaffold cannot use. Hence the explicit
+      # `--base radix`.
+      #
+      # The component list is ruact's own authoritative set
+      # (ScaffoldGenerator#required_shadcn_components), derived from the
+      # 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)."
+        say "Two commands remain — they are interactive and hit the network, so run them yourself:"
+        say ""
+        say "  npx shadcn@latest init --base radix"
+        say "  npx shadcn@latest add #{shadcn_add_list}"
+        say ""
+        say "  (--base radix matters: shadcn now defaults to Base UI, but the components"
+        say "   `ruact:scaffold --shadcn` generates import Radix primitives.)"
+        say "  (init also asks you to pick a style preset — any of them works.)"
+        say ""
+        say "Then scaffold a resource:"
+        say "  bin/rails generate ruact:scaffold Post title:string body:text --shadcn"
+      end
+
       # Story 15.1 — the exact marker tokens delimiting the ruact-managed
       # section of AGENTS.md. For a prose file the only safe idempotency key is
       # an explicit marker pair (`append_gitignore_entries`-style exact-line
@@ -463,6 +662,66 @@ module Ruact
       # Story 14.6 — a valid, lowercase npm "name" for the generated package.json,
       # derived from the app directory. npm names must be lowercase and contain
       # only URL-safe characters; anything else collapses to a hyphen.
+      # Kept verbatim in step with the `initializer.rb.tt` template's own
+      # `config.layout` block, so a migrated app and a fresh one end up reading
+      # the same thing.
+      LAYOUT_SETTING_SNIPPET = <<~RUBY
+        # Render ruact pages through this app's own layout, so the document `<head>`
+        # is yours: stylesheets, favicons, fonts and any gem that writes into
+        # `<head>` reach a ruact page. Requires the layout to call
+        # `<%= ruact_js_assets %>` (this generator adds it next to the React root).
+        config.layout = true
+
+      RUBY
+      private_constant :LAYOUT_SETTING_SNIPPET
+
+      # The initializer exists but is not the shape we know how to edit (someone
+      # rewrote it, or wrapped the configure call). Never guess at it — say what
+      # to add, so the app cannot end up half-migrated in silence.
+      def warn_initializer_not_injectable
+        say_status "skip", "could not find the Ruact.configure block to update", :red
+        say ""
+        say "  Add this line inside `Ruact.configure` in config/initializers/ruact.rb:"
+        say ""
+        say "      config.layout = true"
+        say ""
+        say "  Without it ruact keeps using its built-in shell, which carries no"
+        say "  stylesheet — your app's CSS will not reach a ruact-rendered page."
+        say ""
+      end
+
+      def shadcn?
+        options[:shadcn]
+      end
+
+      # Printed when the layout carries the ruact marker but the anchor found no
+      # root div to inject after. Silence would be the dangerous outcome: the app
+      # keeps rendering through ruact's CSS-less built-in shell, and nothing ever
+      # says why.
+      def warn_layout_migration_failed
+        say_status "skip", "could not locate the React root div in the layout", :red
+        say ""
+        say "  ruact could not add `ruact_js_assets` automatically. Add it by hand,"
+        say "  just after the root div in app/views/layouts/application.html.erb:"
+        say ""
+        say "      <div id=\"root\"></div>"
+        say "      <%= ruact_js_assets %>"
+        say ""
+        say "  Without it your app's CSS cannot reach a ruact-rendered page."
+        say ""
+      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
+      # literal list rather than aborting an otherwise-successful install.
+      def shadcn_add_list
+        require_relative "../scaffold/scaffold_shadcn_preflight"
+        ScaffoldGenerator::ShadcnPreflight::ALL_SHADCN_COMPONENTS.join(" ")
+      rescue StandardError
+        "button input textarea switch select label badge table alert-dialog dropdown-menu"
+      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,2 +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
+<% end -%>