ruact 0.0.20 → 0.0.22

data/lib/ruact/client_manifest.rb

@@ -37,7 +37,19 @@ module Ruact
   # existing manifest + reader is unaffected). {#contract_for} reads it for the
   # Story 13.5 preprocess-time call-site validator; +nil+ means "no contract →
   # no validation" (fail open).
+  #
+  # Story 19-3 — the Vite plugin also records which ruact built the page's
+  # JavaScript, under a key no component can have (a component's is PascalCase
+  # or +folder/_snake+):
+  #
+  #   "__ruact__": { "version": "0.0.22" }
+  #
+  # {#build_version} reads it; it is not a component, for any lookup. A manifest
+  # written by 0.0.21 or before has no such key.
   class ClientManifest
+    # The manifest key of the build's record (Story 19-3).
+    BUILD_KEY = "__ruact__"
+
     # The +chunks+ of every import row (see {#resolve}). One shared frozen
     # array: a render resolves each component once, and the allocation guard
     # counts every array.
@@ -129,6 +141,13 @@ module Ruact
       entry && entry["contract"]
     end
 
+    # Story 19-3 — the ruact version whose Vite plugin wrote this manifest, or
+    # +nil+ when it records none (a build by 0.0.21 or before, or a plugin that
+    # could not read its gem's version).
+    #
+    # @return [String, nil]
+    attr_reader :build_version
+
     # Load from a file path (JSON).
     # Pre-warms the reference cache and freezes the manifest so it cannot be
     # mutated at runtime (AC#5). Pre-warming is required because Ruby's freeze
@@ -138,7 +157,7 @@ module Ruact
       raw      = File.read(path)
       data     = JSON.parse(raw)
       manifest = from_hash(data)
-      data.each_key { |name| manifest.reference_for(name) }
+      data.each_key { |name| manifest.reference_for(name) unless name == BUILD_KEY }
       manifest.freeze
     end
 
@@ -147,9 +166,16 @@ module Ruact
     # first-lookup path works even when +data+ is empty (otherwise
     # +reference_for+ would raise +FrozenError+ trying to memoize on a
     # frozen instance).
+    #
+    # Story 19-3 — the build's record ({BUILD_KEY}) is taken out of the entries
+    # (without changing the Hash given) and kept as {#build_version}.
     def self.from_hash(data)
       manifest = new
+      recorded = data.is_a?(Hash) && data.key?(BUILD_KEY)
+      build = data[BUILD_KEY] if recorded
+      data = data.except(BUILD_KEY) if recorded
       manifest.instance_variable_set(:@data, data)
+      manifest.instance_variable_set(:@build_version, build.is_a?(Hash) ? build["version"]&.to_s : nil)
       manifest.instance_variable_set(:@reference_cache, {})
       manifest
     end

data/lib/ruact/controller/delivery.rb

@@ -18,15 +18,21 @@ module Ruact
 
       include DocumentRendering
 
-      # The headers of a Flight body written row by row: no caching, and no
+      # The headers of a Flight body written row by row: not stored, and no
       # buffering by a proxy that honours `X-Accel-Buffering` (nginx).
+      # `no-store`, not `no-cache` (Story 19-2): a response the browser may
+      # store holds its cache entry while it streams, and Chrome then holds a
+      # second request for the same URL — a `revalidate()`, the same link
+      # clicked again — until the first one ends.
       STREAM_HEADERS = {
         "Content-Type" => "#{RequestKind::FLIGHT_MIME}; charset=utf-8",
-        "Cache-Control" => "no-cache",
+        "Cache-Control" => "no-store",
         "X-Accel-Buffering" => "no"
       }.freeze
 
