Fix RSC payload JSON corruption from Rails view annotations (#2535)

## Summary
- render the RSC payload endpoint template with `formats: [:text]` so
Rails does not apply HTML view annotations
- rename the payload view template to `rsc_payload.text.erb`
- add a regression request spec that enables
`ActionView::Base.annotate_rendered_view_with_filenames` and verifies
NDJSON lines remain parseable

Fixes #2520

## Test Plan
- `bundle exec rubocop
react_on_rails_pro/lib/react_on_rails_pro/concerns/rsc_payload_renderer.rb
react_on_rails_pro/spec/dummy/spec/requests/rsc_payload_spec.rb`
- `cd react_on_rails_pro/spec/dummy && bundle install`
- `cd react_on_rails_pro/spec/dummy && pnpm run node-renderer` (separate
terminal)
- `cd react_on_rails_pro/spec/dummy && bundle exec rspec
spec/requests/rsc_payload_spec.rb`

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Small change to response rendering options plus a regression test; low
risk aside from potential clients expecting a different negotiated
format.
> 
> **Overview**
> For the `rsc_payload` streaming endpoint, forces the render `formats`
to `[:text]` so Rails doesn’t inject HTML view-annotation comments that
can corrupt the NDJSON payload.
> 
> Adds a request spec that enables
`ActionView::Base.annotate_rendered_view_with_filenames` and asserts the
response lines remain JSON-parseable and contain expected `html` chunks.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
fe6374b. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Bug Fixes**
* Prevented NDJSON payload corruption when view annotation is enabled by
rendering RSC payloads as plain text and serving application/x-ndjson;
custom RSC payload templates must produce plain text (e.g., .text) not
HTML.

* **Tests**
* Added integration tests validating NDJSON responses and behavior with
view annotations enabled.

* **Documentation**
* Added upgrade notes describing template override requirements and
migration verification.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: justin808

CHANGELOG.md

@@ -40,6 +40,7 @@ Changes since the last non-beta release.
 - **Handle HTTPX error responses when fetching dev-server bundle/assets for upload**: During development startup races, `get_form_body_for_file` could receive `HTTPX::ErrorResponse` and still call `response.body`, causing an unexpected crash path. The request layer now raises `ReactOnRailsPro::Error` with HTTPX error details before body access and includes regression tests for local path, HTTP success, and HTTP error cases. [PR 2532](https://github.com/shakacode/react_on_rails/pull/2532) by [justin808](https://github.com/justin808).
 - **Fix streaming SSR hangs and silent error absorption in RSC payload injection**: Fixed two related issues: (1) streaming SSR renders hanging forever when errors occur because Node.js `stream.pipe()` doesn't propagate errors or closure from source to destination, and (2) errors in the RSC payload injection pipeline being silently absorbed, preventing them from reaching error reporters like Sentry. Introduced a shared `safePipe` utility and used `'close'` events as reliable termination signals across the streaming pipeline (Node renderer, RSC payload injection, transform streams, and Ruby async task). Also added a Ruby safety net to prevent Rails request hangs when async rendering tasks raise before the first chunk. [PR 2407](https://github.com/shakacode/react_on_rails/pull/2407) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
 - **Node renderer duplicate error reports for render failures**: Fixed duplicate `errorReporter.message` notifications when unexpected exceptions occurred in `handleRenderRequest`. The handler now returns an error `ResponseResult` instead of rethrowing, so the same failure is not reported again by `worker.ts` while still returning a 400 response. [PR 2531](https://github.com/shakacode/react_on_rails/pull/2531) by [justin808](https://github.com/justin808).
+- **Fix RSC payload JSON corruption from Rails view annotations in development**: RSC payload responses were rendered through an HTML template, so when `annotate_rendered_view_with_filenames` was enabled, Rails wrapped NDJSON chunks with HTML comments and broke client-side `JSON.parse`. The payload endpoint now renders the template in text format and serves `application/x-ndjson`, and a request spec covers the annotated-view scenario. If you override `custom_rsc_payload_template`, ensure it resolves to a text or format-neutral template (for example, `.text.erb`) rather than `.html.erb`. When RSC support is enabled, startup now also warns if `Rack::Deflater` is present, because response-transforming middleware can interfere with `ActionController::Live` NDJSON streaming. [PR 2535](https://github.com/shakacode/react_on_rails/pull/2535) by [justin808](https://github.com/justin808).
 
 ### [16.4.0.rc.6] - 2026-03-04
 

…/react_on_rails_pro/rsc_payload.html.erb …/react_on_rails_pro/rsc_payload.text.erbreact_on_rails_pro/app/views/react_on_rails_pro/rsc_payload.html.erb renamed to react_on_rails_pro/app/views/react_on_rails_pro/rsc_payload.text.erb react_on_rails_pro/app/views/react_on_rails_pro/rsc_payload.html.erb renamed to react_on_rails_pro/app/views/react_on_rails_pro/rsc_payload.text.erb

@@ -198,6 +198,16 @@ export REACT_ON_RAILS_PRO_LICENSE="your-license-token-here"
 
 For complete licensing details, see [LICENSE_SETUP.md](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/LICENSE_SETUP.md).
 
+### Additional Upgrade Notes
+
+#### Upgrading to 16.4.0 or later
+
+##### RSC payload template overrides
+
+React on Rails Pro now renders the built-in RSC payload template with `formats: [:text]` so Rails view annotations cannot inject HTML comments into NDJSON responses.
+
+If your app overrides `custom_rsc_payload_template`, make sure that override resolves to a text or format-neutral template path, such as `app/views/.../rsc_payload.text.erb`. Overrides that only exist as `.html.erb` templates will raise `ActionView::MissingTemplate` when the RSC payload endpoint renders.
+
 ### Verify Migration
 
 #### 1. Verify Gem Installation

react_on_rails_pro/docs/updating.md

@@ -15,7 +15,20 @@ def rsc_payload
 
       stream_view_containing_react_components(
         template: custom_rsc_payload_template,
-        layout: false
+        layout: false,
+        # Render as text so Rails does not inject HTML view annotation comments
+        # into the NDJSON stream. Custom template overrides must resolve to a
+        # text or format-neutral template, not `.html.erb`.
+        formats: [:text],
+        content_type: "application/x-ndjson"
+      )
+    rescue ActionView::MissingTemplate => e
+      raise e.exception(
+        "[React on Rails Pro] RSC payload templates are now rendered with format :text. " \
+        "If you override `custom_rsc_payload_template`, make sure the override resolves to " \
+        "a text or format-neutral template (for example `rsc_payload.text.erb`) instead of " \
+        "only `.html.erb`. See react_on_rails_pro/docs/updating.md for upgrade notes.\n\n" \
+        "Original error: #{e.message}"
       )
     end
 

react_on_rails_pro/lib/react_on_rails_pro/concerns/rsc_payload_renderer.rb

@@ -12,6 +12,10 @@ module Stream
     #
     # @param template [String] The path to the template file to be streamed.
     # @param close_stream_at_end [Boolean] Whether to automatically close the stream after rendering (default: true).
+    # @param content_type [String, nil] Optional response content type. Set after rendering but before the first
+    #   stream write, overriding any content type inferred from the template format. When using
+    #   a non-HTML `formats:` value (for example `[:text]`), pass `content_type` too unless
+    #   committing the format-derived MIME type is intentional.
     # @param render_options [Hash] Additional options to pass to `render_to_string`.
     #
     # components must be added to the view using the `stream_react_component` helper.
@@ -30,10 +34,13 @@ module Stream
     #       For more details, refer to `lib/react_on_rails/helper.rb` in the react_on_rails repository.
     #
     # @see ReactOnRails::Helper#stream_react_component
-    def stream_view_containing_react_components(template:, close_stream_at_end: true, **render_options)
+    def stream_view_containing_react_components(
+      template:, close_stream_at_end: true, content_type: nil, **render_options
+    )
       require "async"
       require "async/barrier"
       require "async/limited_queue"
+      warn_on_non_html_formats_without_content_type(render_options[:formats], content_type)
 
       Sync do |parent_task|
         # Initialize async primitives for concurrent component streaming
@@ -48,6 +55,11 @@ def stream_view_containing_react_components(template:, close_stream_at_end: true
         # View may contain extra newlines, chunk already contains a newline
         # Having multiple newlines between chunks causes hydration errors
         # So we strip extra newlines from the template string and add a single newline
+        # `formats: [:text]` causes render_to_string to set response.content_type
+        # to `text/plain`; override it here before the first stream write, which
+        # is when ActionController::Live commits headers. render_to_string itself
+        # never writes to response.stream, so this assignment is always safe.
+        response.content_type = content_type if content_type
         response.stream.write(template_string)
 
         drain_streams_concurrently(parent_task)
@@ -120,5 +132,19 @@ def log_client_disconnect(context, exception)
         "[React on Rails Pro] Client disconnected during streaming (#{context}): #{exception.class}"
       end
     end
+
+    def warn_on_non_html_formats_without_content_type(formats, content_type)
+      return if content_type.present?
+
+      requested_formats = Array(formats).compact.map(&:to_sym)
+      return if requested_formats.empty? || requested_formats.all?(:html)
+
+      Rails.logger.warn(
+        "[React on Rails Pro] stream_view_containing_react_components received non-HTML formats " \
+        "#{requested_formats.inspect} without `content_type:`. Rails will commit the format-derived " \
+        "MIME type (for example `text/plain` for `:text`). Pass `content_type:` explicitly when " \
+        "streaming non-HTML responses."
+      )
+    end
   end
 end

react_on_rails_pro/lib/react_on_rails_pro/concerns/stream.rb

@@ -7,8 +7,10 @@ class Engine < Rails::Engine
     LICENSE_URL = "https://www.shakacode.com/react-on-rails-pro/"
     # TODO: Remove this legacy migration warning path after 16.5.0 stable release (target: 2026-05-31).
     LEGACY_LICENSE_FILE = "config/react_on_rails_pro_license.key"
+    RSC_STREAMING_MIDDLEWARE_WARNING_TARGETS = ["Rack::Deflater"].freeze
     private_constant :LICENSE_URL
     private_constant :LEGACY_LICENSE_FILE
+    private_constant :RSC_STREAMING_MIDDLEWARE_WARNING_TARGETS
 
     initializer "react_on_rails_pro.routes" do
       ActionDispatch::Routing::Mapper.include ReactOnRailsPro::Routes
@@ -20,6 +22,10 @@ class Engine < Rails::Engine
       config.after_initialize { ReactOnRailsPro::Engine.log_license_status }
     end
 
+    initializer "react_on_rails_pro.check_rsc_streaming_middleware" do
+      config.after_initialize { ReactOnRailsPro::Engine.log_rsc_streaming_middleware_warning }
+    end
+
     class << self
       def log_license_status
         status = ReactOnRailsPro::LicenseValidator.license_status
@@ -40,6 +46,24 @@ def log_license_status
         end
       end
 
+      def log_rsc_streaming_middleware_warning
+        return unless ReactOnRailsPro.configuration.enable_rsc_support
+        return if Rails.env.test?
+
+        middleware_names = middleware_stack_names
+        problematic = RSC_STREAMING_MIDDLEWARE_WARNING_TARGETS & middleware_names
+        return if problematic.empty?
+
+        route_path = ReactOnRailsPro.configuration.rsc_payload_generation_url_path
+        Rails.logger.warn(
+          "[React on Rails Pro] React Server Components support is enabled and the middleware " \
+          "stack includes #{problematic.join(', ')}. Compression and other response-transforming " \
+          "middleware can interfere with ActionController::Live NDJSON streaming. If your " \
+          "`#{route_path}` payload route is not already exempt, consider bypassing " \
+          "#{problematic.join(', ')} for that endpoint if you see stalled or corrupted RSC payloads."
+        )
+      end
+
       private
 
       def log_valid_license
@@ -105,6 +129,40 @@ def log_legacy_license_migration_notice
           Rails.logger.info message
         end
       end
+
+      def middleware_stack_names
+        middleware_stack = Rails.application&.middleware
+        return [] unless middleware_stack
+
+        entries =
+          if middleware_stack.respond_to?(:middlewares)
+            middleware_stack.middlewares
+          elsif middleware_stack.respond_to?(:to_a)
+            middleware_stack.to_a
+          else
+            Array(middleware_stack)
+          end
+
+        entries.filter_map { |entry| middleware_entry_name(entry) }.uniq
+      end
+
+      def middleware_entry_name(entry)
+        candidate =
+          if entry.respond_to?(:klass) && entry.klass
+            entry.klass
+          elsif entry.is_a?(Array)
+            entry.first
+          else
+            entry
+          end
+
+        case candidate
+        when Module
+          candidate.name
+        else
+          candidate.to_s.presence
+        end
+      end
     end
   end
 end

react_on_rails_pro/lib/react_on_rails_pro/engine.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe "RSC payload endpoint" do
+  def request_rsc_payload
+    get "/rsc_payload/RscEchoProps", params: { props: { message: "hello" }.to_json }
+  end
+
+  def parsed_chunks
+    response.body.each_line.filter_map do |line|
+      stripped_line = line.strip
+      next if stripped_line.empty?
+
+      begin
+        JSON.parse(stripped_line)
+      rescue JSON::ParserError => e
+        raise "Rails view annotation leaked into RSC payload response: #{stripped_line.inspect}" \
+          if stripped_line.include?("<!--")
+
+        raise "Non-JSON line in RSC payload response: #{stripped_line.inspect} (#{e.message})"
+      end
+    end
+  end
+
+  def expect_valid_rsc_payload_response
+    expect(response).to have_http_status(:ok)
+    expect(response.media_type).to eq("application/x-ndjson")
+
+    chunks = parsed_chunks
+
+    expect(chunks).not_to be_empty
+    html_chunk_message =
+      "Expected at least one RSC chunk to contain an 'html' key, got: #{chunks.inspect}"
+    expect(chunks.any? { |chunk| chunk.key?("html") }).to be(true), html_chunk_message
+  end
+
+  def render_annotated_html_inline_template
+    ApplicationController.render(inline: "<p>hello</p>", type: :erb, layout: false, formats: [:html])
+  end
+
+  it "returns parseable NDJSON without view annotation comments" do
+    request_rsc_payload
+    expect_valid_rsc_payload_response
+  end
+
+  it "returns parseable NDJSON when view annotation comments are enabled" do
+    allow(ActionView::Base).to receive(:annotate_rendered_view_with_filenames).and_return(true)
+
+    # Rails annotation comment format verified against Rails 7.x.
+    # If this assertion fails after a Rails upgrade, check ActionView annotation output.
+    annotated = nil
+    expect { annotated = render_annotated_html_inline_template }.not_to raise_error
+    expect(annotated).to include(
+      "<!--"
+    ), "Rails annotation comment format may have changed - check ActionView annotation output."
+
+    request_rsc_payload
+
+    expect_valid_rsc_payload_response
+  end
+end

react_on_rails_pro/spec/dummy/spec/requests/rsc_payload_spec.rb

@@ -291,4 +291,75 @@
       end
     end
   end
+
+  describe ".log_rsc_streaming_middleware_warning" do
+    def build_application(*middleware_klasses)
+      middleware_entry_class = Struct.new(:klass)
+      middleware_stack_class = Struct.new(:middlewares)
+      rails_application_class = Struct.new(:middleware)
+      middleware_entries = middleware_klasses.map { |klass| middleware_entry_class.new(klass) }
+
+      rails_application_class.new(middleware_stack_class.new(middleware_entries))
+    end
+
+    def build_rsc_configuration(enable_rsc_support:, route_path: "rsc_payload/")
+      instance_double(
+        ReactOnRailsPro::Configuration,
+        enable_rsc_support: enable_rsc_support,
+        rsc_payload_generation_url_path: route_path
+      )
+    end
+
+    it "logs a startup warning when RSC support is enabled with Rack::Deflater in development" do
+      allow(Rails).to receive_messages(
+        application: build_application(Rack::Deflater),
+        env: ActiveSupport::StringInquirer.new("development")
+      )
+      allow(ReactOnRailsPro).to receive(:configuration)
+        .and_return(build_rsc_configuration(enable_rsc_support: true))
+
+      expect(mock_logger).to receive(:warn).with(a_string_including("Rack::Deflater", "rsc_payload/"))
+
+      described_class.log_rsc_streaming_middleware_warning
+    end
+
+    it "does not log a warning when no known streaming hazard is present" do
+      allow(Rails).to receive_messages(
+        application: build_application(ActionDispatch::Executor),
+        env: ActiveSupport::StringInquirer.new("development")
+      )
+      allow(ReactOnRailsPro).to receive(:configuration)
+        .and_return(build_rsc_configuration(enable_rsc_support: true))
+
+      expect(mock_logger).not_to receive(:warn)
+
+      described_class.log_rsc_streaming_middleware_warning
+    end
+
+    it "does not log a warning when RSC support is disabled" do
+      allow(Rails).to receive_messages(
+        application: build_application(Rack::Deflater),
+        env: ActiveSupport::StringInquirer.new("development")
+      )
+      allow(ReactOnRailsPro).to receive(:configuration)
+        .and_return(build_rsc_configuration(enable_rsc_support: false))
+
+      expect(mock_logger).not_to receive(:warn)
+
+      described_class.log_rsc_streaming_middleware_warning
+    end
+
+    it "does not log a warning in test" do
+      allow(Rails).to receive_messages(
+        application: build_application(Rack::Deflater),
+        env: ActiveSupport::StringInquirer.new("test")
+      )
+      allow(ReactOnRailsPro).to receive(:configuration)
+        .and_return(build_rsc_configuration(enable_rsc_support: true))
+
+      expect(mock_logger).not_to receive(:warn)
+
+      described_class.log_rsc_streaming_middleware_warning
+    end
+  end
 end

react_on_rails_pro/spec/react_on_rails_pro/engine_spec.rb

@@ -376,9 +376,11 @@ def render_to_string(**_opts)
   end
 
   describe "Component streaming concurrency" do
-    def run_stream(controller, template: "ignored")
+    def run_stream(controller, template: "ignored", **options)
       Sync do |parent|
-        parent.async { controller.stream_view_containing_react_components(template: template) }
+        parent.async do
+          controller.stream_view_containing_react_components(template: template, **options)
+        end
         yield(parent)
       end
     end
@@ -390,6 +392,7 @@ def setup_stream_test(component_count: 2)
       mocked_response = instance_double(ActionController::Live::Response)
       mocked_stream = instance_double(ActionController::Live::Buffer)
       allow(mocked_response).to receive(:stream).and_return(mocked_stream)
+      allow(mocked_response).to receive(:content_type=)
       allow(mocked_stream).to receive(:write)
       allow(mocked_stream).to receive(:close)
       allow(mocked_stream).to receive(:closed?).and_return(false)
@@ -491,6 +494,30 @@ def setup_stream_test(component_count: 2)
       expect(gaps.all? { |gap| gap >= 0.04 }).to be true
     end
 
+    it "warns when non-HTML formats are streamed without an explicit content type" do
+      _queues, controller, _stream = setup_stream_test(component_count: 0)
+      mock_logger = instance_double(Logger, warn: nil)
+      allow(Rails).to receive(:logger).and_return(mock_logger)
+
+      expect(mock_logger).to receive(:warn).with(/non-HTML formats \[:text\].*without `content_type:`/)
+
+      run_stream(controller, formats: [:text]) do |_parent|
+        sleep 0.1
+      end
+    end
+
+    it "does not warn when non-HTML formats provide an explicit content type" do
+      _queues, controller, _stream = setup_stream_test(component_count: 0)
+      mock_logger = instance_double(Logger, warn: nil)
+      allow(Rails).to receive(:logger).and_return(mock_logger)
+
+      expect(mock_logger).not_to receive(:warn)
+
+      run_stream(controller, formats: [:text], content_type: "application/x-ndjson") do |_parent|
+        sleep 0.1
+      end
+    end
+
     describe "client disconnect handling" do
       it "stops writing on IOError" do
         queues, controller, stream = setup_stream_test(component_count: 1)