RubyGems - ruact - Versions diffs - 0.0.8 → 0.0.10 - Mend

ruact 0.0.8 → 0.0.10

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 (39) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +59 -1
data/LICENSE.txt +21 -0
data/README.md +124 -18
data/SECURITY.md +1 -1
data/lib/generators/ruact/install/install_generator.rb +264 -5
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 +5 -46
data/lib/ruact/doctor.rb +37 -5
data/lib/ruact/layout_source.rb +59 -0
data/lib/ruact/version.rb +1 -1
data/lib/ruact/view_helper.rb +10 -1
data/lib/ruact.rb +1 -0
data/spec/fixtures/readme/children-error.html.erb +3 -0
data/spec/fixtures/readme/children-error.txt +1 -0
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/readme_demo_message_spec.rb +67 -0
data/spec/readme_spec.rb +282 -0
data/spec/ruact/controller_request_spec.rb +203 -0
data/spec/ruact/doctor_spec.rb +81 -6
data/spec/ruact/install_generator_spec.rb +442 -70
data/spec/ruact/layout_source_spec.rb +108 -0
data/spec/ruact/scaffold_generator_spec.rb +14 -0
metadata +30 -5

data/lib/generators/ruact/install/templates/globals.css.tt ADDED Viewed

@@ -0,0 +1,20 @@
+/* Tailwind entry — the SOURCE, not the asset the browser gets.
+ *
+ * Built into app/assets/builds/tailwind.css by the `css` process in
+ * Procfile.dev, which Propshaft then serves and the layout links:
+ *
+ *   this file ──build──> app/assets/builds/tailwind.css
+ *             ──Propshaft──> /assets/tailwind-<digest>.css
+ *             ──stylesheet_link_tag in app/views/layouts──> the page
+ *
+ * `npx shadcn init` appends its design tokens (the CSS variables the
+ * components reference by name) below this import — that is why
+ * components.json points its `tailwind.css` at this file.
+ */
+@import "tailwindcss";
+/* Tailwind v4 declares its class scan here instead of in a config file.
+   Components carry most of the classes; the ERB views carry the page-level
+   ones, so both paths are needed. */
+@source "../components";
+@source "../../views";

data/lib/generators/ruact/install/templates/initializer.rb.tt CHANGED Viewed

@@ -1,6 +1,15 @@
 # frozen_string_literal: true
 Ruact.configure do |config|
+  # Render ruact pages through your app's own layout, so the document `<head>`
+  # is yours: `stylesheet_link_tag`, favicons, fonts, analytics and any gem that
+  # writes into `<head>` all reach a ruact page. Requires the layout to call
+  # `<%%= ruact_js_assets %>` (this generator adds it next to the React root).
+  #
+  # Set to false to use ruact's built-in minimal shell instead — it has no
+  # stylesheet slot, so your app's CSS will NOT reach a ruact-rendered page.
+  config.layout = true
   # Path to the react-client-manifest.json generated by the Vite plugin.
   # Defaults to Rails.root.join("public/react-client-manifest.json").
   # config.manifest_path = Rails.root.join("public", "react-client-manifest.json")

data/lib/generators/ruact/install/templates/package.json.tt CHANGED Viewed

@@ -4,7 +4,8 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "vite build"
+    "build": "vite build"<% if shadcn? %>,
+    "build:css": "@tailwindcss/cli -i app/javascript/styles/globals.css -o app/assets/builds/tailwind.css --minify"<% end %>
   },
   "dependencies": {
     "react": "^19.0.0",
@@ -12,6 +13,11 @@
   },
   "devDependencies": {
     "@vitejs/plugin-react": "^4.3.4",
+<% if shadcn? -%>
+    "@tailwindcss/cli": "^4.0.0",
+    "tailwindcss": "^4.0.0",
+    "tw-animate-css": "^1.0.0",
+<% end -%>
     "vite": "^6.0.7"
   }
 }

data/lib/generators/ruact/install/templates/tsconfig.json.tt ADDED Viewed

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["app/javascript/*"]
+    }
+  },
+  "include": ["app/javascript/**/*.ts", "app/javascript/**/*.tsx"]
+}

data/lib/generators/ruact/scaffold/scaffold_shadcn_preflight.rb CHANGED Viewed

@@ -47,6 +47,16 @@ module Ruact
         # List/DeleteDialog primitives. EVERY entry is a plain `npx shadcn add`
         # primitive — there is NO `data-table` recipe and NO `@tanstack/react-table`
         # dependency (Story 10.2b removed the engine; the List is a plain `table`).
+        # The COMPLETE primitive set — the union of everything any generated
+        # resource can import. `#required_shadcn_components` NARROWS this per
+        # resource (the input-family entries depend on the attribute types),
+        # but `ruact:install --shadcn` runs before any resource exists, so it
+        # prints this superset. A spec pins the narrowed list as a subset of
+        # this one, so the two cannot drift apart.
+        ALL_SHADCN_COMPONENTS = %w[
+          button input textarea switch select label badge table alert-dialog dropdown-menu
+        ].freeze
         def required_shadcn_components
           components = ["button"]
           components << "input"    if form_uses_input?

data/lib/ruact/configuration.rb CHANGED Viewed

@@ -24,6 +24,7 @@ module Ruact
       signed_global_id_default_purpose
       signed_global_id_default_expires_in
       shadcn_compatible_versions
+      layout
     ].freeze
     # @!attribute [r] manifest_path
@@ -135,6 +136,47 @@ module Ruact
     #     suppress the warning — the documented "override" path.
     #   @example Allow shadcn v3 once you have verified it
     #     Ruact.configure { |c| c.shadcn_compatible_versions = [1, 2, 3] }
+    #
+    # @!attribute [r] layout
+    #   @return [Boolean, String] Which document wrapper a ruact page's HTML
+    #     response is rendered into. The Flight response shape
+    #     (`text/x-component`) is never affected — this is only about the
+    #     full-document render a browser gets on a normal navigation.
+    #
+    #     - `false` (default) — render the gem's built-in minimal shell.
+    #     - `true` — render through the controller's normal Rails layout.
+    #     - a String — render through that named layout (e.g. `"ruact"`).
+    #
+    #     The layout path exists because the document `<head>` belongs to the
+    #     host app: `stylesheet_link_tag`, favicons, fonts, analytics and any
+    #     `<head>`-writing gem only reach the page when Rails' own layout owns
+    #     the document. The built-in shell carries no stylesheet slot, so under
+    #     the `false` default a ruact page renders with no app CSS at all —
+    #     which is why `rails generate ruact:install` writes `config.layout =
+    #     true` into the generated initializer and adds `<%= ruact_js_assets %>`
+    #     to your layout in the same run.
+    #
+    #     **This setting is deliberately explicit — there is no auto-detection.**
+    #     ruact used to try to infer whether your layout was ready by inspecting
+    #     it. Deciding that reliably means answering "does this template call
+    #     this method?", which cannot be done by pattern-matching a template
+    #     language: three review rounds each found another shape that fooled it
+    #     (a mention in a comment, a commented-out call, a trim-mode comment),
+    #     and each wrong answer governed how every page in the app rendered.
+    #     One explicit line is worth more than a clever guess here.
+    #
+    #     A layout is ready when it calls `<%= ruact_js_assets %>` (which emits
+    #     the React root's bootstrap entry tags and the per-render Flight
+    #     payload) next to a `<div id="root"></div>`. If it does not, ruact says
+    #     so loudly in development rather than serving a blank page, and
+    #     `rails ruact:doctor` reports it.
+    #   @note A ruact view is rendered in its own pass (it produces the component
+    #     tree), so `content_for` declared inside the view does NOT reach the
+    #     layout. Set document metadata from the controller instead.
+    #   @example Let your layout own the document (what ruact:install writes)
+    #     Ruact.configure { |c| c.layout = true }
+    #   @example Use a dedicated layout for ruact pages only
+    #     Ruact.configure { |c| c.layout = "ruact" }
     ATTRIBUTES.each do |attr|
       attr_reader attr
@@ -188,6 +230,7 @@ module Ruact
         @signed_global_id_default_purpose = nil
         @signed_global_id_default_expires_in = nil
         @shadcn_compatible_versions = [1, 2]
+        @layout = false
       end
     end
@@ -249,7 +292,37 @@ module Ruact
       when :query_route_prefix      then validate_query_route_prefix!(value)
       when :query_parent_controller then validate_query_parent_controller!(value)
       when :shadcn_compatible_versions then validate_shadcn_compatible_versions!(value)
+      when :layout                     then validate_layout!(value)
+      end
+    end
+    # The value selects a render strategy by identity (`true` / `false`) or
+    # names a layout (String). Anything else would otherwise be treated as "not
+    # false" and reach `render_to_string(layout: <value>)`, where a Symbol
+    # layout name or a stray nil surfaces as a confusing first-request 500
+    # instead of a boot-time error. `nil` is rejected on purpose: "no layout" is
+    # spelled `false`, so a nil left over from a conditional in the initializer
+    # is a mistake, not a silent shell fallback.
+    def validate_layout!(value)
+      return if [true, false].include?(value)
+      return if value.is_a?(String) && !value.empty?
+      # `:auto` is rejected BY NAME because it used to be the default. An app
+      # carrying it forward from an older initializer must be told it is gone,
+      # not have it silently reinterpreted as "some truthy value".
+      if value == :auto
+        raise Ruact::ConfigurationError,
+              "Ruact::Configuration#layout no longer supports :auto — it inferred whether your " \
+              "layout was ready by inspecting it, which could not be done reliably. " \
+              "Set `true` to render through your app's layout (make sure it calls " \
+              "`<%= ruact_js_assets %>`), or `false` for ruact's built-in shell."
       end
+      raise Ruact::ConfigurationError,
+            "Ruact::Configuration#layout must be true, false, or a non-empty String layout name; " \
+            "got #{value.inspect} (#{value.class.name}). " \
+            "true renders through your app's layout (which must call ruact_js_assets); " \
+            "false uses ruact's built-in shell."
     end
     def validate_max_upload_bytes!(value)

data/lib/ruact/controller/document_rendering.rb ADDED Viewed

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+module Ruact
+  module Controller
+    # How a ruact response becomes a full HTML DOCUMENT — the wrapper a browser
+    # gets on a normal navigation, as opposed to the raw `text/x-component`
+    # Flight body an in-app navigation gets.
+    #
+    # Split out of `Ruact::Controller` because it answers one self-contained
+    # question ("who owns the `<head>`?") whose answer is load-bearing: the host
+    # app's layout does, because `stylesheet_link_tag`, favicons, fonts,
+    # analytics and every `<head>`-writing gem live there. `#ruact_html_shell`
+    # is the fallback for an app whose layout has not been migrated — it is
+    # deliberately minimal and has NO stylesheet slot.
+    module DocumentRendering
+      extend ActiveSupport::Concern
+      # Proof that a host layout called `ruact_js_assets`: the helper always
+      # emits the `__FLIGHT_DATA` bootstrap script when a payload is present,
+      # and `render_ruact_document` always supplies one. Matching on the payload
+      # script (rather than on the entry `<script src>`) keeps the check true in
+      # BOTH dev and production, whose entry tags differ.
+      RUACT_ASSETS_MARKER = "__FLIGHT_DATA"
+      # What counts as a mount target and what counts as a real call both live in
+      # {Ruact::LayoutSource}, shared with `ruact:install` so the runtime and the
+      # generator can never disagree about whether a layout is migrated.
+      private
+      # Emit the full HTML document a browser gets on a normal navigation.
+      #
+      # `Ruact.config.layout` decides, and it is EXPLICIT — ruact does not try
+      # to infer whether your layout is ready. It used to: three review rounds
+      # each found another template shape that fooled the inference (a mention
+      # in a comment, a commented-out call, a trim-mode comment), and each wrong
+      # answer governed how every page in the app rendered. Answering "does this
+      # template call this method?" is not something pattern-matching can do
+      # reliably, so the question is no longer asked. See
+      # Ruact::Configuration#layout.
+      #
+      # - `false` (the default) → the built-in shell. Byte-identical to ruact's
+      #   behaviour before the layout path existed, with no detection in the
+      #   way, so an app that has not opted in cannot be affected by any of this.
+      # - `true` / a String → render through the app's layout. `ruact:install`
+      #   writes both halves of that opt-in together: `config.layout = true` in
+      #   the initializer AND `<%= ruact_js_assets %>` in the layout.
+      #
+      # An opted-in layout that does not actually emit the assets would produce
+      # a blank page, so the rendered document is checked before it is
+      # committed: that is a configuration error, raised in development/test and
+      # logged-and-degraded in production rather than served to real traffic.
+      def render_ruact_document(payload)
+        layout = Ruact.config.layout
+        return render html: ruact_html_shell(payload).html_safe, layout: false if layout == false
+        unless ruact_layout_resolvable?(layout)
+          __ruact_handle_unready_layout(layout, :missing)
+          return render html: ruact_html_shell(payload).html_safe, layout: false
+        end
+        # Copied to the view by Rails' `view_assigns` plumbing (the name does not
+        # match the `/\A@_/` protected-ivar filter) — that is how the layout's
+        # zero-argument `ruact_js_assets` reaches THIS render's Flight payload.
+        @ruact_flight_payload = payload
+        document = render_to_string(html: "".html_safe, layout: layout)
+        if ruact_document_mountable?(document)
+          render html: document.html_safe, layout: false
+        else
+          __ruact_handle_unready_layout(layout, :unwired)
+          render html: ruact_html_shell(payload).html_safe, layout: false
+        end
+      ensure
+        remove_instance_variable(:@ruact_flight_payload) if instance_variable_defined?(:@ruact_flight_payload)
+      end
+      # A document is only usable if BOTH halves are present: the payload/bootstrap
+      # block AND something to mount into. Checking the assets alone accepts a
+      # layout that calls `ruact_js_assets` in `<head>` but never got the root div
+      # — React then boots with no mount target and the page is silently blank.
+      def ruact_document_mountable?(document)
+        document.include?(RUACT_ASSETS_MARKER) && Ruact::LayoutSource.root?(document)
+      end
+      # Is there a layout to render into at all? Asking FIRST matters: passing
+      # `layout: true` to a controller with no resolvable layout raises
+      # `ArgumentError("There was no default layout for ...")`, which would turn
+      # every page of an API-shaped or `layout false` controller into a 500 in
+      # an app that opted in globally. `_default_layout`'s `require_layout`
+      # argument defaults to false precisely so it can be used as a probe — it
+      # returns nil instead of raising, and honours `action_has_layout?`.
+      #
+      # `NameError` is deliberately NOT swallowed: `_default_layout` re-raises it
+      # as "Could not render layout: ..." to surface a broken layout resolver
+      # (`layout -> { MissingConstant::LAYOUT }`). Turning that into "no layout"
+      # would hide the developer's bug behind a silently degraded page.
+      def ruact_layout_resolvable?(layout)
+        return ruact_layout_exists?(layout) if layout.is_a?(String)
+        resolved = _default_layout(lookup_context, [:html], [])
+        return false if resolved.nil? || resolved == false
+        # `_default_layout` returns a Template for the conventional lookup but a
+        # bare String path for a controller-declared `layout "name"` — and it
+        # returns that String WITHOUT checking the template exists. Treating
+        # "not nil" as resolvable therefore sent a declared-but-missing layout
+        # into `render_to_string`, where it raised `MissingTemplate` instead of
+        # taking the intended degrade-to-shell path.
+        return ruact_layout_exists?(resolved) if resolved.is_a?(String)
+        true
+      rescue NameError
+        raise
+      rescue StandardError
+        false
+      end
+      def ruact_layout_exists?(name)
+        lookup_context.exists?(name.to_s.delete_prefix("layouts/"), ["layouts"])
+      end
+      def __ruact_handle_unready_layout(_layout, reason)
+        detail =
+          if reason == :missing
+            "no layout could be resolved for it"
+          else
+            "the layout it rendered emitted no `ruact_js_assets` output (or no " \
+              "`<div id=\"root\"></div>` to mount into), which would have been a blank page"
+          end
+        message = <<~MSG.strip
+          ruact: #{controller_path}##{action_name} fell back to ruact's built-in HTML shell — #{detail}.
+            `Ruact.config.layout` is set, so this is a configuration error, not a default:
+            the built-in shell has no stylesheet slot, so your app's CSS does not reach this page.
+            Add `<%= ruact_js_assets %>` next to the `<div id="root"></div>` in your layout
+            (`rails generate ruact:install` writes both; `rails ruact:doctor` reports what is missing),
+            or set `Ruact.configure { |c| c.layout = false }` to use the built-in shell deliberately.
+        MSG
+        # A MISSING layout is a legitimate per-controller choice — an API-shaped
+        # controller, or one that declared `layout false`, inside an app that
+        # opted in globally. Raising there would break a normal Rails pattern,
+        # so it degrades to the shell and says so where a developer will see it.
+        #
+        # An UNWIRED layout is different: the developer pointed ruact at a
+        # layout that cannot mount the app, which is their bug to see — loudly
+        # in development, and degraded (never blank) in production.
+        if reason == :missing
+          logger&.info(message) if __ruact_local_env?
+          return
+        end
+        raise Ruact::Error, message if __ruact_local_env?
+        logger&.error(message)
+      end
+      def __ruact_local_env?
+        Rails.env.development? || Rails.env.test?
+      rescue StandardError
+        false
+      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
+end

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
@@ -178,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
@@ -236,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

