RubyGems - ruact - Versions diffs - 0.0.7 → 0.0.9 - Mend

ruact 0.0.7 → 0.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (61) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +59 -1
data/docs/internal/decisions/server-functions-api.md +55 -0
data/lib/generators/ruact/install/install_generator.rb +378 -6
data/lib/generators/ruact/install/templates/AGENTS.md.tt +159 -0
data/lib/generators/ruact/install/templates/Procfile.dev.tt +3 -0
data/lib/generators/ruact/install/templates/globals.css.tt +20 -0
data/lib/generators/ruact/install/templates/initializer.rb.tt +9 -0
data/lib/generators/ruact/install/templates/package.json.tt +7 -1
data/lib/generators/ruact/install/templates/tsconfig.json.tt +18 -0
data/lib/generators/ruact/scaffold/scaffold_shadcn_preflight.rb +10 -0
data/lib/ruact/configuration.rb +73 -0
data/lib/ruact/controller/document_rendering.rb +210 -0
data/lib/ruact/controller.rb +14 -46
data/lib/ruact/doctor.rb +102 -12
data/lib/ruact/erb_preprocessor.rb +113 -0
data/lib/ruact/errors.rb +16 -0
data/lib/ruact/layout_source.rb +59 -0
data/lib/ruact/manifest_resolver.rb +2 -2
data/lib/ruact/serializable.rb +98 -6
data/lib/ruact/server.rb +163 -0
data/lib/ruact/server_functions/introspection.rb +81 -0
data/lib/ruact/server_functions.rb +26 -4
data/lib/ruact/testing/component_query.rb +113 -0
data/lib/ruact/testing/flight_extractor.rb +221 -0
data/lib/ruact/testing/flight_structure_diff.rb +267 -0
data/lib/ruact/testing/flight_wire_parser.rb +138 -0
data/lib/ruact/testing.rb +90 -0
data/lib/ruact/version.rb +1 -1
data/lib/ruact/view_helper.rb +10 -1
data/lib/ruact.rb +1 -0
data/lib/tasks/ruact.rake +55 -2
data/spec/fixtures/story_7_9_views/controller_request_spec_support/exploding_layout_demo/show.html.erb +3 -0
data/spec/fixtures/story_7_9_views/controller_request_spec_support/ghost_layout_demo/show.html.erb +3 -0
data/spec/fixtures/story_7_9_views/controller_request_spec_support/layout_demo/show.html.erb +3 -0
data/spec/fixtures/story_7_9_views/controller_request_spec_support/rootless_layout_demo/show.html.erb +3 -0
data/spec/fixtures/story_7_9_views/controller_request_spec_support/unwired_layout_demo/show.html.erb +3 -0
data/spec/fixtures/story_7_9_views/layouts/bare_host.html.erb +16 -0
data/spec/fixtures/story_7_9_views/layouts/exploding_host.html.erb +24 -0
data/spec/fixtures/story_7_9_views/layouts/rootless_host.html.erb +15 -0
data/spec/fixtures/story_7_9_views/layouts/ruact_host.html.erb +17 -0
data/spec/ruact/controller_request_spec.rb +203 -0
data/spec/ruact/doctor_spec.rb +222 -6
data/spec/ruact/erb_preprocessor_spec.rb +145 -0
data/spec/ruact/install_generator_spec.rb +727 -70
data/spec/ruact/layout_source_spec.rb +108 -0
data/spec/ruact/manifest_resolver_spec.rb +15 -0
data/spec/ruact/scaffold_generator_spec.rb +14 -0
data/spec/ruact/serializable_spec.rb +126 -0
data/spec/ruact/server_bucket_request_spec.rb +291 -0
data/spec/ruact/server_functions/introspection_spec.rb +135 -0
data/spec/ruact/tasks_json_introspection_spec.rb +141 -0
data/spec/ruact/testing/have_ruact_component_spec.rb +170 -0
data/spec/ruact/testing/no_production_load_spec.rb +41 -0
data/spec/support/flight_wire_parser.rb +12 -126
data/spec/support/matchers/flight_fixture_matcher.rb +7 -258
data/vendor/javascript/ruact-server-functions-runtime/index.d.ts +25 -0
data/vendor/javascript/ruact-server-functions-runtime/index.js +104 -7
data/vendor/javascript/ruact-server-functions-runtime/index.test.mjs +173 -0
data/vendor/javascript/vite-plugin-ruact/type-tests/auto-revalidate.test-d.ts +25 -0
metadata +30 -4

