Add cached_stream_react_component helper (#549)

Follow-up to #548  

### What  
- Introduces `cached_stream_react_component`, mirroring
`cached_react_component`:
  - Requires `cache_key` and `props` block (lazy props on HIT)  
  - Honors `:if` / `:unless` and `:cache_options` (TTL/compression)  
- Implements view-level streaming cache by decorating the fiber produced
by `stream_react_component`:
- **MISS**: call `stream_react_component` once, wrap its fiber to buffer
chunks and write-through to `Rails.cache`; return initial chunk
immediately
- **HIT**: read cached chunks; return initial chunk and push a replay
fiber for the remainder
- Preserves streaming semantics/formatting; no behavior change unless
the helper is used
- Adds/updates helper spec coverage to exercise MISS→HIT, skip,
invalidation, and TTL

### Why  
- Prerender caching keys by `js_code` digest (needs serialized props),
so it can’t lazily skip props
- View-level cache enables app-defined keys and true lazy props
evaluation on HIT, matching the non-stream helper’s ergonomics


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

* **New Features**
* Adds cached streaming for server-rendered React components to speed
repeat requests while preserving prerender/hydration behavior, honoring
existing cache controls, conditional caching, and instrumentation.
  * Adds a demo/test page and route for the cached streaming variant.

* **Tests**
* Expanded unit and system tests covering cache miss→hit flow,
write-through caching, invalidation on prop changes,
skip-prerender-cache, that props are not re-evaluated on hit, streaming
chunk ordering, and deterministic mocked streaming.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: ihabadham

app/helpers/react_on_rails_pro_helper.rb

@@ -91,14 +91,99 @@ def cached_react_component_hash(component_name, raw_options = {}, &block)
     end
   end
 
+  # Provide caching support for stream_react_component in a manner akin to Rails fragment caching.
+  # All the same options as stream_react_component apply with the following differences:
+  #
+  # 1. You must pass the props as a block. This is so that the evaluation of the props is not done
+  #    if the cache can be used.
+  # 2. Provide the cache_key option
+  #    cache_key: String or Array (or Proc returning a String or Array) containing your cache keys.
+  #    Since prerender is automatically set to true, the server bundle digest will be included in the cache key.
+  #    The cache_key value is the same as used for conventional Rails fragment caching.
+  # 3. Optionally provide the `:cache_options` key with a value of a hash including as
+  #    :compress, :expires_in, :race_condition_ttl as documented in the Rails Guides
+  # 4. Provide boolean values for `:if` or `:unless` to conditionally use caching.
+  def cached_stream_react_component(component_name, raw_options = {}, &block)
+    ReactOnRailsPro::Utils.with_trace(component_name) do
+      check_caching_options!(raw_options, block)
+      fetch_stream_react_component(component_name, raw_options, &block)
+    end
+  end
+
   if defined?(ScoutApm)
     include ScoutApm::Tracer
     instrument_method :cached_react_component, type: "ReactOnRails", name: "cached_react_component"
     instrument_method :cached_react_component_hash, type: "ReactOnRails", name: "cached_react_component_hash"
+    instrument_method :cached_stream_react_component, type: "ReactOnRails", name: "cached_stream_react_component"
   end
 
   private
 
+  def fetch_stream_react_component(component_name, raw_options, &block)
+    auto_load_bundle = ReactOnRails.configuration.auto_load_bundle || raw_options[:auto_load_bundle]
+
+    unless ReactOnRailsPro::Cache.use_cache?(raw_options)
+      return render_stream_component_with_props(component_name, raw_options, auto_load_bundle, &block)
+    end
+
+    # Compose a cache key consistent with non-stream helper semantics.
+    key_options = raw_options.merge(prerender: true)
+    view_cache_key = ReactOnRailsPro::Cache.react_component_cache_key(component_name, key_options)
+
+    # Attempt HIT without evaluating props block
+    if (cached_chunks = Rails.cache.read(view_cache_key)).is_a?(Array)
+      return handle_stream_cache_hit(component_name, raw_options, auto_load_bundle, cached_chunks)
+    end
+
+    # MISS: evaluate props lazily, stream live, and write-through to view-level cache
+    handle_stream_cache_miss(component_name, raw_options, auto_load_bundle, view_cache_key, &block)
+  end
+
+  def handle_stream_cache_hit(component_name, raw_options, auto_load_bundle, cached_chunks)
+    render_options = ReactOnRails::ReactComponent::RenderOptions.new(
+      react_component_name: component_name,
+      options: { auto_load_bundle: auto_load_bundle }.merge(raw_options)
+    )
+    load_pack_for_generated_component(component_name, render_options)
+
+    initial_result, *rest_chunks = cached_chunks
+    hit_fiber = Fiber.new do
+      rest_chunks.each { |chunk| Fiber.yield(chunk) }
+      nil
+    end
+    @rorp_rendering_fibers << hit_fiber
+    initial_result
+  end
+
+  def handle_stream_cache_miss(component_name, raw_options, auto_load_bundle, view_cache_key, &block)
+    # Kick off the normal streaming helper to get the initial result and the original fiber
+    initial_result = render_stream_component_with_props(component_name, raw_options, auto_load_bundle, &block)
+    original_fiber = @rorp_rendering_fibers.pop
+
+    buffered_chunks = [initial_result]
+    wrapper_fiber = Fiber.new do
+      while (chunk = original_fiber.resume)
+        buffered_chunks << chunk
+        Fiber.yield(chunk)
+      end
+      Rails.cache.write(view_cache_key, buffered_chunks, raw_options[:cache_options] || {})
+      nil
+    end
+    @rorp_rendering_fibers << wrapper_fiber
+    initial_result
+  end
+
+  def render_stream_component_with_props(component_name, raw_options, auto_load_bundle)
+    props = yield
+    options = raw_options.merge(
+      props: props,
+      prerender: true,
+      skip_prerender_cache: true,
+      auto_load_bundle: auto_load_bundle
+    )
+    stream_react_component(component_name, options)
+  end
+
   def check_caching_options!(raw_options, block)
     raise ReactOnRailsPro::Error, "Pass 'props' as a block if using caching" if raw_options.key?(:props) || block.nil?
 

spec/dummy/app/controllers/pages_controller.rb

@@ -41,6 +41,10 @@ def stream_async_components_for_testing
     stream_view_containing_react_components(template: "/pages/stream_async_components_for_testing")
   end
 
+  def cached_stream_async_components_for_testing
+    stream_view_containing_react_components(template: "/pages/cached_stream_async_components_for_testing")
+  end
+
   def rsc_posts_page_over_http
     stream_view_containing_react_components(template: "/pages/rsc_posts_page_over_http")
   end

spec/dummy/app/views/pages/cached_stream_async_components_for_testing.html.erb

@@ -0,0 +1,18 @@
+<%# Cached variant of the test page for streaming components %>
+<%
+  throw_sync = params[:throwSyncError]
+  throw_async = params[:throwAsyncError]
+%>
+<%= cached_stream_react_component(
+  "AsyncComponentsTreeForTesting",
+  cache_key: ["AsyncComponentsTreeForTesting", throw_sync, throw_async],
+  trace: true,
+  id: "AsyncComponentsTreeForTesting-react-component-0",
+) do
+  @app_props_server_render.merge(params.permit(:throwSyncError, :throwAsyncError))
+end %>
+<hr/>
+
+<h1>React Rails Server Streaming Server Rendered Async React Components Tree For Testing (Cached)</h1>
+
+

spec/dummy/config/routes.rb

@@ -23,6 +23,8 @@
   get "stream_async_components" => "pages#stream_async_components", as: :stream_async_components
   get "stream_async_components_for_testing" => "pages#stream_async_components_for_testing",
       as: :stream_async_components_for_testing
+  get "cached_stream_async_components_for_testing" => "pages#cached_stream_async_components_for_testing",
+      as: :cached_stream_async_components_for_testing
   get "stream_async_components_for_testing_client_render" => "pages#stream_async_components_for_testing_client_render",
       as: :stream_async_components_for_testing_client_render
   get "rsc_posts_page_over_http" => "pages#rsc_posts_page_over_http", as: :rsc_posts_page_over_http