ruact 0.0.17 → 0.0.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78c8550850bcded6e5585918c33d4520131a019520f4def020e9e5701a47c7ae
-  data.tar.gz: ab49c696c75137128062c6f9c7fa8b2569b8f918818bcf50f209d3939675af59
+  metadata.gz: afeffed3bf00af43d750b220dbffbdd62758269d578bb649912d7fbee157df86
+  data.tar.gz: 2bae60da180b2a5b6c85fe49c3adc42d3431c1cfee7666c9fdbf79b92815049b
 SHA512:
-  metadata.gz: a4dda8e8c229d941a6d8e852704837259a45653002b2c7465764ae219c58fbaa4188d4490745efe88327ceb736094ccc265b6e38f2cc38d008388bf7cb5d1e88
-  data.tar.gz: 976492c9e23c34d777071ec0fa313ae146d942ba1ade21d939de380e012a0cedc4028c9e997dabe96518ad9b7b00bbd48a4c162eef9270969ba9e2bf5ce4e3a6
+  metadata.gz: 79f5785e73237b512b1fce27e9b085538c57954921bf92544fc8d4f80c2646f27e5e46baa23b1a565beb567b8e4762a108a0f2885b3ec85f9b822216889afadd
+  data.tar.gz: 3421862773a8f0669533bd70e39aed531b9ae2c4ce42205bc6939bc6311d76f5c45e4527d39752793bebc343af29ba96ebffd3fd58a6f414bb16fba879cfcbeb

data/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.18] - 2026-10-07
+
+### Added
+
+- **Client components take children from ERB.** Content between a component's opening and closing tags reaches it as `children`, evaluated on the server like the rest of the template: HTML, `<%= %>` output (escaped as usual), loops, conditionals, partials, and other components, the same one included.
+
+  ```erb
+  <Card title={@post.title}>
+    <p><%= @post.body %></p>
+    <LikeButton postId={@post.id} />
+  </Card>
+  ```
+
+  A component that declares a contract (`__ruactContract`) has to list `children` among its `props` or `slots` to take them. `<Suspense>` works inside a component and around one.
+
+- **A misspelled component name is caught where it is written.** When a manifest is available, a template naming a component that does not exist now fails while it compiles, with `Ruact::UnknownComponentError` naming the tag, the template's file and line, and the closest component (`Did you mean "LikeButton"?`). It used to fail at render with no location. Without a manifest the render reports it, as before.
+
+### Changed
+
+- **Every component tag must close.** `<Dialog open={true}>` with no closing tag used to render as a component without children. It now raises `Ruact::ComponentTagError` at file:line: write `<Dialog open={true} />`, or close it with `</Dialog>`. The same error names a closing tag that closes nothing, and a tag given both content and a `children={...}` prop.
+
+### Removed
+
+- **`Ruact::ChildrenNotSupportedError`.** It was raised for content between a component's tags, which is now supported. Rescue `Ruact::ComponentTagError` for tags that do not pair, or `Ruact::PreprocessorError` for any template error.
+
 ## [0.0.17] - 2026-10-06
 
 ### Changed
@@ -455,7 +480,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **E2E test app** — `e2e/` Rails app (no DB, in-memory Post model) with full CRUD system tests validating the complete request cycle.
 
-[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.17...HEAD
+[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.18...HEAD
+[0.0.18]: https://github.com/luizcg/ruact/releases/tag/v0.0.18
 [0.0.17]: https://github.com/luizcg/ruact/releases/tag/v0.0.17
 [0.0.16]: https://github.com/luizcg/ruact/releases/tag/v0.0.16
 [0.0.15]: https://github.com/luizcg/ruact/releases/tag/v0.0.15

data/README.md

@@ -11,7 +11,7 @@
      scripted and live with the project's other capture harnesses, and the message the demo
      shows is pinned here by `spec/readme_demo_message_spec.rb`. -->
 <img src="https://ruact.dev/readme-write-verify.gif" width="800"
-     alt="An ERB template holding a &lt;LikeButton likes=&#123;@likes&#125; /&gt; tag, and the &quot;use client&quot; React component that tag resolves to. The component renders in a browser and its count changes when it is clicked. Children are then put inside the tag — the JSX habit — and the next request stops server-side with Ruact::ChildrenNotSupportedError, which names the component, the template file and line, and the fix. The children come out again and the page renders." />
+     alt="An ERB template holding a &lt;LikeButton likes=&#123;@likes&#125; /&gt; tag, and the &quot;use client&quot; React component that tag resolves to. The component renders in a browser and its count changes when it is clicked. The tag&#39;s name is then misspelled, and the next request stops server-side with Ruact::UnknownComponentError, which names the tag, the template file and line, and the component it was probably meant to be. The name is corrected and the page renders." />
 
 ## Quick start
 

data/lib/generators/ruact/install/templates/AGENTS.md.tt

@@ -77,14 +77,14 @@ READ IT instead of simulating the name generation. Regenerate after routes/queri
 
 ## Five traps
 
-1. **Component tags take no children.** Client component tags are self-closing
-   ONLY: `<Card content={@body} />`, never `<Card>...</Card>`. Children (a
-   matching closing tag) fail LOUDLY with a `PreprocessorError` at preprocess
-   time — pass content as a prop instead. Sole exception: the built-in
-   `<Suspense fallback="...">...</Suspense>` pair.
+1. **Every component tag closes.** `<Badge label={@x} />` has no children;
+   `<Card title={@t}>...</Card>` passes the ERB between its tags — HTML, loops,
+   partials, other components — to the component as `children`. An opening tag
+   that never closes, or a closing tag with no opening, fails LOUDLY with a
+   `PreprocessorError` naming file:line. `<Suspense fallback="...">` pairs too.
 2. **`{}` props are Ruby, not JavaScript.** `<Badge label={@post.title} />`
    evaluates `@post.title` as a Ruby expression in the ERB. No JS ternaries,
-   no `{...spread}`, no JSX children. A quoted value (`title="Hi"`) is a
+   no `{...spread}`. A quoted value (`title="Hi"`) is a
    plain string and a bare attribute is `true`, as in JSX.
 3. **One action, two response shapes.** A `Ruact::Server` non-GET action
    answers JSON — its instance variables, or `204`, or `{"$redirect": path}` —

data/lib/ruact/client_manifest.rb

@@ -89,6 +89,24 @@ module Ruact
       end
     end
 
+    # Story 18-2 — whether +name+ resolves for SOME controller: the shared key,
+    # or a co-located one in any folder (`posts/_like_button`). The ERB
+    # preprocessor asks while it compiles a template, before it knows which
+    # controller will render it, so a co-located component is never refused
+    # for being looked up from a shared partial.
+    def component?(name)
+      return true if include?(name)
+
+      suffix = "/_#{pascal_to_snake_case(name)}"
+      entries_by_name.keys.any? { |key| key.end_with?(suffix) }
+    end
+
+    # Story 18-2 — the "not found" message {#reference_for} raises, for the
+    # preprocessor to put the template's file:line in front of.
+    def unknown_component_message(name, controller_path: nil)
+      build_unknown_component_message(name, controller_path)
+    end
+
     # Story 13.5 (FR100) — return the optional component +contract+ Hash for
     # +name+, or +nil+ when the component declared none (or is absent from the
     # manifest). Honors the same co-located/shared +resolve_key+ precedence as

data/lib/ruact/component_contract.rb

@@ -103,8 +103,10 @@ module Ruact
     # @param detail [String] the violation clause
     # @param where [Hash] keys +component+, +file+, +line+, +snippet+
     def self.raise_error(detail, where)
-      location = [where[:file], where[:line]].compact.join(":")
-      location = "(unknown location)" if location.empty?
+      location = if where[:file] then [where[:file], where[:line]].compact.join(":")
+                 elsif where[:line] then "line #{where[:line]}"
+                 else "(unknown location)"
+                 end
       message = "ruact: <#{where[:component]}> at #{location} #{detail}."
       message += "\n  in: #{where[:snippet]}" if where[:snippet] && !where[:snippet].empty?
       raise ComponentContractError, message

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/html_converter.rb

@@ -182,6 +182,7 @@ 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
 
       props = build_props(node, tag)
       children = convert_children(node)
@@ -190,6 +191,23 @@ module Ruact
       Flight::ReactElement.new(type: tag, key: node["data-react-key"], props: props)
     end
 
+    # Story 18-2 — a component with children: the wrapper the preprocessor put
+    # around the content between `<Card>` and `</Card>`. Its children become the
+    # 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
+
+      props = entry[:props]
+      children = convert_children(node)
+      unless children.empty?
+        props = props.merge("children" => children.length == 1 ? children.first : children)
+      end
+      Flight::ReactElement.new(type: entry[:ref], key: nil, props: props)
+    end
+
     def convert_suspense_element(node)
       fallback_text = node["data-ruact-fallback"] || ""
       fallback = if fallback_text.empty?

data/lib/ruact/render_pipeline.rb

@@ -251,12 +251,13 @@ module Ruact
       receiver.instance_variable_set(:@__ruact_render_context__, render_context)
       return if receiver.respond_to?(:__ruact_component__)
 
-      receiver.define_singleton_method(:__ruact_component__) do |name, props = {}|
-        ctx = instance_variable_get(:@__ruact_render_context__)
-        raise Ruact::Error, "ruact: __ruact_component__ called outside an active render context" if ctx.nil?
+      ErbPreprocessor::PLACEHOLDERS.each do |helper, placeholder|
+        receiver.define_singleton_method(helper) do |name, props = {}|
+          ctx = instance_variable_get(:@__ruact_render_context__)
+          raise Ruact::Error, "ruact: #{helper} called outside an active render context" if ctx.nil?
 
-        token = ctx.register(name, props)
-        "<!-- #{token} -->"
+          placeholder.call(ctx.register(name, props))
+        end
       end
     end
   end

data/lib/ruact/version.rb

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

data/lib/ruact/view_helper.rb

@@ -32,6 +32,19 @@ module Ruact
       "<!-- #{token} -->".html_safe
     end
 
+    # Story 18-2 — the opening of a component with children. Registers it like
+    # {#__ruact_component__} and opens the wrapper element whose content (the
+    # ERB between the tags, evaluated in place) HtmlConverter hands the
+    # component as `children`. The preprocessor writes the matching
+    # `</ruact-component>`.
+    def __ruact_component_open__(name, props = {})
+      ctx = @ruact_render_context
+      raise Ruact::Error, __ruact_outside_render_message(name) if ctx.nil?
+
+      token = ctx.register(name, props)
+      %(<ruact-component data-ruact-token="#{token}">).html_safe
+    end
+
     # Story 17.0i — a client component in a template Rails is rendering on its
     # own. Says which component and template, and the two ways to a ruact page:
     # `ruact_render` for this template, or listing the action in the

data/vendor/javascript/vite-plugin-ruact/flight-conformance.test.mjs

@@ -32,7 +32,11 @@ function Bad() {
 function LikeButton({ likes, tags }) {
   return h("button", null, `${likes}:${Array.isArray(tags) ? `[${tags.join(",")}]` : String(tags)}`);
 }
-setModuleRegistry({ "/LikeButton.jsx": { LikeButton }, "/Bad.jsx": { Bad } });
+function Card({ title, children }) {
+  return h("section", null, h("h2", null, title), children);
+}
+
+setModuleRegistry({ "/LikeButton.jsx": { LikeButton }, "/Bad.jsx": { Bad }, "/Card.jsx": { Card } });
 
 function streamOf(chunks) {
   return new ReadableStream({
@@ -103,6 +107,22 @@ describe(`React's Flight client (${MODE}) reads a page the Ruby side rendered`,
   });
 });
 
+describe(`a client component with children from ERB (${MODE}) — Story 18-2`, () => {
+  const fixture = MODE === "development" ? "conformance_children_dev.txt" : "conformance_children.txt";
+
+  it("renders the server's children inside the component, a nested one included, and logs nothing", async () => {
+    const { container, root } = await mount(decode([read(fixture)]));
+    expect(container.innerHTML).toBe(
+      "<section><h2>Server title</h2><p>from ERB</p>" +
+      "<button>1:[only]</button><button>2:[only]</button><button>3:[only]</button>" +
+      "<section><h2>inner</h2>nested</section></section>",
+    );
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(consoleError).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
+});
+
 describe(`text rows (${MODE}) — Story 17-0d`, () => {
   const expected = readJSON("text_framing_expected.json");
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruact
 version: !ruby/object:Gem::Version
-  version: 0.0.17
+  version: 0.0.18
 platform: ruby
 authors:
 - Luiz Garcia
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-06 00:00:00.000000000 Z
+date: 2026-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri