ruact 0.0.19 → 0.0.21

data/lib/ruact/query_watch.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Story 19-2 (AC14) — when a `<Suspense>` runs past `suspense_timeout` with a
+  # query in flight, that query is cancelled on the database server.
+  #
+  # `Timeout` gives the block back at the limit, but a query the driver is
+  # waiting on keeps running on the server, and the connection stays busy with
+  # it: the next query on it — this response's, or the next request's once the
+  # connection is back in the pool — waits for it to end (measured with
+  # PostgreSQL: seconds). Inside a transaction even the unwinding waits, at its
+  # ROLLBACK. So at the limit the queries in flight on the connections the
+  # block's thread holds — or that it already gave back — are cancelled, from
+  # another thread if the block is stuck; the connection is free again within
+  # milliseconds.
+  #
+  # PostgreSQL only: `PG::Connection#cancel` is libpq's PQcancel, made to be
+  # called from another thread. Other adapters are left as they are; the
+  # database's own statement timeout is the limit there.
+  #
+  # Not cancelled: a query `load_async` runs. The async executor's thread holds
+  # its connection, not the block's, and nothing ties that query to the block
+  # that waits for it; it runs to its end. The statement timeout is the limit
+  # for those.
+  #
+  # Internal API: not part of the public compatibility contract.
+  class QueryWatch
+    # Who holds a connection the way Active Record records it: the thread, or
+    # the fiber under `isolation_level = :fiber`.
+    def self.current_owner
+      ::ActiveSupport::IsolatedExecutionState.context
+    end
+
+    # Watches +owner+'s connections for +limit+ seconds; nil when there is
+    # nothing to watch (no Active Record).
+    def self.start(owner, limit)
+      return nil unless defined?(::ActiveRecord::Base) && defined?(::PG::Connection)
+
+      new(owner, limit)
+    end
+
+    def initialize(owner, limit)
+      @lock = Mutex.new
+      @done = false
+      @cancelled = false
+      @watcher = Thread.new do
+        sleep(limit)
+        @lock.synchronize { cancel_queries_of(owner) unless @done }
+      end
+    end
+
+    # The block ran past the limit and was given back: cancel what its owner
+    # still has in flight now, whether or not the watcher got there first.
+    def cancel_now(owner)
+      @lock.synchronize { cancel_queries_of(owner) }
+    end
+
+    # Whether a query was cancelled: the error the block then raises
+    # (`ActiveRecord::QueryCanceled`) is the timeout's, not the content's. The
+    # watcher can get there before `Timeout` does.
+    def cancelled?
+      @cancelled
+    end
+
+    # The block ended (or was ended): nothing to cancel any more. Does not wait
+    # for a cancel under way, which opens a connection to the database.
+    def stop
+      @done = true
+      @watcher.kill
+    end
+
+    private
+
+    # The queries are found under each pool's lock and cancelled outside it: a
+    # cancel opens a connection to the database, and the pool's lock is every
+    # thread's checkout. A connection nobody holds could be handed to another
+    # request in between and have that request's query cancelled; the window
+    # is the time a cancel takes to reach the server, on the timeout path only.
+    def cancel_queries_of(owner)
+      in_flight(owner).each do |raw|
+        raw.cancel
+        @cancelled = true
+      rescue StandardError
+        nil
+      end
+    end
+
+    def in_flight(owner)
+      ::ActiveRecord::Base.connection_handler.connection_pool_list(:all).flat_map do |pool|
+        pool.synchronize { pool.connections.filter_map { |connection| query_of(connection, owner) } }
+      rescue StandardError
+        []
+      end
+    end
+
+    # The owner's own connection, or one already back in the pool: unwinding a
+    # `with_connection` gives the connection back with its query still running.
+    # A query in flight on a connection nobody holds is one nobody waits for.
+    def query_of(connection, owner)
+      return unless connection.owner.nil? || connection.owner.equal?(owner)
+
+      raw = connection.instance_variable_get(:@raw_connection)
+      raw if raw.is_a?(::PG::Connection) && raw.transaction_status == ::PG::PQTRANS_ACTIVE
+    end
+  end
+end

data/lib/ruact/railtie.rb

@@ -46,6 +46,18 @@ module Ruact
       app.config.middleware.use Ruact::NavigationBoundary::Middleware
     end
 
+    # Story 19-1 (ADR D1) — in development, a `load_async` that cannot run in
+    # the background says so (Ruact::LoadAsyncNote). Nothing in production, and
+    # nothing at all without Active Record.
+    initializer "ruact.load_async_note" do
+      next unless Rails.env.development?
+
+      ActiveSupport.on_load(:active_record) do
+        require_relative "load_async_note"
+        ActiveRecord::Relation.prepend(Ruact::LoadAsyncNote::Relation)
+      end
+    end
+
     rake_tasks { load File.expand_path("../tasks/ruact.rake", __dir__) }
 
     # Load the client manifest at boot (and on each code reload in development).

data/lib/ruact/render_context.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module Ruact
   # Per-render mutable state holding the components encountered during ERB
-  # evaluation. One instance is allocated by the controller per render, passed
-  # explicitly through the pipeline, and discarded when the response is sent.
+  # evaluation, and — in an action that streams — the `<Suspense>` blocks whose
+  # content is rendered after the shell is sent. One instance is allocated by
+  # the controller per render, passed explicitly through the pipeline, and
+  # discarded when the response is sent.
   #
   # No shared state, no thread-local lookup — the instance lives only as long
   # as the render call. Satisfies NFR8 and the `Ruact/NoSharedState` cop with
@@ -11,20 +15,83 @@ module Ruact
   #
   # Internal API: not part of the public compatibility contract.
   class RenderContext
-    def initialize
+    # A `<Suspense>` block waiting to be rendered: the view it was written in,
+    # the block, the template Rails was rendering when it met the tag
+    # (`t(".key")` and error messages read it), and the local variables the
+    # block can see, as they were then (Story 19-2: a `for` loop reuses one
+    # variable, a local can be reassigned below the tag).
+    Block = Struct.new(:view, :block, :virtual_path, :template, :location, :locals)
+
+    # @param deferring [Boolean] whether a `<Suspense>`'s content is rendered
+    #   after the shell (an action that streams) instead of in place
+    def initialize(deferring: false)
+      # Story 19-2 — every marker this render writes carries it, so a marker a
+      # `cache` block stored in another render never passes for one of this
+      # render's: it would name another component, or another boundary's block.
+      @id = SecureRandom.hex(4)
       @components = []
+      @deferring  = deferring
+      @blocks     = []
     end
 
     attr_reader :components
 
+    # Whether a `<Suspense>`'s content is rendered after the shell.
+    def deferring?
+      @deferring
+    end
+
     def register(name, props)
-      token = "__RUACT_#{@components.length}__"
+      # Frozen: the converter keys a Hash by it, which would copy an unfrozen one.
+      token = "__RUACT_#{@id}_#{@components.length}__".freeze
       @components << { token: token, name: name, props: props }
       token
     end
 
-    def by_token(token)
-      @components.find { |c| c[:token] == token }
+    # Keeps a `<Suspense>` block for later and returns its key.
+    #
+    # @param block [Block]
+    # @return [String]
+    def defer_block(block)
+      @blocks << block
+      "#{@id}-#{@blocks.length - 1}".freeze
+    end
+
+    # The block registered under +key+, or nil when the key is not this
+    # render's — a marker that came out of a `cache` block another render wrote.
+    #
+    # @return [Block, nil]
+    def block(key)
+      id, index = key.to_s.split("-", 2)
+      return nil unless id == @id && index.to_s.match?(/\A\d+\z/)
+
+      @blocks[Integer(index, 10)]
+    end
+
+    # Whether the development message for a `<Suspense>` in an action that
+    # does not stream was given in this render: once per response.
+    def unstreamed_suspense_noted?
+      @unstreamed_suspense_noted == true
+    end
+
+    def note_unstreamed_suspense!
+      @unstreamed_suspense_noted = true
+    end
+
+    # The registered components with the client reference +manifest+ gives
+    # each, in the shape {HtmlConverter} reads:
+    # `[{ token:, name:, ref:, props: }, ...]`. Raises what the manifest raises
+    # for a component it does not have. +from+ skips the first components (the
+    # ones a previous call resolved).
+    def resolve(manifest, controller_path: nil, from: 0)
+      entries = from.zero? ? @components : @components.drop(from)
+      entries.map { |entry| resolve_entry(entry, manifest, controller_path: controller_path) }
+    end
+
+    # One registered component, resolved as {#resolve} does.
+    def resolve_entry(entry, manifest, controller_path: nil)
+      ref = manifest.reference_for(entry[:name], controller_path: controller_path)
+      { token: entry[:token], name: entry[:name], ref: ref, props: entry[:props] }
     end
   end
 end

