fix(pro-dummy): make manual node-renderer validation reliable

Addresses the follow-up issues surfaced during review of #3158, where
validating a renderer fix locally required repo-specific workarounds.

Three independent breakages, one shared cause: the dummy app could make a
correct fix look broken or silently validate stale build artifacts.

1. `bin/dev` failed with `overlay.sockPort should be a number` because
   `bin/dev` exports `SHAKAPACKER_DEV_SERVER_PORT` as a string and
   Shakapacker passes it through unchanged on `devServer.port`. The Pro
   dummy's webpack development config forwarded that string straight to
   `@pmmmwh/react-refresh-webpack-plugin`, whose schema requires a number.
   Coerce with `Number()` (applied to both Pro dummy and execjs dummy).

2. Rails precompile hook failed with `cannot load such file -- ostruct`
   on Ruby 3.5+ because the Pro Gemfile was missing the explicit
   `ostruct`, `logger`, `benchmark` declarations the open-source Gemfile
   already had.

3. The dummy consumes the *built* `react-on-rails-pro-node-renderer/lib/`,
   not the TypeScript sources, so renderer fixes weren't exercised until
   the package was rebuilt. Add `node-renderer:fresh` and
   `node-renderer:build-watch` scripts, document the rebuild requirement
   inline in `Procfile.dev`, expand the Pro CLAUDE.md, and add a dedicated
   `validating-node-renderer-changes.md` checklist for reviewers.

Fixes #3177

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

Author: justin808

.claude/docs/manual-dev-environment-testing.md

@@ -2,7 +2,7 @@
 
 Automated tests can pass while the development environment is completely broken. CI starts services explicitly and runs in a controlled environment — it does not exercise `bin/dev`, Procfile orchestration, or the actual browser experience. This guide ensures agents verify the dev environment works end-to-end before submitting a PR.
 
-**Related:** [PR Testing Guide](pr-testing-guide.md), [Testing Build Scripts](testing-build-scripts.md)
+**Related:** [PR Testing Guide](pr-testing-guide.md), [Testing Build Scripts](testing-build-scripts.md), [Validating Node Renderer Changes](validating-node-renderer-changes.md)
 
 ## The Rule
 

.claude/docs/validating-node-renderer-changes.md

