ruact 0.0.16 → 0.0.18

data/lib/ruact/erb_preprocessor.rb

@@ -14,186 +14,289 @@ module Ruact
   # The placeholder is replaced by an HTML comment with a unique token:
   #   <!-- __RUACT_0__ -->
   #
+  # A component with children (Story 18-2) keeps its content as ERB, inside a
+  # wrapper element HtmlConverter turns into the component's `children`:
+  #
+  #   <Card title={@t}><p><%= @body %></p></Card>
+  #   → <%= __ruact_component_open__("Card", { "title" => @t }) %><p><%= @body %></p></ruact-component>
+  #
   # The actual ClientReference + props are registered in the binding and
   # collected by HtmlConverter after the ERB renders.
-  class ErbPreprocessor
+  class ErbPreprocessor # rubocop:disable Metrics/ClassLength
     # Matches a PascalCase opening tag with optional attributes and optional self-closing.
     # Examples:
     #   <Button />
     #   <LikeButton postId={@post.id} initialCount={5} />
-    #   <Dialog open={true}>
+    #   <Card title={@post.title}>
     COMPONENT_TAG_RE = %r{<([A-Z][A-Za-z0-9]*)(\s[^>]*)?\s*/?>}
 
     # Matches <Suspense ...> opening tags (handled before general PascalCase processing).
     SUSPENSE_OPEN_RE  = /<Suspense\b([^>]*?)>/m
-    SUSPENSE_CLOSE_RE = %r{</Suspense>}
-
-    # Story 15.2 (FR106) — 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 loud-children detection scans these left-to-right with a stack: an
-    # opening pushes, a self-closing (`/>`) is ignored, and a closing that pops a
-    # matching opening means that opening had children (paired usage) → loud
-    # error. A single linear pass (no backreference/lazy backtracking) keeps the
-    # component-dense fast path linear regardless of how many tags go unclosed.
-    COMPONENT_ANY_TAG_RE = %r{<(/)?([A-Z][A-Za-z0-9]*)(?:\s[^>]*)?>}
+    SUSPENSE_CLOSE_RE = %r{</Suspense\s*>}
+
+    # 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
+    # walks these left to right with one stack (Story 18-2).
+    COMPONENT_ANY_TAG_RE = %r{<(/)?([A-Z][A-Za-z0-9]*)(?:\s[^>]*|/)?>}
 
     # Cheap allocation-free probe (`String#match?`) for "is there ANY PascalCase
-    # closing tag at all?". The loud-children scan only matters when one exists,
-    # so this gates the (copy-heavy) mask/scan work off the common all-self-
-    # closing fast path. `</Suspense>` matches too — harmless, it gets masked.
-    CLOSING_TAG_PROBE_RE = %r{</[A-Z][A-Za-z0-9]*>}
+    # closing tag at all?". Without one there is nothing to pair, so the
+    # template takes the single-pass path; `</Suspense>` matches too — harmless.
+    CLOSING_TAG_PROBE_RE = %r{</[A-Z][A-Za-z0-9]*[\s/>]}
 
     # Newline-preserving mask for ERB islands (`<% … %>`, `<%= … %>`, `<%# … %>`).
-    # The loud-children scan blanks these first so a `</Card>` that lives inside
-    # Ruby/ERB string or comment text can never be mistaken for a real component
-    # closing tag (a valid bare `<Dialog>` opening must not error because some
-    # unrelated `<% "</Dialog>" %>` appears later).
+    # 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
 
