ruact 0.0.19 → 0.0.21

data/lib/ruact/deferred_render.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "json"
+require "timeout"
+
+module Ruact
+  # Story 19-1 — the render of a page whose `<Suspense>` content runs after the
+  # shell is sent: the shell first, then each boundary, one at a time, in page
+  # order, each block evaluated only when its row is due.
+  #
+  #   run = DeferredRender.new(html, render_context, pipeline)
+  #   write(run.shell)
+  #   write(run.next_rows) while run.pending?
+  #
+  # A block runs in the view it was written in, with the template path Rails
+  # had when it met the tag, under `Ruact.config.suspense_timeout`. A block
+  # that raises, or runs past the timeout, becomes an error row for its
+  # boundary — reported through `Rails.error` and logged — and the next block
+  # runs. {Flight::Renderer} only ever serializes elements: evaluating, logging
+  # and reporting are here, outside `lib/ruact/flight/` (NFR10).
+  #
+  # Internal API: not part of the public compatibility contract.
+  class DeferredRender
+    TIMEOUT_DIGEST = "ruact:suspense-timeout"
+    ERROR_DIGEST   = "ruact:suspense-error"
+
+    # The content ran past `suspense_timeout`. Its own: a `Timeout::Error` the
+    # content raised itself (`Net::ReadTimeout` is one) is the content's error.
+    class Expired < StandardError; end
+
+    # What production says about a block that raised: nothing of the error.
+    PRODUCTION_MESSAGE = "An error occurred in a <Suspense>"
+
+    # React's development client reads an error's `stack` as frames; a few
+    # name the template and the gem without burying the overlay.
+    STACK_FRAMES = 12
+
+    # @param html [String] the page ActionView rendered with its blocks kept
+    #   (`RenderContext.new(deferring: true)`)
+    # @param pipeline [RenderPipeline] the manifest, controller path, logger
+    #   and wire flavour the render uses
+    # @param guard [#call, nil] wraps each block's evaluation, inside the
+    #   timeout: called with a block, returns its value or raises (the
+    #   controller's development check for writes the response can no longer
+    #   carry)
+    def initialize(html, render_context, pipeline, guard: nil)
+      @render_context  = render_context
+      @manifest        = pipeline.manifest
+      @controller_path = pipeline.controller_path
+      @development     = pipeline.development
+      @logger          = pipeline.logger
+      @guard           = guard
+      @registry        = []
+      @renderer = Flight::Renderer.new(convert(html), @manifest,
+                                       strict_serialization: Ruact.config.strict_serialization,
+                                       on_as_json_warning: pipeline.as_json_warning_callback,
+                                       development: @development)
+    end
+
+    # The shell's rows, as one string.
+    def shell
+      @renderer.shell.join
+    end
+
+    # Whether a boundary is still to be rendered.
+    def pending?
+      @renderer.pending?
+    end
+
+    # How many boundaries are still to be rendered.
+    def pending_count
+      @renderer.pending_count
+    end
+
+    # Renders the next boundary and returns its rows, as one string: the rows
+    # its content brings and its model row, or an error row.
+    def next_rows
+      boundary = @renderer.take_boundary
+      within_timeout(boundary[:delay]) do
+        @renderer.boundary_rows(boundary[:id], content(boundary[:element]))
+      end.join
+    rescue StandardError => e
+      raise if boundary.nil?
+
+      skip_unconverted_components
+      report(e, boundary)
+      @renderer.error_rows(boundary[:id], error_payload(e), boundary: boundary).join
+    end
+
+    private
+
+    # A block that failed may have registered components its HTML, now thrown
+    # away, was going to use: the next block's conversion starts after them.
+    def skip_unconverted_components
+      @registry.fill(nil, @registry.length...@render_context.components.length)
+    end
+
+    # The block's HTML as elements; content that is already elements as is.
+    def content(element)
+      return element unless element.is_a?(Flight::DeferredContent)
+
+      block = @render_context.block(element.key)
+      raise Ruact::Error, Flight::DeferredContent::STALE if block.nil?
+
+      html = @guard ? @guard.call { evaluate(block) } : evaluate(block)
+      convert(html)
+    end
+
+    # Runs the block in its view, with the template path and its local
+    # variables as they were when the tag was met, and returns what it wrote.
+    # Only what it writes: a value it ends on is not content.
+    def evaluate(pending)
+      declared = DeclaredContent.take(pending.view) if @development
+      html = with_locals(pending.block, pending.locals) { run_in_view(pending) }
+      DeclaredContent.check!(pending.view, declared) if declared
+      html
+    end
+
+    def run_in_view(pending)
+      pending.view.instance_exec(pending) do |entry|
+        saved = [@virtual_path, @current_template]
+        @virtual_path = entry.virtual_path
+        @current_template = entry.template
+        begin
+          capture do
+            entry.block.call
+            nil
+          end
+        ensure
+          @virtual_path, @current_template = saved
+        end
+      end
+    end
+
+    # Sets the block's local variables to +locals+ while it runs, and back
+    # after. A block shares them with the template and with the blocks met
+    # after it.
+    def with_locals(block, locals)
+      return yield if locals.nil? || locals.empty?
+
+      scope = block.binding
+      now = locals.keys.to_h { |name| [name, scope.local_variable_get(name)] }
+      locals.each { |name, value| scope.local_variable_set(name, value) }
+      begin
+        yield
+      ensure
+        now.each { |name, value| scope.local_variable_set(name, value) }
+      end
+    end
+
+    # The components registered since the last conversion are resolved and
+    # added: a block registers its own as it runs. One the manifest cannot
+    # resolve fails this conversion and keeps its place (nil), so the next
+    # block does not meet it again.
+    def convert(html)
+      failure = nil
+      @render_context.components.drop(@registry.length).each do |entry|
+        @registry << @render_context.resolve_entry(entry, @manifest, controller_path: @controller_path)
+      rescue StandardError => e
+        @registry << nil
+        failure ||= e
+      end
+      raise failure if failure
+
+      HtmlConverter.convert(html.to_s, @registry.compact)
+    end
+
+    # The block's `delay` and the block itself, within `suspense_timeout`.
+    # `Timeout.timeout` with no exception class unwinds the block with an
+    # exception that is not a StandardError, so a `rescue` in the view, or
+    # Active Record wrapping what a query raised, cannot take it; it raises
+    # `Timeout::Error` out here. It interrupts Ruby code, not a query running
+    # inside a database driver that holds the VM lock (measured in 19-0).
+    # A `delay` longer than the limit ends in the timeout row at once, as it
+    # did before blocks ran later.
+    def within_timeout(delay, &)
+      limit = Ruact.config.suspense_timeout
+      return wait_then(delay, &) unless limit&.positive?
+      raise Expired, "the delay (#{delay}s) is longer than suspense_timeout" if delay && delay > limit
+
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      # A query still running at the limit is cancelled on the server, so its
+      # connection is free again (Story 19-2, QueryWatch).
+      owner = QueryWatch.current_owner
+      watch = QueryWatch.start(owner, limit)
+      begin
+        Timeout.timeout(limit) { wait_then(delay, &) }
+      rescue StandardError => e
+        raise unless expired?(e, started, limit, watch)
+
+        watch&.cancel_now(owner)
+        raise Expired, "ran past suspense_timeout (#{limit}s)", cause: e
+      ensure
+        watch&.stop
+      end
+    end
+
+    # A `Timeout::Error` is ours only when the limit has passed; earlier, it is
+    # the content's. Any other error is ours when the watch cancelled a query
+    # at the limit: what the cancelled query raised.
+    def expired?(error, started, limit, watch)
+      return watch&.cancelled? || false unless error.is_a?(Timeout::Error)
+
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) - started >= limit
+    end
+
+    def wait_then(delay)
+      sleep(delay) if delay&.positive?
+      yield
+    end
+
+    def timed_out?(error)
+      error.is_a?(Expired)
+    end
+
+    def error_payload(error)
+      return Flight::RowEmitter.error_payload("Suspense timeout exceeded", digest: TIMEOUT_DIGEST) if timed_out?(error)
+      return Flight::RowEmitter.error_payload(PRODUCTION_MESSAGE, digest: ERROR_DIGEST) unless @development
+
+      payload = Flight::RowEmitter.error_payload("#{error.class}: #{error.message}", digest: ERROR_DIGEST)
+      payload["stack"] = development_stack(error)
+      payload
+    end
+
+    # React's development client reads each frame of `stack` as
+    # `[function, file, line, column, enclosing line, enclosing column]` and
+    # rebuilds the server's call stack from it. A four-element frame (what this
+    # sent before Story 19-2) left the last two undefined, and every frame came
+    # out at line 2. Ruby has no column and no enclosing function: column 1,
+    # enclosing 0 (none).
+    def development_stack(error)
+      Array(error.backtrace).first(STACK_FRAMES).filter_map do |frame|
+        match = frame.match(/\A(.+?):(\d+)(?::in [`'](.+)')?\z/)
+        match && [match[3] || "(ruby)", match[1], Integer(match[2], 10), 1, 0, 0]
+      end
+    end
+
+    def report(error, boundary)
+      what = timed_out?(error) ? "ran past suspense_timeout (#{Ruact.config.suspense_timeout}s)" : "raised"
+      @logger&.error("[ruact] <Suspense> content#{where(boundary)} #{what}: #{error.class}: #{error.message}")
+      return unless defined?(Rails) && Rails.respond_to?(:error)
+
+      Rails.error.report(error, handled: true, severity: :error, source: "ruact.suspense")
+    end
+
+    def where(boundary)
+      element = boundary[:element]
+      return "" unless element.is_a?(Flight::DeferredContent)
+
+      location = @render_context.block(element.key)&.location
+      location ? " at #{location.path}:#{location.lineno}" : ""
+    end
+  end
+end

data/lib/ruact/doctor.rb

@@ -8,7 +8,7 @@ module Ruact
   # Runs a suite of installation health checks and prints ✓/✗ per check.
   # Extracted from the ruact:doctor Rake task for direct testability (FR27).
   class Doctor # rubocop:disable Metrics/ClassLength
-    CHECKS = %i[manifest vite flight_client controller layout head_assets streaming legacy_constant
+    CHECKS = %i[manifest vite flight_client controller layout head_assets streaming load_async legacy_constant
                 serialize_only flight_middleware].freeze
     # Built via Array#join so the gem-CI `name-propagation` guard does not
     # match these literals against itself (Story 5.1 review F4 — the doctor
@@ -484,7 +484,47 @@ module Ruact
     def check_streaming
       mode  = Ruact.streaming_mode || :buffered
       label = mode == :enabled ? "enabled" : "buffered"
-      [:pass, "streaming: #{label} (#{streaming_server_hint})"]
+      message = "streaming: #{label} (#{streaming_server_hint})"
+      declaring = streaming_controllers.length
+      return [:pass, message] if declaring.zero?
+
+      # Story 19-2 (AC20) — the doctor sees no request: what it can say is
+      # where a page that streams silently does not.
+      [:pass, "#{message}; #{pluralize_count(declaring, 'controller')} #{declaring == 1 ? 'streams' : 'stream'} " \
+              "(ruact_streaming or ActionController::Live) — behind a proxy, the app must be reached over " \
+              "HTTP/1.1 (nginx: `proxy_http_version 1.1;`), or those pages are sent whole",
+       PROXY_HTTP11]
+    end
+
+    # Story 19-2 (AC20) — what makes a proxy talk HTTP/1.1 to the app.
+    PROXY_HTTP11 = "Behind nginx, set `proxy_http_version 1.1;` where it proxies to the app: by default it " \
+                   "talks HTTP/1.0 upstream, and a page declared with ruact_streaming is then sent whole " \
+                   "(the app logs it once)."
+    private_constant :PROXY_HTTP11
+
+    # Controller files that declare `ruact_streaming` or include
+    # `ActionController::Live`. Reads source, as {#island_controllers} does.
+    def streaming_controllers
+      Dir.glob(Rails.root.join("app", "controllers", "**", "*.rb").to_s).select do |file|
+        File.read(file).match?(/^\s*(ruact_streaming\b|include\s+ActionController::Live\b)/)
+      end
+    end
+
+    # Story 19-1 (ADR D1) — whether `load_async` runs its query in the
+    # background. It is how a page starts its queries early, so they finish
+    # while the shell is sent; without an executor (a new Rails app's default)
+    # it loads where it is called. A warning, not a failure: an app that never
+    # calls `load_async` has nothing to fix.
+    def check_load_async
+      return [:pass, "load_async: Active Record is not loaded"] unless defined?(::ActiveRecord::Base)
+
+      executor = ::ActiveRecord.async_query_executor
+      return [:pass, "load_async: runs in the background (async_query_executor = #{executor.inspect})"] if executor
+
+      [:warn,
+       "load_async: runs its query where it is called — config.active_record.async_query_executor is not " \
+       "set. Set it to :global_thread_pool (config/application.rb) so a page's queries start early and " \
+       "finish while its shell is sent."]
     end
 
     # Detects host-app references to the legacy gem constant or require path

data/lib/ruact/erb_preprocessor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "ripper"
+
 module Ruact
   # Transforms ERB source before Ruby evaluation.
   #
@@ -12,7 +14,7 @@ module Ruact
   #   <%= __ruact_component__("LikeButton", { "postId" => @post.id, "initialCount" => 5 }) %>
   #
   # The placeholder is replaced by an HTML comment with a unique token:
-  #   <!-- __RUACT_0__ -->
+  #   <!-- __RUACT_a1b2c3d4_0__ -->
   #
   # A component with children (Story 18-2) keeps its content as ERB, inside a
   # wrapper element HtmlConverter turns into the component's `children`:
@@ -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
@@ -220,7 +399,13 @@ module Ruact
       props_ruby = pairs.map { |prop, expr| "#{prop.inspect} => #{expr}" }.join(", ")
       props_hash = props_ruby.empty? ? "{}" : "{ #{props_ruby} }"
       helper = kind == :self_closing ? "__ruact_component__" : "__ruact_component_open__"
-      %(<%= #{helper}(#{name.inspect}, #{props_hash}) %>)
+      # Story 19-2 — a tag written over several lines keeps them, so every
+      # line below it is still the template's own in an error and a backtrace
+      # (the props' own code carries the line breaks it has). Nothing is
+      # allocated for a tag on one line: the guard on allocations counts
+      # every component.
+      missing = match.count("\n") - props_hash.count("\n")
+      %(<%= #{helper}(#{name.inspect}, #{props_hash}) #{"\n" * missing if missing.positive?}%>)
     rescue ComponentContractError, ComponentTagError, UnknownComponentError
       # Already carry file:line and the fix — re-raise AS-IS (do NOT append the
       # generic "at line N: snippet" tail).
@@ -248,6 +433,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,37 @@ 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
+    # key of its block in the render context. The serializer never sees one —
+    # it defers a boundary's children without looking at them, and the caller
+    # of {Renderer#take_boundary} renders it.
+    class DeferredContent
+      # Story 19-2 — what a boundary says when its marker came out of a `cache`
+      # block another render wrote: its content was never in the fragment.
+      STALE = "A <Suspense> inside `cache` was read from the cache, and its content is not in the " \
+              "cached fragment: put the <Suspense> outside the `cache` block (cache what is inside it)."
+
+      attr_reader :key
+
+      def initialize(key)
+        @key = key
+      end
+    end
+
     # Points to a "use client" module — will become an I row + $L<id> reference.
     class ClientReference
       attr_reader :module_id, :export_name