-      # The same, for a document written in parts.
+      # The same, for a document written in parts — `no-cache`: `no-store`
+      # would keep the page out of the browser's back/forward cache, and the
+      # router stops a document it leaves while it still loads.
       DOCUMENT_STREAM_HEADERS = {
         "Content-Type" => "text/html; charset=utf-8",
         "Cache-Control" => "no-cache",
@@ -48,6 +54,13 @@ module Ruact
       # pushed before it, as they are ready.
       BODY_CLOSE = "</body>"
 
+      # Story 19-2 — written around the pushed rows of a streamed document, so
+      # the client router knows a document still loading has rows to come: it
+      # stops such a document when it leaves the page, and only such a one (a
+      # document that is still being parsed, its rows all in, is left alone).
+      STREAMING_OPEN = "(self.__FLIGHT_DATA=self.__FLIGHT_DATA||[]).streaming=true"
+      STREAMING_DONE = "self.__FLIGHT_DATA.streaming=false"
+
       private
 
       # Build the wire output and write it to the response. Nothing is written
@@ -86,9 +99,9 @@ module Ruact
 
         document = ruact_document_html(shell)
         cut = document.rindex(BODY_CLOSE) || document.length
-        __ruact_stream(run, DOCUMENT_STREAM_HEADERS, document[0...cut], document[cut..]) do |rows|
-          __ruact_flight_push(rows)
-        end
+        open = "<script#{__ruact_nonce_attr}>"
+        __ruact_stream(run, DOCUMENT_STREAM_HEADERS, "#{document[0...cut]}#{open}#{STREAMING_OPEN}</script>",
+                       "#{open}#{STREAMING_DONE}</script>#{document[cut..]}") { |rows| __ruact_flight_push(rows, open) }
       end
 
       # Writes +first+, then each boundary's rows (through the block, when given),
@@ -97,6 +110,8 @@ module Ruact
       # not sent stays pending, for the browser's transport to label.
       def __ruact_stream(run, headers, first, last = nil)
         headers.each { |name, value| response.headers[name] = value }
+        Streaming.keep_unbuffered(response.headers)
+        @__ruact_streamed = true
         stream = response.stream
         begin
           stream.write(first)
@@ -122,9 +137,9 @@ module Ruact
       # One boundary's rows, as the script a streamed document carries them in:
       # pushed onto the queue the bootstrap reads. Written as
       # {InlineScript.string_literal} writes it — no byte of the payload can
-      # close the `<script>`.
-      def __ruact_flight_push(rows)
-        "<script>(self.__FLIGHT_DATA=self.__FLIGHT_DATA||[]).push(#{InlineScript.string_literal(rows)})</script>"
+      # close the `<script>`. +open+ carries the request's CSP nonce, if any.
+      def __ruact_flight_push(rows, open = "<script>")
+        "#{open}(self.__FLIGHT_DATA=self.__FLIGHT_DATA||[]).push(#{InlineScript.string_literal(rows)})</script>"
       end
 
       # Story 19-1 (D4) — has the client closed its end? Asked before each

data/lib/ruact/controller/streaming.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module Ruact
   module Controller
     # Story 19-1 (ADR D6, option A) — which actions send their page as it
@@ -110,6 +112,60 @@ module Ruact
         end
       end
 
+      # Story 19-2 (AC20) — said once per process, in every environment: an
+      # action declared with `ruact_streaming` got a request over HTTP/1.0, so
+      # Live gave it an ordinary response and the page was sent whole. nginx
+      # talks HTTP/1.0 to its upstream unless told otherwise, so in production
+      # this is a proxy's configuration, found here or not at all.
+      UNSTREAMED = "%<action>s streams (ruact_streaming or ActionController::Live), but Live gave it an " \
+                   "ordinary response — a request over HTTP/1.0 — so the page was sent whole, not " \
+                   "streamed. Behind nginx, set `proxy_http_version 1.1;` where it proxies to the app. " \
+                   "(Rack::Test and controller tests get an ordinary response too.) (Said once.)"
+
+      # Logs {UNSTREAMED} the first time an action that streams could not.
+      #
+      # @api private
+      # @param controller [ActionController::Metal]
+      # @return [void]
+      def self.note_unstreamed(controller)
+        return if @unstreamed_noted
+
+        @unstreamed_noted = true
+        action = "#{controller.class.name}##{controller.action_name}"
+        controller.logger&.warn("[ruact] #{format(UNSTREAMED, action: action)}")
+        nil
+      end
+
+      # Forgets that it logged (specs).
+      #
+      # @api private
+      def self.reset_unstreamed_note!
+        @unstreamed_noted = false
+      end
+
+      # Story 19-2 (AC19.3) — Rack 2's `Rack::ETag` digests a 200 body unless
+      # the response has an `ETag` or a `Last-Modified`, reading it whole first
+      # (`Cache-Control: no-cache` does not stop it): a page that streams was
+      # held until its last `<Suspense>`. Measured with Rack 2.2.24. A weak ETag
+      # of its own, new for every response, so that no `If-None-Match` ever
+      # matches it. Rack 3 leaves a body it cannot hold in memory alone.
+      RACK_ETAG_BUFFERS = Gem::Version.new(::Rack.release) < Gem::Version.new("3")
+
+      # Sets that ETag on +headers+ when the app runs on Rack 2 — unless the
+      # action set its own validator (`fresh_when`), which already keeps
+      # `Rack::ETag` away and which conditional GET needs.
+      #
+      # @api private
+      # @param headers [Hash, ActionDispatch::Response::Headers]
+      # @return [void]
+      def self.keep_unbuffered(headers)
+        return unless RACK_ETAG_BUFFERS
+        return if headers.key?("ETag") || headers.key?("Last-Modified")
+
+        headers["ETag"] = %(W/"ruact-stream-#{SecureRandom.hex(8)}")
+        nil
+      end
+
       # Includes `ActionController::Live` in +controller+ for `ruact_streaming`,
       # marked as ruact's doing so {LiveInclusion} does not take it for the app's.
       #
@@ -221,6 +277,14 @@ module Ruact
       # support runs Live inline).
       def process_action(*)
         super
+      rescue StandardError => e
+        # Story 19-2 (AC6) — raised once the page was sent (an `after_action`):
+        # Live only logs what is raised after the response started, so the
+        # app's error reporting would never hear of it.
+        if @__ruact_streamed && defined?(Rails) && Rails.respond_to?(:error)
+          Rails.error.report(e, handled: false, severity: :error, source: "ruact.stream")
+        end
+        raise
       ensure
         __ruact_check_writes_after_stream
         __ruact_release_connections if __ruact_on_live_thread?

data/lib/ruact/controller.rb

@@ -92,7 +92,7 @@ module Ruact
     # are only ever invoked internally by `ruact_html_shell`; the others only
     # by templates).
     private :ruact_js_assets, :ruact_head_assets, :__ruact_component__, :__ruact_component_open__,
-            :__ruact_suspense__
+            :__ruact_suspense__, :__ruact_nonce_attr
 
     # Resolves the manifest for this render. In PRODUCTION this is the boot-time
     # cached +Ruact.manifest+ (set by Railtie#config.to_prepare) — no per-request
@@ -106,6 +106,15 @@ module Ruact
       ManifestResolver.resolve
     end
 
+    # Story 19-3 — {BuildSkew.note} for the manifest this render resolved: the
+    # message when its build is another ruact's (logged once per version),
+    # else nil.
+    def __ruact_build_skew(manifest)
+      return unless manifest.respond_to?(:build_version)
+
+      BuildSkew.note(manifest.build_version, logger: logger)
+    end
+
     # Only activate RSC rendering when the matching .html.erb template exists AND
     # the client will accept an HTML response (AC FR26; Story 10.0).
     # `request.format.html?` is false for a `*/*` wildcard (curl/bots/
@@ -177,16 +186,23 @@ module Ruact
       # its headers on the first row.
       self.status = status if status
 
-      pipeline  = RenderPipeline.new(ruact_manifest,
-                                     controller_path: controller_path, logger: logger,
-                                     development: Flight::Renderer.development_default)
+      manifest = ruact_manifest
+      # Story 19-3 — in development, the page says loudly when its JavaScript
+      # was built by another ruact (`ruact_js_assets` reads this). The manifest
+      # this render resolved anyway: no other request to the Vite dev server.
+      @ruact_build_skew = __ruact_build_skew(manifest) if Rails.env.development?
+      pipeline = RenderPipeline.new(manifest,
+                                    controller_path: controller_path, logger: logger,
+                                    development: Flight::Renderer.development_default)
       # Story 19-1 — in an action that streams, the first load and a
       # navigation alike, each `<Suspense>`'s content renders after the shell
       # is sent: the view keeps its blocks instead of running them. Only when
       # the response really is Live's: on HTTP/1.0 (nginx's default to its
       # upstream) Live gives an ordinary response, which the server sends as
       # soon as anything is written — the page then renders whole, in place.
-      streaming = self.class.ruact_streaming?(action_name) && response.is_a?(ActionController::Live::Response)
+      declared = self.class.ruact_streaming?(action_name)
+      streaming = declared && response.is_a?(ActionController::Live::Response)
+      Streaming.note_unstreamed(self) if declared && !streaming
 
       # Allocate a per-render context and expose it to the view via a normal
       # (non-`@_`-prefixed) instance variable on the controller. Rails 8's

data/lib/ruact/declared_content.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Story 19-2 (AC10) — in development, `content_for`/`provide` inside a
+  # `<Suspense>` that runs after the shell is an error of that block: the layout
+  # was sent before the block ran, so nothing it declares shows. What the view
+  # had declared is taken before the block and compared after.
+  #
+  # Internal API: not part of the public compatibility contract.
+  module DeclaredContent
+    # What +view+ has declared so far, or nil when it keeps no record.
+    def self.take(view)
+      return nil unless view.respond_to?(:view_flow) && view.view_flow.respond_to?(:content)
+
+      # Copies: the record keeps a SafeBuffer per name, which `content_for`
+      # appends to in place (and whose `to_s` is itself).
+      view.view_flow.content.transform_values { |content| String.new(content.to_s) }
+    end
+
+    # Raises when +view+ declared more than +before+. A name only read
+    # (`content_for?`, `yield :name`) appears in the record empty: Rails'
+    # record defaults every name it is asked for to "".
+    def self.check!(view, before)
+      after = view.view_flow.content
+      changed = after.keys.reject { |name| name == :layout || after[name].to_s == before.fetch(name, "") }
+      return if changed.empty?
+
+      raise Ruact::Error,
+            "#{changed.map { |name| "content_for :#{name}" }.join(', ')} inside a <Suspense> runs after the " \
+            "layout was sent, so the layout never shows it. Move it outside the <Suspense>."
+    end
+  end
+end

data/lib/ruact/deferred_render.rb

@@ -99,14 +99,24 @@ module Ruact
     def content(element)
       return element unless element.is_a?(Flight::DeferredContent)
 
-      block = @render_context.block(element.index)
+      block = @render_context.block(element.key)
+      raise Ruact::Error, Flight::DeferredContent::STALE if block.nil?
+
       html = @guard ? @guard.call { evaluate(block) } : evaluate(block)
       convert(html)
     end
 
-    # Runs the block in its view, with the template path restored, and returns
-    # what it wrote. Only what it writes: a value it ends on is not content.
+    # Runs the block in its view, with the template path and its local
+    # variables as they were when the tag was met, and returns what it wrote.
+    # Only what it writes: a value it ends on is not content.
     def evaluate(pending)
+      declared = DeclaredContent.take(pending.view) if @development
+      html = with_locals(pending.block, pending.locals) { run_in_view(pending) }
+      DeclaredContent.check!(pending.view, declared) if declared
+      html
+    end
+
+    def run_in_view(pending)
       pending.view.instance_exec(pending) do |entry|
         saved = [@virtual_path, @current_template]
         @virtual_path = entry.virtual_path
@@ -122,6 +132,22 @@ module Ruact
       end
     end
 
+    # Sets the block's local variables to +locals+ while it runs, and back
+    # after. A block shares them with the template and with the blocks met
+    # after it.
+    def with_locals(block, locals)
+      return yield if locals.nil? || locals.empty?
+
+      scope = block.binding
+      now = locals.keys.to_h { |name| [name, scope.local_variable_get(name)] }
+      locals.each { |name, value| scope.local_variable_set(name, value) }
+      begin
+        yield
+      ensure
+        now.each { |name, value| scope.local_variable_set(name, value) }
+      end
+    end
+
     # The components registered since the last conversion are resolved and
     # added: a block registers its own as it runs. One the manifest cannot
     # resolve fails this conversion and keeps its place (nil), so the next
@@ -153,16 +179,31 @@ module Ruact
       raise Expired, "the delay (#{delay}s) is longer than suspense_timeout" if delay && delay > limit
 
       started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      # A query still running at the limit is cancelled on the server, so its
+      # connection is free again (Story 19-2, QueryWatch).
+      owner = QueryWatch.current_owner
+      watch = QueryWatch.start(owner, limit)
       begin
         Timeout.timeout(limit) { wait_then(delay, &) }
-      rescue Timeout::Error => e
-        # Ours only when the limit has passed; earlier, it is the content's.
-        raise if Process.clock_gettime(Process::CLOCK_MONOTONIC) - started < limit
+      rescue StandardError => e
+        raise unless expired?(e, started, limit, watch)
 
+        watch&.cancel_now(owner)
         raise Expired, "ran past suspense_timeout (#{limit}s)", cause: e
+      ensure
+        watch&.stop
       end
     end
 
+    # A `Timeout::Error` is ours only when the limit has passed; earlier, it is
+    # the content's. Any other error is ours when the watch cancelled a query
+    # at the limit: what the cancelled query raised.
+    def expired?(error, started, limit, watch)
+      return watch&.cancelled? || false unless error.is_a?(Timeout::Error)
+
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) - started >= limit
+    end
+
     def wait_then(delay)
       sleep(delay) if delay&.positive?
       yield