@@ -0,0 +1,122 @@
+# Validating Node Renderer Changes
+
+Manual validation checklist for changes under `packages/react-on-rails-pro-node-renderer/src/**`.
+
+**Why this exists:** the Pro dummy app consumes the _built_ renderer at
+`packages/react-on-rails-pro-node-renderer/lib/**`. Editing TypeScript under `src/` does
+nothing until that lib output is regenerated, so a correct fix can look broken (or worse,
+a regression can look fine because the dummy is still running stale lib output).
+
+**Related:** [Manual Dev Environment Testing](manual-dev-environment-testing.md)
+
+## When This Applies
+
+If your PR touches **any** of these, run through the checklist below:
+
+- `packages/react-on-rails-pro-node-renderer/src/**`
+- `packages/react-on-rails-pro-node-renderer/package.json` (especially `protocolVersion`,
+  `exports`, or runtime dependencies)
+- Any worker pool, JWT auth, integrations (Sentry/Honeybadger), or VM-context code in the
+  renderer
+
+## Pre-flight: Toolchain
+
+The Pro dummy app requires Ruby 3.3.x. If you are on a newer Ruby (3.5+), the dummy's
+Gemfile already pulls in `ostruct`, `logger`, and `benchmark` as explicit gems to silence
+warnings, but you may still hit unrelated incompatibilities. When in doubt, switch to the
+documented Ruby version:
+
+```bash
+mise use ruby@3.3.7  # or rbenv/asdf equivalent
+cd react_on_rails_pro/spec/dummy
+bundle install
+```
+
+## Step 1: Rebuild the Renderer Package
+
+Pick **one** of these depending on how you plan to iterate:
+
+**One-shot rebuild (recommended for a single validation pass):**
+
+```bash
+pnpm --filter react-on-rails-pro-node-renderer run build
+```
+
+**Or use the dummy's convenience script:**
+
+```bash
+cd react_on_rails_pro/spec/dummy
+pnpm run node-renderer:fresh   # builds the package, then starts the renderer
+```
+
+**Watch mode (recommended when iterating on the renderer source):**
+
+Either uncomment the `node-renderer-build` line in `react_on_rails_pro/spec/dummy/Procfile.dev`,
+or in a separate terminal run:
+
+```bash
+pnpm --filter react-on-rails-pro-node-renderer run build-watch
+```
+
+> If you skip this step, the dummy app will silently keep using the previous lib build.
+> Symptoms: a fix you just applied does not change behavior, or a regression you expected
+> to see does not appear.
+
+## Step 2: Start the Dummy App
+
+```bash
+cd react_on_rails_pro/spec/dummy
+bin/dev
+```
+
+Verify:
+
+- [ ] `bin/dev` starts without `overlay.sockPort should be a number` (webpack-dev-server)
+- [ ] `bin/dev` starts without `cannot load such file -- ostruct` (Rails precompile)
+- [ ] All Procfile.dev processes are healthy after 30 seconds
+- [ ] The `node-renderer` process logs that it bound to port 3800
+
+## Step 3: Exercise the SSR Endpoints
+
+For PRs touching streaming, hydration, RSC, or VM-context code, hit the routes that
+actually exercise the renderer (not just static pages):
+
+- [ ] `http://localhost:3000/stream_native_metadata` — renders without `ReferenceError`
+      (e.g. `performance is not defined`) in the renderer logs
+- [ ] `http://localhost:3000/hybrid_metadata_streaming` — same
+- [ ] Any route specifically related to your change
+
+For each route:
+
+- [ ] Page returns 200 and renders SSR content (view-source shows component markup)
+- [ ] No errors in the `node-renderer` Procfile pane
+- [ ] No errors in the Rails server log
+- [ ] No errors in the browser console
+
+## Step 4: Confirm You Tested the New Code
+
+It is easy to validate stale lib output without realizing it. Confirm:
+
+- [ ] `lib/` mtime is newer than the `src/` file you changed (compare
+      `ls -la packages/react-on-rails-pro-node-renderer/lib/` against
+      `ls -la packages/react-on-rails-pro-node-renderer/src/`)
+- [ ] If you used watch mode, you saw a rebuild line in the watcher output after your
+      most recent edit
+- [ ] Restart the `node-renderer` Procfile process after the rebuild — `node` does not
+      hot-reload required modules
+
+## Reporting Results in the PR
+
+```markdown
+## Node Renderer Validation
+
+- [x] Rebuilt `react-on-rails-pro-node-renderer` package
+- [x] Verified `lib/` mtime newer than `src/` after edit
+- [x] `bin/dev` starts cleanly
+- [x] `/stream_native_metadata` renders without errors
+- [x] `/hybrid_metadata_streaming` renders without errors
+- [x] No errors in node-renderer logs
+```
+
+If you cannot validate manually (e.g. no local Ruby toolchain), say so explicitly and
+note that the change is type-checked / unit-tested only.

CLAUDE.md

@@ -45,5 +45,6 @@ Use these docs for Claude-oriented operational guidance:
 - `.claude/docs/docs-competitive-landscape.md`
 - `.claude/docs/docs-templates.md`
 - `.claude/docs/manual-dev-environment-testing.md`
+- `.claude/docs/validating-node-renderer-changes.md`
 
 For Pro-package specifics, also read `react_on_rails_pro/CLAUDE.md`.

react_on_rails_pro/CLAUDE.md

@@ -58,6 +58,16 @@ The node renderer is a standalone Fastify HTTP server (separate Node.js process)
 - Integrations: Sentry, Honeybadger (optional peer deps)
 - Protocol versioning: `protocolVersion` in package.json must match gem expectations
 
+**Validating source changes against the dummy app:** the dummy consumes the _built_
+`packages/react-on-rails-pro-node-renderer/lib/**`, so edits under `src/**` are not
+picked up until the package is rebuilt. Use one of:
+
+- `pnpm --filter react-on-rails-pro-node-renderer run build` (one-shot)
+- `cd react_on_rails_pro/spec/dummy && pnpm run node-renderer:fresh` (rebuild + start)
+- `pnpm --filter react-on-rails-pro-node-renderer run build-watch` (watch in another shell)
+
+See `.claude/docs/validating-node-renderer-changes.md` for the full checklist.
+
 ### Yalc Dependency Chain
 
 Pro dummy's preinstall builds and links packages in this order:

react_on_rails_pro/Gemfile.development_dependencies

@@ -54,6 +54,12 @@ group :development, :test do
   gem "rbs", require: false
   gem "scss_lint", require: false
   gem "fakefs", require: "fakefs/safe"
