ruact 0.0.18 → 0.0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afeffed3bf00af43d750b220dbffbdd62758269d578bb649912d7fbee157df86
-  data.tar.gz: 2bae60da180b2a5b6c85fe49c3adc42d3431c1cfee7666c9fdbf79b92815049b
+  metadata.gz: 69c5f93d5a39e751e7f69b953ffd1101660e464df4397cadee932c12ba81b4fd
+  data.tar.gz: 518c3a0c1183cbc82fd13ca3d6d621502e28713b5d9dd21bd46beeca30ecc775
 SHA512:
-  metadata.gz: 79f5785e73237b512b1fce27e9b085538c57954921bf92544fc8d4f80c2646f27e5e46baa23b1a565beb567b8e4762a108a0f2885b3ec85f9b822216889afadd
-  data.tar.gz: 3421862773a8f0669533bd70e39aed531b9ae2c4ce42205bc6939bc6311d76f5c45e4527d39752793bebc343af29ba96ebffd3fd58a6f414bb16fba879cfcbeb
+  metadata.gz: 115756074639ab4849ae2982cf7d4e13176f20f383302f8961b1ed5f09148e1bec74560f2e1f42ef2aa26262449d6c0536c89ce205748176bad9aa0f5006fbfb
+  data.tar.gz: c55a816d7f40810470e42f86f8111ae3fc2e1e4ab150a31153626c26dedb8de1f76166483acb004722239d1696626bbe0bef218237bb34b665da7320e7e200c2

