ruact 0.0.20 → 0.0.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69c5f93d5a39e751e7f69b953ffd1101660e464df4397cadee932c12ba81b4fd
-  data.tar.gz: 518c3a0c1183cbc82fd13ca3d6d621502e28713b5d9dd21bd46beeca30ecc775
+  metadata.gz: e96181a35f53a1a25da4cd4db1ca655aeff15cdd5190f56aaafb97f1a2a19361
+  data.tar.gz: e9034d5a9f16dee7a5a319483364dbbf049a6b0aecf63073c3efcfe66ce6baa4
 SHA512:
-  metadata.gz: 115756074639ab4849ae2982cf7d4e13176f20f383302f8961b1ed5f09148e1bec74560f2e1f42ef2aa26262449d6c0536c89ce205748176bad9aa0f5006fbfb
-  data.tar.gz: c55a816d7f40810470e42f86f8111ae3fc2e1e4ab150a31153626c26dedb8de1f76166483acb004722239d1696626bbe0bef218237bb34b665da7320e7e200c2
+  metadata.gz: c90a2671ac0774bd51f726af1dc22ab58ba048ee6354b1078888ad2704289214caa6b6189b8909c72ab074546a37dc80676fb49576e630d09d1629eb09ff22ba
+  data.tar.gz: e71ea90b4a5ee1450fd5c772fe7a99c9641b5febb8465ea0e7649fc1ab00db670fcdd3333b34bffbcc870bb0d719deb9b236f40769e6277097f0a3cdaa0bc115

data/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.21] - 2026-10-15
+
+### Changed
+
+- **Leaving a page whose document is still arriving stops loading it.** A page that streams keeps its document open until its last `<Suspense>`; when the router leaves the page (a link, a form) before that, it now calls `window.stop()` first, so the connection closes and the server, which asks before each block, starts no further block for a page nobody will see. Only a document that streams and still has rows to come: the server marks it. Stopping it also stops what that document was still loading — measured in Chrome: an image still loading stays broken, a `fetch` in flight fails with `TypeError`, and a module `import()` in flight fails (importing it again works). The boundaries of the page being left stay quiet, as for a navigation that replaced another: no "response ended before the whole page arrived" error is reported for them. Only while the document itself is loading — a page that has finished is not touched. `revalidate()` stays on the page and does not stop it: stopping would fail the page's other requests in flight, a server function or a `useQuery` among them. When the navigation that stopped it ends without replacing the page — the network, a 403 or a 500 to a form, a redirect that fails, or a second click that superseded the first and failed — the router fetches the page it is still on again, once, so its boundaries do not keep their fallback.
+- **A link or Back/Forward to an `#anchor` of the page on screen is left to the browser.** The client router fetched and rendered the same page again for `/posts/1#comments` while on `/posts/1`; now the browser scrolls, nothing is fetched, and a page still streaming is not stopped. A link to another page with an anchor is the router's, as before.
+- **`content_for` inside a `<Suspense>` that runs later is an error of that boundary, in development.** The layout was sent before the block ran, so what it declared never showed. Reading (`content_for?`, `yield :name`) still works.
+- **The development overlay shows every `<Suspense>` that failed**, one under the other, instead of only the last; a click closes it, and the next failure opens it again.
+- **A streamed Flight response is `Cache-Control: no-store`** (it was `no-cache`). A response the browser may store holds its cache entry while it streams, and Chrome then held a second request for the same URL — `revalidate()` on a page still streaming, the same link clicked again — until the first one ended. The streamed document keeps `no-cache`, so the page can still enter the back/forward cache.
+
+- **An action declared with `ruact_streaming` that got a request over HTTP/1.0 now says so.** Live answers HTTP/1.0 with an ordinary response, so the page is sent whole — and nginx talks HTTP/1.0 to the app unless told `proxy_http_version 1.1;`, so in production a page that should stream silently did not. The app now logs a warning the first time it happens in the process, in every environment, naming the action and the nginx line (Rack::Test, in an app's request specs, speaks HTTP/1.0 too, so it shows there once). `rails ruact:doctor` (and `--json`) adds the same hint to its streaming check when a controller declares `ruact_streaming` or includes `ActionController::Live`.
+
+- **Every script ruact writes carries the request's CSP nonce.** An app whose Content Security Policy allows scripts by nonce (`config.content_security_policy_nonce_generator`, no `'unsafe-inline'`) blocked the inline `__FLIGHT_DATA` script, the development module that loads Vite, and — on a page that streams — each `<Suspense>`'s rows: the page never mounted, or its fallbacks never resolved. The nonce is now on all of them, and on the entry `<script src>`. Without a nonce generator not a byte changes. In development React's own Flight client tries `eval()` for its debugging features and goes on without it; a policy without `'unsafe-eval'` reports that refusal in development only.
+
+- **The `AGENTS.md` that `rails generate ruact:install` writes names what a `<Suspense>` that streams cannot hold.** Besides status, redirect, cookies, session and flash: `content_for`, and the locale, tenant or database role a middleware scopes (they belong in an `around_action`); and a `cache` block goes inside a `<Suspense>`, never around one.
+
+### Fixed
+
+- **On Rack 2, a page that streams was held until its last `<Suspense>`.** Rack 2's `Rack::ETag` (in every Rails app's middleware) reads a 200 body whole to digest it, unless the response already has an `ETag` or a `Last-Modified` — `Cache-Control: no-cache` does not stop it, contrary to what ruact assumed. Rails 7.2 through 8.1 accept Rack 2.2, so an app on it got no streaming at all: no shell, no fallback, the page at the end. On Rack 2 a streamed response now carries a weak `ETag` of its own, new for every response, so no `If-None-Match` ever matches it — unless the action set its own `ETag` or `Last-Modified` (`fresh_when`), which already keeps `Rack::ETag` away and is left as it is. Measured with Rack 2.2.24. Rack 3 is unchanged.
+- **A client component or a `<Suspense>` inside a `cache` block no longer comes back as another one.** A fragment cache stores the HTML a render produced, with the markers that render gave its components and blocks; read back in another render, a marker could name one of *that* render's components (the page showed the wrong component, with its props) or another boundary's block (a `<Suspense>` showed another one's content). Every marker now carries the id of the render that wrote it. A client component read from the cache raises `Ruact::HtmlConverterError`, naming the `cache` and what to do (keep the component outside it); a `<Suspense>` read from the cache gets an error row for that boundary only, saying the same, and the rest of the page renders; the server logs it and reports it to `Rails.error` (`source: "ruact.suspense"`), whether the page streams or not. A marker cached by 0.0.20 or before, read after the upgrade, is taken for one of another render too.
+- **A `<Suspense>` that runs later sees its local variables as they were at the tag.** In an action that streams, the block ran after the rest of the template and read a local as it was then: every block of a `for` loop showed the last item, and a local reassigned below the tag showed the new value. Locals are now kept when the tag is met and given back to the block when it runs. What is kept is the variable, not a copy of its object: a list appended to below the tag shows the item appended. A local an earlier `<Suspense>` reassigns is not seen by the ones after it. Instance variables are still read when the block runs.
+- **A query still running when a `<Suspense>` passes `suspense_timeout` is cancelled (PostgreSQL).** The timeout gave the response back, but the query went on running on the server, and its connection — back in the pool — made the next query on it wait until it ended (seconds). At the limit ruact now cancels the queries in flight on the connections the block holds or just gave back (`PG::Connection#cancel`; the block's fiber under `isolation_level = :fiber`); the connection is free again at once, and the boundary gets the timeout. A query `load_async` started is not cancelled: the async executor's thread holds its connection. Other adapters are unchanged. For those queries, and with any other adapter, the database's statement timeout stays the limit.
+- **Error lines below a component tag written over several lines are right.** The preprocessor put a multi-line tag on one line, so Rails named a line too early for any error below it (an error page, a backtrace) — since component tags existed. The tag's line breaks are kept.
+- **The development overlay's backtrace names the right template lines.** React's development client reads each server frame as six fields; ruact sent four, and every frame came out at line 2.
+- **An exception raised after a streamed page was sent (an `after_action`) reaches `Rails.error`.** `ActionController::Live` only logs what is raised once the response has started, so an app's error reporting never heard of it; ruact reports it (`source: "ruact.stream"`). The page in the browser is unchanged.
+
 ## [0.0.20] - 2026-10-14
 
 ### Added
@@ -518,7 +544,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **E2E test app** — `e2e/` Rails app (no DB, in-memory Post model) with full CRUD system tests validating the complete request cycle.
 
-[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.20...HEAD
+[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.21...HEAD
+[0.0.21]: https://github.com/luizcg/ruact/releases/tag/v0.0.21
 [0.0.20]: https://github.com/luizcg/ruact/releases/tag/v0.0.20
 [0.0.19]: https://github.com/luizcg/ruact/releases/tag/v0.0.19
 [0.0.18]: https://github.com/luizcg/ruact/releases/tag/v0.0.18

data/lib/generators/ruact/install/templates/AGENTS.md.tt

@@ -78,14 +78,15 @@ READ IT instead of simulating the name generation. Regenerate after routes/queri
    `<Card title={@t}>...</Card>` passes the ERB between its tags to the
    component as `children`. An unclosed or stray tag fails LOUDLY with a
    `PreprocessorError` naming file:line. `<Suspense fallback="...">` pairs too;
-   under `ruact_streaming` its content runs AFTER the page is sent, so status,
-   redirect, cookies, session and flash belong in the controller, not inside it.
+   under `ruact_streaming` its content runs AFTER the page is sent: status,
+   redirect, cookies, session, flash, `content_for` and locale/tenant/DB-role
+   scopes belong in the controller (`around_action`), not inside it or in a
+   middleware; a `cache` block goes inside a `<Suspense>`, never around one.
    In a loop of items holding components, give each item a `data-react-key`
    (the record's id): React matches them by position otherwise, silently.
 2. **`{}` props are Ruby, not JavaScript.** `<Badge label={@post.title} />`
-   evaluates `@post.title` as a Ruby expression in the ERB. No JS ternaries,
-   no `{...spread}`. A quoted value (`title="Hi"`) is a
-   plain string and a bare attribute is `true`, as in JSX.
+   evaluates `@post.title` as a Ruby expression: no JS ternaries, no `{...spread}`.
+   A quoted value (`title="Hi"`) is a plain string; a bare attribute is `true`.
 3. **One action, two response shapes.** A `Ruact::Server` non-GET action
    answers JSON — its instance variables, or `204`, or `{"$redirect": path}` —
    when the request's `Accept` header is exactly `application/json`, which is
@@ -144,8 +145,7 @@ duration, or a deliberate `expires_in: nil` for a non-expiring token.
 - `bin/rails ruact:routes -- --json` — the accessor/route table (each accessor's
   name, kind, verb, path, params) as JSON, from the same route table codegen
   reads; bare `ruact:routes` prints a compact human table.
-- Both `--json` outputs are EXPERIMENTAL — the shape may change; gate on their
-  `schema_version` field (currently `0`), do not treat it as a stable contract.
+- Both `--json` outputs are EXPERIMENTAL: gate on `schema_version` (now `0`).
 - `bin/rails ruact:server_functions:generate` — regenerates the TS module;
   exits 1 on a naming collision or an invalid name.
 - `bin/dev` — boots Rails AND Vite (both required: Vite serves the client components).

data/lib/ruact/cached_blocks.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Story 19-2 — a render that renders `<Suspense>` content in place writes no
+  # block marker: one in its HTML came out of a `cache` block a render that
+  # streamed wrote. Its boundary gets an error row ({Flight::Renderer}); this
+  # says so on the server, as {DeferredRender} does for a render that streams.
+  #
+  # Internal API: not part of the public compatibility contract.
+  module CachedBlocks
+    # Only the attribute as written in a tag (`="`): text that mentions it is
+    # escaped.
+    MARKER = %( #{Markers::BLOCK_ATTR}=").freeze
+    private_constant :MARKER
+
+    # Logs and reports a block marker in +html+.
+    #
+    # @param html [String]
+    # @param logger [Logger, nil]
+    # @return [void]
+    def self.report(html, logger)
+      return unless html.include?(MARKER)
+
+      error = Ruact::Error.new(Flight::DeferredContent::STALE)
+      logger&.error("[ruact] #{error.message}")
+      Rails.error.report(error, handled: true, severity: :error, source: "ruact.suspense") if
+        defined?(Rails) && Rails.respond_to?(:error)
+    end
+  end
+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
@@ -177,16 +177,18 @@ 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)
+      pipeline = RenderPipeline.new(ruact_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

@@ -484,7 +484,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?