ruact 0.0.12 → 0.0.14

data/lib/ruact/controller/document_rendering.rb

@@ -7,11 +7,15 @@ module Ruact
     # 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.
+    # question: who owns the `<head>`? `Ruact.config.layout` decides.
+    # `rails generate ruact:install` writes `"ruact"` — the layout the gem
+    # ships (Story 17.0b), which links the client-component CSS and the app's
+    # stylesheets named in `config.layout_stylesheets`, and edits no file of
+    # the app. `true` renders through the app's own layout instead, so its whole
+    # `<head>` (favicons, fonts, analytics, `<head>`-writing gems) reaches the
+    # page, at the price of wiring that layout by hand. `#ruact_html_shell` is
+    # the `false` fallback — deliberately minimal, with no slot for the app's
+    # stylesheets.
     module DocumentRendering
       extend ActiveSupport::Concern
 
@@ -42,15 +46,26 @@ module Ruact
       # - `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.
+      # - `"ruact"` (what `ruact:install` writes) → the layout the gem ships,
+      #   found by name through the view path the Railtie appends. An app that
+      #   ejects it (`rails generate ruact:layout`) wins by view-path order.
+      # - `true` / another String → the app's own layout, which has to call
+      #   `<%= ruact_js_assets %>` next to a `<div id="root"></div>` (and
+      #   `<%= ruact_head_assets %>` in `<head>`); the install prints those lines
+      #   rather than editing the file.
       #
       # 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)
+        __ruact_warn_turbo_form_submission if __ruact_local_env?
+        # Set for EVERY branch, the shell included: besides carrying the payload
+        # to a layout's zero-argument `ruact_js_assets`, it is how
+        # `ruact_head_assets` knows this document is ruact's and emits the Turbo
+        # meta (Story 17.0f). Removed in `ensure`, so a later plain-Rails render
+        # through the same layout never inherits it.
+        @ruact_flight_payload = payload
         layout = Ruact.config.layout
         return render html: ruact_html_shell(payload).html_safe, layout: false if layout == false
 
@@ -59,10 +74,10 @@ module Ruact
           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
+        # `@ruact_flight_payload` is 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.
         document = render_to_string(html: "".html_safe, layout: layout)
 
         if ruact_document_mountable?(document)
@@ -119,7 +134,9 @@ module Ruact
         lookup_context.exists?(name.to_s.delete_prefix("layouts/"), ["layouts"])
       end
 
-      def __ruact_handle_unready_layout(_layout, reason)
+      def __ruact_handle_unready_layout(layout, reason)
+        return __ruact_handle_missing_gem_layout if reason == :missing && layout == Ruact::GEM_LAYOUT
+
         detail =
           if reason == :missing
             "no layout could be resolved for it"
@@ -131,10 +148,10 @@ module Ruact
         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.
+            the built-in shell has none of your stylesheets, 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.
+            (`rails ruact:doctor` names the layout and the missing line), use the layout ruact ships
+            with `config.layout = "ruact"`, or set `config.layout = false` for the built-in shell.
         MSG
 
         # A MISSING layout is a legitimate per-controller choice — an API-shaped
@@ -155,6 +172,44 @@ module Ruact
         logger&.error(message)
       end
 