data/lib/ruact/render_pipeline.rb

@@ -55,6 +55,8 @@ module Ruact
     #   - `:erb` or `:html` is not a `String`,
     #   - `input` contains extra keys beyond the documented shapes,
     #   - `mode` is not in {VALID_MODES}.
+    #   - (`:erb` input) the template holds a `<Suspense>`: its content is a block only ActionView
+    #     renders. Raised when the Enumerator is consumed.
     #   All `ArgumentError` messages name the offending input and reference
     #   `RenderPipeline#render` for the canonical contract.
     #
@@ -64,7 +66,8 @@ module Ruact
     #
     # @example Pre-rendered HTML, streaming output
     #   ctx = Ruact::RenderContext.new
-    #   pipeline.render({ html: "<!-- __RUACT_0__ -->", render_context: ctx }, mode: :stream)
+    #   html = Ruact::Markers.component(ctx.register("NavBar", {}))
+    #   pipeline.render({ html: html, render_context: ctx }, mode: :stream)
     #   # => #<Enumerator: ...>  (yields Flight rows lazily)
     def render(input, mode: :string)
       validate_mode!(mode)
@@ -72,6 +75,20 @@ module Ruact
       mode == :string ? enum.to_a.join : enum
     end
 
+    # What the render reads — for a {DeferredRender} built on it.
+    attr_reader :manifest, :controller_path, :logger, :development
+
+    # The warning for a value serialized through `as_json`, logged; nil without
+    # a logger.
+    def as_json_warning_callback
+      return nil if @logger.nil?
+
+      lambda do |class_name, attrs|
+        @logger.warn("[ruact] WARNING: #{class_name} serialized via as_json — ALL attributes exposed to client: " \
+                     "#{attrs}. Use `include Ruact::Serializable` with `ruact_props` for explicit control")
+      end
+    end
+
     private
 
     ALLOWED_INPUT_KEYS = %i[erb binding html render_context].freeze
@@ -142,6 +159,16 @@ module Ruact
             "ruact: render input :binding must be a Binding; got #{bnd.class} (#{DOCSTRING_REF})"
     end
 
+    # A `<Suspense>`'s content is the body of a helper block, and only
+    # ActionView's `capture` renders one.
+    def refuse_suspense!(transformed)
+      return unless transformed.include?("__ruact_suspense__(")
+
+      raise ArgumentError,
+            "ruact: render input :erb cannot hold a <Suspense>: its content is a block, which only " \
+            "ActionView's `capture` can render. Render the template through ActionView (#{DOCSTRING_REF})"
+    end
+
     def validate_html_shape!(input)
       html = input[:html]
       unless html.is_a?(String)
@@ -179,6 +206,7 @@ module Ruact
         # so passing nil is byte-for-byte equivalent while avoiding any dev HTTP
         # fetch / test-double dispatch inside callers that measure this path.
         transformed    = ErbPreprocessor.transform(erb_source, registry: nil)
+        refuse_suspense!(transformed)
         receiver       = binding_context.eval("self")
         prev_ctx       = receiver.instance_variable_get(:@__ruact_render_context__)
         inject_helper!(binding_context, render_context)
@@ -189,11 +217,7 @@ module Ruact
             receiver.instance_variable_set(:@__ruact_render_context__, prev_ctx)
           end
 
-        registry = render_context.components.map do |entry|
-          ref = @manifest.reference_for(entry[:name], controller_path: @controller_path)
-          { token: entry[:token], name: entry[:name], ref: ref, props: entry[:props] }
-        end
-
+        registry = render_context.resolve(@manifest, controller_path: @controller_path)
         root_element = HtmlConverter.convert(html, registry)
 
         Flight::Renderer.each(root_element, @manifest,
@@ -209,10 +233,8 @@ module Ruact
     # the caller may discard the RenderContext immediately after `render` returns — the
     # returned Enumerator does not reference the RenderContext.
     def render_html_enum(html, render_context, streaming:)
-      registry = render_context.components.map do |entry|
-        ref = @manifest.reference_for(entry[:name], controller_path: @controller_path)
-        { token: entry[:token], name: entry[:name], ref: ref, props: entry[:props] }
-      end
+      CachedBlocks.report(html, @logger) unless render_context.deferring?
+      registry = render_context.resolve(@manifest, controller_path: @controller_path)
       strict     = Ruact.config.strict_serialization
       warning_cb = as_json_warning_callback
 
@@ -226,18 +248,6 @@ module Ruact
       end
     end
 
-    def as_json_warning_callback
-      return nil if @logger.nil?
-
-      lambda do |class_name, attrs|
-        @logger.warn(
-          "[ruact] WARNING: #{class_name} serialized via as_json — " \
-          "ALL attributes exposed to client: #{attrs}. " \
-          "Use `include Ruact::Serializable` with `ruact_props` for explicit control"
-        )
-      end
-    end
-
     # Install __ruact_component__ on the binding's receiver and stash the active
     # render context on the receiver as @__ruact_render_context__. The singleton
     # method reads the ivar dynamically, so nested renders sharing the same

data/lib/ruact/request_kind.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Internal — how a request says what it wants from ruact. Two questions, with
+  # different answers on purpose:
+  #
+  # - {.flight?} — does the client want a Flight body back rather than an HTML
+  #   document? Either header says so: `Accept: text/x-component` (any Flight
+  #   client) or `Ruact-Request: 1` (ruact's router, which sends both).
+  # - {.from_router?} — did ruact's own router send it? Only `Ruact-Request: 1`
+  #   says that; {NavigationBoundary} answers router navigations to pages that
+  #   are not ruact's, and must not answer anyone else.
+  module RequestKind
+    # The Flight media type, as requested and as answered.
+    FLIGHT_MIME = "text/x-component"
+    # The header ruact's router adds to every request it makes.
+    ROUTER_HEADER = "Ruact-Request"
+    ROUTER_ENV = "HTTP_RUACT_REQUEST"
+
+    # @param request [ActionDispatch::Request]
+    def self.flight?(request)
+      request.headers["Accept"]&.include?(FLIGHT_MIME) || request.headers[ROUTER_HEADER] == "1"
+    end
+
+    # @param env [Hash] the Rack env (it runs before Rails builds a request)
+    def self.from_router?(env)
+      env[ROUTER_ENV] == "1"
+    end
+
+    # Which header made {.flight?} true, as the request sent it — for a log
+    # line that names it.
+    def self.flight_signal(request)
+      request.headers["Accept"].to_s.include?(FLIGHT_MIME) ? "Accept: #{FLIGHT_MIME}" : "#{ROUTER_HEADER}: 1"
+    end
+  end
+end

data/lib/ruact/server.rb

@@ -407,7 +407,7 @@ module Ruact
     # Classify the negotiated response shape from the request signals
     # (`__ruact_function_call?`, Accept, verb) and the ruact-owned outcome flags
     # (`@__ruact_function_redirect` set by the Bucket-2 {#redirect_to};
-    # `@__ruact_negotiated_page` set by {Ruact::Controller#emit_ruact_response} /
+    # `@__ruact_negotiated_page` set by {Ruact::Controller::Delivery#emit_ruact_response} /
     # its Flight `redirect_to`). Returns nil when ruact did not negotiate the
     # response, so the log stays silent on plain Rails actions.
     #
@@ -441,7 +441,7 @@ module Ruact
     end
 
     # The page-render (Bucket-1 / HTML-shell) shape, keyed on the flag
-    # {Ruact::Controller#emit_ruact_response} set when ruact rendered the page.
+    # {Ruact::Controller::Delivery#emit_ruact_response} set when ruact rendered the page.
     # nil for a plain Rails render (the flag was never set) → the log stays
     # silent on a non-negotiated response.
     def __ruact_page_shape_and_signal
@@ -458,11 +458,7 @@ module Ruact
     # The Flight deciding signal, faithful to how the request announced itself:
     # the `Accept: text/x-component` header, or the `Ruact-Request: 1` header.
     def __ruact_flight_signal
-      if request.headers["Accept"].to_s.include?("text/x-component")
-        "Accept: text/x-component"
-      else
-        "Ruact-Request: 1"
-      end
+      RequestKind.flight_signal(request)
     end
 
     # @return [Boolean] true only in a real Rails development environment

data/lib/ruact/testing/flight_extractor.rb

@@ -15,7 +15,8 @@ module Ruact
     #
     #   1. a raw `text/x-component` body (RSC/navigation request), OR
     #   2. a full HTML document embedding the payload in the `__FLIGHT_DATA`
-    #      bootstrap `<script>` (a plain browser GET).
+    #      bootstrap `<script>` (a plain browser GET) — and, in a page that
+    #      streams, in the script each `<Suspense>`'s rows are pushed in.
     #
     # A `Ruact::Server` function-call/query answer is plain JSON, not Flight —
     # feeding it here raises {NotAFlightResponseError} pointing at `JSON.parse`,
@@ -36,6 +37,16 @@ module Ruact
         \)\s*;
       /mx
 
