Merge remote-tracking branch 'origin/main' into codex/example-migrations-docs

* origin/main:
  chore: remove redundant --rsc-pro install generator flag (#3105)
  ci: warn (don't fail) on Bencher main regression (#3168)
  test: enable RSpec --profile to surface slowest package tests (#3176)
  fix(node-renderer): expose performance in VM context when supportModules (#3158)
  docs: remove stale immediate_hydration references (#3139) (#3159)
  docs: restore absolute URL for node-renderer testing example (#3179)
  Bump Rspack dependencies to v2 (^2.0.0-0) (#3084)
  chore: remove obsolete webpack <5.106.0 pin (#3175)
  Move Node Renderer entry point to renderer/ directory (#3165)
  docs: address RSC pitfalls review follow-ups (#3155) (#3156)
  docs: remove fabricated DevConsole reference, link verified RSC tools (#2527) (#3163)

# Conflicts:
#	docs/oss/building-features/node-renderer/js-configuration.md

Author: justin808

.github/workflows/benchmark.yml

@@ -157,7 +157,12 @@ jobs:
       # ============================================
 
       - name: Install Bencher CLI
-        uses: bencherdev/bencher@main
+        # Pinned: step 7a's alert-detection heuristic greps stderr for
+        # "Alert[s]" / "threshold violation" / "boundary violation". Those strings
+        # are not a documented API contract, so upgrading the CLI requires
+        # re-verifying that the expected phrases still appear in alert output.
+        # Expected stderr phrases at v0.6.2: "🚨 N Alerts", "Alert detected".
+        uses: bencherdev/bencher@v0.6.2
 
       - name: Add tools directory to PATH
         run: |
@@ -650,11 +655,27 @@ jobs:
             echo "::warning::Bencher baseline not found for start-point hash '$START_POINT_HASH' — regression comparison unavailable for this run"
             BENCHER_EXIT_CODE=0
           fi
-          rm -f "$BENCHER_STDERR"
 
-          # Export exit code early so downstream alerting steps (7b/7c) always see it,
-          # even if the post-processing below (step summary, PR comments) fails.
+          # Distinguish regression alerts from operational failures (auth/API/network/CLI)
+          # so that main can warn-only on the former while still failing hard on the latter.
+          # Match Bencher's actual alert output (e.g., "🚨 2 Alerts", "Alert detected") via
+          # a word-bounded, case-insensitive "Alert[s]". The word boundary (\b) already
+          # prevents matching lowercase "alerts" inside URL paths (e.g., "/v0/.../alerts"),
+          # so the case-insensitive flag adds robustness against future CLI wording changes
+          # (e.g., lowercase "1 alert") without reintroducing the URL-path false positive.
+          BENCHER_HAS_ALERT=0
+          if [ $BENCHER_EXIT_CODE -ne 0 ] && \
+             { grep -qiE "\bAlerts?\b" "$BENCHER_STDERR" || \
+               grep -qiE "threshold violation|boundary violation" "$BENCHER_STDERR"; }; then
+            BENCHER_HAS_ALERT=1
+          fi
+          # Cleanup is also handled by the `trap 'rm -f "$BENCHER_STDERR"' EXIT` above,
+          # so we don't need an explicit rm here.
+
+          # Export exit code and alert flag early so downstream steps (7b/7c/7d) always
+          # see them, even if the post-processing below (step summary, PR comments) fails.
           echo "BENCHER_EXIT_CODE=$BENCHER_EXIT_CODE" >> "$GITHUB_ENV"
+          echo "BENCHER_HAS_ALERT=$BENCHER_HAS_ALERT" >> "$GITHUB_ENV"
 
           # Post report to job summary and PR comment(s) if there's HTML output
           if [ -s bench_results/bencher_report.html ]; then
@@ -703,7 +724,7 @@ jobs:
       # STEP 7b: ALERT ON MAIN REGRESSION
       # ============================================
       - name: Create GitHub Issue for main regression
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main' && env.BENCHER_EXIT_CODE != '0'
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' && env.BENCHER_EXIT_CODE != '0' && env.BENCHER_HAS_ALERT == '1'
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
@@ -789,14 +810,35 @@ jobs:
           fi
 
       # ============================================
-      # STEP 7c: FAIL WORKFLOW ON MAIN REGRESSION
+      # STEP 7c: WARN ON MAIN REGRESSION
+      # ============================================
+      # Regressions are surfaced via the Bencher dashboard, the auto-opened tracking
+      # issue (Step 7b), and the job-summary report. Do not fail the workflow on regression
+      # alerts: single-run alerts on GitHub-hosted runners are dominated by environmental
+      # noise (alert sets across consecutive runs have ~0 overlap), so blocking main
+      # produces churn without signal. Re-enable a hard gate once thresholds/sample-size
+      # tolerate that noise. Operational errors (auth/API/network/CLI) are handled in
+      # step 7d and still fail the workflow.
+      - name: Warn if Bencher detected regression on main
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' && env.BENCHER_EXIT_CODE != '0' && env.BENCHER_HAS_ALERT == '1'
+        env:
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          echo "::warning::Bencher flagged a regression on main (exit ${BENCHER_EXIT_CODE:-1}). See the open regression issue (label: performance-regression), the Bencher dashboard, and the workflow run: ${RUN_URL}"
+
+      # ============================================
+      # STEP 7d: FAIL ON NON-REGRESSION BENCHER ERRORS
       # ============================================
-      # Only fail on main — PR benchmarks are informational (triggered by 'benchmark' label).
-      # Regressions on PRs are surfaced via Bencher report comments, not workflow failures.
-      - name: Fail workflow if Bencher detected regression on main
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main' && env.BENCHER_EXIT_CODE != '0'
+      # If bencher exited non-zero but stderr did not contain regression alert
+      # indicators, this is an operational failure (auth/API/network/CLI) rather than
+      # a performance signal. These should still fail the workflow on main so a broken
+      # benchmark pipeline (missing uploads, bad credentials, Bencher outage, etc.) is
+      # not silently hidden behind a warning annotation.
+      - name: Fail on non-regression Bencher error on main
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' && env.BENCHER_EXIT_CODE != '0' && env.BENCHER_HAS_ALERT != '1'
         run: |
-          echo "Bencher detected a regression (exit code: ${BENCHER_EXIT_CODE:-1})"
+          echo "::error::Bencher exited ${BENCHER_EXIT_CODE:-1} on main with no regression alert in stderr — this indicates an operational failure (auth/API/network/CLI), not a performance regression. Check the logs above."
+          # Preserve the original Bencher exit code in CI logs for diagnostic context.
           exit "${BENCHER_EXIT_CODE:-1}"
 
       # ============================================

.lychee.toml

@@ -80,6 +80,7 @@ exclude = [
   # ============================================================================
   '^https://blog\.shakacode\.com',  # May block automated requests
   '^https?://(www\.)?foxford\.ru',  # Russian site, often blocks bots
+  '^https://(www\.)?guavapass\.com',  # TLS handshake fails from GitHub Actions (bot filter)
   '^https://(www\.)?airgoat\.com',  # Returns 403
   '^https://(www\.)?first\.io',     # Returns 403
   '^https://(www\.)?estately\.com', # Returns 403

CHANGELOG.md

@@ -24,12 +24,25 @@ After a release, run `/update-changelog` in Claude Code to analyze commits, writ
 
 ### [Unreleased]
 
+#### Removed
+
+- **[Pro]** **Removed the `--rsc-pro` install generator flag**: `--rsc` already implies Pro, so the separate mode was unnecessary. Behaviors previously gated on `--rsc-pro` (Pro verification checklist, prerelease install note, exact Pro gem pin on prereleases) now fire on `--rsc` installs. See also [Issue 3104](https://github.com/shakacode/react_on_rails/issues/3104), which tracks unrelated silent-failure bugs in the Pro upgrade automation. [PR 3105](https://github.com/shakacode/react_on_rails/pull/3105) by [ihabadham](https://github.com/ihabadham).
+
+#### Changed
+
+- **[Pro]** **Pro generator now creates the Node Renderer at `renderer/node-renderer.js`**: The canonical location for the Node Renderer entry point is now a dedicated top-level `renderer/` directory instead of `client/`, making it straightforward to exclude from production Docker builds that strip JS sources after bundling. Docs and Pro `spec/dummy` now use the new path consistently. Existing apps are unaffected — the generator skips files that already exist (including a legacy `client/node-renderer.js`). Fixes [Issue 3073](https://github.com/shakacode/react_on_rails/issues/3073). [PR 3165](https://github.com/shakacode/react_on_rails/pull/3165) by [justin808](https://github.com/justin808).
+
 #### Fixed
 
+- **[Pro]** **Node renderer now exposes `performance` when `supportModules: true`**: React 19's development build of `React.lazy` calls `performance.now()`, which previously threw `ReferenceError: performance is not defined` inside the node renderer's VM context unless users manually added `performance` via `additionalContext`. `performance` is now included in the default globals alongside `Buffer`, `process`, etc. Fixes [Issue 3154](https://github.com/shakacode/react_on_rails/issues/3154). [PR 3158](https://github.com/shakacode/react_on_rails/pull/3158) by [justin808](https://github.com/justin808).
 - **Client startup now recovers if initialization begins during `interactive` after `DOMContentLoaded` already fired**: React on Rails now still initializes the page when the client bundle starts in the browser timing window after `DOMContentLoaded` but before the document reaches `complete`. Fixes [Issue 3150](https://github.com/shakacode/react_on_rails/issues/3150). [PR 3151](https://github.com/shakacode/react_on_rails/pull/3151) by [ihabadham](https://github.com/ihabadham).
 - **Doctor accepts TypeScript server bundle entrypoints**: `react_on_rails:doctor` now resolves common source entrypoint suffixes (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`) before warning that the server bundle is missing, preventing false positives when apps use `server-bundle.ts`. [PR 3111](https://github.com/shakacode/react_on_rails/pull/3111) by [justin808](https://github.com/justin808).
 - **Doctor no longer fails custom projects for a missing generated `bin/dev`**: `react_on_rails:doctor` now downgrades a missing official React on Rails `bin/dev` launcher from an error to a warning and adds explicit guidance when a custom `./dev` script is detected, so custom projects can pass diagnostics when their development setup is intentional. Fixes [Issue 3103](https://github.com/shakacode/react_on_rails/issues/3103). [PR 3117](https://github.com/shakacode/react_on_rails/pull/3117) by [justin808](https://github.com/justin808).
 
+#### Changed
+
+- **Rspack install scaffolding now targets Rspack v2**: `react_on_rails:install --rspack` and `bin/switch-bundler` now generate the Rspack v2 package line (`@rspack/core@^2.0.0-0`, `@rspack/cli@^2.0.0-0`, `@rspack/plugin-react-refresh@^2.0.0`) while keeping `rspack-manifest-plugin@^5.0.0`, which is already compatible. Closes [Issue 3082](https://github.com/shakacode/react_on_rails/issues/3082). [PR 3084](https://github.com/shakacode/react_on_rails/pull/3084) by [justin808](https://github.com/justin808).
+
 ### [16.6.0] - 2026-04-09
 
 #### Removed

benchmarks/bench-node-renderer.rb

@@ -23,7 +23,7 @@ def read_protocol_version
 
 def read_password_from_config
   config_path = File.expand_path(
-    "../react_on_rails_pro/spec/dummy/client/node-renderer.js",
+    "../react_on_rails_pro/spec/dummy/renderer/node-renderer.js",
     __dir__
   )
   config_content = File.read(config_path)

docs/oss/api-reference/generator-details.md

@@ -50,7 +50,7 @@ can pass the redux option if you'd like to have redux setup for you automaticall
     Passing the --pro generator option sets up React on Rails Pro with Node
     server rendering, fragment caching, and code-splitting support.
     Requires the react_on_rails_pro gem (add it to your Gemfile first).
-    Creates the Pro initializer, node-renderer.js, and adds the Node Renderer
+    Creates the Pro initializer, renderer/node-renderer.js, and adds the Node Renderer
     process to Procfile.dev.
 
 * RSC (React Server Components)
@@ -215,7 +215,7 @@ rails generate react_on_rails:install --pro
 **What gets created:**
 
 - `config/initializers/react_on_rails_pro.rb` - Pro configuration with Node Renderer settings
-- `client/node-renderer.js` - Node Renderer bootstrap file
+- `renderer/node-renderer.js` - Node Renderer bootstrap file
 - Node Renderer process added to `Procfile.dev`
 - Pro npm packages (`react-on-rails-pro`, `react-on-rails-pro-node-renderer`)
 

docs/oss/api-reference/ruby-api-pro.md

@@ -47,9 +47,9 @@ Streams a server-rendered React component using React 18's `renderToPipeableStre
 
 Requires the controller to use `stream_view_containing_react_components`.
 
-Options: same as `react_component` plus:
+Options: same as `react_component`.
 
-- `:immediate_hydration` (default: `true`) — controls hydration timing
+> **Note (Pro):** React on Rails Pro hydrates streamed components early (before `DOMContentLoaded`) automatically — no per-component toggle is exposed.
 
 ```ruby
 <%= stream_react_component("App", props: { data: @data }) %>

docs/oss/building-features/code-splitting.md

@@ -252,7 +252,7 @@ in your webpack configuration. That turns off the polyfills for things like `__d
 
 ### Node Renderer
 
-In your `node-renderer.js` file which runs node renderer, you need to specify `supportModules` options as follows:
+In your `renderer/node-renderer.js` file which runs node renderer, you need to specify `supportModules` options as follows:
 
 ```js
 const path = require('path');

docs/oss/building-features/node-renderer/basics.md

@@ -27,7 +27,7 @@ See the [Memory Leaks guide](../../../pro/js-memory-leaks.md) for common leak pa
 
 **node-renderer** is a standalone Node application to serve React SSR requests from a **Rails** client. You don't need any **Ruby** code to setup and launch it. You can configure with the command line or with a launch file.
 
-> **Generator shortcut:** Running `rails generate react_on_rails:install --pro` (or `rails generate react_on_rails:pro` for existing apps) automatically creates `client/node-renderer.js`, adds the Node Renderer process to `Procfile.dev`, and installs the required npm packages. See [Installation](../../../pro/installation.md) for details. The manual setup below is for apps that need custom configuration.
+> **Generator shortcut:** Running `rails generate react_on_rails:install --pro` (or `rails generate react_on_rails:pro` for existing apps) automatically creates `renderer/node-renderer.js`, adds the Node Renderer process to `Procfile.dev`, and installs the required npm packages. See [Installation](../../../pro/installation.md) for details. The manual setup below is for apps that need custom configuration.
 
 ## Simple Command Line for node-renderer
 
@@ -65,7 +65,7 @@ For the most control over the setup, create a JavaScript file to start the NodeR
    # or: yarn add react-on-rails-pro-node-renderer
    # or: bun add react-on-rails-pro-node-renderer
    ```
-4. Configure a JavaScript file that will launch the rendering server per the docs in [Node Renderer JavaScript Configuration](./js-configuration.md). For example, create a file `node-renderer.js`. Here is a simple example that uses all the defaults except for serverBundleCachePath:
+4. Configure a JavaScript file that will launch the rendering server per the docs in [Node Renderer JavaScript Configuration](./js-configuration.md). For example, create a file `renderer/node-renderer.js`. Here is a simple example that uses all the defaults except for serverBundleCachePath:
 
    ```javascript
    import path from 'path';
@@ -78,7 +78,7 @@ For the most control over the setup, create a JavaScript file to start the NodeR
    reactOnRailsProNodeRenderer(config);
    ```
 
-5. Now you can launch your renderer server with `node node-renderer.js`. You will probably add a script to your `package.json`.
+5. Now you can launch your renderer server with `node renderer/node-renderer.js`. You will probably add a script to your `package.json`.
 6. You can use a command line argument of `-p SOME_PORT` to override any configured or ENV value for the port.
 
 ## Setup Rails Application
@@ -157,13 +157,14 @@ The Node Renderer must be started as a background process before running tests.
 # .github/workflows/test.yml (GitHub Actions example)
 jobs:
   test:
+    runs-on: ubuntu-latest
     env:
       # Job-level: both the renderer and Rails test steps need this
       RENDERER_PASSWORD: ${{ secrets.RENDERER_PASSWORD }}
     steps:
       - name: Start Node Renderer
         run: |
-          node client/node-renderer.js &
+          node renderer/node-renderer.js &
           # Wait for the renderer to be ready.
           # The renderer uses cleartext HTTP/2 (h2c), so use --http2-prior-knowledge for the probe.
           # --max-time 2 prevents hangs if the port is open but the process is stalled.

docs/oss/building-features/node-renderer/container-deployment.md

@@ -131,6 +131,8 @@ end
 
 ## Dockerfile Example
 
+> **Why the renderer entry point lives in a dedicated `renderer/` directory:** Production Docker builds commonly strip JavaScript sources after the client bundles are built, since the Rails app no longer needs them at runtime. Keeping the renderer entry point in its own top-level directory (separate from `client/`) makes it trivial to exclude from that cleanup — the Node Renderer process still needs its entry file and dependencies at runtime.
+
 A minimal Dockerfile that bundles Rails and the Node Renderer in a single image:
 
 ```dockerfile
@@ -175,10 +177,10 @@ For the single-container pattern, use a process manager like [overmind](https://
 ```text
 # Procfile
 rails: bundle exec rails server -b 0.0.0.0 -p 3000
-renderer: node client/node-renderer.js
+renderer: node renderer/node-renderer.js
 ```
 
-> **Tip:** For sidecar containers, use the same image but override the `CMD` — one container runs `bundle exec rails server`, the other runs `node client/node-renderer.js` (or your Node Renderer entry point).
+> **Tip:** For sidecar containers, use the same image but override the `CMD` — one container runs `bundle exec rails server`, the other runs `node renderer/node-renderer.js` (or your Node Renderer entry point).
 
 ## Docker Compose Example
 
@@ -199,7 +201,7 @@ services:
 
   renderer:
     build: .
-    command: node client/node-renderer.js
+    command: node renderer/node-renderer.js
     ports:
       - '3800:3800'
     environment:
@@ -220,7 +222,7 @@ services:
 By default, the Node Renderer binds to `localhost`. For **sidecar containers** in the same Kubernetes pod, that works because the containers share a network namespace. For **separate workloads** or Docker Compose setups without shared networking, bind to `0.0.0.0`:
 
 ```javascript
-// node-renderer.js
+// renderer/node-renderer.js
 import { reactOnRailsProNodeRenderer } from 'react-on-rails-pro-node-renderer';
 
 const config = {
@@ -488,7 +490,7 @@ spec:
 
         - name: node-renderer
           image: your-app:latest # Same image as Rails
-          command: ['node', 'client/node-renderer.js']
+          command: ['node', 'renderer/node-renderer.js']
           ports:
             - containerPort: 3800
           env:

docs/oss/building-features/node-renderer/debugging.md

@@ -63,7 +63,7 @@ Use Node's built-in flag to write heap snapshots on demand:
 ```bash
 cd react_on_rails_pro/spec/dummy
 # Adjust the port if your Rails app points at a different renderer URL.
-NODE_OPTIONS="--heapsnapshot-signal=SIGUSR2" RENDERER_PORT=3800 node client/node-renderer.js
+NODE_OPTIONS="--heapsnapshot-signal=SIGUSR2" RENDERER_PORT=3800 node renderer/node-renderer.js
 ```
 
 Then capture snapshots at different times: