ruact 0.0.19 → 0.0.20

data/lib/ruact/erb_preprocessor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "ripper"
+
 module Ruact
   # Transforms ERB source before Ruby evaluation.
   #
@@ -34,6 +36,10 @@ module Ruact
     SUSPENSE_OPEN_RE  = /<Suspense\b([^>]*?)>/m
     SUSPENSE_CLOSE_RE = %r{</Suspense\s*>}
 
+    # Any Suspense tag: capture 1 is the slash of a closing tag, capture 2 the
+    # attributes, capture 3 the slash of a self-closing one.
+    SUSPENSE_TAG_RE = %r{<(/)?Suspense\b([^>]*?)(/)?>}m
+
     # Matches ANY PascalCase component tag: opening (`<Card>`), self-closing
     # (`<Card />`), or closing (`</Card>`). Capture 1 is the leading slash
     # (present only on a closing tag); capture 2 is the name. The pairing scan
@@ -48,22 +54,36 @@ module Ruact
     # Newline-preserving mask for ERB islands (`<% … %>`, `<%= … %>`, `<%# … %>`).
     # The pairing scan blanks these first so a `</Card>` that lives inside
     # Ruby/ERB string or comment text is never taken for a real closing tag.
-    ERB_ISLAND_RE = /<%.*?%>/m
+    # `<%%` is ERB's escape for a literal `<%`: text, not an island.
+    ERB_ISLAND_RE = /<%(?!%).*?%>/m
 
     # An ERB comment, which renders nothing.
     ERB_COMMENT_RE = /<%#.*?%>/m
 
-    # The element a paired component's content is wrapped in until
-    # {HtmlConverter} turns it into the component's `children`.
-    WRAPPER_TAG = "ruact-component"
+    # What ends a `<Suspense>`: the {ViewHelper#__ruact_suspense__} block its
+    # content is the body of. The empty output tag after it keeps Rails' ERB
+    # from trimming a `</Suspense>` that sits alone on its line, which would eat
+    # the line break after it (text the page shows).
+    SUSPENSE_BLOCK_CLOSE = %(<% end %><%= "" %>)
+
+    # Ripper node types inside which `break`, `next`, `redo`, `return`, `it`
+    # and `_1` belong to a block of their own, not to the Suspense's block.
+    OWN_BLOCK_NODES = %i[brace_block do_block lambda def defs class module sclass].freeze
+    # Loops give `break`, `next` and `redo` a scope of their own, but not `it`
+    # or `_1`, which still name the enclosing block's parameter.
+    LOOP_NODES = %i[while until while_mod until_mod for].freeze
+    LOOP_WORDS = %w[break next redo].freeze
+
+    # One ERB tag's flag (`=`, `==`, `-`, or `#` for a comment) and its Ruby code.
+    ERB_CODE_RE = /<%(?!%)(==|=|-|#)?(.*?)-?%>/m
 
     # What each helper the transformed template calls leaves in the HTML, by
     # its render-context token: a component, or the opening of one with
-    # children. {RenderPipeline} installs these for a plain-ERB render;
-    # ViewHelper writes the same strings in ActionView.
+    # children ({Markers}). {RenderPipeline} installs these for a plain-ERB
+    # render; ViewHelper writes the same markers in ActionView.
     PLACEHOLDERS = {
-      __ruact_component__: ->(token) { "<!-- #{token} -->" },
-      __ruact_component_open__: ->(token) { %(<#{WRAPPER_TAG} data-ruact-token="#{token}">) }
+      __ruact_component__: ->(token) { Markers.component(token) },
+      __ruact_component_open__: ->(token) { Markers.component_open(token) }
     }.freeze
 
     # Transform ERB source, replacing component tags with ERB placeholders.
@@ -90,29 +110,188 @@ module Ruact
       # Step 1: component tags → ERB placeholders. Story 18-2: a tag with a
       # matching closing tag is a component WITH children; its content stays
       # ERB, evaluated in place, inside a wrapper element.
+      # Suspense pairs are checked on the template as written, so an error names
+      # the template's own line.
+      check_suspense!(source) if source.include?("Suspense")
+
       result = if source.match?(CLOSING_TAG_PROBE_RE)
                  rewrite_paired(source)
                else
                  rewrite_self_closing(source)
                end
 
-      # Step 2: <Suspense> paired tags → <ruact-suspense> HTML elements.
-      result
-        .gsub(SUSPENSE_OPEN_RE) do
-          attrs    = ::Regexp.last_match(1)
-          fallback = extract_string_attr(attrs, "fallback") || ""
-          escaped  = fallback.gsub('"', "&quot;")
-          # Optional `delay="2.5"` — the server-side wait (seconds) before
-          # the deferred chunk streams. Forwarded to SuspenseElement#delay.
-          delay      = extract_string_attr(attrs, "delay")
-          delay_attr = delay ? %( data-ruact-delay="#{delay.gsub('"', '&quot;')}") : ""
-          %(<ruact-suspense data-ruact-fallback="#{escaped}"#{delay_attr}>)
-        end
-        .gsub(SUSPENSE_CLOSE_RE, "</ruact-suspense>")
+      rewrite_suspense(result)
     end
 
     private
 
+    # Step 2: `<Suspense>` pairs. Each pair becomes a
+    # {ViewHelper#__ruact_suspense__} call whose block is what sits between the
+    # tags; the helper writes the Suspense marker around it ({Markers}), and
+    # decides when the block is evaluated. `delay="2.5"` is optional: the
+    # server-side wait (seconds) before the deferred chunk streams, forwarded to
+    # SuspenseElement#delay. `<Suspense ... />` is a pair with nothing in it. A
+    # tag inside an ERB island is Ruby text and is left alone. The generated ERB
+    # keeps the tag's line breaks, so later lines keep their numbers.
+    def rewrite_suspense(source)
+      return source unless source.include?("Suspense")
+
+      out = +""
+      cursor = 0
+      suspense_tags(source).each do |tag|
+        out << source[cursor...tag[:from]]
+        out << rewrite_suspense_tag(tag, source[tag[:from]...tag[:to]].count("\n"))
+        cursor = tag[:to]
+      end
+      out << source[cursor..]
+    end
+
+    # Every Suspense tag outside an ERB island, in order.
+    def suspense_tags(source)
+      tags = []
+      mask_erb(source).scan(SUSPENSE_TAG_RE) do
+        m = ::Regexp.last_match
+        kind = if m[1] then :close
+               elsif m[3] then :empty
+               else :open
+               end
+        tags << { kind: kind, from: m.begin(0), to: m.end(0), attrs: source[m.begin(2)...m.end(2)] }
+      end
+      tags
+    end
+
+    # Every `<Suspense>` has its `</Suspense>` (as a component tag does, Story
+    # 18-2), in the same ERB block — the helper call it becomes opens a Ruby
+    # block that the closing tag ends — and takes literal attribute values.
+    # Raises {ComponentTagError} / {PreprocessorError} with the line.
+    def check_suspense!(source)
+      open = []
+      suspense_tags(source).each do |tag|
+        case tag[:kind]
+        when :open then open << tag
+        when :close
+          opening = open.pop
+          raise_stray("Suspense", line_at(source, tag[:from])) if opening.nil?
+          check_same_block!(source, opening, tag)
+        end
+        check_literal_attributes!(source, tag) unless tag[:kind] == :close
+      end
+      return if open.empty?
+
+      raise ComponentTagError,
+            "ruact: <Suspense> at #{location(line_at(source, open.first[:from]))} is never closed — close it with " \
+            "`</Suspense>`."
+    end
+
+    # The Ruby of the ERB tags between a pair has to stand on its own: an `if`
+    # or a block opened or closed between them would take the pair's `end`.
+    # Parsed inside parentheses, which no `end` in it can close, within a
+    # method and a block, where `yield`, `next` and `return` are Ruby. When the
+    # template's Ruby does not parse at all, Rails reports that, with its line.
+    #
+    # The content is then the body of a block, so `break`, `next`, `return`,
+    # `it` and `_1` written at its own level would apply to that block, not to
+    # the loop or block around the Suspense: refused, with what to do instead.
+    def check_same_block!(source, opening, closing)
+      tree = parse_erb_code(source[opening[:to]...closing[:from]])
+      if tree.nil?
+        return if parse_erb_code(source).nil?
+
+        raise ComponentTagError,
+              "ruact: <Suspense> at #{location(line_at(source, opening[:from]))} and its </Suspense> at line " \
+              "#{line_at(source, closing[:from])} are not in the same ERB block — an `if`, a loop or a block opens " \
+              "or closes between them. Put both tags inside that block, or both outside it."
+      end
+
+      word = escaping_word(first_node(tree, :paren))
+      return unless word
+      return if word == "it" && it_is_a_local?(source[0...opening[:from]])
+
+      advice = word.start_with?("_") || word == "it" ? "Name the block's parameter." : "Move it outside the Suspense."
+      raise ComponentTagError,
+            "ruact: <Suspense> at #{location(line_at(source, opening[:from]))} — `#{word}` between its tags would " \
+            "apply to the Suspense's own block, not to the loop or block around it. #{advice}"
+    end
+
+    # The Ripper tree of the Ruby in +erb+'s tags (comments left out), as the
+    # body of a block in a method, in parentheses; nil when it does not parse.
+    def parse_erb_code(erb)
+      code = erb.to_enum(:scan, ERB_CODE_RE).filter_map do
+        m = ::Regexp.last_match
+        m[2] unless m[1] == "#"
+      end
+      Ripper.sexp("def __ruact_check\nproc do\n(\n#{code.join("\n")}\n)\nend\nend")
+    end
+
+    # The first node of +type+ in +tree+, depth first: for {#parse_erb_code}'s
+    # tree, the parentheses the template's code sits in.
+    def first_node(tree, type)
+      return nil unless tree.is_a?(Array)
+      return tree if tree.first == type
+
+      tree.each do |child|
+        found = first_node(child, type)
+        return found if found
+      end
+      nil
+    end
+
+    # The first `break`, `next`, `redo`, `return`, implicit `it` or numbered
+    # parameter that would apply to the Suspense's block, if any. +in_loop+:
+    # inside a loop of the content's own, where only `it` and `_1` still do.
+    def escaping_word(node, in_loop: false)
+      return nil unless node.is_a?(Array)
+      return nil if OWN_BLOCK_NODES.include?(node.first)
+
+      word = escaping_word_at(node)
+      return word if word && !(in_loop && LOOP_WORDS.include?(word))
+
+      in_loop ||= LOOP_NODES.include?(node.first)
+      node.each do |child|
+        found = escaping_word(child, in_loop: in_loop)
+        return found if found
+      end
+      nil
+    end
+
+    def escaping_word_at(node)
+      case node.first
+      when :break, :next, :redo, :return then node.first.to_s
+      when :return0 then "return"
+      when :vcall then "it" if node.dig(1, 1) == "it"
+      when :var_ref then node.dig(1, 1) if node.dig(1, 1).to_s.match?(/\A_[1-9]\z/)
+      end
+    end
+
+    # Whether the template before a `<Suspense>` makes `it` a local variable —
+    # a block parameter (`|it|`) or an assignment — in which case `it` between
+    # the tags is that variable, as Ruby would read it. (A partial's local
+    # named `it` is not seen here.)
+    def it_is_a_local?(before)
+      before.to_enum(:scan, ERB_CODE_RE).any? do
+        code = ::Regexp.last_match(2)
+        code.match?(/\|[^|]*\bit\b[^|]*\|/) || code.match?(/\bit\s*(?:=(?![=~>])|\|\|=|&&=)/)
+      end
+    end
+
+    def check_literal_attributes!(source, tag)
+      return unless tag[:attrs].include?("<%") || tag[:attrs].include?("%>")
+
+      raise PreprocessorError,
+            "ruact: <Suspense> at #{location(line_at(source, tag[:from]))} — `fallback` and `delay` take literal " \
+            "text, not ERB."
+    end
+
+    def rewrite_suspense_tag(tag, line_breaks)
+      breaks = "\n" * line_breaks
+      return %(<% end #{breaks}%><%= "" %>) if tag[:kind] == :close
+
+      fallback = extract_string_attr(tag[:attrs], "fallback") || ""
+      delay    = extract_string_attr(tag[:attrs], "delay")
+      opening  = %(<%= __ruact_suspense__(#{fallback.inspect}, #{delay.inspect}) do #{breaks}%>)
+      tag[:kind] == :empty ? opening + SUSPENSE_BLOCK_CLOSE : opening
+    end
+
     # The common path: no PascalCase closing tag anywhere, so every component
     # tag should be self-closing. One gsub, no masking copies — the render
     # benchmark's allocation profile depends on it. An opening tag that is not
@@ -188,7 +367,7 @@ module Ruact
     end
 
     def rewrite_tag(source, tag, paired)
-      return "</#{WRAPPER_TAG}>" if tag[:closing]
+      return Markers::WRAPPER_CLOSE if tag[:closing]
 
       kind = if !paired.key?(tag[:from]) then :self_closing
              elsif paired[tag[:from]] then :with_children
@@ -248,6 +427,8 @@ module Ruact
     # allocation.
     def inside_erb?(source, offset)
       opened = source.rindex("<%", offset)
+      # `<%%` is a literal `<%`, not an island: look further back.
+      opened = opened.positive? ? source.rindex("<%", opened - 1) : nil while opened && source[opened + 2] == "%"
       return false unless opened
 
       closed = source.index("%>", opened + 2)

data/lib/ruact/flight/react_element.rb

@@ -16,17 +16,32 @@ module Ruact
 
     # Represents a React Suspense boundary.
     # `fallback` is a ReactElement shown while the deferred content is loading.
-    # `children` is the actual content (emitted as a deferred row after `delay` seconds).
+    # `children` is the content, emitted as a deferred row after the shell: an
+    # element tree, or a {DeferredContent} rendered when its row is due.
+    # `delay` is the wait, in seconds, before that row when the response
+    # streams; nil waits nothing.
     class SuspenseElement
       attr_reader :fallback, :children, :delay
 
-      def initialize(fallback:, children:, delay: 1.5)
+      def initialize(fallback:, children:, delay: nil)
         @fallback  = fallback
         @children  = children
         @delay     = delay
       end
     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 —
+    # it defers a boundary's children without looking at them, and the caller
+    # of {Renderer#take_boundary} renders it.
+    class DeferredContent
+      attr_reader :index
+
+      def initialize(index)
+        @index = index
+      end
+    end
+
     # Points to a "use client" module — will become an I row + $L<id> reference.
     class ClientReference
       attr_reader :module_id, :export_name

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,88 @@ 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
+        if boundary[:element].is_a?(DeferredContent)
+          raise Ruact::Error, "ruact: Renderer#next_boundary cannot render a block; use #take_boundary"
+        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