+      # Story 19-1 — in a page that streams, each `<Suspense>`'s rows arrive
+      # later, in a script of their own pushed onto the same queue
+      # (`Ruact::Controller::Delivery#__ruact_flight_push`). Read after the
+      # bootstrap script, in document order.
+      STREAMED_PUSH = /
+        \(self\.__FLIGHT_DATA=self\.__FLIGHT_DATA\|\|\[\]\)\.push\(
+        (?<literal>"(?:\\.|[^"\\])*")
+        \)
+      /x
+
       # A Flight wire body always starts with a row header: `<hex>:` (id + colon)
       # or a hint row `:H`. JSON bodies start with `{`/`[`/`"`; HTML with `<`.
       FLIGHT_ROW_START = /\A\s*(?:\h+:|:H)/
@@ -133,9 +144,15 @@ module Ruact
                   "This response did not render a ruact component (no Flight data was inlined)."
           end
 
-          literal = match[:literal]
-          # The literal is JSON (ruact >= 0.0.15). The Ruby-literal decoder stays
-          # for documents captured from earlier versions.
+          # The streamed pushes are JSON literals ({InlineScript}), written
+          # after the bootstrap script.
+          later = html[match.end(0)..].scan(STREAMED_PUSH).map { |(streamed)| JSON.parse(streamed) }
+          decode_literal(match[:literal]) + later.join
+        end
+
+        # The literal is JSON (ruact >= 0.0.15). The Ruby-literal decoder stays
+        # for documents captured from earlier versions.
+        def decode_literal(literal)
           JSON.parse(literal)
         rescue JSON::ParserError
           decode_ruby_string_literal(literal)

data/lib/ruact/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ruact
-  VERSION = "0.0.19"
+  VERSION = "0.0.21"
 end

data/lib/ruact/view_helper/suspense.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Ruact
+  module ViewHelper
+    # The helper a `<Suspense>` becomes ({ErbPreprocessor}). Part of
+    # {ViewHelper}.
+    module Suspense
+      # A `<Suspense>`: the preprocessor makes the ERB between its tags this
+      # block's body, and passes the `fallback` and `delay` attributes as the
+      # template wrote them.
+      #
+      # In an action that streams (`ruact_streaming`), the block is kept, not
+      # run: the marker ({Markers}) carries its index, and the response renders
+      # it after the shell is sent ({DeferredRender}). Anywhere else the content
+      # is evaluated here, in place, so the page renders as one piece — and, in
+      # development, the log says the action could stream.
+      #
+      # Only what the block writes is the content: a value it ends on is not
+      # (`capture` would print a block's value when it writes nothing).
+      def __ruact_suspense__(fallback, delay = nil, &block)
+        ctx = @ruact_render_context
+        if ctx&.deferring?
+          index = ctx.defer_block(RenderContext::Block.new(self, block, @virtual_path, @current_template,
+                                                           caller_locations(1, 1).first, __ruact_locals(block)))
+          return "#{Markers.suspense_open(fallback, delay, block: index)}#{Markers::SUSPENSE_CLOSE}".html_safe
+        end
+
+        __ruact_note_unstreamed_suspense(ctx, caller_locations(1, 1).first) if ctx
+        content = capture do
+          yield
+          nil
+        end
+        "#{Markers.suspense_open(fallback, delay)}#{content}#{Markers::SUSPENSE_CLOSE}".html_safe
+      end
+
+      # Story 19-2 (AC8.3) — the local variables +block+ sees, as they are when
+      # the tag is met. The block runs later; without these it would see a local
+      # as it is then — the last item of a `for` loop, a value reassigned below.
+      def __ruact_locals(block)
+        scope = block.binding
+        scope.local_variables.to_h { |name| [name, scope.local_variable_get(name)] }
+      end
+
+      # Story 19-1 — a `<Suspense>` in an action that does not stream renders its
+      # content before the page is sent, as it always did. Development says so,
+      # once per response, with the line that makes the action stream.
+      def __ruact_note_unstreamed_suspense(ctx, location)
+        return unless defined?(Rails) && Rails.env.development?
+        return if ctx.unstreamed_suspense_noted?
+
+        ctx.note_unstreamed_suspense!
+
+        owner = respond_to?(:controller) ? controller : nil
+        return unless owner.respond_to?(:action_name) && owner.respond_to?(:logger)
+        # Declared, and answering a request it cannot stream to (HTTP/1.0).
+        return if owner.class.respond_to?(:ruact_streaming?) && owner.class.ruact_streaming?(owner.action_name)
+
+        where = location ? " (#{location.path.delete_prefix("#{Rails.root}/")}:#{location.lineno})" : ""
+        owner.logger&.warn(
+          "[ruact] #{owner.class.name}##{owner.action_name} renders a <Suspense>#{where} in an action " \
+          "that does not stream, so its content ran before the page was sent. To send the page first " \
+          "and the content when it is ready, add `ruact_streaming only: :#{owner.action_name}` to " \
+          "#{owner.class.name}."
+        )
+      end
+
+      private :__ruact_note_unstreamed_suspense, :__ruact_locals
+    end
+  end
+end