@@ -181,11 +222,16 @@ module Ruact
       payload
     end
 
-    # React's development client reads `stack` as `[function, file, line, column]`.
+    # React's development client reads each frame of `stack` as
+    # `[function, file, line, column, enclosing line, enclosing column]` and
+    # rebuilds the server's call stack from it. A four-element frame (what this
+    # sent before Story 19-2) left the last two undefined, and every frame came
+    # out at line 2. Ruby has no column and no enclosing function: column 1,
+    # enclosing 0 (none).
     def development_stack(error)
       Array(error.backtrace).first(STACK_FRAMES).filter_map do |frame|
         match = frame.match(/\A(.+?):(\d+)(?::in [`'](.+)')?\z/)
-        match && [match[3] || "(ruby)", match[1], Integer(match[2], 10), 0]
+        match && [match[3] || "(ruby)", match[1], Integer(match[2], 10), 1, 0, 0]
       end
     end
 
@@ -201,7 +247,7 @@ module Ruact
       element = boundary[:element]
       return "" unless element.is_a?(Flight::DeferredContent)
 
-      location = @render_context.block(element.index).location
+      location = @render_context.block(element.key)&.location
       location ? " at #{location.path}:#{location.lineno}" : ""
     end
   end

data/lib/ruact/doctor.rb

@@ -145,14 +145,25 @@ module Ruact
 
     private
 
+    # Story 19-3 — the manifest also says which ruact built the JavaScript; a
+    # build by another one (or by one that recorded none, 0.0.21 and before)
+    # fails: the page then runs another release's runtime against this server.
     def check_manifest
       path = manifest_path
-      if Pathname(path).exist?
-        [:pass, "Manifest found at #{path}"]
-      else
-        [:fail, "Manifest not found — run vite build",
-         "Run vite build (or bin/dev) to generate the client manifest."]
+      unless Pathname(path).exist?
+        return [:fail, "Manifest not found — run vite build",
+                "Run vite build (or bin/dev) to generate the client manifest."]
       end
+
+      built = ClientManifest.from_hash(JSON.parse(File.read(path))).build_version
+      return [:pass, "Manifest found at #{path} (built by ruact #{built})"] unless BuildSkew.skewed?(built)
+
+      by = built ? "ruact #{built}" : "a ruact that did not record its version (0.0.21 or before)"
+      [:fail, "Manifest at #{path} was built by #{by}; this app runs ruact #{Ruact::VERSION}",
+       BuildSkew.remedy(Rails.root)]
+    rescue JSON::ParserError => e
+      [:fail, "Manifest at #{path} is not valid JSON (#{e.message.lines.first.strip})",
+       "Rebuild it: run vite build (or bin/dev)."]
     end
 
     def check_vite
@@ -484,7 +495,30 @@ module Ruact
     def check_streaming
       mode  = Ruact.streaming_mode || :buffered
       label = mode == :enabled ? "enabled" : "buffered"
-      [:pass, "streaming: #{label} (#{streaming_server_hint})"]
+      message = "streaming: #{label} (#{streaming_server_hint})"
+      declaring = streaming_controllers.length
+      return [:pass, message] if declaring.zero?
+
+      # Story 19-2 (AC20) — the doctor sees no request: what it can say is
+      # where a page that streams silently does not.
+      [:pass, "#{message}; #{pluralize_count(declaring, 'controller')} #{declaring == 1 ? 'streams' : 'stream'} " \
+              "(ruact_streaming or ActionController::Live) — behind a proxy, the app must be reached over " \
+              "HTTP/1.1 (nginx: `proxy_http_version 1.1;`), or those pages are sent whole",
+       PROXY_HTTP11]
+    end
+
+    # Story 19-2 (AC20) — what makes a proxy talk HTTP/1.1 to the app.
+    PROXY_HTTP11 = "Behind nginx, set `proxy_http_version 1.1;` where it proxies to the app: by default it " \
+                   "talks HTTP/1.0 upstream, and a page declared with ruact_streaming is then sent whole " \
+                   "(the app logs it once)."
+    private_constant :PROXY_HTTP11
+
+    # Controller files that declare `ruact_streaming` or include
+    # `ActionController::Live`. Reads source, as {#island_controllers} does.
+    def streaming_controllers
+      Dir.glob(Rails.root.join("app", "controllers", "**", "*.rb").to_s).select do |file|
+        File.read(file).match?(/^\s*(ruact_streaming\b|include\s+ActionController::Live\b)/)
+      end
     end
 
     # Story 19-1 (ADR D1) — whether `load_async` runs its query in the

data/lib/ruact/erb_preprocessor.rb

@@ -14,7 +14,7 @@ module Ruact
   #   <%= __ruact_component__("LikeButton", { "postId" => @post.id, "initialCount" => 5 }) %>
   #
   # The placeholder is replaced by an HTML comment with a unique token:
-  #   <!-- __RUACT_0__ -->
+  #   <!-- __RUACT_a1b2c3d4_0__ -->
   #
   # A component with children (Story 18-2) keeps its content as ERB, inside a
   # wrapper element HtmlConverter turns into the component's `children`:
@@ -399,7 +399,13 @@ module Ruact
       props_ruby = pairs.map { |prop, expr| "#{prop.inspect} => #{expr}" }.join(", ")
       props_hash = props_ruby.empty? ? "{}" : "{ #{props_ruby} }"
       helper = kind == :self_closing ? "__ruact_component__" : "__ruact_component_open__"
-      %(<%= #{helper}(#{name.inspect}, #{props_hash}) %>)
+      # Story 19-2 — a tag written over several lines keeps them, so every
+      # line below it is still the template's own in an error and a backtrace
+      # (the props' own code carries the line breaks it has). Nothing is
+      # allocated for a tag on one line: the guard on allocations counts
+      # every component.
+      missing = match.count("\n") - props_hash.count("\n")
+      %(<%= #{helper}(#{name.inspect}, #{props_hash}) #{"\n" * missing if missing.positive?}%>)
     rescue ComponentContractError, ComponentTagError, UnknownComponentError
       # Already carry file:line and the fix — re-raise AS-IS (do NOT append the
       # generic "at line N: snippet" tail).

data/lib/ruact/flight/react_element.rb

@@ -31,14 +31,19 @@ module Ruact
     end
 
     # The content of a Suspense boundary that has not been rendered yet: the
-    # index of its block in the render context. The serializer never sees one —
+    # key of its block in the render context. The serializer never sees one —
     # it defers a boundary's children without looking at them, and the caller
     # of {Renderer#take_boundary} renders it.
     class DeferredContent
-      attr_reader :index
+      # Story 19-2 — what a boundary says when its marker came out of a `cache`
+      # block another render wrote: its content was never in the fragment.
+      STALE = "A <Suspense> inside `cache` was read from the cache, and its content is not in the " \
+              "cached fragment: put the <Suspense> outside the `cache` block (cache what is inside it)."
 
-      def initialize(index)
-        @index = index
+      attr_reader :key
+
+      def initialize(key)
+        @key = key
       end
     end
 

data/lib/ruact/flight/renderer.rb

@@ -85,8 +85,11 @@ module Ruact
       # a {DeferredContent} needs {#take_boundary}.
       def next_boundary(streaming:)
         boundary = take_boundary
+        # A block this render cannot run: its marker came out of a `cache`
+        # block a render that streamed wrote.
         if boundary[:element].is_a?(DeferredContent)
-          raise Ruact::Error, "ruact: Renderer#next_boundary cannot render a block; use #take_boundary"
+          return error_rows(boundary[:id],
+                            RowEmitter.error_payload(DeferredContent::STALE, digest: "ruact:suspense-error"))
         end
 
         if streaming && boundary[:delay]&.positive?

data/lib/ruact/html_converter.rb

@@ -8,7 +8,7 @@ module Ruact
   # Rules:
   # - HTML attributes → React equivalents (class→className, for→htmlFor, etc.)
   # - data-react-key="x" → becomes the React key on the element
-  # - HTML comments matching __RUACT_N__ tokens → replaced by client component refs
+  # - HTML comments matching __RUACT_<render>_<n>__ tokens → replaced by client component refs
   # - Text nodes → plain Ruby strings
   # - Multiple root nodes → wrapped in a Fragment (array)
   # rubocop:disable Metrics/ClassLength
@@ -35,6 +35,11 @@ module Ruact
       "spellcheck" => "spellCheck"
     }.freeze
 
+    # A client component's marker (`__RUACT_<render>_<n>__`, the render's id
+    # being eight hex digits, {RenderContext}), or one 0.0.20 and before wrote
+    # (`__RUACT_<n>__`), which a `cache` block may still hold.
+    TOKEN = /\A__RUACT_(?:\h{8}_)?\d+__\z/
+
     # Tags whose `value` attribute maps to React's `defaultValue` (uncontrolled).
     DEFAULT_VALUE_TAGS = %w[textarea select].freeze
 
@@ -167,7 +172,11 @@ module Ruact
         # Check if this is a Ruact component placeholder
         token = Markers.comment_token(node)
         entry = @registry[token]
-        return nil unless entry
+        unless entry
+          raise Ruact::HtmlConverterError, stale_component_message(token) if token.match?(TOKEN)
+
+          return nil
+        end
 
         Flight::ReactElement.new(
           type: entry[:ref],
@@ -200,7 +209,7 @@ module Ruact
     def convert_component_with_children(node)
       token = Markers.wrapper_token(node)
       entry = @registry[token]
-      raise Ruact::HtmlConverterError, "ruact: no component registered for #{token.inspect}" unless entry
+      raise Ruact::HtmlConverterError, stale_component_message(token) unless entry
 
       props = entry[:props]
       children = convert_children(node)
@@ -210,6 +219,15 @@ module Ruact
       Flight::ReactElement.new(type: entry[:ref], key: nil, props: props)
     end
 
+    # Story 19-2 — a marker this render did not write: it came out of a
+    # `cache` block, which stores a component's marker and not the component.
+    def stale_component_message(token)
+      "ruact: the page holds the marker of a client component (#{token}) that this render did not " \
+        "register — it came out of a `cache` block, which stores the component's marker but not the " \
+        "component. Move the client component outside the `cache` block (cache the HTML around it, or " \
+        "the data it is given)."
+    end
+
     def convert_suspense_element(node)
       fallback_text = Markers.suspense_fallback(node)
       fallback = if fallback_text.empty?

data/lib/ruact/markers.rb

@@ -8,14 +8,18 @@ module Ruact
   # Three markers:
   #
   # - a client component: an HTML comment holding the token its
-  #   {RenderContext} entry was registered under — `<!-- __RUACT_0__ -->`;
+  #   {RenderContext} entry was registered under — `<!-- __RUACT_a1b2c3d4_0__ -->`;
   # - a client component with children: an element wrapped around the
-  #   children's HTML — `<ruact-component data-ruact-token="__RUACT_0__">…`;
+  #   children's HTML — `<ruact-component data-ruact-token="__RUACT_a1b2c3d4_0__">…`;
   # - a Suspense boundary: an element wrapped around its content, carrying the
   #   fallback text and the optional delay —
   #   `<ruact-suspense data-ruact-fallback="Loading…">…</ruact-suspense>`. A
-  #   boundary whose content is rendered later is empty and carries the index
-  #   of its block in the {RenderContext} instead (`data-ruact-block="0"`).
+  #   boundary whose content is rendered later is empty and carries the key
+  #   of its block in the {RenderContext} instead (`data-ruact-block="a1b2c3d4-0"`).
+  #
+  # Every token and key carries the id of the render that wrote it, so a
+  # marker a `cache` block stored in another render is never taken for one of
+  # this render's.
   #
   # {ErbPreprocessor} writes the ERB that produces them, the view helpers
   # ({ViewHelper}, and {RenderPipeline} for a plain-ERB render) write the
@@ -49,7 +53,7 @@ module Ruact
     # attribute values as written in the template. Only `"` is escaped: the
     # rest of the text stays as the template wrote it (entities included, which
     # the HTML parser then decodes). The preprocessor refuses ERB in either.
-    # +block+ is the index of the boundary's content in the render context,
+    # +block+ is the key of the boundary's content in the render context,
     # when that content is rendered later.
     def self.suspense_open(fallback, delay, block: nil)
       delay_attr = delay ? %( #{DELAY_ATTR}="#{delay.gsub('"', '&quot;')}") : ""
@@ -72,11 +76,10 @@ module Ruact
       node[FALLBACK_ATTR] || ""
     end
 
-    # The index of the block a Suspense wrapper's content is rendered from
+    # The key of the block a Suspense wrapper's content is rendered from
     # later, or nil when the content is in the wrapper.
     def self.suspense_block(node)
-      value = node[BLOCK_ATTR]
-      value && Integer(value, 10)
+      node[BLOCK_ATTR]
     end
 
     # The delay of a Suspense wrapper, in seconds, or nil when it is absent,