Add RSC and Node Renderer documentation to CLAUDE.md and README.md

Document the three-bundle architecture (client, server SSR, RSC), Node
Renderer setup requirements, VM sandbox constraints, RSC component
classification rules, and common troubleshooting patterns. Update README
with current version targets, RSC section, expanded config file list,
and all six Procfile.dev processes.

Motivated by the debugging challenges in PR #723 where undocumented
constraints (VM sandbox lacks require/MessageChannel, 'use client'
classification, Node renderer must run for tests) caused significant
debugging time. Filed shakacode/react_on_rails#3076 with upstream
doc suggestions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: justin808

CLAUDE.md

@@ -16,6 +16,76 @@ bundle exec rubocop
 bundle exec rubocop -a
 ```
 
+## Architecture: Three Bundle System
+
+This project builds **three separate Rspack bundles** via Shakapacker:
+
+| Bundle | Config | Output | Runtime |
+|--------|--------|--------|---------|
+| **Client** | `clientWebpackConfig.js` | `public/packs/` | Browser |
+| **Server (SSR)** | `serverWebpackConfig.js` | `ssr-generated/` | Node renderer VM sandbox |
+| **RSC** | `rscWebpackConfig.js` | RSC output dir | Node renderer (full Node.js) |
+
+### Key constraints
+
+- The **server bundle runs in a VM sandbox** (`vm.createContext()`), NOT full Node.js. It lacks `require`, `MessageChannel`, `TextEncoder`, and other Node/browser globals.
+- Use `resolve.fallback: false` (NOT `externals`) for Node builtins in the server bundle — the VM has no `require()`, so externalized `require('path')` calls will crash.
+- The **RSC bundle** targets Node.js directly with the `react-server` condition, so Node builtins work normally there.
+- A `BannerPlugin` injects a `MessageChannel` polyfill into the server bundle because `react-dom/server.browser` needs it at module load time.
+
+### Build commands
+
+```bash
+# Build only the server bundle
+SERVER_BUNDLE_ONLY=yes bin/shakapacker
+
+# Build only the RSC bundle
+RSC_BUNDLE_ONLY=true bin/shakapacker
+
+# Watch modes (used by Procfile.dev)
+SERVER_BUNDLE_ONLY=yes bin/shakapacker --watch
+RSC_BUNDLE_ONLY=true bin/shakapacker --watch
+```
+
+## Node Renderer
+
+React on Rails Pro's NodeRenderer must be running for SSR and RSC payload generation.
+
+- **Port**: 3800 (configured in `config/initializers/react_on_rails_pro.rb`)
+- **Launcher**: `node react-on-rails-pro-node-renderer.js`
+- **Auth**: Requires `RENDERER_PASSWORD` env var (defaults to `local-dev-renderer-password` in dev/test, required with no fallback in production)
+- **Started automatically** by `bin/dev` / `Procfile.dev`
+
+### Testing requirement
+
+**The Node renderer must be running before `bundle exec rspec`.** Tests will fail with `Net::ReadTimeout` if it is not running. CI starts it as a background process and waits up to 30 seconds for TCP readiness on port 3800.
+
+### Enabled environments
+
+The renderer is enabled when `Rails.env.local?` (development + test) or `REACT_USE_NODE_RENDERER=true`. Production requires explicit env var configuration.
+
+## RSC Component Classification
+
+React on Rails Pro auto-classifies components based on the `'use client'` directive:
+
+- **With `'use client'`** → registered via `ReactOnRails.register()` (traditional SSR/client component)
+- **Without `'use client'`** → registered via `registerServerComponent()` (React Server Component)
+
+### Common gotcha: `.server.jsx` files
+
+In this codebase, `.server.jsx` does NOT mean "React Server Component" — it means traditional **server-side rendering** (e.g., `StaticRouter`). If a `.server.jsx` file uses client APIs like `ReactOnRails.getStore()` or React hooks, it **needs** the `'use client'` directive to prevent RSC misclassification. The naming predates RSC and refers to the Rails SSR render path.
+
+### Key files
+
+| File | Purpose |
+|------|---------|
+| `config/webpack/rscWebpackConfig.js` | RSC bundle configuration |
+| `config/webpack/rspackRscPlugin.js` | Detects `'use client'` directives, emits React Flight manifests |
+| `client/app/packs/rsc-bundle.js` | RSC entry point |
+| `client/app/packs/rsc-client-components.js` | Client component registration for RSC |
+| `config/initializers/react_on_rails_pro.rb` | Node renderer + RSC configuration |
+| `react-on-rails-pro-node-renderer.js` | Node renderer launcher |
+
 ## Conductor Compatibility (Version Managers)
 
 ### Problem

README.md

@@ -83,19 +83,19 @@ You can see this tutorial live here: [http://reactrails.com/](http://reactrails.
   + [Configuration Files](#configuration-files)
   + [Additional Resources](#additional-resources)
 + [Thruster HTTP/2 Proxy](#thruster-http2-proxy)
++ [React Server Components (RSC)](#react-server-components-rsc)
 + [Sass, CSS Modules, and Tailwind CSS integration](#sass-css-modules-and-tailwind-css-integration)
   + [Fonts with SASS](#fonts-with-sass)
 + [Process Management during Development](#process-management-during-development)
-+ [Rendering with Express Server](#rendering-with-express-server)
-  + [Setup](#setup)
 + [Contributors](#contributors)
   + [About ShakaCode](#about-shakacode)
   + [RubyMine and WebStorm](#rubymine-and-webstorm)
 + [Open Code of Conduct](#open-code-of-conduct)
 
 ## Demoed Functionality
 
-- Example of using the [react_on_rails gem](https://github.com/shakacode/react_on_rails) for easy React + Rspack integration with Rails.
+- Example of using [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/) with the NodeRenderer for server-side rendering.
+- Example of [React Server Components (RSC)](#react-server-components-rsc) with streaming and selective hydration.
 - Example of React with [CSS Modules](http://glenmaddern.com/articles/css-modules) inside Rails using modern Shakapacker/Rspack builds.
 - Example of enabling hot reloading of both JS and CSS (modules) from your Rails app in development mode. Change your code. Save. Browser updates without a refresh!
 - Example of React/Redux with Rails Action Cable.
@@ -110,18 +110,17 @@ You can see this tutorial live here: [http://reactrails.com/](http://reactrails.
 
 See package.json and Gemfile for versions
 
-1. [react_on_rails gem](https://github.com/shakacode/react_on_rails/)
-1. [React](http://facebook.github.io/react/)
+1. [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/) with NodeRenderer for SSR and React Server Components
+1. [React 19](http://facebook.github.io/react/) with React Server Components support
 1. [Redux](https://github.com/reactjs/redux)
 1. [react-router](https://github.com/reactjs/react-router)
 1. [react-router-redux](https://github.com/reactjs/react-router-redux)
 1. [Rspack with hot-reload](https://rspack.dev/guide/features/dev-server) (for local dev)
-1. [Babel transpiler](https://github.com/babel/babel)
+1. [SWC transpiler](https://swc.rs/) for fast JavaScript/TypeScript compilation
 1. [Ruby on Rails 8](http://rubyonrails.org/) for backend app and comparison with plain HTML
 1. [Thruster](https://github.com/basecamp/thruster) - Zero-config HTTP/2 proxy for optimized asset delivery
 1. [Heroku deployment guide](https://devcenter.heroku.com/articles/getting-started-with-rails8)
 1. [Deployment to the ControlPlane](.controlplane/readme.md)
-1. [Turbolinks 5](https://github.com/turbolinks/turbolinks)
 1. [Tailwind CSS](https://github.com/tailwindlabs/tailwindcss)
 
 ## Basic Demo Setup
@@ -183,10 +182,10 @@ assets_bundler: rspack
 
 ### Version Targets
 
-- `react_on_rails` gem: `16.4.0`
-- `react-on-rails` npm package: `16.4.0`
-- `shakapacker` gem/npm package: `9.7.0`
-- `@rspack/core` and `@rspack/cli`: `2.0.0-beta.7` (latest published v2 prerelease at the time of this update)
+- `react_on_rails_pro` gem: `16.6.0.rc.0`
+- `react-on-rails-pro` npm package: `16.6.0-rc.0`
+- `shakapacker` gem/npm package: `10.0.0-rc.0`
+- `@rspack/core` and `@rspack/cli`: `2.0.0-beta.7`
 
 ### Why Rspack
 
@@ -197,10 +196,13 @@ assets_bundler: rspack
 ### Configuration Files
 
 All bundler configuration is in `config/webpack/`:
-- `webpackConfig.js` - Main Shakapacker entry point
+- `webpackConfig.js` - Main Shakapacker entry point (routes to client, server, or RSC config)
 - `commonWebpackConfig.js` - Shared configuration
-- `clientWebpackConfig.js` - Client bundle settings
-- `serverWebpackConfig.js` - Server-side rendering bundle
+- `clientWebpackConfig.js` - Client bundle settings (browser, with HMR)
+- `serverWebpackConfig.js` - Server-side rendering bundle (runs in Node renderer VM sandbox)
+- `rscWebpackConfig.js` - React Server Components bundle (runs in Node renderer, full Node.js)
+- `rspackRscPlugin.js` - Custom plugin that detects `'use client'` directives and emits React Flight manifests
+- `bundlerUtils.js` - Shared bundler detection utilities
 - `development.js`, `production.js`, `test.js` - Environment-specific settings
 
 ### Additional Resources
@@ -243,6 +245,47 @@ The server automatically benefits from HTTP/2, caching, and compression without
 
 For detailed information, troubleshooting, and advanced configuration options, see [docs/thruster.md](docs/thruster.md).
 
+## React Server Components (RSC)
+
+This project demonstrates React Server Components with React on Rails Pro. Visit `/server-components` to see the demo page.
+
+### How It Works
+
+The app builds **three separate bundles**:
+
+1. **Client bundle** — Browser JavaScript with HMR, built by `clientWebpackConfig.js`
+2. **Server bundle** — Traditional SSR, runs in the Node renderer's VM sandbox, built by `serverWebpackConfig.js`
+3. **RSC bundle** — React Server Components with the `react-server` condition, runs in full Node.js, built by `rscWebpackConfig.js`
+
+The [React on Rails Pro NodeRenderer](https://www.shakacode.com/react-on-rails-pro/) runs on port 3800 and handles both SSR rendering and RSC payload generation. A custom `RspackRscPlugin` detects `'use client'` directives in source files and emits the React Flight manifests (`react-client-manifest.json`, `react-server-client-manifest.json`) that React uses to resolve client component references during streaming.
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `config/webpack/rscWebpackConfig.js` | RSC bundle configuration |
+| `config/webpack/rspackRscPlugin.js` | `'use client'` detection and manifest generation |
+| `client/app/packs/rsc-bundle.js` | RSC entry point — registers server components |
+| `client/app/packs/rsc-client-components.js` | Client component registration for RSC hydration |
+| `config/initializers/react_on_rails_pro.rb` | NodeRenderer and RSC configuration |
+| `react-on-rails-pro-node-renderer.js` | Node renderer launcher (port 3800, 3 workers) |
+| `client/app/bundles/server-components/` | RSC demo components |
+
+### Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `Net::ReadTimeout` in tests | Node renderer not running | Start it with `bin/dev` or `node react-on-rails-pro-node-renderer.js` |
+| Component renders blank/empty div | Missing `'use client'` directive | Add `'use client'` to components using client APIs (hooks, stores, event handlers) |
+| `MessageChannel is not defined` | Server bundle VM missing polyfill | Check `BannerPlugin` in `serverWebpackConfig.js` |
+| `require is not defined` | Server bundle using `externals` | Use `resolve.fallback: false` instead — the VM sandbox has no `require()` |
+| RSC manifests missing | RSC bundle not built | Run `RSC_BUNDLE_ONLY=true bin/shakapacker` |
+
+### Further Reading
+
+- [React on Rails Pro RSC Documentation](https://www.shakacode.com/react-on-rails-pro/)
+- [React Server Components RFC](https://github.com/reactjs/rfcs/blob/main/text/0188-server-components.md)
+
 ## Sass, CSS Modules, and Tailwind CSS Integration
 This example project uses mainly Tailwind CSS for styling.
 Besides this, it also demonstrates Sass and CSS modules, particularly for some CSS transitions.
@@ -270,12 +313,18 @@ export default class CommentBox extends React.Component {
 ### Fonts with SASS
 The tutorial makes use of a custom font OpenSans-Light. We're doing this to show how to add assets for the CSS processing. The font files are located under [client/app/assets/fonts](client/app/assets/fonts) and are loaded by both the Rails asset pipeline and the Rspack HMR server.
 
-## Process management during development
+## Process Management during Development
 ```bash
 bundle exec foreman start -f <Procfile>
 ```
 
-1. [`Procfile.dev`](Procfile.dev): Starts the Rspack Dev Server and Rails with Hot Reloading.
+1. [`Procfile.dev`](Procfile.dev): Starts all development processes with Hot Reloading:
+   - `rescript` — ReScript watch mode
+   - `rails` — Rails server via Thruster on port 3000
+   - `wp-client` — Client Rspack dev server with HMR
+   - `wp-server` — Server Rspack watcher for SSR bundle
+   - `wp-rsc` — RSC Rspack watcher for React Server Components bundle
+   - `node-renderer` — React on Rails Pro Node renderer on port 3800
 1. [`Procfile.dev-static`](Procfile.dev-static): Starts the Rails server and generates static assets that are used for tests.
 
 ## Contributors