data/lib/ruact/view_helper.rb

@@ -3,6 +3,7 @@
 require "erb"
 require "json"
 require "socket"
+require_relative "view_helper/suspense"
 
 module Ruact
   # ActionView helper module included in ActionView::Base via Railtie.
@@ -14,6 +15,9 @@ module Ruact
   # +@ruact_render_context+ and copied to the view by Rails's view_assigns
   # plumbing — see Story 7.9 / Bug 7.8-B) is per-request — no shared state.
   module ViewHelper
+    # `<Suspense>`: the content in place, or kept for after the shell.
+    include Suspense
+
     # Registers +name+ with +props+ in the per-render RenderContext (set by
     # Ruact::Controller#ruact_render on the controller as +@ruact_render_context+;
     # Rails copies it to the view via +_assigns_for_view_context+ because the
@@ -28,8 +32,7 @@ module Ruact
       ctx = @ruact_render_context
       raise Ruact::Error, __ruact_outside_render_message(name) if ctx.nil?
 
-      token = ctx.register(name, props)
-      "<!-- #{token} -->".html_safe
+      Markers.component(ctx.register(name, props)).html_safe
     end
 
     # Story 18-2 — the opening of a component with children. Registers it like
@@ -41,8 +44,7 @@ module Ruact
       ctx = @ruact_render_context
       raise Ruact::Error, __ruact_outside_render_message(name) if ctx.nil?
 
-      token = ctx.register(name, props)
-      %(<ruact-component data-ruact-token="#{token}">).html_safe
+      Markers.component_open(ctx.register(name, props)).html_safe
     end
 
     # Story 17.0i — a client component in a template Rails is rendering on its
@@ -228,66 +230,66 @@ module Ruact
 
     # The `__FLIGHT_DATA` inline bootstrap `<script>` — pushes the per-render
     # Flight payload onto the global queue the bootstrap entry drains on boot.
-    #
-    # The payload carries application data (props, record content), so it is
-    # embedded as a JSON string literal with `<`, `>`, `&`, U+2028 and U+2029
-    # escaped as `\uXXXX`. No byte of the payload can then close the `<script>`
-    # — `</SCRIPT>`, `</script >` and `<!--` included — and every character
-    # reaches JavaScript intact (a Ruby `String#inspect` literal did neither:
-    # it escaped only a lowercase `</script>`, and its `\e`-style escapes mean
-    # something else in JS).
-    SCRIPT_UNSAFE = /[<>&\u2028\u2029]/
-    private_constant :SCRIPT_UNSAFE
-
-    # A JSON string literal that is also safe inside a `<script>` element.
-    # The payload is UTF-8 by construction (the serializer normalizes every
-    # string); a binary-tagged buffer is retagged, not transcoded.
-    def __ruact_script_safe_json(string)
-      utf8 = string.encoding == Encoding::UTF_8 ? string : string.dup.force_encoding(Encoding::UTF_8)
-      JSON.generate(utf8).gsub(SCRIPT_UNSAFE) { |char| format("\\u%04x", char.ord) }
-    end
-
+    # The payload is written as {InlineScript.string_literal} writes it (a
+    # Ruby `String#inspect` literal, used before, escaped only a lowercase
+    # `</script>`, and its `\e`-style escapes mean something else in JS).
     def ruact_flight_data_script(flight_payload)
       <<~HTML.strip
-        <script>
+        <script#{__ruact_nonce_attr}>
           (function() {
             var d = (self.__FLIGHT_DATA = self.__FLIGHT_DATA || []);
-            d.push(#{__ruact_script_safe_json(flight_payload)});
+            d.push(#{InlineScript.string_literal(flight_payload)});
           })();
         </script>
       HTML
     end
 
+    # Story 19-2 (AC21) — the request's CSP nonce as a `<script>` attribute, so
+    # an app whose policy allows scripts by nonce (no `'unsafe-inline'`) runs
+    # the ones ruact writes. Empty without a nonce generator: the bytes are
+    # those of before.
+    def __ruact_nonce_attr
+      source = respond_to?(:request, true) ? request : nil
+      nonce = source.content_security_policy_nonce if source.respond_to?(:content_security_policy_nonce)
+      nonce ? %( nonce="#{ERB::Util.html_escape(nonce)}") : ""
+    end
+
     # The bootstrap entry `<script>` tags — dev serves the virtual module from
     # the Vite dev server (with the react-refresh preamble + `@vite/client`);
     # prod reads the hashed URL from the Vite manifest. Both target the SAME
     # virtual entry id (`Ruact.bootstrap_virtual_id`) so dev/prod stay in lockstep.
+    #
+    # Story 19-1 — the entry is `async`: it runs as soon as it has loaded. A
+    # module script is otherwise deferred to the end of the document, and a
+    # page that streams ends after its last `<Suspense>` — its fallback would
+    # never show. The bootstrap then reads the rows the document pushes while
+    # it is still open.
     def ruact_vite_tags
       if Rails.env.development? && vite_dev_running?
         # @vitejs/plugin-react normally injects this preamble by processing index.html.
         # Since our HTML is generated by Rails (not Vite), we inject it manually.
         # Without it, every JSX file throws "can't detect preamble" at runtime.
+        # One async module, so the preamble still runs before any component
+        # module: it installs the preamble, then imports the client and the
+        # bootstrap, in that order.
         dev_server = Ruact.config.vite_dev_server.chomp("/")
-        react_preamble = <<~JS
-          <script type="module">
+        <<~HTML
+          <script type="module" async#{__ruact_nonce_attr}>
             import RefreshRuntime from '#{dev_server}/@react-refresh';
             RefreshRuntime.injectIntoGlobalHook(window);
             window.$RefreshReg$ = () => {};
             window.$RefreshSig$ = () => (type) => type;
             window.__vite_plugin_react_preamble_installed__ = true;
+            await import('#{dev_server}/@vite/client');
+            await import('#{ruact_bootstrap_dev_url}');
           </script>
-        JS
-
-        react_preamble + <<~HTML
-          <script type="module" src="#{dev_server}/@vite/client"></script>
-          <script type="module" src="#{ruact_bootstrap_dev_url}"></script>
         HTML
       else
         # Production: read the hashed URL from the Vite manifest, keyed on the
         # virtual entry id (the manifest key Vite emits for the virtual input).
         entry = vite_manifest_entry(Ruact.bootstrap_virtual_id)
         src   = entry ? "/assets/#{entry['file']}" : "/assets/application.js"
-        tag   = %(<script type="module" src="#{src}"></script>)
+        tag   = %(<script type="module" async src="#{src}"#{__ruact_nonce_attr}></script>)
         # Story 17-0k — in development with neither the Vite dev server nor a
         # build, that script 404s and the page stays empty with no error.
         Rails.env.development? && entry.nil? ? "#{ruact_vite_down_warning}\n#{tag}" : tag