ruact 0.0.19 → 0.0.21

data/lib/ruact/flight/renderer.rb

@@ -4,10 +4,26 @@ require "json"
 
 module Ruact
   module Flight
-    # Renders a React element tree to a Flight wire format string.
+    # Renders a React element tree to Flight rows, in the order React's client
+    # must read them.
     #
-    # Usage:
-    #   output = Renderer.render(root_element, bundler_config)
+    # A render has two parts. The **shell** is every row the page needs to show
+    # with its Suspense fallbacks: the imports and model rows the tree
+    # references, then the root row. Each **deferred boundary** — the content of
+    # a `<Suspense>` — then gets its own rows, one boundary at a time, each
+    # preceded by the import and text rows it brings.
+    #
+    #   renderer = Renderer.new(root, manifest)
+    #   renderer.shell                                   # => ["1:I[...]\n", "0:[...]\n"]
+    #   renderer.next_boundary(streaming: true) while renderer.pending?
+    #
+    # A boundary whose content is not rendered yet ({DeferredContent}) is taken
+    # with {#take_boundary}, rendered by the caller, and handed back to
+    # {#boundary_rows} — or to {#error_rows} when rendering it failed.
+    #
+    # {.each} and {.render} walk all of it:
+    #
+    #   Renderer.render(root_element, bundler_config)
     #   # => "1:I[...]\n0:[\"$\",\"div\",...]\n"
     class Renderer
       def self.render(model, bundler_config, **)
@@ -38,54 +54,91 @@ module Ruact
                                strict_serialization: strict_serialization,
                                on_as_json_warning: on_as_json_warning,
                                development: development)
+        @serializer = Serializer.new(@request)
       end
 
-      # Yields Flight rows one at a time.
-      # Flush order: imports → regular → root → deferred (with optional delay) → errors.
-      # When streaming: false (initial HTML shell), deferred delays are skipped.
-      def each(streaming: true, &block)
-        return enum_for(:each, streaming: streaming) unless block_given?
+      # The shell's rows: the imports and model rows the tree references, then
+      # the root row (id 0). Call once, before {#next_boundary}.
+      def shell
+        raise Ruact::Error, "ruact: Renderer#shell was already taken" if @shell_taken
 
+        @shell_taken = true
         root_id = @request.allocate_id # => 0
+        root_json = JSON.generate(@serializer.serialize_model(@request.root_model))
+        @request.take_rows << RowEmitter.model(root_id, root_json)
+      end
 
-        serializer = Serializer.new(@request)
-        root_value = serializer.serialize_model(@request.root_model)
-        root_json  = JSON.generate(root_value)
-        root_row   = RowEmitter.model(root_id, root_json)
-
-        @request.completed_import_chunks.each(&block)
-        @request.completed_regular_chunks.each(&block)
-        yield root_row
-
-        # Deferred chunks: emitted after root, optionally delayed (Suspense streaming).
-        # When the chunk delay exceeds suspense_timeout, an E-type error row is emitted instead.
-        @request.deferred_chunks.each do |deferred|
-          if streaming && deferred[:delay]&.positive?
-            timeout = Ruact.config.suspense_timeout
-            if timeout&.positive? && deferred[:delay] > timeout
-              error = RowEmitter.error_payload("Suspense timeout exceeded", digest: "ruact:suspense-timeout")
-              yield RowEmitter.error(deferred[:id], JSON.generate(error))
-              next
-            end
-            sleep(deferred[:delay])
-          end
+      # Whether a deferred boundary is still to be rendered.
+      def pending?
+        @request.deferred?
+      end
 
-          # Serialize deferred content — may produce new import rows, and new
-          # regular rows (a string of 1024+ bytes becomes a `T` row the deferred
-          # model row references as `$<id>`).
-          import_count_before  = @request.completed_import_chunks.length
-          regular_count_before = @request.completed_regular_chunks.length
-          deferred_value = serializer.serialize_model(deferred[:element])
+      # How many deferred boundaries are still to be rendered.
+      def pending_count
+        @request.deferred_left
+      end
 
-          # Yield the rows discovered during deferred serialization BEFORE the
-          # row that references them.
-          @request.completed_import_chunks[import_count_before..].each(&block)
-          @request.completed_regular_chunks[regular_count_before..].each(&block)
+      # The rows of the next deferred boundary: the import and text rows its
+      # content brings, then its model row. When +streaming+, a boundary with a
+      # `delay` waits it first — or, when the delay exceeds `suspense_timeout`,
+      # gets an error row instead. For content that is already an element tree;
+      # 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)
+          return error_rows(boundary[:id],
+                            RowEmitter.error_payload(DeferredContent::STALE, digest: "ruact:suspense-error"))
+        end
 
-          yield RowEmitter.model(deferred[:id], JSON.generate(deferred_value))
+        if streaming && boundary[:delay]&.positive?
+          timeout = Ruact.config.suspense_timeout
+          if timeout&.positive? && boundary[:delay] > timeout
+            error = RowEmitter.error_payload("Suspense timeout exceeded", digest: "ruact:suspense-timeout")
+            return error_rows(boundary[:id], error)
+          end
+          sleep(boundary[:delay])
         end
 
-        @request.completed_error_chunks.each(&block)
+        boundary_rows(boundary[:id], boundary[:element])
+      end
+
+      # Takes the next deferred boundary: `{ id:, element:, delay: }`, its
+      # content (`element`) still to be rendered. Hand it back, rendered, to
+      # {#boundary_rows}, or to {#error_rows}.
+      def take_boundary
+        raise Ruact::Error, "ruact: Renderer#next_boundary before #shell" unless @shell_taken
+        raise Ruact::Error, "ruact: Renderer#next_boundary with no boundary pending" unless pending?
+
+        boundary = @request.next_deferred
+        boundary.merge(mark: @request.deferred_count)
+      end
+
+      # The rows of a boundary taken with {#take_boundary}, whose content
+      # rendered to +element+.
+      def boundary_rows(id, element)
+        value = @serializer.serialize_model(element)
+        @request.take_rows << RowEmitter.model(id, JSON.generate(value))
+      end
+
+      # The row of a boundary taken with {#take_boundary} whose content failed
+      # to render: an error row with +payload+ ({RowEmitter.error_payload}).
+      # The boundaries its content deferred before it failed are dropped (no row
+      # references them); the rows it wrote before it failed still go out
+      # first, as they may be what a later row needs.
+      def error_rows(id, payload, boundary: nil)
+        @request.drop_deferred_since(boundary[:mark]) if boundary
+        @request.take_rows << RowEmitter.error(id, JSON.generate(payload))
+      end
+
+      # Yields every row: the shell, then each deferred boundary.
+      # When +streaming+ is false (the initial HTML document), delays are skipped.
+      def each(streaming: true, &)
+        return enum_for(:each, streaming: streaming) unless block_given?
+
+        shell.each(&)
+        next_boundary(streaming: streaming).each(&) while pending?
       end
     end
   end

data/lib/ruact/flight/request.rb

@@ -2,21 +2,17 @@
 
 module Ruact
   module Flight
-    # Central state for a single Flight render.
-    # Owns the ID allocator, chunk queues, and dedup tracker.
+    # Central state for a single Flight render: the id allocator, the rows the
+    # serializer has written and not yet handed out, the deferred boundaries
+    # still to render, and the client-reference de-duplication table.
+    #
+    # The serializer writes rows here ({#add_import}, {#add_row}) and defers
+    # Suspense content ({#defer}); {Renderer} takes them in the order the
+    # client must read them ({#take_rows}, {#next_deferred}).
     class Request
-      # I rows — flushed first
-      attr_reader :completed_import_chunks
-      # model rows
-      attr_reader :completed_regular_chunks
-      # E rows — flushed last
-      attr_reader :completed_error_chunks
-      # { id:, element:, delay: } — emitted after root row
-      attr_reader :deferred_chunks
       # object_id => "$L<hex>" reference (dedup)
       attr_reader :written_objects
-      attr_reader :next_chunk_id, :pending_chunks, :bundler_config, :root_model,
-                  :strict_serialization, :on_as_json_warning, :development
+      attr_reader :bundler_config, :root_model, :strict_serialization, :on_as_json_warning, :development
 
       def initialize(model, bundler_config, strict_serialization: false, on_as_json_warning: nil,
                      development: false)
@@ -26,13 +22,12 @@ module Ruact
         @suspense_symbol_ref  = nil
         @boundary_ref         = nil
         @next_chunk_id = 0
-        @pending_chunks = 0
         @bundler_config = bundler_config
 
-        @completed_import_chunks  = []
-        @completed_regular_chunks = []
-        @completed_error_chunks   = []
-        @deferred_chunks          = []
+        @imports  = [] # I rows
+        @rows     = [] # model and text rows other than the root
+        @deferred = [] # { id:, element:, delay: }, in the order they were met
+        @next_deferred = 0
 
         @written_objects = {}.compare_by_identity
 
@@ -46,12 +41,69 @@ module Ruact
         id
       end
 
+      # An import row. Imports are handed out before any model row taken with them.
+      def add_import(row)
+        @imports << row
+      end
+
+      # A model or text row that a later row references.
+      def add_row(row)
+        @rows << row
+      end
+
+      # The rows written since the last call: imports first, then the rest, in
+      # the order they were written. Whatever references them comes after.
+      def take_rows
+        taken = @imports + @rows
+        @imports.clear
+        @rows.clear
+        taken
+      end
+
+      # Defers Suspense content: its row is rendered by {Renderer} after the
+      # shell. Returns the id the row will have.
+      def defer(element, delay)
+        id = allocate_id
+        @deferred << { id: id, element: element, delay: delay }
+        id
+      end
+
+      # Whether deferred content is still to be rendered (content deferred while
+      # rendering a deferred row counts too).
+      def deferred?
+        @next_deferred < @deferred.length
+      end
+
+      # The next deferred content, in the order it was met.
+      def next_deferred
+        deferred = @deferred[@next_deferred]
+        @next_deferred += 1
+        deferred
+      end
+
+      # How many deferred contents were met so far: a mark for
+      # {#drop_deferred_since}.
+      def deferred_count
+        @deferred.length
+      end
+
+      # Forgets the contents deferred since +mark+ — the Suspense boundaries
+      # inside a boundary whose row is an error, which no row references.
+      def drop_deferred_since(mark)
+        @deferred.slice!(mark..)
+      end
+
+      # How many deferred contents are still to be rendered.
+      def deferred_left
+        @deferred.length - @next_deferred
+      end
+
       # The `"$<hex>"` reference to this response's `"$Sreact.suspense"` symbol
       # row, emitted once, before the first row that uses it.
       def suspense_symbol_ref
         @suspense_symbol_ref ||= begin
           id = allocate_id
-          @completed_regular_chunks << RowEmitter.model(id, JSON.generate("$Sreact.suspense"))
+          add_row(RowEmitter.model(id, JSON.generate("$Sreact.suspense")))
           "$#{id.to_s(16)}"
         end
       end
@@ -66,18 +118,10 @@ module Ruact
       def boundary_ref
         @boundary_ref ||= begin
           id = allocate_id
-          @completed_import_chunks << RowEmitter.import(id, JSON.generate(BOUNDARY_METADATA))
+          add_import(RowEmitter.import(id, JSON.generate(BOUNDARY_METADATA)))
           "$L#{id.to_s(16)}"
         end
       end
-
-      def increment_pending
-        @pending_chunks += 1
-      end
-
-      def decrement_pending
-        @pending_chunks -= 1
-      end
     end
   end
 end

data/lib/ruact/flight/serializer.rb

@@ -61,9 +61,7 @@ module Ruact
         # Large strings get their own T row
         if value.bytesize >= LARGE_TEXT_THRESHOLD
           id = @request.allocate_id
-          @request.increment_pending
-          row = RowEmitter.text(id, value)
-          @request.completed_regular_chunks << row
+          @request.add_row(RowEmitter.text(id, value))
           # A plain "$<hex>" reference: React reads "$T" as a temporary
           # reference (Story 18-1).
           return "$#{id.to_s(16)}"
@@ -149,8 +147,7 @@ module Ruact
 
       def serialize_suspense(element)
         # Allocate ID for the deferred content row (emitted after root row + delay)
-        deferred_id = @request.allocate_id
-        @request.deferred_chunks << { id: deferred_id, element: element.children, delay: element.delay }
+        deferred_id = @request.defer(element.children, element.delay)
 
         fallback_value = element.fallback ? serialize_model(element.fallback) : nil
 
@@ -221,11 +218,7 @@ module Ruact
         metadata = @request.bundler_config.resolve(ref.module_id, ref.export_name)
 
         id = @request.allocate_id
-        @request.increment_pending
-
-        json = JSON.generate(metadata)
-        row  = RowEmitter.import(id, json)
-        @request.completed_import_chunks << row
+        @request.add_import(RowEmitter.import(id, JSON.generate(metadata)))
 
         lazy_ref = "$L#{id.to_s(16)}"
         @request.written_objects[ref] = lazy_ref

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
 
@@ -52,7 +57,9 @@ module Ruact
     end
 
     def initialize(component_registry)
-      @registry = component_registry
+      # Indexed once by token: each marker in the HTML is one lookup. Built
+      # without a pair array per entry (the render allocation guard counts them).
+      @registry = component_registry.each_with_object({}) { |entry, by_token| by_token[entry[:token]] = entry } # rubocop:disable Style/ReduceToHash
     end
 
     # Convert an HTML string into a ReactElement tree (instance form).
@@ -163,9 +170,13 @@ module Ruact
 
       when Nokogiri::XML::Node::COMMENT_NODE
         # Check if this is a Ruact component placeholder