data/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.20] - 2026-10-14
+
+### Added
+
+- **`ruact_streaming` — a page sent as it renders.** In an action the controller declares (`ruact_streaming`, `ruact_streaming only: :show`, `except:`; without arguments, every ruact page of the controller), the shell and the `<Suspense>` fallbacks reach the browser first, and each `<Suspense>`'s content runs after that, one at a time, in page order (a `<Suspense>` inside one waits behind the page's others), in the view and with the template path it was written in, and arrives when it is ready — on the first load (the document stays open and pushes each boundary's rows) and on a navigation. Those actions run under `ActionController::Live`, applied per action: the controller's other actions respond as before, with their `ETag`, on the request's thread. `Controller.action(:name)` endpoints included. Over HTTP/1.0 — nginx's default to its upstream; set `proxy_http_version 1.1` — Live cannot stream, and the page renders whole, as without `ruact_streaming`.
+- **A `<Suspense>` that fails, in development, over the page.** A `<Suspense>` whose content raises gets an error row: its fallback stays, the next one runs, the response stays 200, and the error goes to `Rails.error` (`source: "ruact.suspense"`) and the log. Development shows it over the page, with the Ruby backtrace; production says only that a part failed (`ruact:suspense-error`).
+- **`ruact:doctor` checks `load_async`.** A new check, `load_async`, warns when `config.active_record.async_query_executor` is not set (`load_async` then runs its query where it is called); in development the first such `load_async` says so in the log.
+
+### Fixed
+
+- **A `<Suspense>` written as text inside ERB code stays as written.** `<%= "<Suspense>" %>` printed ruact's internal `<ruact-suspense …>` markup instead of the text (and a tag with attributes there did not compile). Tags inside `<% %>` and `<%= %>` are now left alone, as component tags already were.
+- **Error lines after a `<Suspense>` tag written over several lines are right.** The tag was rewritten onto one line, so Rails named an earlier line for any error below it.
+
+### Changed
+
+- **Every `<Suspense>` must close, in the same template and the same ERB block.** A `<Suspense>` with no `</Suspense>`, a `</Suspense>` that closes nothing, or a pair split across an ERB block (`<% if %><Suspense><% end %>…</Suspense>`) raises `Ruact::ComponentTagError` naming the template's line, as a component tag already does. Before, such a template rendered whatever the HTML parser made of it, sometimes with the content outside the boundary. This counts `<Suspense>` written as text in an attribute, a `<script>` or an HTML comment, and a pair opened in one partial and closed in another. `<Suspense fallback="…" />` is a boundary with nothing in it.
+- **A `<Suspense>`'s content is its own Ruby scope.** A local variable assigned between the tags is not visible after `</Suspense>`; instance variables and `content_for` still cross it. `break`, `next`, `redo` and `return` written between the tags outside a loop or block of their own, and `it` or `_1` outside a block of their own, would apply to the Suspense and not to the loop around it, so they raise `Ruact::ComponentTagError` with the line: name the block's parameter, or move the statement out. An `it` the template made a local before the tag (`|it|`, `it = …`) is that local. This is what lets the content be rendered later.
+- **`fallback` and `delay` take literal text.** ERB inside either now raises `Ruact::PreprocessorError` with the line. It never worked: the fallback came out empty and the page showed a stray `">`.
+- **In an action that streams, a `<Suspense>`'s content runs after the shell is sent.** Code inside it that the rest of the template depended on — an instance variable read further down, a `content_for` — now runs later. Status, redirects, headers, cookies, the session and the flash are set in the controller, before the page renders: written inside a `<Suspense>` they never reach the browser, and development makes that an error of the boundary (and logs it when an `after_action` does it).
+- **No default `delay`.** A `<Suspense>` waited 1.5 s before its content on every streamed navigation, even when the content was ready. `delay=` still waits that long, inside `suspense_timeout`.
+- **`suspense_timeout` limits real time.** It bounds how long a `<Suspense>`'s content may run (an explicit `delay` included), with a timeout a `rescue` of `StandardError` in the content does not catch (Active Record wrapping a query's error included); past it the boundary gets the timeout error and the next one runs. It does not stop a query the database is running — set the database's statement timeout for that.
+- **An error inside a `<Suspense>` no longer makes the response a 500** in an action that streams: the boundary gets the error (see Added). An exception once the response has started is reported and the response closed, without Rails' `/500.html` script.
+- **The entry script is `async`, on every ruact page.** It runs as soon as it has loaded, so a page that streams shows its fallbacks; the bootstrap waits for `#root` when a layout puts `ruact_js_assets` above it.
+- **A controller that includes `ActionController::Live` streams every page**, with the content of each `<Suspense>` rendered after the shell; `ruact_streaming` is the documented way. A controller with neither responds as before, and development says, once per response, which line makes an action with a `<Suspense>` stream.
+- **Connections a streamed action took are given back when it ends.** Under Live the action runs in a thread of its own, and a `Model.connection` there kept its connection until the thread was reused.
+- **Supported Rails is 7.2 through 8.1.** The test matrix named Rails 7.0 and 7.1 but ran 7.2 in those cells (`~> 7.0` admits every 7.x), so neither was ever tested; on them, `rails generate ruact:scaffold` fails. The matrix now runs 7.2, 8.0 and 8.1, each cell checks it loaded the Rails it names, and 7.0 and 7.1 are no longer claimed. Rails itself maintains only 8.0 and 8.1.
+- **The render path was reorganised, with no change to what a page sends.** What a template leaves for the converter, how a render hands out its rows (the shell first, then each Suspense boundary), how a response is written, and how the browser opens a page's Flight stream each live in one place now; the Flight bytes are the same, checked against the wire fixtures and in a browser. Internal classes changed shape (`Ruact::RenderContext`, `Ruact::Flight::Request`, `Ruact::Flight::Renderer`, `Ruact::RenderPipeline`); none of them is public API.
+
+## [0.0.19] - 2026-10-08
+
+### Fixed
+
+- **A component exported from a file that exports several now renders as itself.** When one file exported more than one client component — as shadcn/ui's `components/ui/dialog.tsx` exports `Dialog`, `DialogTrigger`, `DialogContent` and the rest — every ERB tag naming one of them rendered whichever of the file's components the manifest listed first, with no error: a `<DialogTrigger>` rendered a `Dialog`, and a dialog composed from its parts in ERB never opened. Each tag now imports its own export. Files exporting a single component were not affected.
+
+### Changed
+
+- **The `AGENTS.md` section the install writes tells agents to key list items.** In an ERB loop whose items hold components, each item needs a `data-react-key`: ERB has no `key`, so React matches the items by position, and when the list changes a component's state shows on the wrong item, with no warning. Re-run `rails generate ruact:install --force` to refresh the section.
+
 ## [0.0.18] - 2026-10-07
 
 ### Added