+    # 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 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.
+    PLACEHOLDERS = {
+      __ruact_component__: ->(token) { "<!-- #{token} -->" },
+      __ruact_component_open__: ->(token) { %(<#{WRAPPER_TAG} data-ruact-token="#{token}">) }
+    }.freeze
+
     # Transform ERB source, replacing component tags with ERB placeholders.
     # Returns the transformed source string.
     #
     # +identifier+ is the template path (forwarded by {ErbPreprocessorHook} as
-    # +template.identifier+) so a Story 13.5 contract violation can name the
-    # call site's file:line. +registry+ is the component contract source — an
-    # injectable seam (Story 7.1 explicit-context grain); it defaults to the
-    # process-loaded {Ruact.manifest}. Pass +registry: nil+ (or a stub) in
-    # specs to control contract lookup; +nil+ forces fail-open (no validation).
+    # +template.identifier+) so an error can name the call site's file:line.
+    # +registry+ is the component contract source — an injectable seam (Story
+    # 7.1 explicit-context grain); it defaults to the process-loaded
+    # {Ruact.manifest}. Pass +registry: nil+ (or a stub) in specs to control
+    # contract lookup; +nil+ forces fail-open (no validation).
     def self.transform(source, identifier: nil, registry: :default)
       new.transform(source, identifier: identifier, registry: registry)
     end
 
     def transform(source, identifier: nil, registry: :default)
       # NOTE: +registry+ stays the +:default+ sentinel here. It is resolved to
-      # +Ruact.manifest+ LAZILY, only inside the component-tag block below — a
-      # source with no PascalCase tags must touch the registry not at all
-      # (AC2/AC6 fast-path invariant).
-      # Step 1: transform <Suspense> paired tags into <ruact-suspense> HTML elements.
-      # This runs before the general component regex so Suspense isn't treated as a component.
-      result = source
-               .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}>)
+      # +Ruact.manifest+ LAZILY, only when a component tag exists — a source
+      # with no PascalCase tags must touch the registry not at all (AC2/AC6
+      # fast-path invariant).
+      @identifier = identifier
+      @registry   = registry
+
+      # 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.
+      result = if source.match?(CLOSING_TAG_PROBE_RE)
+                 rewrite_paired(source)
+               else
+                 rewrite_self_closing(source)
                end
-        .gsub(SUSPENSE_CLOSE_RE, "</ruact-suspense>")
 
-      # Step 1.5 (Story 15.2 / FR106): before the general component pass, fail
-      # loudly if any PascalCase component tag is used with children (a matching
-      # closing tag). Silent degradation of `<Card>Hello</Card>` — the #1
-      # predictable JSX-habit mistake — becomes a self-contained, re-raised-as-is
-      # PreprocessorError naming the fix. It scans the ORIGINAL +source+ (so
-      # file:line is exact) and masks Suspense (the one legitimate paired
-      # PascalCase tag) newline-for-newline, so `<Suspense>...</Suspense>` can
-      # never trip and every reported line matches the template verbatim.
-      detect_children!(source, identifier)
-
-      # Step 2: transform remaining PascalCase self-closing / opening component tags.
-      result.gsub(COMPONENT_TAG_RE) do |match|
-        component_name = ::Regexp.last_match(1)
-        attrs_string   = ::Regexp.last_match(2).to_s.strip
-        match_start    = ::Regexp.last_match.begin(0)
-        line           = result[0...match_start].count("\n") + 1
-
-        begin
-          # lazy — only when a tag exists. `resolve_soft` returns the dev-fetched
-          # manifest (same source the render path uses, so the boot-race doesn't
-          # silence FR100 contract checks in dev) and FAILS OPEN to nil when the
-          # manifest is unresolvable (contract validation is opt-in/fail-open;
-          # the render path surfaces the clear error). In prod this is the
-          # boot-loaded Ruact.manifest, unchanged.
-          registry = ManifestResolver.resolve_soft if registry == :default
-          pairs = ComponentAttributes.parse(attrs_string)
-          validate_contract(registry, component_name, pairs.map(&:first),
-                            at: { file: identifier, line: line, snippet: match.strip })
-          props_ruby = pairs.map { |name, expr| "#{name.inspect} => #{expr}" }.join(", ")
-          props_hash = props_ruby.empty? ? "{}" : "{ #{props_ruby} }"
-          %(<%= __ruact_component__(#{component_name.inspect}, #{props_hash}) %>)
-        rescue ComponentContractError
-          # Already carries file:line + offending prop + suggestion — re-raise
-          # AS-IS (do NOT append the generic "at line N: snippet" tail).
-          raise
-        rescue PreprocessorError => e
-          raise PreprocessorError, "#{e.message} at line #{line}: #{match.strip}"
+      # 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
-      end
+        .gsub(SUSPENSE_CLOSE_RE, "</ruact-suspense>")
     end
 
     private
 
-    # Story 15.2 (FR106) — raise a loud, self-contained {ChildrenNotSupportedError}
-    # on the FIRST PascalCase component tag used with children (a matching closing
-    # tag). +source+ is the ORIGINAL template text; +identifier+ is the template
-    # path (from {ErbPreprocessorHook}). Suspense — the one legitimate paired
-    # PascalCase tag — is masked newline-for-newline first, so it never trips AND
-    # every byte position (hence every reported line) still lines up with the raw
-    # template. The line uses the same idiom as Step 2 (`count("\n") + 1`) on the
-    # OPENING tag's offset. Message mirrors {ComponentContract.raise_error} shape
-    # so both loud preprocess errors read identically. A no-op when no pair is
-    # present — the fast path stays byte-identical.
-    def detect_children!(source, identifier)
-      # Fast path: a children pair REQUIRES a literal PascalCase closing tag, so
-      # a source without one (the common all-self-closing case) can never trip —
-      # bail before allocating anything. `match?` builds no MatchData, and this
-      # skips the mask/scan copies entirely, keeping the hot render/preprocess
-      # path's allocation profile flat (the benchmark renders only self-closing
-      # components, so it must stay at baseline).
-      return unless source.match?(CLOSING_TAG_PROBE_RE)
-
-      # ERB islands first, then Suspense — both blank their text newline-for-
-      # newline so byte offsets (hence reported lines) still match the raw
-      # template, while neither ERB string text nor the legitimate Suspense pair
-      # can be seen by the tag scan.
-      scan = mask_suspense(mask_erb(source))
-      # PER-NAME open stacks (name → [offsets]) so a closing tag checks for a
-      # matching open in O(1) via `open_ats[name].last`, keeping the whole scan
-      # linear even under thousands of stray/unmatched PascalCase closing tags
-      # (a global stack + `rindex` was quadratic — Codex Round 3).
-      open_ats = Hash.new { |h, k| h[k] = [] }
+    # 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
+    # self-closing hands the whole template to {#rewrite_paired}, which masks
+    # ERB: `<%# wrap in <Card> later %>` is a comment, not an unclosed tag.
+    # So does any tag inside an ERB island (a commented-out component): the
+    # paired path leaves those alone.
+    def rewrite_self_closing(source)
+      catch(:open_tag) do
+        return source.gsub(COMPONENT_TAG_RE) do |match|
+          name = ::Regexp.last_match(1)
+          next match if name == "Suspense"
+
+          throw :open_tag unless match.end_with?("/>")
+          throw :open_tag if inside_erb?(source, ::Regexp.last_match.begin(0))
+
+          placeholder(name, ::Regexp.last_match(2).to_s.strip, match,
+                      line_at(source, ::Regexp.last_match.begin(0)), :self_closing)
+        end
+      end
+      rewrite_paired(source)
+    end
+
+    # Story 18-2 — pair opening and closing tags with one stack over the
+    # template with ERB islands and Suspense blanked (offsets preserved, so
+    # every line reported is the template's own), then rewrite each tag in
+    # place: a paired opening becomes {ViewHelper#__ruact_component_open__}'s
+    # wrapper, its closing `</ruact-component>`, a self-closing tag the usual
+    # placeholder. Tags inside ERB text are left alone.
+    def rewrite_paired(source)
+      scan   = mask_suspense(mask_erb(source))
+      tags   = []
+      stack  = []
+      paired = {}
 
       scan.scan(COMPONENT_ANY_TAG_RE) do
-        m    = ::Regexp.last_match
-        name = m[2]
+        m = ::Regexp.last_match
+        tag = { name: m[2], from: m.begin(0), to: m.end(0) }
+        tags << tag
 
         if m[1] # a closing tag `</Name>`
-          at = open_ats[name].last
-          next unless at # stray close with no open → literal text, ignore
-
-          raise_children_error(name, identifier, scan, at)
-        elsif m[0].end_with?("/>") # self-closing → carries no children
-          next
-        else # an opening tag `<Name ...>` — record the NEAREST open of this name
-          open_ats[name] << m.begin(0)
+          tag[:closing] = true
+          open = stack.pop
+          raise_stray(tag[:name], line_at(source, tag[:from])) if open.nil?
+          # `<Card><Box></Card>`: the tag left open is the one to fix.
+          raise_open_tag(source, open) unless open[:name] == tag[:name]
+
+          # The value says whether anything sits between the tags: an empty
+          # pair passes no children, like `<Card />`. Read from the template
+          # itself — ERB between the tags (`<%= @body %>`) is content, an ERB
+          # comment is not.
+          paired[open[:from]] = !source[open[:to]...tag[:from]].gsub(ERB_COMMENT_RE, "").strip.empty?
+        elsif !m[0].end_with?("/>")
+          stack << tag
         end
       end
+      raise_open_tag(source, stack.first) unless stack.empty?
+
+      splice(source, tags, paired)
+    end
+
+    # +source+ with each tag replaced by its placeholder. +paired+ maps an
+    # opening tag's offset to whether its pair holds anything.
+    def splice(source, tags, paired)
+      out    = +""
+      cursor = 0
+      tags.each do |tag|
+        out << source[cursor...tag[:from]]
+        out << rewrite_tag(source, tag, paired)
+        cursor = tag[:to]
+      end
+      out << source[cursor..]
+    end
+
+    def rewrite_tag(source, tag, paired)
+      return "</#{WRAPPER_TAG}>" if tag[:closing]
+
+      kind = if !paired.key?(tag[:from]) then :self_closing
+             elsif paired[tag[:from]] then :with_children
+             else :empty_pair
+             end
+      text = source[tag[:from]...tag[:to]]
+      placeholder(tag[:name], text.match(COMPONENT_TAG_RE)[2].to_s.strip, text, line_at(source, tag[:from]), kind)
+    end
+
+    # The ERB placeholder for one component tag. Props are parsed (and the
+    # opt-in contract checked) here; a pair with content passes `children` too.
+    # +kind+ is :self_closing, :empty_pair or :with_children.
+    def placeholder(name, attrs_string, match, line, kind)
+      children = kind == :with_children
+      # lazy — only when a tag exists. `resolve_soft` returns the dev-fetched
+      # manifest (same source the render path uses, so the boot-race doesn't
+      # silence FR100 contract checks in dev) and FAILS OPEN to nil when the
+      # manifest is unresolvable (contract validation is opt-in/fail-open; the
+      # render path surfaces the clear error). In prod this is the boot-loaded
+      # Ruact.manifest, unchanged.
+      @registry = ManifestResolver.resolve_soft if @registry == :default
+      pairs = ComponentAttributes.parse(attrs_string)
+      names = pairs.map(&:first)
+      raise_children_twice(name, line) if children && names.include?("children")
+
+      check_known!(name, line)
+      validate_contract(@registry, name, children ? names + ["children"] : names,
+                        at: { file: @identifier, line: line, snippet: match.strip })
+      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}) %>)
+    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).
+      raise
+    rescue PreprocessorError => e
+      raise PreprocessorError, "#{e.message} at line #{line}: #{match.strip}"
+    end
+
+    # Story 18-2 — a component the manifest does not have fails here, with the
+    # template's file:line, instead of at render with no location. Skipped
+    # when there is no manifest to ask (fail open, like the contract check).
+    def check_known!(name, line)
+      return unless @registry.respond_to?(:component?)
+      return if @registry.component?(name)
+
+      message = @registry.unknown_component_message(name, controller_path: controller_path_from(@identifier))
+      # With a close name on offer it is a typo; "did you run the Vite build?"
+      # would send the reader the wrong way.
+      message = message.lines.grep_v(/Did you run the Vite build/).join.rstrip if message.include?('Did you mean "')
+      raise UnknownComponentError, message.sub(/\Aruact: /, "ruact: <#{name}> at #{location(line)} — ")
+    end
+
+    # Whether +offset+ sits inside an ERB island (`<% … %>`): the nearest `<%`
+    # before it closes after it. One search back, one short search forward; no
+    # allocation.
+    def inside_erb?(source, offset)
+      opened = source.rindex("<%", offset)
+      return false unless opened
+
+      closed = source.index("%>", opened + 2)
+      closed.nil? || closed + 2 > offset
+    end
+
+    def line_at(source, offset)
+      source[0...offset].count("\n") + 1
+    end
+
+    def location(line)
+      @identifier ? "#{@identifier}:#{line}" : "line #{line}"
+    end
+
+    def raise_open_tag(source, tag)
+      text = source[tag[:from]...tag[:to]]
+      raise_unclosed(tag[:name], line_at(source, tag[:from]),
+                     attrs: text.match(COMPONENT_TAG_RE)[2].to_s.strip, snippet: text)
+    end
+
+    # A tag that looks open may only be a `>` inside an attribute value
+    # (`title="a > b"`, `title="<%= @t %>"`) cutting the tag short; the
+    # attribute's own error says that, so it goes first.
+    def raise_unclosed(name, line, attrs:, snippet:)
+      begin
+        ComponentAttributes.parse(attrs)
+      rescue PreprocessorError => e
+        raise PreprocessorError, "#{e.message} at line #{line}: #{snippet.strip}"
+      end
+      raise ComponentTagError,
+            "ruact: <#{name}> at #{location(line)} is never closed — write `<#{name} ... />` for a " \
+            "component without children, or close it with `</#{name}>`."
+    end
 
-      nil
+    def raise_stray(name, line)
+      raise ComponentTagError,
+            "ruact: </#{name}> at #{location(line)} closes nothing — there is no open <#{name}> before it."
     end
 
-    # Raise the self-contained {ChildrenNotSupportedError}. +at+ is the OPENING
-    # tag's byte offset in +scan+ (position-faithful to the raw source), so the
-    # line uses the same idiom as Step 2. Message mirrors
-    # {ComponentContract.raise_error} so both loud preprocess errors read alike.
-    def raise_children_error(component, identifier, scan, at)
-      line     = scan[0...at].count("\n") + 1
-      location = [identifier, line].compact.join(":")
-      location = "(unknown location)" if location.empty?
-      raise ChildrenNotSupportedError,
-            "ruact: <#{component}> at #{location} children are not supported " \
-            "— pass content as a prop, e.g. `<#{component} content={...} />`."
+    def raise_children_twice(name, line)
+      raise ComponentTagError,
+            "ruact: <#{name}> at #{location(line)} has content between its tags and a `children={...}` " \
+            "prop — pass one of them."
     end
 
-    # Blank out Suspense open/close tags (the one legitimate paired PascalCase
-    # tag) while preserving EVERY newline and byte offset, so the loud-children
-    # scan neither trips on `<Suspense>...</Suspense>` nor mis-reports a line when
-    # a multi-line Suspense opening precedes the offending tag. Non-newline chars
-    # → spaces (same length); newlines kept verbatim.
+    # Blank out Suspense open/close tags while preserving EVERY newline and
+    # byte offset, so the pairing scan neither sees `<Suspense>...</Suspense>`
+    # nor mis-reports a line after a multi-line Suspense opening. Non-newline
+    # chars → spaces (same length); newlines kept verbatim.
     def mask_suspense(source)
       source
         .gsub(SUSPENSE_OPEN_RE)  { |m| m.gsub(/[^\n]/, " ") }
@@ -202,7 +305,7 @@ module Ruact
 
     # Blank ERB islands (position-faithful, see {mask_suspense}) so component
     # tags that appear only inside Ruby/ERB string or comment text are invisible
-    # to the loud-children tag scan.
+    # to the pairing scan.
     def mask_erb(source)
       source.gsub(ERB_ISLAND_RE) { |m| m.gsub(/[^\n]/, " ") }
     end

data/lib/ruact/errors.rb

@@ -22,21 +22,21 @@ module Ruact
   # re-wrapping it with the generic "at line N: snippet" tail.
   class ComponentContractError < PreprocessorError; end
 
-  # Story 15.2 (FR106) — raised by {Ruact::ErbPreprocessor} at preprocess time
-  # when a PascalCase component tag is used with children (a matching closing
-  # tag, e.g. `<Card>Hello</Card>`). ruact component tags are self-closing only:
-  # a component receives a props Hash, never a children element tree. This is the
-  # #1 predictable JSX-habit mistake, and it used to degrade silently (the
-  # children leaked into the surrounding HTML while the component rendered with
-  # none). Subclasses {PreprocessorError} so it flows through the same dev error
-  # overlay (NFR30 lineage) and the hook treats it uniformly — but the distinct
-  # class (mirroring {ComponentContractError}) lets the preprocessor re-raise it
-  # AS-IS (its message already carries the component name + file:line + the exact
-  # fix) and lets the 15.7 capstone assert this trap fails loudly by class. The
-  # sole legitimate paired PascalCase tag, `<Suspense>...</Suspense>`, is
-  # normalized to `<ruact-suspense>` in Step 1 before this detection runs, so it
-  # never trips.
-  class ChildrenNotSupportedError < PreprocessorError; end
+  # Story 18-2 — raised by {Ruact::ErbPreprocessor} at preprocess time when a
+  # component tag does not pair: an opening tag never closed (write `<Card />`
+  # or close it with `</Card>`), a closing tag that closes nothing, or content
+  # between the tags together with a `children=` prop. The message carries
+  # the tag, file:line and the fix, so the preprocessor re-raises it as is.
+  # Replaces Story 15.2's ChildrenNotSupportedError: components take children now.
+  class ComponentTagError < PreprocessorError; end
+
+  # Story 18-2 — raised by {Ruact::ErbPreprocessor} when a template names a
+  # client component the manifest does not have (a typo, a missing
+  # "use client"). The same message {ClientManifest#reference_for} raises at
+  # render — with the closest name — plus the template's file:line, because
+  # it is caught while the template compiles. Only when a manifest is
+  # available; without one the render path reports it, as before.
+  class UnknownComponentError < PreprocessorError; end
 
   # Raised when application code attempts to mutate Ruact::Configuration outside
   # of a Ruact.configure block. The configuration is frozen after initialization

data/lib/ruact/flight/renderer.rb

@@ -14,17 +14,30 @@ module Ruact
         each(model, bundler_config, streaming: false, **).to_a.join
       end
 
-      def self.each(model, bundler_config, strict_serialization: false, on_as_json_warning: nil,
-                    streaming: true, &)
-        new(model, bundler_config,
-            strict_serialization: strict_serialization,
-            on_as_json_warning: on_as_json_warning).each(streaming: streaming, &)
+      # Keyword options other than +streaming:+ go to {#initialize}
+      # (strict_serialization:, on_as_json_warning:, development:).
+      def self.each(model, bundler_config, streaming: true, **, &)
+        new(model, bundler_config, **).each(streaming: streaming, &)
       end
 
-      def initialize(model, bundler_config, strict_serialization: false, on_as_json_warning: nil)
+      # Whether rows carry the slots React's development client reads (see
+      # Serializer#element_tuple): in Rails' development environment only. The
+      # test environment keeps the production wire, so what a request spec
+      # asserts is what production sends.
+      def self.development_default
+        return false unless defined?(Rails) && Rails.respond_to?(:env)
+
+        Rails.env.development?
+      rescue StandardError
+        false
+      end
+
+      def initialize(model, bundler_config, strict_serialization: false, on_as_json_warning: nil,
+                     development: false)
         @request = Request.new(model, bundler_config,
                                strict_serialization: strict_serialization,
-                               on_as_json_warning: on_as_json_warning)
+                               on_as_json_warning: on_as_json_warning,
+                               development: development)
       end
 
       # Yields Flight rows one at a time.