-        token = node.content.strip
-        entry = @registry.find { |c| c[:token] == token }
-        return nil unless entry
+        token = Markers.comment_token(node)
+        entry = @registry[token]
+        unless entry
+          raise Ruact::HtmlConverterError, stale_component_message(token) if token.match?(TOKEN)
+
+          return nil
+        end
 
         Flight::ReactElement.new(
           type: entry[:ref],
@@ -181,8 +192,8 @@ module Ruact
 
     def convert_element(node)
       tag = node.name.downcase
-      return convert_suspense_element(node) if tag == "ruact-suspense"
-      return convert_component_with_children(node) if tag == ErbPreprocessor::WRAPPER_TAG
+      return convert_suspense_element(node) if tag == Markers::SUSPENSE_TAG
+      return convert_component_with_children(node) if tag == Markers::WRAPPER_TAG
 
       props = build_props(node, tag)
       children = convert_children(node)
@@ -196,9 +207,9 @@ module Ruact
     # component's `children` prop, converted like any element's; an empty pair
     # passes none, like `<Card />`.
     def convert_component_with_children(node)
-      token = node["data-ruact-token"]
-      entry = @registry.find { |c| c[:token] == token }
-      raise Ruact::HtmlConverterError, "ruact: no component registered for #{token.inspect}" unless entry
+      token = Markers.wrapper_token(node)
+      entry = @registry[token]
+      raise Ruact::HtmlConverterError, stale_component_message(token) unless entry
 
       props = entry[:props]
       children = convert_children(node)
@@ -208,39 +219,38 @@ 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 = node["data-ruact-fallback"] || ""
+      fallback_text = Markers.suspense_fallback(node)
       fallback = if fallback_text.empty?
                    nil
                  else
                    Flight::ReactElement.new(type: "p", key: nil, props: { "children" => fallback_text })
                  end
 
-      child_nodes = convert_children(node)
-      children = child_nodes.length == 1 ? child_nodes.first : child_nodes
-
       # Optional `delay="2.5"` from the ERB → SuspenseElement#delay (the
-      # server-side wait, in seconds, before the deferred chunk streams). When
-      # absent, blank, unparseable, or non-finite, SuspenseElement falls back to
-      # its default.
-      delay_attr = node["data-ruact-delay"]
-      delay = begin
-        if delay_attr && !delay_attr.to_s.strip.empty?
-          # A string overflow like "1e309" parses to Infinity (Float() does not
-          # raise) — guard finiteness so a non-finite delay can't reach the
-          # renderer's sleep(delay) and raise RangeError.
-          parsed = Float(delay_attr)
-          parsed.finite? ? parsed : nil
-        end
-      rescue ArgumentError, TypeError
-        nil
-      end
+      # server-side wait, in seconds, before the deferred row streams); nil
+      # when absent or unusable.
+      delay = Markers.suspense_delay(node)
+      Flight::SuspenseElement.new(fallback: fallback, children: suspense_children(node), delay: delay)
+    end
 
-      if delay
-        Flight::SuspenseElement.new(fallback: fallback, children: children, delay: delay)
-      else
-        Flight::SuspenseElement.new(fallback: fallback, children: children)
-      end
+    # The content of a Suspense wrapper: its converted children, or — when its
+    # block is rendered later — a reference to that block.
+    def suspense_children(node)
+      block = Markers.suspense_block(node)
+      return Flight::DeferredContent.new(block) if block
+
+      child_nodes = convert_children(node)
+      child_nodes.length == 1 ? child_nodes.first : child_nodes
     end
 
     def convert_children(node)

data/lib/ruact/inline_script.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ruact
+  # Internal — data written inside an inline `<script>` element.
+  #
+  # The Flight 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.
+  module InlineScript
+    UNSAFE = /[<>&\u2028\u2029]/
+
+    # A JSON string literal for +string+ that is safe inside a `<script>`.
+    # The payload is UTF-8 by construction (the serializer normalizes every
+    # string); a binary-tagged buffer is retagged, not transcoded.
+    def self.string_literal(string)
+      utf8 = string.encoding == Encoding::UTF_8 ? string : string.dup.force_encoding(Encoding::UTF_8)
+      JSON.generate(utf8).gsub(UNSAFE) { |char| format("\\u%04x", char.ord) }
+    end
+  end
+end

data/lib/ruact/load_async_note.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Story 19-1 (ADR D1) — in development, a `load_async` that cannot run in
+  # the background says so, once per process.
+  #
+  # `load_async` is how a page starts its queries early, so they finish while
+  # the shell is sent. Without `config.active_record.async_query_executor` —
+  # the default of a new Rails app — Active Record has no thread to run the
+  # query in and loads it where `load_async` is called, waiting for it, with no
+  # sign that it did. The note sits in `load_async` itself, not in every
+  # `<Suspense>`: an app that never calls it has nothing to fix.
+  #
+  # The other cases where Rails loads synchronously with the executor set
+  # (inside a transaction, a full queue) are in the guide, not here.
+  module LoadAsyncNote
+    MESSAGE = "[ruact] load_async ran its query where it was called and waited for it: " \
+              "config.active_record.async_query_executor is not set, so Active Record has no thread to run " \
+              "it in. Set `config.active_record.async_query_executor = :global_thread_pool` " \
+              "(config/application.rb) so a page's queries start early and finish while its shell is sent. " \
+              "(Said once.)"
+
+    # Prepended to ActiveRecord::Relation in development by the Railtie.
+    module Relation
+      def load_async
+        LoadAsyncNote.note(::ActiveRecord.async_query_executor)
+        super
+      end
+    end
+
+    # Logs {MESSAGE} the first time it is asked with no executor.
+    #
+    # @param executor [Symbol, nil] `ActiveRecord.async_query_executor`
+    # @return [void]
+    def self.note(executor)
+      return unless executor.nil?
+      return if @noted
+
+      @noted = true
+      Rails.logger&.warn(MESSAGE)
+      nil
+    end
+
+    # Forgets that it logged (specs).
+    #
+    # @api private
+    def self.reset!
+      @noted = false
+    end
+  end
+end

data/lib/ruact/markers.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Internal — what an evaluated template leaves in its HTML for
+  # {HtmlConverter} to turn into React elements: the protocol between
+  # evaluating a template and converting it.
+  #
+  # Three markers:
+  #
+  # - a client component: an HTML comment holding the token its
+  #   {RenderContext} entry was registered under — `<!-- __RUACT_a1b2c3d4_0__ -->`;
+  # - a client component with children: an element wrapped around the
+  #   children's HTML — `<ruact-component data-ruact-token="__RUACT_a1b2c3d4_0__">…`;
+  # - a Suspense boundary: an element wrapped around its content, carrying the
+  #   fallback text and the optional delay —
+  #   `<ruact-suspense data-ruact-fallback="Loading…">…</ruact-suspense>`. A
+  #   boundary whose content is rendered later is empty and carries the key
+  #   of its block in the {RenderContext} instead (`data-ruact-block="a1b2c3d4-0"`).
+  #
+  # Every token and key carries the id of the render that wrote it, so a
+  # marker a `cache` block stored in another render is never taken for one of
+  # this render's.
+  #
+  # {ErbPreprocessor} writes the ERB that produces them, the view helpers
+  # ({ViewHelper}, and {RenderPipeline} for a plain-ERB render) write the
+  # component markers, {HtmlConverter} reads all three. None of them spells
+  # these strings itself.
+  module Markers
+    # The element a paired component's content is wrapped in.
+    WRAPPER_TAG = "ruact-component"
+    WRAPPER_CLOSE = "</#{WRAPPER_TAG}>".freeze
+
+    # The element a Suspense boundary's content is wrapped in.
+    SUSPENSE_TAG = "ruact-suspense"
+    SUSPENSE_CLOSE = "</#{SUSPENSE_TAG}>".freeze
+
+    TOKEN_ATTR    = "data-ruact-token"
+    FALLBACK_ATTR = "data-ruact-fallback"
+    DELAY_ATTR    = "data-ruact-delay"
+    BLOCK_ATTR    = "data-ruact-block"
+
+    # The marker for a client component, by its render-context token.
+    def self.component(token)
+      "<!-- #{token} -->"
+    end
+
+    # The opening of a client component with children; {WRAPPER_CLOSE} ends it.
+    def self.component_open(token)
+      %(<#{WRAPPER_TAG} #{TOKEN_ATTR}="#{token}">)
+    end
+
+    # The opening of a Suspense boundary, from the `fallback` and `delay`
+    # attribute values as written in the template. Only `"` is escaped: the
+    # rest of the text stays as the template wrote it (entities included, which
+    # the HTML parser then decodes). The preprocessor refuses ERB in either.
+    # +block+ is the key of the boundary's content in the render context,
+    # when that content is rendered later.
+    def self.suspense_open(fallback, delay, block: nil)
+      delay_attr = delay ? %( #{DELAY_ATTR}="#{delay.gsub('"', '&quot;')}") : ""
+      block_attr = block ? %( #{BLOCK_ATTR}="#{block}") : ""
+      %(<#{SUSPENSE_TAG} #{FALLBACK_ATTR}="#{fallback.gsub('"', '&quot;')}"#{delay_attr}#{block_attr}>)
+    end
+
+    # The token a component marker (an HTML comment node) carries.
+    def self.comment_token(node)
+      node.content.strip
+    end
+
+    # The token a component-with-children wrapper carries.
+    def self.wrapper_token(node)
+      node[TOKEN_ATTR]
+    end
+
+    # The fallback text of a Suspense wrapper ("" when there is none).
+    def self.suspense_fallback(node)
+      node[FALLBACK_ATTR] || ""
+    end
+
+    # The key of the block a Suspense wrapper's content is rendered from
+    # later, or nil when the content is in the wrapper.
+    def self.suspense_block(node)
+      node[BLOCK_ATTR]
+    end
+
+    # The delay of a Suspense wrapper, in seconds, or nil when it is absent,
+    # blank, unparseable or not finite (`"1e309"` parses to Infinity without
+    # raising, and must not reach a `sleep`).
+    def self.suspense_delay(node)
+      value = node[DELAY_ATTR]
+      return nil if value.nil? || value.to_s.strip.empty?
+
+      parsed = Float(value)
+      parsed.finite? ? parsed : nil
+    rescue ArgumentError, TypeError
+      nil
+    end
+  end
+end

data/lib/ruact/navigation_boundary.rb

@@ -37,7 +37,7 @@ module Ruact
       end
 
       def call(env)
-        return @app.call(env) unless env["HTTP_RUACT_REQUEST"] == "1"
+        return @app.call(env) unless RequestKind.from_router?(env)
         return native_response if @classifier.classify(env) == :native
 
         @app.call(env)
@@ -60,7 +60,7 @@ module Ruact
         headers[HEADER] = NATIVE
         headers["content-type"] = "text/plain; charset=utf-8"
         headers["cache-control"] = "no-store"
-        headers["vary"] = "Ruact-Request"
+        headers["vary"] = RequestKind::ROUTER_HEADER
         headers
       end
     end