+      # Story 17.0b — `layouts/ruact` ships with the gem and the Railtie appends
+      # its view path. Missing means that path never reached this controller: the
+      # Railtie did not run, or something REPLACED the view paths instead of
+      # adding to them. Not a per-controller choice, so it is logged in
+      # production too — a page served without the app's CSS and no trace of why
+      # is the failure this layout exists to prevent.
+      def __ruact_handle_missing_gem_layout
+        message = <<~MSG.strip
+          ruact: #{controller_path}##{action_name} fell back to ruact's built-in HTML shell — ruact's own
+            layout (`layouts/ruact`, shipped with the gem) could not be found for this controller.
+            Its view path is added by the Ruact Railtie: check that the app boots through it, and that
+            nothing replaces this controller's view paths (`self.view_paths = …`) instead of adding to them.
+            Or copy the layout into your app with `rails generate ruact:layout`.
+        MSG
+        __ruact_local_env? ? logger&.info(message) : logger&.error(message)
+      end
+
+      # Story 17.0h — a form on a Turbo page that posts to a ruact action. Turbo
+      # fetches it and gets back a ruact document, which carries
+      # `turbo-visit-control=reload`. What Turbo then does depends on the status
+      # and on a surrounding Turbo Frame (a 4xx reloads the form's page, a 2xx
+      # is dropped, a 5xx is pasted into the Turbo page), but never shows the
+      # answer — the validation errors, what was typed. The browser, submitting
+      # natively, would. Said in development and test (decision of Luiz); every
+      # Turbo request carries `X-Turbo-Request-Id`.
+      def __ruact_warn_turbo_form_submission
+        return if request.nil? || request.get? || request.head?
+        return if request.headers["X-Turbo-Request-Id"].blank?
+
+        logger&.warn(<<~MSG.strip)
+          [ruact] #{self.class.name}##{action_name} answered a Turbo form submission
+            (#{request.request_method} #{request.path}) with a ruact page (#{response.status}). Turbo does not
+            show a ruact page as a form's answer — it reloads a page, drops the answer, or pastes this document
+            into its own — so validation errors and what was typed are lost. Add data-turbo="false" to that
+            form, so the browser submits it and shows the answer.
+        MSG
+      end
+
       def __ruact_local_env?
         Rails.env.development? || Rails.env.test?
       rescue StandardError
@@ -175,6 +230,7 @@ module Ruact
               <meta charset="UTF-8" />
               <meta name="viewport" content="width=device-width, initial-scale=1" />
               #{ruact_csrf_meta_tag}
+              #{ruact_head_assets}
               <title>Rails RSC</title>
             </head>
             <body>

data/lib/ruact/controller/page_rendering.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Ruact
+  module Controller
+    # Story 17.0i — an explicit `render` of a ruact page goes through ruact.
+    #
+    # `render :new, status: :unprocessable_entity`, the Rails idiom for a failed
+    # save, used to answer 500 on a ruact page: Rails rendered the template on
+    # its own and the first client component raised. `render` is PUBLIC, as
+    # Rails has it — the `responders` gem calls `controller.render`; Rails
+    # excludes its own public methods from `action_methods`, so it is not
+    # routable.
+    module PageRendering
+      # Story 17.0i — `render :new, status: :unprocessable_entity`, the Rails idiom
+      # for a failed save, on a ruact page. Rails would render the template itself,
+      # outside a `ruact_render`, and the first client component in it would raise.
+      # So a `render` of a ruact PAGE of this controller — the same predicate
+      # `default_render` uses: `ruact_page_action?` and the template in this
+      # controller's own folder — goes through `ruact_render`, with its `status:`,
+      # `locals:` and `location:`, when that `.html.erb` is the template RAILS
+      # would pick for this request: the format it negotiated (a `.json` path,
+      # `params[:format]`, the `respond_to` branch, the Accept header) decides, so
+      # a scaffold's `format.json { render :show }` still renders `show.json`.
+      # Everything else is Rails' own: other renderers (`json:`, `plain:`,
+      # `partial:`…, including the `render plain:` / `html:` ruact itself issues),
+      # a template of another folder, an action outside `ruact_pages`. `layout:`
+      # and `content_type:` do not apply: a ruact page is rendered into
+      # `config.layout`, as HTML or Flight, like every ruact page.
+      def render(*args, &block)
+        page = block ? nil : __ruact_page_render(args)
+        return super unless page
+
+        self.location = url_for(page[:location]) if page[:location]
+        # As Rails' own `assigns:` does: instance variables of the view.
+        page[:assigns]&.each { |name, value| instance_variable_set(:"@#{name}", value) }
+        __ruact_render(**page.slice(:template, :locals, :status, :details))
+      ensure
+        # The declined-option note explains THIS render only (review R4): a
+        # later render in the request — a `rescue_from`'s — must not inherit it.
+        if instance_variable_defined?(:@__ruact_declined_render_options)
+          remove_instance_variable(:@__ruact_declined_render_options)
+        end
+      end
+
+      private
+
+      # The options of a plain template render — the only `render` ruact takes
+      # over. Anything else (`json:`, `plain:`, `partial:`, a registered renderer
+      # like `turbo_stream:`, an option a gem adds, like wicked_pdf's `pdf:`, or a
+      # key Rails ignores, like `alert:`) means the render is not ruact's to
+      # answer — Rails renders it, and the error that follows names the option
+      # (Story 17.0i review R3, decision of Luiz).
+      # `prefixes:` is not among them (review R4): it names the folders to look
+      # in, and a page is this controller's own folder only.
+      TEMPLATE_RENDER_OPTIONS = %i[action template locals status location layout content_type
+                                   formats variants variant handlers locale assigns].freeze
+      private_constant :TEMPLATE_RENDER_OPTIONS
+
+      # The `ruact_render` arguments for an explicit `render` of one of this
+      # controller's ruact pages, or nil. Rails' own `_normalize_args` reads the
+      # arguments (`render :new` → action, `render "posts/new"` → template), on a
+      # copy: it hands a Hash argument back as itself.
+      def __ruact_page_render(args)
+        options = _normalize_args(*args.map { |arg| arg.is_a?(Hash) ? arg.dup : arg })
+        action = __ruact_render_target(options)
+        return nil unless action && self.class.ruact_page_action?(action)
+
+        page = self.class.ruact_template_path(action)
+        return nil unless File.exist?(page)
+        return __ruact_decline(options) unless (options.keys - TEMPLATE_RENDER_OPTIONS).empty?
+
+        details = __ruact_render_details(options)
+        return nil unless __ruact_rails_would_render?(action, details, page)
+
+        { template: "#{controller_path}/#{action}", locals: options[:locals] || {}, status: options[:status],
+          location: options[:location], assigns: options[:assigns], details: details }
+      end
+
+      # A render of a ruact page with an option ruact does not take goes to Rails.
+      # When it named the page (`action:` / `template:`), the options are kept so
+      # the error that follows — a client component rendered outside ruact — says
+      # which ones (`Ruact::ViewHelper#__ruact_component__`). `render json:` names
+      # no template: nothing to explain.
+      def __ruact_decline(options)
+        unknown = options.keys - TEMPLATE_RENDER_OPTIONS
+        @__ruact_declined_render_options = unknown if options.key?(:action) || options.key?(:template)
+        nil
+      end
+
+      # The lookup details of a render, as Rails' own render passes them: each an
+      # Array, a nil ignored; `variant:` is `variants:`.
+      def __ruact_render_details(options)
+        details = options.slice(:formats, :variants, :handlers, :locale)
+        details[:variants] = options[:variant] if options.key?(:variant) && !options.key?(:variants)
+        details.compact.transform_values { |value| Array(value) }
+      end
+
+      # Whether Rails, left alone, would render `page` for `action`: the lookup
+      # it does itself, with the formats it negotiated for this request (and a
+      # render's own `formats:` / `variants:` / `handlers:` / `locale:`). A Flight request
+      # negotiates every format, HTML first — the page; a `.json` request or a
+      # `format.json` branch negotiates JSON — the JSON template, or Rails' own
+      # MissingTemplate.
+      def __ruact_rails_would_render?(action, details, page)
+        template = lookup_context.find_template(action, [controller_path], false, [], details)
+        __ruact_page_template?(template.identifier, action, page)
+      rescue ActionView::MissingTemplate
+        false
+      end
+
+      # The page itself, or a locale/variant of it Rails picked (`new.pt-BR.html.erb`,
+      # `new.html+phone.erb`): the same folder, the same action, HTML, ERB.
+      def __ruact_page_template?(identifier, action, page)
+        File.identical?(File.dirname(identifier), File.dirname(page)) &&
+          File.basename(identifier).match?(/\A#{Regexp.escape(action)}(\.[\w-]+)?\.html(\+[\w-]+)?\.erb\z/)
+      end
+
+      # The action whose template `options` name, when it is one of this
+      # controller's: `action: "new"`, `template: "<controller_path>/new"`, or
+      # nothing at all (`render status: 422` — the current action's template).
+      def __ruact_render_target(options)
+        if options.key?(:template)
+          directory, name = File.split(options[:template].to_s)
+          directory == controller_path ? name : nil
+        elsif options.key?(:action)
+          name = options[:action].to_s
+          name.include?("/") ? nil : name
+        else
+          action_name
+        end
+      end
+    end
+  end
+end

data/lib/ruact/controller/pages.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Ruact
+  module Controller
+    # Story 17.0g (FR116, decision D2) — a ruact "page" is a whole controller or
+    # the actions it declares.
+    #
+    # Including `Ruact::Controller` makes every action with an `.html.erb` a
+    # page; `ruact_pages only:` / `except:` narrows that. `default_render` and
+    # the navigation boundary (Ruact::NavigationBoundary) both read
+    # `ruact_page_action?` — one definition, so what renders through ruact and
+    # what the router treats as ruact cannot disagree.
+    module Pages
+      extend ActiveSupport::Concern
+
+      included do
+        # Story 17.0g — the pages this controller declared with `ruact_pages`, or
+        # nil (every action with a template is a page). Inherited, and
+        # redeclarable by a subclass.
+        class_attribute :__ruact_pages, instance_accessor: false, instance_predicate: false, default: nil
+      end
+
+      class_methods do
+        # Story 17.0g (FR116) — narrow which actions of this controller are ruact
+        # pages. Without it, every action with a template is one; with it, only
+        # the declared actions are, and the rest render as ordinary Rails.
+        #
+        # An action listed in `only:` is a page even without a template of its
+        # own — the way to have `ruact_render(template: "posts/show")` treated as
+        # one by the navigation boundary. Names that are not actions of the
+        # declaring controller fail loudly the first time one of its pages is
+        # looked up: a typo must not quietly become "not a ruact page". A
+        # declaration a subclass inherits is not checked against it — on a base
+        # controller it is a policy for children that each have some of the
+        # actions.
+        #
+        # @param only [Symbol, String, Array<Symbol, String>] the page actions
+        # @param except [Symbol, String, Array<Symbol, String>] every action but these
+        # @return [void]
+        # @example Only `show` renders through ruact
+        #   class PostsController < ApplicationController
+        #     include Ruact::Controller
+        #     ruact_pages only: %i[show]
+        #   end
+        def ruact_pages(only: nil, except: nil)
+          raise ArgumentError, "ruact_pages takes exactly one of only: or except: (#{name})" if only.nil? == except.nil?
+
+          self.__ruact_pages = { only: only && Array(only).map(&:to_s).freeze,
+                                 except: except && Array(except).map(&:to_s).freeze,
+                                 declared_in: self }.freeze
+        end
+
+        # Whether `action` is a page this controller renders through ruact:
+        # every action unless `ruact_pages` narrowed it. Calling `ruact_pages`
+        # again replaces the declaration (it does not accumulate). The navigation boundary
+        # (Ruact::NavigationBoundary) and `default_render` both read this.
+        #
+        # @param action [String, Symbol]
+        # @return [Boolean]
+        # @raise [Ruact::ConfigurationError] when `ruact_pages` names an action
+        #   this controller does not have
+        def ruact_page_action?(action)
+          declared = __ruact_pages
+          return true if declared.nil?
+
+          Pages.check_declared!(self, declared) if declared[:declared_in].equal?(self)
+          return declared[:only].include?(action.to_s) if declared[:only]
+
+          !declared[:except].include?(action.to_s)
+        end
+
+        # Listed in `ruact_pages only:` by THIS controller, as a method of it — a
+        # page by declaration, template or not (the method renders another one).
+        # Everything else needs the template in the controller's own folder,
+        # which is what `default_render` renders: a template reached through a
+        # parent's folder (an inherited declaration, an inherited action, a
+        # template-only name) renders as plain Rails, so the router must not be
+        # told it is a ruact page. A subclass that renders another template on
+        # purpose redeclares its pages.
+        #
+        # @param action [String, Symbol]
+        # @return [Boolean]
+        def ruact_declared_page?(action)
+          declared = __ruact_pages
+          return false unless declared && declared[:declared_in].equal?(self)
+
+          Array(declared[:only]).include?(action.to_s) && action_methods.include?(action.to_s)
+        end
+      end
+
+      # The typo check, run for the class that DECLARED the pages (see
+      # `ruact_pages`). Only `only:` is checked: an `except:` naming a missing
+      # action excludes nothing and harms nothing. A template-only action (no
+      # method, a view Rails renders implicitly) is an action.
+      #
+      # @api private
+      # @param owner [Class] the controller that declared `declared`
+      # @param declared [Hash] a `__ruact_pages` declaration
+      # @return [void]
+      # @raise [Ruact::ConfigurationError] when `only:` names no action of it
+      def self.check_declared!(owner, declared)
+        names = Array(declared[:only])
+        return if names.empty?
+
+        unknown = names - owner.action_methods.to_a
+        unknown = unknown.reject { |action| File.exist?(owner.ruact_template_path(action)) }
+        return if unknown.empty?
+
+        what = unknown.one? ? "is not an action" : "are not actions"
+        raise Ruact::ConfigurationError,
+              "#{owner.name} declares ruact_pages for #{unknown.join(', ')}, which #{what} of it " \
+              "(no method and no template). Check the spelling in `ruact_pages`."
+      end
+    end
+  end
+end

data/lib/ruact/controller.rb

@@ -6,15 +6,21 @@ require "uri"
 require_relative "view_helper"
 require_relative "validation_errors_collector"
 require_relative "controller/document_rendering"
+require_relative "controller/pages"
+require_relative "controller/page_rendering"
 
 module Ruact
-  # Include in ApplicationController to enable RSC rendering.
+  # Include in the controllers whose pages render through ruact (island mode,
+  # the install default — Story 17.0g), or in ApplicationController to render
+  # the whole app through it (`rails generate ruact:install --app`).
   #
-  #   class ApplicationController < ActionController::Base
+  #   class ProductsController < ApplicationController
   #     include Ruact::Controller
   #   end
   #
-  # After that, any action whose view is a .html.erb file will automatically:
+  # After that, any action whose view is a .html.erb file (narrowed with
+  # `ruact_pages only:` / `except:`, see Ruact::Controller::Pages) will
+  # automatically:
   # - Respond to text/x-component requests with a raw Flight payload
   # - Respond to text/html requests with an HTML shell + inline Flight payload
   module Controller
@@ -31,6 +37,40 @@ module Ruact
     # 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
+    # Which actions are ruact pages — the whole controller, or the ones it
+    # declares with `ruact_pages` (Story 17.0g). See Ruact::Controller::Pages.
+    include Ruact::Controller::Pages
+    # An explicit `render` of a ruact page goes through ruact (Story 17.0i).
+    # See Ruact::Controller::PageRendering.
+    include Ruact::Controller::PageRendering
+
+    # Story 17.0f — "is this action a ruact PAGE?", answered at CLASS level so the
+    # navigation boundary (Ruact::NavigationBoundary) can ask it before any action
+    # runs, and so it and `default_render` read ONE definition rather than two
+    # that could drift (the 2026-09-16 spike's classifier kept its own copy).
+    class_methods do
+      # The template `default_render` looks for — the literal
+      # `Rails.root/app/views/<controller_path>/<action>.html.erb`, not the view
+      # path lookup, which is what keeps an engine's own templates (Devise's)
+      # out. `controller_path`, not the class name with "_controller" cut out
+      # of it: `RemoteControllersController` used to look in
+      # `remotes_controller/`.
+      #
+      # @param action [String, Symbol]
+      # @return [Pathname]
+      def ruact_template_path(action)
+        Rails.root.join("app", "views", controller_path, "#{action}.html.erb")
+      end
+
+      # A GET to `action` renders through ruact: it is a page, and it either
+      # has its template or was declared by name (it renders another one).
+      #
+      # @param action [String, Symbol]
+      # @return [Boolean]
+      def ruact_page?(action)
+        ruact_page_action?(action) && (ruact_declared_page?(action) || File.exist?(ruact_template_path(action)))
+      end
+    end
 
     private
 
@@ -38,7 +78,7 @@ module Ruact
     # controller a public instance method is exposed as a routable action. Demote
     # the mixed-in helper methods so they are never callable as actions (they are
     # only ever invoked internally by `ruact_html_shell`).
-    private :ruact_js_assets, :__ruact_component__
+    private :ruact_js_assets, :ruact_head_assets, :__ruact_component__
 
     # Resolves the manifest for this render. In PRODUCTION this is the boot-time
     # cached +Ruact.manifest+ (set by Railtie#config.to_prepare) — no per-request
@@ -102,11 +142,26 @@ module Ruact
     # +template+: logical template name (e.g. "posts/custom"), or nil to use
     #             the current action's default template.
     # +locals+:   hash of local variables to pass to the template.
-    def ruact_render(template: nil, locals: {})
+    # +status+:   the response status, as `render` takes it (Story 17.0i) —
+    #             `:unprocessable_entity`, `422`… — in the HTML document and the
+    #             Flight payload alike. Omitted, the response keeps the status it
+    #             has (200).
+    def ruact_render(template: nil, locals: {}, status: nil)
+      __ruact_render(template: template, locals: locals, status: status)
+    end
+
+    # `ruact_render`, plus the lookup details an explicit `render` carries
+    # (`variants:`, `locale:`, `formats:`, `handlers:` — Story 17.0i review R3):
+    # the page renders with the variant or locale Rails would have used.
+    def __ruact_render(template: nil, locals: {}, status: nil, details: {})
       # Story 13.3 (FR98, AC4) — seed the collector from a redirect-back flash
       # before the view evaluates, so `errors={ruact_errors}` surfaces surviving
       # errors (no-op on a plain render — `ruact_errors` then returns `{}`).
       __ruact_read_errors_from_flash
+      # Resolved the way `render status:` resolves it (Rack::Utils.status_code),
+      # and set BEFORE anything is written: the streamed Flight response sends
+      # its headers on the first row.
+      self.status = status if status
 
       pipeline  = RenderPipeline.new(ruact_manifest, controller_path: controller_path, logger: logger)
       streaming = ruact_request? && self.class.ancestors.include?(ActionController::Live)
@@ -126,7 +181,7 @@ module Ruact
       # (NFR8). See Story 7.9 / Bug 7.8-B.
       with_render_context do |render_context|
         opts = template ? { template: template } : { action: action_name }
-        html = render_to_string(opts.merge(layout: false, locals: locals))
+        html = render_to_string(opts.merge(details).merge(layout: false, locals: locals))
         emit_ruact_response(pipeline, html, render_context, streaming: streaming)
       end
     end
@@ -188,7 +243,8 @@ module Ruact
     end
 
     # Overrides Rails redirect_to for RSC requests: emits a Flight redirect row
-    # (`0:{"redirectUrl":"...","redirectType":"push"}`) instead of a 302 response.
+    # (`0:` followed by a JSON object with `redirectUrl` and `redirectType: "push"`)
+    # instead of a 302 response.
     # This allows the client-side router to handle the navigation without an extra
     # HTTP round-trip.  Non-RSC requests and external-origin redirects fall through
     # to the standard Rails implementation.
@@ -217,6 +273,10 @@ module Ruact
       # Story 13.3 (FR98, AC4) — the Inertia "redirect back with errors" path:
       # stash any `ruact_errors`-registered errors in flash so they survive this
       # Flight redirect and re-render as an `errors` prop (no-op when untouched).
+      # Only here: the next request is the router's Flight GET, which renders
+      # no layout. A plain 302 (a form outside `ruact_pages`, Story 17.0g) is
+      # followed by a full page whose layout may print every flash entry — that
+      # action is plain Rails and re-renders its errors the Rails way.
       __ruact_stash_errors_in_flash
 
       # Story 15.5 (FR109) — mark the Flight-redirect sub-shape for the dev log.
@@ -231,14 +291,21 @@ module Ruact
         request.headers["Ruact-Request"] == "1"
     end
 
+    # Rails keeps `redirect_to` PUBLIC, and this module's body is private from
+    # `private` above: the `responders` gem (Devise's `respond_with`) calls
+    # `controller.redirect_to` with an explicit receiver (Story 17.0i). Public
+    # is not routable here — Rails excludes its own public methods from
+    # `action_methods`.
+    public :redirect_to
+
+    # Implicit rendering needs the action's OWN template: an action declared a
+    # page without one renders itself (`ruact_render(template: …)`).
     def ruact_template_exists?
-      File.exist?(default_template_path)
+      self.class.ruact_page_action?(action_name) && File.exist?(default_template_path)
     end
 
     def default_template_path
-      action = action_name
-      controller = self.class.name.underscore.sub("_controller", "")
-      Rails.root.join("app", "views", controller, "#{action}.html.erb")
+      self.class.ruact_template_path(action_name)
     end
   end
 end