data/lib/ruact/controller.rb CHANGED Viewed

@@ -5,6 +5,7 @@ require "socket"
 require "uri"
 require_relative "view_helper"
 require_relative "validation_errors_collector"
+require_relative "controller/document_rendering"
 module Ruact
   # Include in ApplicationController to enable RSC rendering.
@@ -27,6 +28,9 @@ module Ruact
     # and so the shared `vite_dev_running?` / `vite_manifest_entry` helpers are
     # reachable here without duplication.
     include Ruact::ViewHelper
+    # Who owns the `<head>` — the host app's layout, with ruact's built-in shell
+    # as the un-migrated fallback. See Ruact::Controller::DocumentRendering.
+    include Ruact::Controller::DocumentRendering
     private
@@ -157,6 +161,12 @@ module Ruact
     # (matching the legacy `#from_html` ordering) before any streaming
     # response headers are mutated.
     def emit_ruact_response(pipeline, html, render_context, streaming:)
+      # Story 15.5 (FR109) — record which page shape ruact rendered so the
+      # `Ruact::Server` dev log (`__ruact_log_response_shape!`) can name it and,
+      # crucially, stay SILENT on a plain Rails render (this flag is never set
+      # there). `@__`-prefixed → never leaks into `view_assigns`.
+      @__ruact_negotiated_page = ruact_request? ? :flight : :html_shell
       if ruact_request? && streaming
         enumerator = pipeline.render({ html: html, render_context: render_context }, mode: :stream)
         response.headers["Content-Type"]      = "text/x-component; charset=utf-8"
@@ -172,7 +182,7 @@ module Ruact
         if ruact_request?
           render plain: payload, content_type: "text/x-component"
         else
-          render html: ruact_html_shell(payload).html_safe, layout: false
+          render_ruact_document(payload)
         end
       end
     end
@@ -209,6 +219,9 @@ module Ruact
       # Flight redirect and re-render as an `errors` prop (no-op when untouched).
       __ruact_stash_errors_in_flash
+      # Story 15.5 (FR109) — mark the Flight-redirect sub-shape for the dev log.
+      @__ruact_negotiated_page = :flight_redirect
       render plain: "0:#{JSON.generate({ 'redirectUrl' => redirect_url, 'redirectType' => 'push' })}\n",
              content_type: "text/x-component"
     end
@@ -227,50 +240,5 @@ module Ruact
       controller = self.class.name.underscore.sub("_controller", "")
       Rails.root.join("app", "views", controller, "#{action}.html.erb")
     end
-    def ruact_html_shell(flight_payload)
-      # Story 14.2 — the JS asset block (entry `<script>` tags + `__FLIGHT_DATA`)
-      # is delegated to the single `Ruact::ViewHelper#ruact_js_assets`
-      # implementation. The bootstrap entry script is a deferred ES module, so it
-      # runs after the inline `__FLIGHT_DATA` classic script has populated the
-      # queue regardless of source order — emitting the whole block in `<body>`
-      # is correct.
-      <<~HTML
-        <!DOCTYPE html>
-        <html lang="en">
-          <head>
-            <meta charset="UTF-8" />
-            <meta name="viewport" content="width=device-width, initial-scale=1" />
-            #{ruact_csrf_meta_tag}
-            <title>Rails RSC</title>
-          </head>
-          <body>
-            <div id="root"></div>
-            #{ruact_js_assets(flight_payload)}
-          </body>
-        </html>
-      HTML
-    end
-    # Story 8.3 review R7 — emits `<meta name="csrf-token" content="...">`
-    # into the shell so the JS runtime's `<meta>` lookup can forward a
-    # valid `X-CSRF-Token` on every server-function (mutation) call. Without
-    # this, hosts that route `ruact_render` through the gem's HTML shell (the
-    # standard path) have no token in the document and the host's
-    # `protect_from_forgery` rejects every non-GET server function.
-    #
-    # Returns an empty string when CSRF protection isn't available
-    # (non-Rails specs, or hosts that have deliberately stripped
-    # `form_authenticity_token` from the controller surface).
-    def ruact_csrf_meta_tag
-      return "" unless respond_to?(:form_authenticity_token, true)
-      token = form_authenticity_token
-      return "" if token.nil? || token.empty?
-      %(<meta name="csrf-token" content="#{ERB::Util.html_escape(token)}" />)
-    rescue StandardError
-      ""
-    end
   end
 end