@@ -171,14 +171,46 @@ module Ruact
       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",
-         "Run rails generate ruact:install to add the React shell to 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

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/version.rb CHANGED Viewed

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

data/lib/ruact/view_helper.rb CHANGED Viewed

@@ -44,12 +44,21 @@ module Ruact
     # (no drift). Available in every view via the railtie's
     # `ActionView::Base.include(Ruact::ViewHelper)`.
     #
+    # Called from a LAYOUT the argument is normally omitted: the payload for the
+    # render in flight is picked up from `@ruact_flight_payload`, which
+    # `Ruact::Controller#render_ruact_document` sets on the controller and Rails
+    # copies to the view (the name does not match the `/\A@_/` protected-ivar
+    # filter). On a plain Rails page — no ruact render in flight — that ivar is
+    # absent and the helper emits only the entry tags, exactly as before.
+    #
     # @param flight_payload [String, nil] the per-render Flight wire payload to
-    #   inline as `__FLIGHT_DATA`; omit (or pass nil) to emit only the entry tags.
+    #   inline as `__FLIGHT_DATA`. Omit inside a layout to use the render in
+    #   flight; an explicit argument always wins.
     # @return [ActiveSupport::SafeBuffer] the asset markup, html_safe
     # @example In a layout
     #   <%= ruact_js_assets %>
     def ruact_js_assets(flight_payload = nil)
+      flight_payload ||= @ruact_flight_payload
       parts = []
       parts << ruact_flight_data_script(flight_payload) unless flight_payload.nil?
       parts << ruact_vite_tags

data/lib/ruact.rb CHANGED Viewed

@@ -7,6 +7,7 @@ require_relative "ruact/serializable"
 require_relative "ruact/signed_references"
 require_relative "ruact/flight"
 require_relative "ruact/string_distance"
+require_relative "ruact/layout_source"
 require_relative "ruact/component_contract"
 require_relative "ruact/erb_preprocessor"
 require_relative "ruact/render_context"

data/spec/fixtures/readme/children-error.html.erb ADDED Viewed

@@ -0,0 +1,3 @@
+<h1><%= @greeting %></h1>
+<LikeButton likes={@likes}>Like</LikeButton>

data/spec/fixtures/readme/children-error.txt ADDED Viewed

	@@ -0,0 +1 @@
1	+ ruact: <LikeButton> at app/views/home/index.html.erb:3 children are not supported — pass content as a prop, e.g. `<LikeButton content={...} />`.

data/spec/fixtures/story_7_9_views/controller_request_spec_support/exploding_layout_demo/show.html.erb ADDED Viewed

@@ -0,0 +1,3 @@
+<div>
+  <DemoButton label={"hello"} />
+</div>

data/spec/fixtures/story_7_9_views/controller_request_spec_support/ghost_layout_demo/show.html.erb ADDED Viewed

@@ -0,0 +1,3 @@
+<div>
+  <DemoButton label={"hello"} />
+</div>

data/spec/fixtures/story_7_9_views/controller_request_spec_support/layout_demo/show.html.erb ADDED Viewed

@@ -0,0 +1,3 @@
+<div>
+  <DemoButton label={"hello"} />
+</div>