ruact 0.0.12 → 0.0.14

data/lib/ruact/routing.rb

@@ -24,9 +24,9 @@ module Ruact
   # The path segment reuses {Ruact::ServerFunctions::NameBridge} verbatim
   # (D4): `def search_users` → `GET /q/searchUsers`, named
   # `ruact_query_searchUsers`. Invalid or JS-reserved method names raise
-  # {Ruact::ConfigurationError} at route-draw time; two query classes mounting
-  # the same method name collide on the route NAME / path and fail Rails' own
-  # duplicate checks — both are loud boot failures, never request-time
+  # {Ruact::ConfigurationError} at route-draw time, and so do two query
+  # classes mounting the same method name (they would collide on the route
+  # name and on the export) — both are loud boot failures, never request-time
   # surprises.
   #
   # The generated dispatch controller PRESERVES the query class's namespace
@@ -56,11 +56,29 @@ module Ruact
 
         query_class.public_instance_methods(false).each do |query_method|
           js_identifier = ServerFunctions::NameBridge.to_js_identifier(query_method)
-          mapper.get("#{prefix}/#{js_identifier}",
-                     to: "#{target}##{query_method}",
-                     as: :"ruact_query_#{js_identifier}")
+          begin
+            mapper.get("#{prefix}/#{js_identifier}",
+                       to: "#{target}##{query_method}",
+                       as: :"ruact_query_#{js_identifier}")
+          rescue ArgumentError => e
+            raise unless e.message.include?("already in use")
+
+            raise_query_name_taken!(query_class, query_method, "#{prefix}/#{js_identifier}")
+          end
         end
       end
+
+      # Rails' own message ("Invalid route name, already in use") names a route
+      # the app never wrote. Name the query, the method and the way out.
+      def raise_query_name_taken!(query_class, query_method, path)
+        raise Ruact::ConfigurationError,
+              "#{query_class}##{query_method} cannot be mounted: GET #{path} is already mounted " \
+              "in these routes — by another query class that also defines `#{query_method}`, or " \
+              "by `ruact_queries #{query_class}` appearing twice. Query names share one namespace " \
+              "(one route and one export of @/.ruact/server-functions per name): remove the " \
+              "duplicate mount, or rename one of the methods (the scaffold names its search " \
+              "after the resource: search_posts, search_comments)."
+      end
     end
   end
 end

data/lib/ruact/server.rb

@@ -277,12 +277,21 @@ module Ruact
       _ensure_url_is_http_header_safe(location)
       location = _enforce_open_redirect_protection(location, allow_other_host: allow_other_host)
 
+      # Story 13.3 (FR98) — registered errors ride flash to the page the
+      # runtime navigates to (a router Flight GET: no layout prints them). A
+      # function call never reaches Ruact::Controller#redirect_to's Flight path,
+      # so the stash lives here too (Story 17.0g review R3). Same-origin only,
+      # like that path: after a redirect to another origin the flash entry
+      # would wait in the session for whatever page the user opens next.
+      path = __ruact_redirect_path(location)
+      __ruact_stash_errors_in_flash if path.start_with?("/") && !path.start_with?("//")
+
       # Story 15.0 (F6) — a Bucket-2 `redirect_to` is a ruact-owned response
       # (`$redirect`; registered errors ride flash), not an injection opt-out.
       @__ruact_function_response_owned = true
       # Story 15.5 (FR109) — mark the `$redirect` sub-shape for the dev log.
       @__ruact_function_redirect = true
-      render json: { "$redirect" => __ruact_redirect_path(location) }
+      render json: { "$redirect" => path }
     end
 
     private

data/lib/ruact/version.rb

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

data/lib/ruact/view_helper.rb

@@ -25,12 +25,71 @@ module Ruact
     # placeholder in the HTML output.
     def __ruact_component__(name, props = {})
       ctx = @ruact_render_context
-      raise Ruact::Error, "ruact: __ruact_component__ called outside a ruact_render flow" if ctx.nil?
+      raise Ruact::Error, __ruact_outside_render_message(name) if ctx.nil?
 
       token = ctx.register(name, props)
       "<!-- #{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
+    # controller's `ruact_pages`. The file and line come from the
+    # `ActionView::Template::Error` Rails wraps this in.
+    def __ruact_outside_render_message(name)
+      template = @current_template&.virtual_path
+      where = template ? "\"#{template}\"" : "this template"
+      # The helper is in every view. A controller action without the concern
+      # has no `ruact_render` to call; a mailer (its view's `controller`) or a
+      # `Controller.render` that ran no action cannot render through ruact at all.
+      owner = respond_to?(:controller) ? controller : nil
+      declined = owner&.instance_variable_get(:@__ruact_declined_render_options)
+      return __ruact_declined_options_message(name, where, declined) if declined.present?
+
+      if owner && !(defined?(Ruact::Controller) && owner.class.include?(Ruact::Controller) &&
+                    __ruact_page_request?(owner))
+        return __ruact_not_a_page_message(name, where) unless __ruact_page_request?(owner)
+
+        return "ruact: <#{name} /> is a client component, and #{where} is being rendered by " \
+               "#{owner.class.name}, which does not include Ruact::Controller. Add " \
+               "`include Ruact::Controller` to it: its pages then render through ruact."
+      end
+
+      # A partial or a layout is not a page: rendering it as one is not the fix.
+      call = if template.nil? || File.basename(template).start_with?("_") || template.start_with?("layouts/")
+               "`ruact_render(template: …, status: …)` for the page that renders it"
+             else
+               "`ruact_render(template: \"#{template}\", status: …)`"
+             end
+      "ruact: <#{name} /> is a client component, and #{where} is being rendered by Rails, outside ruact. " \
+        "Render it through ruact: #{call} — or, when it is this controller's page and the controller " \
+        "declares `ruact_pages`, add the action there (`render :action` then goes through ruact)."
+    end
+
+    # A controller answering a request with an action — not a mailer, not an
+    # `ActionController::Renderer` (no action ran).
+    def __ruact_page_request?(owner)
+      defined?(ActionController::Metal) && owner.is_a?(ActionController::Metal) && owner.action_name.present?
+    end
+
+    # Story 17.0i review R3 — the page was ruact's, but `render` carried an
+    # option ruact does not take, so Rails rendered it.
+    def __ruact_declined_options_message(name, where, options)
+      named = options.map { |option| "`#{option}:`" }.join(", ")
+      "ruact: <#{name} /> is a client component, and #{where} is a ruact page, but its `render` got " \
+        "#{named} — not a render option ruact takes — so Rails rendered it outside ruact. Remove it " \
+        "(a flash message goes in `flash.now`), or render the page with `ruact_render`."
+    end
+
+    def __ruact_not_a_page_message(name, where)
+      "ruact: <#{name} /> is a client component, and #{where} is being rendered outside a request to a " \
+        "ruact controller (a mailer, or `Controller.render`). Client components render only in a page a " \
+        "ruact controller renders."
+    end
+
+    private :__ruact_outside_render_message, :__ruact_page_request?, :__ruact_not_a_page_message,
+            :__ruact_declined_options_message
+
     # Story 14.2 (FR104) — emits ruact's full JavaScript asset block: the
     # dev/prod bootstrap entry `<script>` tags (re-targeting the virtual entry
     # `virtual:ruact/bootstrap` — in dev the react-refresh preamble + `@vite/client`
@@ -65,8 +124,94 @@ module Ruact
       parts.join("\n").html_safe
     end
 
+    # The `<head>` half of the asset contract: the stylesheets Vite emitted for
+    # the client components, linked so they reach the page in production.
+    #
+    # Vite is an ASSET bundler, not a JS bundler — a `"use client"` component
+    # that imports CSS (its own, or one a package ships) produces a stylesheet
+    # recorded on the manifest entry beside `file`. Nothing linked it, so the
+    # styling was built, digest-stamped, served and never referenced. Only
+    # production was affected: the dev server injects that CSS through JS.
+    #
+    # **Why this is separate from {#ruact_js_assets}, and why it belongs in
+    # `<head>`.** The JS helper is injected before `</body>`, and the built-in
+    # shell emits it there too — a position that did not matter while it emitted
+    # only a `<script>`. A stylesheet there is discovered late and sits AFTER
+    # when the browser finds it, and it means third-party CSS outranks the app's
+    # own. So ruact declares that it contributes CSS and says WHERE, rather than
+    # smuggling it through a helper named for JavaScript.
+    #
+    # **Cascade.** Call it ABOVE the app's `stylesheet_link_tag`, so the app's
+    # own CSS is loaded afterwards. The layout ruact ships (`layouts/ruact`,
+    # Story 17.0b) does exactly that; a layout of the app's own does it by hand
+    # (`rails generate ruact:install` prints the line, it never edits a layout).
+    # Order decides ties only — specificity, `!important` and cascade layers all
+    # outrank it — but ties are the common case, and losing them by default is
+    # what makes third-party CSS feel like it "takes over".
+    #
+    # **With the dev server reachable it links no stylesheet**, deliberately:
+    # Vite is already injecting the CSS, and linking the file on disk would serve
+    # whatever the last build left there. In development WITHOUT the dev server it
+    # falls back to the built manifest, matching what `ruact_vite_tags` does.
+    #
+    # It reads the SAME manifest entry as {#ruact_js_assets}, in the same render,
+    # so the script and the stylesheet can never come from different builds.
+    #
+    # **In a document ruact renders it also emits
+    # `<meta name="turbo-visit-control" content="reload">`** (Story 17.0f), in
+    # every environment: Turbo Drive then loads a ruact page in full instead of
+    # swapping it into its own document. Outside a ruact render — the same layout
+    # rendering a plain Rails page — it does not.
+    #
+    # @return [ActiveSupport::SafeBuffer] the meta (in a ruact document) followed
+    #   by the `<link>` markup, html_safe; no links in development with Vite
+    #   running, when no entry exists, or when the entry declares no CSS
+    # @example In a layout
+    #   <head>
+    #     <%= ruact_head_assets %>
+    #     <%= stylesheet_link_tag :app %>
+    #   </head>
+    def ruact_head_assets
+      tags = []
+      tags.push(TURBO_VISIT_CONTROL, TURBO_PREFETCH) if ruact_document?
+      tags.concat(ruact_component_stylesheets) unless Rails.env.development? && vite_dev_running?
+      tags.join("\n").html_safe
+    end
+
+    # Story 17.0f (FR117) — a document ruact rendered must not be swapped into
+    # the page by Turbo Drive: Turbo would keep ITS document, the ruact bootstrap
+    # (a module script, evaluated once per document) would not run again, and
+    # the two routers would end up fighting over one page — dead links and
+    # blank pages after a single round trip (spike 2026-09-12, S3–S7). With this
+    # meta Turbo does a full load instead. It does not depend on Vite, so it is
+    # emitted in development too.
+    TURBO_VISIT_CONTROL = %(<meta name="turbo-visit-control" content="reload">)
+
+    # Story 17.0f (decided by Luiz, 2026-09-25) — in a document ruact rendered,
+    # the ruact router owns every click, but a layout that also loads Turbo 8
+    # still lets Turbo PREFETCH links on hover: a GET that runs the destination's
+    # action for a click Turbo will never handle (seen in playgrounds/
+    # nav-islands). Off in ruact documents; untouched everywhere else.
+    TURBO_PREFETCH = %(<meta name="turbo-prefetch" content="false">)
+
     private
 
+    # Whether the document being rendered is ruact's. `render_ruact_document`
+    # sets `@ruact_flight_payload` for the whole render (copied into the view by
+    # Rails), and removes it after. The same layout rendering a plain Rails page
+    # — the app's layout, in whole-app mode — does not have it, and must not
+    # tell Turbo to reload every visit.
+    def ruact_document?
+      instance_variable_defined?(:@ruact_flight_payload) && !@ruact_flight_payload.nil?
+    end
+
+    def ruact_component_stylesheets
+      entry = vite_manifest_entry(Ruact.bootstrap_virtual_id)
+      return [] if entry.nil?
+
+      Array(entry["css"]).map { |file| %(<link rel="stylesheet" href="/assets/#{file}">) }
+    end
+
     # The `__FLIGHT_DATA` inline bootstrap `<script>` — pushes the per-render
     # Flight payload onto the global queue the bootstrap entry drains on boot.
     # `</script>` in the payload is escaped to prevent an HTML/XSS breakout
@@ -139,7 +284,19 @@ module Ruact
       false
     end
 
+    # Memoized FOR THE DURATION OF ONE RENDER, which is what lets
+    # `ruact_head_assets` and `ruact_js_assets` promise they describe the same
+    # build. They are separate calls in the template, so without this a deploy
+    # landing between them serves one build's stylesheet beside another build's
+    # script — verified reachable in review, not hypothetical.
     def vite_manifest_entry(src_path)
+      @__ruact_manifest_entries ||= {}
+      return @__ruact_manifest_entries[src_path] if @__ruact_manifest_entries.key?(src_path)
+
+      @__ruact_manifest_entries[src_path] = read_vite_manifest_entry(src_path)
+    end
+
+    def read_vite_manifest_entry(src_path)
       manifest_path = Rails.root.join("public", "assets", ".vite", "manifest.json")
       return nil unless File.exist?(manifest_path)
 

data/lib/ruact/views/layouts/ruact.html.erb

@@ -0,0 +1,32 @@
+<%# The document a ruact page renders into when `config.layout = "ruact"` (what
+    `rails generate ruact:install` writes). It ships with the gem and is found by
+    name through a view path the Railtie appends, behind the app's — so an
+    `app/views/layouts/ruact.html.erb` wins over it. `rails generate ruact:layout`
+    puts a copy there; once copied, that file is the app's and no longer changes
+    when the gem does.
+
+    What reaches the <head>: CSRF and CSP, the stylesheets Vite built for the
+    client components, then the app's stylesheets named in
+    `config.layout_stylesheets` — in that order, so the app's CSS loads last and
+    wins ties. What does NOT: the app's JavaScript (importmap, Turbo, Stimulus)
+    and anything else its own layout adds. The page that rendered the document
+    owns its navigation; to bring more of the app in, copy this file.
+
+    The <title> is the app's name on every page: a ruact view renders in its own
+    pass, so nothing it sets can reach this layout. A copied layout can title
+    pages however it likes. %>
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= (Rails.application.class.module_parent_name || Rails.application.class.name).to_s.titleize %></title>
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+    <%= ruact_head_assets %>
+    <%= stylesheet_link_tag(*Ruact.config.layout_stylesheets) if Ruact.config.layout_stylesheets.any? %>
+  </head>
+  <body>
+    <div id="root"></div>
+    <%= ruact_js_assets %>
+  </body>
+</html>

data/lib/ruact.rb

@@ -19,10 +19,25 @@ require_relative "ruact/view_helper"
 require_relative "ruact/erb_preprocessor_hook"
 require_relative "ruact/server_functions"
 require_relative "ruact/query"
+# Story 17.0f — loaded here, not only by the Railtie initializer that installs
+# it, so `config.middleware.delete Ruact::NavigationBoundary::Middleware` in
+# config/application.rb can name the constant before initializers run.
+require_relative "ruact/navigation_boundary"
 # Railtie loads ruact/controller when inside a Rails app
 require_relative "ruact/railtie" if defined?(Rails)
 
 module Ruact
+  # Story 17.0b — the name of the layout the gem ships (lib/ruact/views/layouts/
+  # ruact.html.erb), and what `rails generate ruact:install` writes into
+  # `config.layout`.
+  GEM_LAYOUT = "ruact"
+
+  # Story 17.0g — a real `include` of Ruact::Controller in a Ruby source line,
+  # as `ruact:install` and `ruact:doctor` read it: `include Ruact::Controller`,
+  # `include(Ruact::Controller)`, `include ::Ruact::Controller`, or among
+  # others in one `include`. A mention in a comment does not count.
+  CONTROLLER_INCLUDE = /^[ \t]*include\b[^\n#]*?(?<![\w:])(?:::)?Ruact::Controller\b/
+
   class << self
     attr_accessor :manifest, :streaming_mode
 
@@ -46,6 +61,20 @@ module Ruact
       File.expand_path("../vendor/javascript/vite-plugin-ruact/index.js", __dir__)
     end
 
+    # Story 17.0b — the directory of views the gem ships: today, the
+    # `layouts/ruact` document a ruact page renders into when
+    # `config.layout = "ruact"`. The Railtie APPENDS it to the controller view
+    # paths, so it sits behind the app and every engine — an app's own
+    # `app/views/layouts/ruact.html.erb` wins — and `rails generate ruact:layout`
+    # copies from here when an app wants to own that file.
+    #
+    # Under `lib/` on purpose: `app/` is not packaged (see {Ruact::Packaging}).
+    #
+    # @return [String] absolute path to lib/ruact/views
+    def views_path
+      File.expand_path("ruact/views", __dir__)
+    end
+
     # Story 14.2 (FR104) — the SINGLE source of truth for the bootstrap entry id.
     # ruact's React entry is served as the virtual module `virtual:ruact/bootstrap`
     # (by the bundled Vite plugin) instead of a `app/javascript/application.jsx`