@@ -480,7 +518,9 @@ 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.18...HEAD
+[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.20...HEAD
+[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
 [0.0.17]: https://github.com/luizcg/ruact/releases/tag/v0.0.17
 [0.0.16]: https://github.com/luizcg/ruact/releases/tag/v0.0.16

data/CONTRIBUTING.md

@@ -62,12 +62,13 @@ every pull request. Running them locally first is the difference between one rou
 
 | CI job | What it checks |
 |---|---|
-| `rspec` | the Ruby suite, on Ruby 3.2/3.3 × Rails 7.0/7.1/7.2/8.0 — eight cells |
+| `rspec` | the Ruby suite, on Ruby 3.2/3.3 × Rails 7.2/8.0/8.1 — six cells, each checking it loaded the Rails it names |
 | `rubocop` | style, plus the three custom cops below |
 | `yard` | every public method carries YARD documentation |
 | `js` | the Vite plugin's vitest suite, including its Ruby↔JS byte-parity cases, and a type-level test over the generated accessors |
 | `benchmark` | render-pipeline allocations against a recorded baseline |
 | `name-propagation` | greps the tree for names retired before v0.1.0 |
+| `browser` | the browser proof of a page that streams (`spec/browser/deferred_suspense/run`): a Rails app on Puma with the gem by path, in Chromium, in development and production, and the perturbation that must fail |
 | `gate` | that `CHANGELOG.md` gained something if this branch changed what the published gem contains, and that a version bump is one legal semver step to a version nothing has released |
 
 <!-- ci-jobs:end -->
@@ -95,8 +96,14 @@ npm test
 npm run typecheck
 ```
 
-To reproduce one matrix cell other than the default — `RAILS_VERSION` is what the eight `rspec` cells vary,
-and unset means 8.0:
+and, for the `browser` job (Node and Chromium; ports 4190 and 5199):
+
+```bash
+spec/browser/deferred_suspense/run
+```
+
+To reproduce one matrix cell other than the default — `RAILS_VERSION` is what the six `rspec` cells vary,
+and unset means 8.1:
 
 ```bash
 RAILS_VERSION=7.2 bundle install && bundle exec rspec

data/README.md

@@ -98,7 +98,7 @@ Every item below is shipped in this gem at v0.0.11:
 - **Signed record references** — `Ruact.signed_global_id(record, for:, expires_in:)` out, `Ruact.locate_signed(token, for:)` back in; a tampered token is a `400`, not a lookup. [Docs](https://ruact.dev/docs/api/server-actions)
 - **Client-side navigation** — link interception, scroll restoration and redirect-after-POST, derived from your Rails routes. [Docs](https://ruact.dev/docs/concepts/navigation)
 - **A CRUD generator** — `rails generate ruact:scaffold Post title:string body:text` delegates the model, migration and route to Rails' own `resource` generator, then adds the ruact layer. Plain semantic HTML by default; `--shadcn` opts into the Tailwind/shadcn path. It does not run migrations — `rails db:migrate` is still yours. [Docs](https://ruact.dev/docs/api/scaffold)
-- **`bin/rails ruact:doctor`** — nine checks over the manifest, Vite, the layout, the client-component CSS and streaming; exits `1` when one fails. [Docs](https://ruact.dev/docs/api/ruact-doctor)
+- **`bin/rails ruact:doctor`** — checks the manifest, Vite, the layout, the client-component CSS and streaming; exits `1` when one fails. [Docs](https://ruact.dev/docs/api/ruact-doctor)
 - **One runtime dependency** — `nokogiri`. Rails itself is not a declared dependency of this gem.
 
 ## AI tools and coding agents

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

@@ -1,8 +1,7 @@
 <!-- ruact:begin -->
 <!-- Managed by `rails generate ruact:install`. Re-run it with --force after a
-     gem upgrade to refresh ONLY this marked section; everything you write
-     outside the markers is preserved. Kept in sync manually with the online
-     copy at https://ruact.dev/llms.txt -->
+     gem upgrade to refresh ONLY this marked section; everything outside the
+     markers is preserved. Kept in sync by hand with https://ruact.dev/llms.txt -->
 
 # ruact — conventions for coding agents
 
@@ -20,8 +19,7 @@ truth" below) instead of guessing.
   adds it; `ruact_pages only:` narrows it). The page's renderer owns navigation:
   going between a ruact page and a plain Rails/Turbo page is a full page load.
 - Interactive components live in `app/javascript/components/` as `"use client"`
-  files, mounted from ERB with a PascalCase self-closing tag:
-  `<LikeButton postId={@post.id} />`.
+  files, mounted from ERB with a PascalCase tag: `<LikeButton postId={@post.id} />`.
 - Mutations are ordinary non-GET controller actions on a controller that does
   `include Ruact::Server`. Reads are `Ruact::Query` classes in `app/queries/`.
 - ruact generates a typed TypeScript module from the route table; React imports
@@ -62,10 +60,9 @@ import { categories, useQuery } from "@/.ruact/server-functions";
 const { data, loading, error } = useQuery(categories);
 ```
 
-Query params come from the method's keyword arguments and accept ONLY
-`string | number | boolean | null` (arrays/objects are rejected). Queries run
-the host controller's callback chain (authentication etc.) before the query
-object is instantiated.
+Query params are the method's keyword arguments, ONLY `string | number |
+boolean | null` (arrays/objects are rejected). Queries run the host
+controller's callback chain (authentication etc.) before the query object.
 
 ## Ground truth — read the generated file
 
@@ -78,10 +75,13 @@ READ IT instead of simulating the name generation. Regenerate after routes/queri
 ## Five traps
 
 1. **Every component tag closes.** `<Badge label={@x} />` has no children;
-   `<Card title={@t}>...</Card>` passes the ERB between its tags — HTML, loops,
-   partials, other components — to the component as `children`. An opening tag
-   that never closes, or a closing tag with no opening, fails LOUDLY with a
-   `PreprocessorError` naming file:line. `<Suspense fallback="...">` pairs too.
+   `<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.
+   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

data/lib/generators/ruact/install/templates/initializer.rb.tt

@@ -41,7 +41,10 @@ Ruact.configure do |config|
   # Recommended: true in production to prevent accidental attribute exposure.
   # config.strict_serialization = Rails.env.production?
 
-  # Timeout in seconds for deferred Suspense chunks. Default: 5.0.
+  # How long a <Suspense>'s content may run, in seconds of real time, in an
+  # action declared with `ruact_streaming`; past it, its boundary shows an
+  # error and the next one runs. A backstop: it does not stop a query the
+  # database is running — the database's statement timeout does. Default: 5.0.
   # config.suspense_timeout = 5.0
 
   # Base URL of the Vite dev server. Default: "http://localhost:5173".

data/lib/ruact/client_manifest.rb

@@ -49,9 +49,13 @@ module Ruact
     # every client component eagerly (`virtual:ruact/registry`), so there is
     # nothing to load — and React reads +chunks+ as `[chunkId, filename]` pairs,
     # which the manifest's one-URL list is not.
-    def resolve(module_id, _export_name)
-      entry = by_module_id(module_id)
-      raise "ClientManifest: no entry for module_id=#{module_id.inspect}" unless entry
+    #
+    # The entry is looked up by module AND export: one file can export several
+    # components (shadcn/ui's dialog.tsx exports Dialog, DialogTrigger, …), and
+    # each tag imports its own.
+    def resolve(module_id, export_name)
+      entry = data.each_value.find { |e| e["id"] == module_id && e["name"] == export_name }
+      raise "ClientManifest: no entry for module_id=#{module_id.inspect} export=#{export_name.inspect}" unless entry
 
       [entry["id"], NO_CHUNKS, entry["name"]]
     end
@@ -248,9 +252,5 @@ module Ruact
     def entries_by_name
       data
     end
-
-    def by_module_id(id)
-      data.values.find { |entry| entry["id"] == id }
-    end
   end
 end

data/lib/ruact/configuration.rb

@@ -38,7 +38,12 @@ module Ruact
     #     raise Ruact::SerializationError. Defaults to false in development, true in production.
     #
     # @!attribute [r] suspense_timeout
-    #   @return [Float] Seconds before a deferred Suspense chunk times out. Default: 5.0.
+    #   @return [Float] Seconds of real time a `<Suspense>`'s content may run in an
+    #     action that streams (`ruact_streaming`) before its boundary gets the
+    #     timeout error and the next one runs; an explicit `delay` counts inside
+    #     it. A backstop, not a limit on the database: a query the driver is
+    #     running keeps running (measured with PostgreSQL in Story 19-1) — the
+    #     database's statement timeout is what stops it. Default: 5.0.
     #
     # @!attribute [r] vite_dev_server
     #   @return [String] Base URL of the Vite dev server. Default: "http://localhost:5173".

data/lib/ruact/controller/delivery.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require "socket"
+require_relative "document_rendering"
+
+module Ruact
+  module Controller
+    # How a rendered ruact page reaches the client: as a Flight body, or as an
+    # HTML document carrying the payload ({DocumentRendering}) — all at once,
+    # or, in an action that streams ({Streaming}), the shell first and each
+    # `<Suspense>`'s rows as its content is rendered. Also the Flight body of a
+    # redirect the client router follows itself.
+    #
+    # Everything that decides what a ruact response looks like on the wire, its
+    # headers included, is here.
+    module Delivery
+      extend ActiveSupport::Concern
+
+      include DocumentRendering
+
+      # The headers of a Flight body written row by row: no caching, and no
+      # buffering by a proxy that honours `X-Accel-Buffering` (nginx).
+      STREAM_HEADERS = {
+        "Content-Type" => "#{RequestKind::FLIGHT_MIME}; charset=utf-8",
+        "Cache-Control" => "no-cache",
+        "X-Accel-Buffering" => "no"
+      }.freeze
+
+      # The same, for a document written in parts.
+      DOCUMENT_STREAM_HEADERS = {
+        "Content-Type" => "text/html; charset=utf-8",
+        "Cache-Control" => "no-cache",
+        "X-Accel-Buffering" => "no"
+      }.freeze
+
+      # What Rails itself writes once the response has started, on the request's
+      # thread, while the first block may be running: the session cookie and the
+      # session's own keys (`commit_session`, `commit_flash`, and the CSRF token
+      # Rails stores at commit since 7.1), and the headers a middleware adds on
+      # the way out. Not the block's writes.
+      RAILS_WRITES = {
+        "header" => %w[set-cookie server-timing content-security-policy
+                       content-security-policy-report-only x-runtime].freeze,
+        "session" => %w[session_id flash _csrf_token].freeze
+      }.freeze
+
+      # Where a streamed document is cut: the rows of each `<Suspense>` are
+      # pushed before it, as they are ready.
+      BODY_CLOSE = "</body>"
+
+      private
+
+      # Build the wire output and write it to the response. Nothing is written
+      # until the page (or, when it streams, its shell) has rendered without
+      # raising — that way a missing-component error still surfaces as a
+      # normal 500 response.
+      def emit_ruact_response(pipeline, html, render_context, streaming:)
+        # Story 15.5 (FR109) — record which page shape ruact rendered so the
+        # `Ruact::Server` dev log (`__ruact_log_response_shape!`) can name it and,
+        # crucially, stay SILENT on a plain Rails render (this flag is never set
+        # there). `@__`-prefixed → never leaks into `view_assigns`.
+        @__ruact_negotiated_page = ruact_request? ? :flight : :html_shell
+        if streaming
+          return __ruact_stream_page(DeferredRender.new(html, render_context, pipeline,
+                                                        guard: __ruact_late_write_guard))
+        end
+
+        input = { html: html, render_context: render_context }
+        if ruact_request?
+          render plain: pipeline.render(input, mode: :string), content_type: RequestKind::FLIGHT_MIME
+        else
+          render_ruact_document(pipeline.render(input, mode: :string))
+        end
+      end
+
+      # Story 19-1 — the shell, then each boundary as its block is rendered.
+      # A page that left nothing for later responds as one that does not stream.
+      def __ruact_stream_page(run)
+        shell = run.shell
+        unless run.pending?
+          return render(plain: shell, content_type: RequestKind::FLIGHT_MIME) if ruact_request?
+
+          return render_ruact_document(shell)
+        end
+        return __ruact_stream(run, STREAM_HEADERS, shell) if ruact_request?
+
+        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
+      end
+
+      # Writes +first+, then each boundary's rows (through the block, when given),
+      # then +last+. No exception leaves here with the stream open: Live would
+      # append Rails' `/500.html` script to a page already on screen. What was
+      # 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 }
+        stream = response.stream
+        begin
+          stream.write(first)
+          while run.pending?
+            if __ruact_client_gone?
+              __ruact_log_cut_short(run, "the client left")
+              break
+            end
+            rows = run.next_rows
+            stream.write(block_given? ? yield(rows) : rows)
+          end
+          stream.write(last) if last
+        rescue ActionController::Live::ClientDisconnected, IOError, SystemCallError => e
+          __ruact_log_cut_short(run, "the client left (#{e.class})")
+        rescue StandardError => e
+          __ruact_report_stream_error(e, run)
+        ensure
+          @__ruact_streamed_state = __ruact_response_state if Flight::Renderer.development_default
+          stream.close
+        end
+      end
+
+      # 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>"
+      end
+
+      # Story 19-1 (D4) — has the client closed its end? Asked before each
+      # block: the server does not notice on its own, and a write to a client
+      # that left does not fail until the one after it (measured in 19-0).
+      # Puma hands the socket over as `puma.socket`; with another server, or
+      # none, nothing is asked.
+      def __ruact_client_gone?
+        socket = request.env["puma.socket"]
+        return false if socket.nil? || !socket.respond_to?(:wait_readable) || !socket.wait_readable(0)
+
+        # The end of the connection reads as nil or as "", depending on how the
+        # peer closed it.
+        socket.recv_nonblock(1, Socket::MSG_PEEK).to_s.empty?
+      rescue IO::WaitReadable
+        false
+      rescue SystemCallError, IOError
+        true
+      end
+
+      def __ruact_log_cut_short(run, why)
+        left = run.pending_count
+        logger&.info("[ruact] #{self.class.name}##{action_name}: #{why}; " \
+                     "#{left} <Suspense> #{left == 1 ? 'boundary was' : 'boundaries were'} not rendered")
+      end
+
+      # An exception once the response has started, outside a block (the end of
+      # the layout, the serializer): reported and logged, and the stream closed.
+      def __ruact_report_stream_error(error, run)
+        logger&.error("[ruact] #{self.class.name}##{action_name} raised while streaming, after the " \
+                      "response started: #{error.class}: #{error.message}. The response was closed; " \
+                      "#{run.pending_count} <Suspense> boundaries were not rendered.")
+        Rails.error.report(error, handled: true, severity: :error, source: "ruact.stream") if Rails.respond_to?(:error)
+      end
+
+      # Story 19-1 (D5) — in development, a block that writes a cookie, the
+      # session, the flash or a header is an error of that block: the response
+      # started before the block ran, so the write would be lost.
+      def __ruact_late_write_guard
+        return nil unless Flight::Renderer.development_default
+
+        lambda do |&evaluate|
+          before = __ruact_response_state
+          html = evaluate.call
+          changed = __ruact_state_changes(before, __ruact_response_state)
+          raise Ruact::Error, __ruact_late_write_message(changed, "a <Suspense>") unless changed.empty?
+
+          html
+        end
+      end
+
+      # Story 19-1 (D5) — the same, for what runs after the page was sent (an
+      # `after_action`): it cannot be a block's error any more, so it is logged.
+      def __ruact_check_writes_after_stream
+        before = @__ruact_streamed_state
+        return if before.nil?
+
+        @__ruact_streamed_state = nil
+        changed = __ruact_state_changes(before, __ruact_response_state)
+        return if changed.empty?
+
+        logger&.error("[ruact] #{self.class.name}##{action_name}: " \
+                      "#{__ruact_late_write_message(changed, 'code after the page was sent')}")
+      end
+
+      def __ruact_late_write_message(changed, where)
+        "#{where} wrote #{changed.join(', ')} after the response started, so the browser never gets it. " \
+          "Status, headers, cookies, the session and the flash are set in the controller, before the page " \
+          "renders."
+      end
+
+      # What a response can no longer carry once it has started. Each part is
+      # read on its own: a controller without a session has no session to read.
+      # Reading does not load what is not loaded — the session, the flash — so
+      # development behaves as production does.
+      def __ruact_response_state
+        {
+          "header" => __ruact_read_state("header") { response.headers.to_h.transform_keys(&:downcase) },
+          "cookie" => __ruact_read_state("cookie") { request.cookie_jar.to_hash.except(__ruact_session_cookie) },
+          "session" => __ruact_read_state("session") { session.loaded? ? session.to_hash : {} },
+          "flash" => __ruact_read_state("flash") { request.flash_hash&.to_hash || {} }
+        }
+      end
+
+      def __ruact_read_state(kind)
+        yield.except(*RAILS_WRITES.fetch(kind, []))
+      rescue StandardError
+        nil
+      end
+
+      # The session store's cookie: the key the app configured, or the one the
+      # store falls back to without one. Not `request.session_options[:key]`:
+      # Rack takes the key out of the options it keeps.
+      def __ruact_session_cookie
+        key = Rails.application.config.session_options[:key]
+        key ||= request.session.instance_variable_get(:@by).try(:key)
+        (key || "_session_id").to_s
+      rescue StandardError
+        "_session_id"
+      end
+
+      # `["the cookie theme", "the header X-Trace"]` — what differs.
+      def __ruact_state_changes(before, after)
+        before.flat_map do |kind, was|
+          now = after[kind]
+          next [] if was.nil? || now.nil? || was == now
+
+          (was.keys | now.keys).reject { |key| was[key] == now[key] }.map { |key| "the #{kind} #{key}" }
+        end
+      end
+
+      # The Flight body of a redirect: one row the client router reads and
+      # follows (`redirectType: "push"`), instead of a 302 the browser would.
+      def __ruact_render_flight_redirect(url)
+        render plain: "0:#{JSON.generate({ 'redirectUrl' => url, 'redirectType' => 'push' })}\n",
+               content_type: RequestKind::FLIGHT_MIME
+      end
+    end
+  end
+end

data/lib/ruact/controller/document_rendering.rb

@@ -59,6 +59,13 @@ module Ruact
       # committed: that is a configuration error, raised in development/test and
       # logged-and-degraded in production rather than served to real traffic.
       def render_ruact_document(payload)
+        render html: ruact_document_html(payload).html_safe, layout: false
+      end
+
+      # The document {#render_ruact_document} sends, as a String — what a page
+      # that streams sends up to its last `</body>` ({Delivery}). Every check
+      # above runs here, before a byte of the response is written.
+      def ruact_document_html(payload)
         __ruact_warn_turbo_form_submission if __ruact_local_env?
         # Set for EVERY branch, the shell included: besides carrying the payload
         # to a layout's zero-argument `ruact_js_assets`, it is how
@@ -67,11 +74,11 @@ module Ruact
         # through the same layout never inherits it.
         @ruact_flight_payload = payload
         layout = Ruact.config.layout
-        return render html: ruact_html_shell(payload).html_safe, layout: false if layout == false
+        return ruact_html_shell(payload) if layout == false
 
         unless ruact_layout_resolvable?(layout)
           __ruact_handle_unready_layout(layout, :missing)
-          return render html: ruact_html_shell(payload).html_safe, layout: false
+          return ruact_html_shell(payload)
         end
 
         # `@ruact_flight_payload` is copied to the view by Rails' `view_assigns`
@@ -79,13 +86,10 @@ module Ruact
         # that is how the layout's zero-argument `ruact_js_assets` reaches THIS
         # render's Flight payload.
         document = render_to_string(html: "".html_safe, layout: layout)
+        return document if ruact_document_mountable?(document)
 
-        if ruact_document_mountable?(document)
-          render html: document.html_safe, layout: false
-        else
-          __ruact_handle_unready_layout(layout, :unwired)
-          render html: ruact_html_shell(payload).html_safe, layout: false
-        end
+        __ruact_handle_unready_layout(layout, :unwired)
+        ruact_html_shell(payload)
       ensure
         remove_instance_variable(:@ruact_flight_payload) if instance_variable_defined?(:@ruact_flight_payload)
       end
@@ -219,10 +223,9 @@ module Ruact
       def ruact_html_shell(flight_payload)
         # Story 14.2 — the JS asset block (entry `<script>` tags + `__FLIGHT_DATA`)
         # is delegated to the single `Ruact::ViewHelper#ruact_js_assets`
-        # implementation. The bootstrap entry script is a deferred ES module, so it
-        # runs after the inline `__FLIGHT_DATA` classic script has populated the
-        # queue regardless of source order — emitting the whole block in `<body>`
-        # is correct.
+        # implementation, which writes the inline `__FLIGHT_DATA` script before
+        # the entry `<script>`: the entry is `async` (Story 19-1) and runs as
+        # soon as it loads, so the queue has to be there first.
         <<~HTML
           <!DOCTYPE html>
           <html lang="en">