@@ -50,7 +63,8 @@ module Ruact
           if streaming && deferred[:delay]&.positive?
             timeout = Ruact.config.suspense_timeout
             if timeout&.positive? && deferred[:delay] > timeout
-              yield RowEmitter.error(deferred[:id], JSON.generate("Suspense timeout exceeded"))
+              error = RowEmitter.error_payload("Suspense timeout exceeded", digest: "ruact:suspense-timeout")
+              yield RowEmitter.error(deferred[:id], JSON.generate(error))
               next
             end
             sleep(deferred[:delay])
@@ -58,7 +72,7 @@ module Ruact
 
           # 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 `$T<id>`).
+          # 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])

data/lib/ruact/flight/request.rb

@@ -16,11 +16,15 @@ module Ruact
       # 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
+                  :strict_serialization, :on_as_json_warning, :development
 
-      def initialize(model, bundler_config, strict_serialization: false, on_as_json_warning: nil)
+      def initialize(model, bundler_config, strict_serialization: false, on_as_json_warning: nil,
+                     development: false)
         @strict_serialization = strict_serialization
         @on_as_json_warning   = on_as_json_warning
+        @development          = development
+        @suspense_symbol_ref  = nil
+        @boundary_ref         = nil
         @next_chunk_id = 0
         @pending_chunks = 0
         @bundler_config = bundler_config
@@ -42,6 +46,31 @@ module Ruact
         id
       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"))
+          "$#{id.to_s(16)}"
+        end
+      end
+
+      # The runtime's own client component that catches an error in a Suspense
+      # child (runtime/suspense-boundary.js). Not in the app's manifest: the
+      # runtime registers it under this id.
+      BOUNDARY_METADATA = ["ruact:boundary", [], "SuspenseBoundary"].freeze
+
+      # The `"$L<hex>"` reference to {BOUNDARY_METADATA}'s import row, emitted
+      # once per response.
+      def boundary_ref
+        @boundary_ref ||= begin
+          id = allocate_id
+          @completed_import_chunks << RowEmitter.import(id, JSON.generate(BOUNDARY_METADATA))
+          "$L#{id.to_s(16)}"
+        end
+      end
+
       def increment_pending
         @pending_chunks += 1
       end

data/lib/ruact/flight/row_emitter.rb

@@ -22,6 +22,15 @@ module Ruact
         "#{id.to_s(16)}:E#{error_json}\n"
       end
 
+      # The error object React's Flight client reads from an E row. Its
+      # development build reads `stack` and `env`; a bare string crashes it.
+      # Its production build drops the message and keeps `digest`, so the
+      # digest is a stable code the runtime turns back into the message
+      # (runtime/suspense-boundary.js, DIGEST_MESSAGES).
+      def self.error_payload(message, digest:)
+        { "digest" => digest, "name" => "Error", "message" => message, "stack" => [], "env" => "Server" }
+      end
+
       # A large text row (binary framing, no trailing newline)
       def self.text(id, text)
         byte_length = text.bytesize