+
+  # Added for Ruby 3.5+ compatibility to silence warnings.
+  # jbuilder and other gems lazy-require these stdlib bits that became default gems in 3.5.
+  gem "benchmark", require: false
+  gem "logger", require: false
+  gem "ostruct", require: false
 end
 
 group :test do

react_on_rails_pro/Gemfile.lock

@@ -247,6 +247,7 @@ GEM
       racc (~> 1.4)
     nokogiri (1.19.2-x86_64-linux-gnu)
       racc (~> 1.4)
+    ostruct (0.6.3)
     package_json (0.2.0)
     parallel (1.27.0)
     parser (3.3.10.0)
@@ -475,6 +476,7 @@ PLATFORMS
 
 DEPENDENCIES
   amazing_print
+  benchmark
   bootsnap
   bundler
   capybara (>= 3.38.0)
@@ -490,9 +492,11 @@ DEPENDENCIES
   jquery-rails
   launchy
   listen
+  logger
   net-http
   net-imap
   net-smtp
+  ostruct
   pg
   pry (>= 0.14.1)
   pry-byebug!

react_on_rails_pro/spec/dummy/Gemfile.lock

@@ -271,6 +271,7 @@ GEM
       racc (~> 1.4)
     nokogiri (1.19.2-x86_64-linux-musl)
       racc (~> 1.4)
+    ostruct (0.6.3)
     package_json (0.2.0)
     parallel (1.27.0)
     parser (3.3.10.0)
@@ -524,6 +525,7 @@ PLATFORMS
 
 DEPENDENCIES
   amazing_print
+  benchmark
   bootsnap
   capybara (>= 3.38.0)
   capybara-screenshot
@@ -538,9 +540,11 @@ DEPENDENCIES
   jquery-rails
   launchy
   listen
+  logger
   net-http
   net-imap
   net-smtp
+  ostruct
   pg
   prism-rails
   pry (>= 0.14.1)

react_on_rails_pro/spec/dummy/Procfile.dev

@@ -11,4 +11,9 @@ rails-server-assets: HMR=true SERVER_BUNDLE_ONLY=true bin/shakapacker --watch
 rails-rsc-assets: HMR=true RSC_BUNDLE_ONLY=true bin/shakapacker --watch
 
 # Start Node server for server rendering.
+# NOTE: This consumes the *built* `packages/react-on-rails-pro-node-renderer/lib/**`.
+# When validating source changes under `packages/react-on-rails-pro-node-renderer/src/**`,
+# either rebuild once (`pnpm --filter react-on-rails-pro-node-renderer run build`) or
+# uncomment the `node-renderer-build` line below to watch and rebuild on every save.
+# node-renderer-build: pnpm --filter react-on-rails-pro-node-renderer run build-watch
 node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=3800 node --inspect renderer/node-renderer.js

react_on_rails_pro/spec/dummy/config/webpack/development.js

@@ -11,7 +11,9 @@ const developmentEnvOnly = (clientWebpackConfig, _serverWebpackConfig) => {
     clientWebpackConfig.plugins.push(
       new ReactRefreshWebpackPlugin({
         overlay: {
-          sockPort: devServer.port,
+          // bin/dev sets SHAKAPACKER_DEV_SERVER_PORT as a string, which Shakapacker
+          // surfaces unchanged on devServer.port. The plugin schema requires a number.
+          sockPort: Number(devServer.port),
         },
       }),
     );

react_on_rails_pro/spec/dummy/package.json

@@ -105,7 +105,9 @@
     "build:server": "RAILS_ENV=production NODE_ENV=production SERVER=true bin/shakapacker",
     "build:clean": "rm -rf public/webpack && rm -rf ssr-generated || true",
     "node-renderer-debug": "RENDERER_PORT=3800 ndb renderer/node-renderer.js",
-    "node-renderer": "RENDERER_PORT=3800 node renderer/node-renderer.js"
+    "node-renderer": "RENDERER_PORT=3800 node renderer/node-renderer.js",
+    "node-renderer:fresh": "pnpm --filter react-on-rails-pro-node-renderer run build && RENDERER_PORT=3800 node renderer/node-renderer.js",
+    "node-renderer:build-watch": "pnpm --filter react-on-rails-pro-node-renderer run build-watch"
   },
   "license": "UNLICENSED",
   "repository": {