data/lib/ruact/doctor.rb CHANGED Viewed

@@ -6,7 +6,7 @@ require "pathname"
 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
+  class Doctor # rubocop:disable Metrics/ClassLength
     CHECKS = %i[manifest vite controller layout streaming 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
@@ -64,6 +64,14 @@ module Ruact
     # future status) is treated as a failure (review finding R1).
     SUCCESS_STATUSES = %i[pass warn].freeze
+    # Story 15.3 (FR107) — version of the machine-readable `ruact:doctor --json`
+    # document (see {#as_json}). This is an **EXPERIMENTAL / UNSTABLE** contract:
+    # `0` signals the shape may change without a major version bump while the
+    # agent-facing introspection surface is iterated. Gate any parser on it.
+    # Distinct from {Ruact::ServerFunctions::Snapshot::VERSION_V2} (the internal
+    # codegen bridge version) — do not conflate the two.
+    SCHEMA_VERSION = 0
     # @param serialize_only_root [String] directory whose `**/*.rb` is scanned
     #   for the serialize-only tripwire. Defaults to the gem's own `lib/`;
     #   injectable so specs can point it at a fixture tree.
@@ -78,16 +86,61 @@ module Ruact
     def run
       puts "[ruact] Health check"
-      results = CHECKS.map { |check| send(:"check_#{check}") }
-      results.each { |status, message| puts format_result(status, message) }
+      computed = results
+      computed.each { |status, message| puts format_result(status, message) }
       # A :warn must NOT fail the run (Story 13.1 AC3); only :pass / :warn are
       # success. An unexpected status (rendered `✗`) fails loudly rather than
       # being silently treated as a pass (review finding R1).
-      passed = results.all? { |status, _| SUCCESS_STATUSES.include?(status) }
+      passed = passed?(computed)
       puts "Run rails generate ruact:install to fix configuration issues" unless passed
       passed
     end
+    # Runs every check ONCE and returns the raw result tuples, index-aligned with
+    # {CHECKS}. Each tuple is `[status, message]` or `[status, message,
+    # remediation]` (the optional 3rd element is a machine-readable fix string,
+    # nil when the check has no cleanly separable remediation). Shared by {#run}
+    # (human path) and {#as_json} (JSON path) so a check like `check_vite` — which
+    # opens a socket — never runs twice. (Story 15.3)
+    #
+    # @return [Array<Array>] one tuple per check, in {CHECKS} order.
+    def results
+      CHECKS.map { |check| send(:"check_#{check}") }
+    end
+    # @param computed [Array<Array>] result tuples (defaults to a fresh {#results} run).
+    # @return [Boolean] true when NO check failed — only `:pass`/`:warn` are
+    #   success (mirrors {#run}'s rule; an unexpected status fails).
+    def passed?(computed = results)
+      computed.all? { |status, _| SUCCESS_STATUSES.include?(status) }
+    end
+    # Story 15.3 (FR107) — the machine-readable `ruact:doctor --json` document.
+    # Reuses the SAME {#results} tuples the human path prints (no double-run), so
+    # the JSON never disagrees with the `✓/⚠/✗` output. EXPERIMENTAL shape — gate
+    # parsers on `schema_version` (see {SCHEMA_VERSION}). Emits NO prose — the
+    # rake task prints ONLY this document in JSON mode.
+    #
+    # @return [Hash] `{ "schema_version" => Integer, "status" =>
+    #   "pass"|"fail", "checks" => [{ "name" =>, "status" =>, "message" =>,
+    #   "remediation" => (String|nil) }] }`.
+    def as_json
+      computed = results
+      {
+        "schema_version" => SCHEMA_VERSION,
+        "status" => passed?(computed) ? "pass" : "fail",
+        "checks" => CHECKS.each_index.map do |i|
+          status, message, remediation = computed[i]
+          {
+            "name" => CHECKS[i].to_s,
+            "status" => status.to_s,
+            "message" => message,
+            "remediation" => remediation
+          }
+        end
+      }
+    end
     private
     def check_manifest
@@ -95,7 +148,8 @@ module Ruact
       if Pathname(path).exist?
         [:pass, "Manifest found at #{path}"]
       else
-        [:fail, "Manifest not found — run vite build"]
+        [:fail, "Manifest not found — run vite build",
+         "Run vite build (or bin/dev) to generate the client manifest."]
       end
     end
@@ -103,7 +157,8 @@ module Ruact
       TCPSocket.new("localhost", 5173).close
       [:pass, "Vite accessible at localhost:5173"]
     rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
-      [:fail, "Vite not accessible at localhost:5173 — run npm run dev"]
+      [:fail, "Vite not accessible at localhost:5173 — run npm run dev",
+       "Run npm run dev (or bin/dev) to start the Vite dev server."]
     end
     def check_controller
@@ -111,17 +166,51 @@ module Ruact
       if File.exist?(path) && File.read(path).include?("Ruact::Controller")
         [:pass, "Ruact::Controller included in ApplicationController"]
       else
-        [:fail, "Ruact::Controller not included in ApplicationController"]
+        [:fail, "Ruact::Controller not included in ApplicationController",
+         "Run rails generate ruact:install to include Ruact::Controller in ApplicationController."]
       end
     end
+    # Two independent halves have to line up, and BOTH are silent when wrong:
+    # the layout has to call `ruact_js_assets`, and `Ruact.config.layout` has to
+    # be on. Miss either and ruact renders its built-in shell — which carries no
+    # stylesheet, so the app's own CSS never reaches a ruact page and nothing
+    # errors. Reporting each half separately is the point: "add one line" and
+    # "flip one setting" are different fixes.
+    #
+    # `Ruact::LayoutSource` is the SHARED definition of "calls the helper" —
+    # the runtime and `ruact:install` read it too, so this check cannot drift
+    # into disagreeing with what actually happens at render time (it did:
+    # a `<%# TODO: add ruact_js_assets %>` comment used to pass here).
     def check_layout
       path = Rails.root.join("app", "views", "layouts", "application.html.erb")
-      if File.exist?(path) && File.read(path).include?("ruact: root")
-        [:pass, "React shell present in application.html.erb"]
-      else
-        [:fail, "React shell missing from application.html.erb"]
+      unless File.exist?(path)
+        return [:fail, "React shell missing from application.html.erb",
+                "Run rails generate ruact:install to add the React shell to application.html.erb."]
       end
+      content    = File.read(path)
+      has_root   = Ruact::LayoutSource.root?(content)
+      has_assets = Ruact::LayoutSource.wired?(content)
+      opted_in   = Ruact.config.layout != false
+      return layout_unwired_result unless has_root && has_assets
+      return layout_not_opted_in_result unless opted_in
+      [:pass, "layout owns the document (React root + ruact_js_assets, config.layout on)"]
+    end
+    def layout_unwired_result
+      [:fail, "layout is missing the React root and/or the ruact_js_assets call",
+       "Add <%= ruact_js_assets %> next to <div id=\"root\"></div> in " \
+       "app/views/layouts/application.html.erb (or re-run rails generate ruact:install). " \
+       "Without both, ruact renders its built-in shell and your app's CSS never reaches the page."]
+    end
+    def layout_not_opted_in_result
+      [:warn, "layout is ready but Ruact.config.layout is false",
+       "Your layout calls ruact_js_assets, but ruact is still rendering its built-in shell " \
+       "(which has no stylesheet). Set `config.layout = true` in config/initializers/ruact.rb."]
     end
     def check_streaming
@@ -198,7 +287,8 @@ module Ruact
       [:warn,
        "#{present.join(', ')} is mounted and may transform `text/x-component` (Flight) responses, " \
        "breaking the wire contract / streaming. Exclude Flight responses from compression " \
-       "(don't compress `text/x-component`) or mount it so it does not wrap the Flight routes."]
+       "(don't compress `text/x-component`) or mount it so it does not wrap the Flight routes.",
+       "Exclude text/x-component from compression, or mount the middleware so it does not wrap Flight routes."]
     end
     # Returns the app middleware stack to scan, or nil when unavailable (no

data/lib/ruact/erb_preprocessor.rb CHANGED Viewed

@@ -28,6 +28,29 @@ module Ruact
     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[^>]*)?>}
+    # 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]*>}
+    # 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).
+    ERB_ISLAND_RE = /<%.*?%>/m
     # Matches a +{ruby_expr}+ attribute value — captures everything between the braces.
     # We use a simple bracket-depth counter approach during scanning instead of regex
     # because expressions can contain nested braces: {foo.bar({ a: 1 })}.
@@ -66,6 +89,16 @@ module Ruact
                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)
@@ -99,6 +132,86 @@ module Ruact
     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] = [] }
+      scan.scan(COMPONENT_ANY_TAG_RE) do
+        m    = ::Regexp.last_match
+        name = m[2]
+        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)
+        end
+      end
+      nil
+    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={...} />`."
+    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.
+    def mask_suspense(source)
+      source
+        .gsub(SUSPENSE_OPEN_RE)  { |m| m.gsub(/[^\n]/, " ") }
+        .gsub(SUSPENSE_CLOSE_RE) { |m| m.gsub(/[^\n]/, " ") }
+    end
+    # 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.
+    def mask_erb(source)
+      source.gsub(ERB_ISLAND_RE) { |m| m.gsub(/[^\n]/, " ") }
+    end
     # Extract a string attribute value (double or single quoted) from an attrs string.
     def extract_string_attr(attrs, name)
       m = attrs.match(/\b#{Regexp.escape(name)}\s*=\s*"([^"]*)"/) ||

data/lib/ruact/errors.rb CHANGED Viewed

@@ -22,6 +22,22 @@ 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
   # Raised when application code attempts to mutate Ruact::Configuration outside
   # of a Ruact.configure block. The configuration is frozen after initialization
   # to prevent runtime drift; see Story 7.3 for the rationale and the decision

data/lib/ruact/layout_source.rb ADDED Viewed

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+module Ruact
+  # Answers one question in ONE place: does this layout actually wire ruact up?
+  #
+  # Two callers need that answer and must not disagree about it — the runtime
+  # (`Ruact::Controller::DocumentRendering`, deciding whether it is safe to
+  # render through the host layout) and `ruact:install` (deciding whether the
+  # layout still needs migrating). When they each carried their own notion of
+  # "present", they drifted: the generator skipped a layout as already-migrated
+  # on a `<%# TODO: add ruact_js_assets %>` comment, while the runtime read the
+  # same layout as unwired. Both were string-matching a NAME where only a CALL
+  # counts.
+  module LayoutSource
+    # ERB comments are stripped before anything else. A commented-out call —
+    # `<%# <%= ruact_js_assets %> %>`, which a developer produces the moment
+    # they disable it while debugging — emits NOTHING, so counting it as wired
+    # would report a layout as migrated when it is not. The `-?` covers ERB's
+    # trim-mode forms (`<%-#` / `-%>`), which Erubi treats as comments too and
+    # an earlier version of this pattern missed.
+    ERB_COMMENT = /<%-?#.*?-?%>/m
+    # An ERB OUTPUT tag calling the helper: `<%= ruact_js_assets %>` and the raw
+    # `<%== ... %>` form, with or without arguments or surrounding whitespace.
+    # Scanning stops at the tag's own `%>` rather than forbidding `%` outright —
+    # `<%= raw("100%") + ruact_js_assets %>` is a legitimate call that a
+    # `[^%]*` pattern rejected, while still never matching a bare mention that
+    # merely follows some other tag.
+    ASSETS_CALL = /<%=+(?:(?!%>).)*?\bruact_js_assets\b/m
+    # The React mount target, as an attribute rather than as a substring. The
+    # lookbehind is what stops `data-id="root"` (and any other `*-id`) from
+    # counting: those are not the mount point, and a document that has one but
+    # no real root gives React nothing to mount into. Unquoted `id=root` is
+    # valid HTML and is accepted.
+    ROOT_ATTRIBUTE = /(?<![-\w])id\s*=\s*(?:"root"|'root'|root(?=[\s>]))/
+    # The whole element, for a generator that needs something to inject AFTER.
+    ROOT_ELEMENT = %r{<div\s[^>]*#{ROOT_ATTRIBUTE.source}[^>]*>\s*</div>}
+    class << self
+      # Does this ERB source actually CALL `ruact_js_assets`?
+      def wired?(source)
+        without_comments(source).match?(ASSETS_CALL)
+      end
+      # Does this markup carry a React mount target? Used on RENDERED HTML by
+      # the runtime and on ERB source by the generator; the attribute shape is
+      # the same either way.
+      def root?(markup)
+        markup.to_s.match?(ROOT_ATTRIBUTE)
+      end
+      def without_comments(source)
+        source.to_s.gsub(ERB_COMMENT, "")
+      end
+    end
+  end
+end

data/lib/ruact/manifest_resolver.rb CHANGED Viewed

@@ -79,8 +79,8 @@ module Ruact
       return nil if soft
       raise ManifestError, <<~MSG.strip
-        [ruact] Vite dev server inacessível em #{base_url} e nenhum \
-        react-client-manifest.json encontrado em #{file_path} — rode `bin/dev`.
+        [ruact] Vite dev server unreachable at #{base_url} and no \
+        react-client-manifest.json found at #{file_path} — run `bin/dev`.
       MSG
     end

data/lib/ruact/serializable.rb CHANGED Viewed

@@ -5,32 +5,71 @@ module Ruact
   # client component. Declare which attributes are safe to serialize with
   # +ruact_props+; only those attributes will be included in the wire payload.
   #
-  # @example
+  # Works on POROs and on ActiveRecord models alike. For a PORO the loud check
+  # fires at class-load; for an ActiveRecord model (whose attribute readers are
+  # defined lazily) the same loud check is deferred to the first
+  # +ruact_serialize+ — see {ClassMethods#ruact_props}.
+  #
+  # @example PORO
   #   class Post
   #     include Ruact::Serializable
   #     attr_reader :id, :title, :secret
   #     ruact_props :id, :title   # :secret is never sent to the client
   #   end
+  #
+  # @example ActiveRecord model
+  #   class Post < ApplicationRecord
+  #     include Ruact::Serializable
+  #     ruact_props :id, :title   # other columns never cross to the client
+  #   end
   module Serializable
     def self.included(base)
       base.extend(ClassMethods)
       base.instance_variable_set(:@ruact_props, [])
+      base.instance_variable_set(:@ruact_deferred_props, [])
     end
     module ClassMethods
       # Declare which instance methods should be included in the serialized
-      # payload. Raises +ArgumentError+ at class-load time if any name has no
-      # corresponding method defined on the class.
+      # payload.
+      #
+      # The loud-omission guarantee is preserved: a name with no corresponding
+      # method still raises a clean +ArgumentError+. Only the *timing* of that
+      # check depends on the class:
+      #
+      # * **PORO** — checked eagerly at class-load (macro-invocation) time, as
+      #   before. A typo'd/absent prop raises immediately.
+      # * **ActiveRecord model** — ActiveRecord defines its attribute reader
+      #   methods lazily (on first instance access), so at macro-invocation time
+      #   +method_defined?(:title)+ is +false+ even for a real column. Checking
+      #   eagerly would either reject a valid model at boot or require a live DB
+      #   connection at class-load (a Rails anti-pattern). So for a lazy-attribute
+      #   class the not-yet-defined names are recorded and their loud check is
+      #   deferred to the first +ruact_serialize+ (via +respond_to?+ on the
+      #   instance), where the DB is up. A genuine typo still raises the same
+      #   clean +ArgumentError+ — just at first render of that model, not at boot.
       #
       # @param attrs [Array<Symbol>]
+      # @raise [ArgumentError] immediately for an undefined prop on a PORO; at
+      #   first +ruact_serialize+ for an undefined prop on an ActiveRecord model.
       def ruact_props(*attrs)
+        deferred = []
         attrs.each do |attr|
-          unless method_defined?(attr)
-            raise ArgumentError,
-                  "ruact_props: method `#{attr}` is not defined on #{self}"
+          next if method_defined?(attr)
+          # Lazy-attribute (ActiveRecord) class: the reader may still appear on
+          # first instance access. Record it and check loudly on first serialize
+          # instead of failing a valid model at boot.
+          if ruact_lazy_attribute_class?
+            deferred << attr
+            next
           end
+          raise ArgumentError,
+                "ruact_props: method `#{attr}` is not defined on #{self}"
         end
         @ruact_props = attrs
+        @ruact_deferred_props = deferred
       end
       # Returns the list of declared prop names as symbols.
@@ -46,12 +85,65 @@ module Ruact
         end
         []
       end
+      # Names whose eager loud check was deferred to first serialize (lazy
+      # ActiveRecord attributes). Read from the same class that declared the
+      # props, so subclasses share the parent declaration.
+      #
+      # @return [Array<Symbol>]
+      def ruact_deferred_props_list
+        klass = self
+        while klass
+          if klass.instance_variable_defined?(:@ruact_props)
+            return klass.instance_variable_get(:@ruact_deferred_props) || []
+          end
+          klass = klass.superclass
+        end
+        []
+      end
+      # Run the deferred loud check once, on first +ruact_serialize+. A recorded
+      # name that the instance does not +respond_to?+ (a typo, or a genuinely
+      # absent column) raises the same clean +ArgumentError+ the eager path would.
+      #
+      # Memoization keys on the *validated deferred list itself* (not a bare
+      # boolean), so any change to the effective declaration — a re-declaration
+      # on this class OR on an ancestor whose props a subclass inherits — is
+      # detected and re-validated loudly on the next serialize. Once a given
+      # list has been validated it costs one array comparison per serialize.
+      #
+      # @param instance [Object]
+      # @raise [ArgumentError]
+      def ruact_validate_deferred_props!(instance)
+        deferred = ruact_deferred_props_list
+        return if @ruact_deferred_props_validated == deferred
+        deferred.each do |attr|
+          next if instance.respond_to?(attr)
+          raise ArgumentError,
+                "ruact_props: method `#{attr}` is not defined on #{self}"
+        end
+        @ruact_deferred_props_validated = deferred
+      end
+      # True when this class defines its attribute reader methods lazily, i.e.
+      # an ActiveRecord model. Detected WITHOUT a hard ActiveRecord dependency
+      # (the gem stays single-dep +nokogiri+): the constant is only referenced
+      # when it is already defined in the host.
+      #
+      # @return [Boolean]
+      def ruact_lazy_attribute_class?
+        !!(defined?(ActiveRecord::Base) && self < ActiveRecord::Base)
+      end
     end
     # Serialize only the attributes declared with +ruact_props+.
     #
     # @return [Hash{String => Object}]
     def ruact_serialize
+      self.class.ruact_validate_deferred_props!(self)
       self.class.ruact_props_list.to_h { |attr| [attr.to_s, public_send(attr)] }
     end
   end