ruact 0.0.12 → 0.0.13

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

@@ -9,6 +9,9 @@
     "noEmit": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
+    // Vite's client types. Without them a client component importing a
+    // stylesheet for its side effect has no declaration to resolve against.
+    "types": ["vite/client"],
     "baseUrl": ".",
     "paths": {
       "@/*": ["app/javascript/*"]

data/lib/generators/ruact/layout/layout_generator.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "ruact"
+
+module Ruact
+  module Generators
+    # Copies the layout ruact pages render into (`layouts/ruact`, shipped with
+    # the gem) into the app, so the app owns it.
+    #
+    # Nothing needs configuring afterwards: the gem's view path is APPENDED by
+    # the Railtie, behind the app's, so `app/views/layouts/ruact.html.erb` wins
+    # by view-path order the moment it exists. That is the point of the ejected
+    # copy — add the app's JavaScript, fonts, meta tags or anything else
+    # `config.layout_stylesheets` cannot express.
+    #
+    # The cost, said once here and again when the command runs: an ejected
+    # layout no longer changes when the gem does.
+    #
+    # Run: rails generate ruact:layout
+    class LayoutGenerator < Rails::Generators::Base
+      source_root Ruact.views_path
+
+      desc "Copies ruact's layout into app/views/layouts/ruact.html.erb so your app owns it"
+
+      DESTINATION = "app/views/layouts/ruact.html.erb"
+
+      # `copy_file` already refuses to overwrite silently: an existing file
+      # prompts, or is skipped/overwritten under `--skip`/`--force`, which is
+      # the Rails convention every other generator follows.
+      def copy_layout
+        copy_file "layouts/ruact.html.erb", DESTINATION
+      end
+
+      # Only on `generate` (not `destroy`), and phrased for what is true: the copy
+      # renders ruact pages while `config.layout` is "ruact" — under `true` or
+      # `false` it is not used at all.
+      def explain
+        return unless behavior == :invoke
+
+        say ""
+        say "  #{DESTINATION} renders ruact pages in place of the one ruact ships,"
+        say "  as long as config.layout is \"ruact\". It will no longer change when you upgrade the gem —"
+        say "  compare it with #{File.join(Ruact.views_path, 'layouts/ruact.html.erb')}"
+        say "  after an upgrade. Keep `<%= ruact_head_assets %>` in <head>, and"
+        say "  `<div id=\"root\"></div>` with `<%= ruact_js_assets %>` in <body>:"
+        say "  `rails ruact:doctor` checks all three."
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/ruact/scaffold/templates/controller.rb.tt

@@ -2,9 +2,10 @@
 
 # <%= controller_class_name %>Controller — a complete CRUD on the v2 route-driven contract.
 #
-# `include Ruact::Server` (sibling of the Ruact::Controller already on
-# ApplicationController via `ruact:install`) gives this controller two
-# behaviours at once:
+# `include Ruact::Controller` makes this controller's pages ruact pages — the
+# install no longer puts it on ApplicationController (Story 17.0g: island mode
+# is the default; in whole-app mode, `ruact:install --app`, including it again
+# here is a no-op). `include Ruact::Server` then gives it two behaviours:
 #
 #   - GET actions (index/show/new/edit) need NO explicit `ruact_render` —
 #     Ruact::Controller#default_render activates the RSC pipeline implicitly
@@ -22,6 +23,7 @@
 # NOTE: `include Ruact::Server` must come AFTER `protect_from_forgery` (inherited
 # from ApplicationController) so the CSRF check precedes these actions.
 class <%= controller_class_name %>Controller < ApplicationController
+  include Ruact::Controller
   include Ruact::Server
 
   # --- GET pages (rendered as RSC) -----------------------------------------

data/lib/ruact/configuration.rb

@@ -9,7 +9,7 @@ module Ruact
   # `Ruact::ConfigurationError` with the offending attribute, the caller's
   # file:line, and the suggested fix. Re-calling `Ruact.configure` after boot
   # replaces the configuration atomically and emits a `[ruact]` warning.
-  class Configuration
+  class Configuration # rubocop:disable Metrics/ClassLength -- an attribute list with a validator per attribute; Doctor and InstallGenerator carry the same disable
     # The set of public attributes; new attributes added here automatically
     # inherit the freeze contract via the `define_method` writer below.
     ATTRIBUTES = %i[
@@ -25,6 +25,7 @@ module Ruact
       signed_global_id_default_expires_in
       shadcn_compatible_versions
       layout
+      layout_stylesheets
     ].freeze
 
     # @!attribute [r] manifest_path
@@ -144,17 +145,21 @@ module Ruact
     #     full-document render a browser gets on a normal navigation.
     #
     #     - `false` (default) — render the gem's built-in minimal shell.
+    #     - `"ruact"` — render through the layout the gem ships
+    #       (`lib/ruact/views/layouts/ruact.html.erb`, Story 17.0b): CSRF, CSP,
+    #       the client-component CSS, then the app stylesheets named in
+    #       {#layout_stylesheets}. What `rails generate ruact:install` writes.
+    #       It edits no layout of the app; an app that puts its own
+    #       `app/views/layouts/ruact.html.erb` in place (`rails generate
+    #       ruact:layout` copies the gem's) wins by view-path order.
     #     - `true` — render through the controller's normal Rails layout.
-    #     - a String — render through that named layout (e.g. `"ruact"`).
+    #     - another String — render through that named layout.
     #
-    #     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.
+    #     The trade-off between the last two and `"ruact"`: the app's own layout
+    #     brings its whole `<head>` (favicons, fonts, analytics, `<head>`-writing
+    #     gems) but has to be wired by hand; the gem's layout needs no wiring but
+    #     brings only the stylesheets. The built-in shell carries neither — under
+    #     the `false` default a ruact page renders with no app CSS at all.
     #
     #     **This setting is deliberately explicit — there is no auto-detection.**
     #     ruact used to try to infer whether your layout was ready by inspecting
@@ -173,10 +178,26 @@ module Ruact
     #   @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
+    #   @example Render through the layout ruact ships (what ruact:install writes)
     #     Ruact.configure { |c| c.layout = "ruact" }
+    #   @example Let your own application layout own the document
+    #     Ruact.configure { |c| c.layout = true }
+    #
+    # @!attribute [r] layout_stylesheets
+    #   @return [Array<Symbol, String>] The app stylesheets the gem's layout
+    #     (`layouts/ruact`, used when `layout` is `"ruact"`) links, passed as-is
+    #     to `stylesheet_link_tag`. They come AFTER the client-component CSS
+    #     (`ruact_head_assets`), so the app's own CSS loads last and wins ties.
+    #
+    #     Defaults to `[:app]`, what `rails new` 8.x puts in its layout: under
+    #     Propshaft it expands to every stylesheet on the load path, including a
+    #     Tailwind build. Under Sprockets `:app` means a file called `app.css`,
+    #     which is why `rails generate ruact:install` writes `["application"]`
+    #     there instead. `[]` links none. Anything more than a list of names —
+    #     a media attribute, fonts, other `<head>` tags — is what ejecting the
+    #     layout is for: `rails generate ruact:layout`.
+    #   @example A Sprockets app
+    #     Ruact.configure { |c| c.layout_stylesheets = ["application"] }
     ATTRIBUTES.each do |attr|
       attr_reader attr
 
@@ -231,6 +252,7 @@ module Ruact
         @signed_global_id_default_expires_in = nil
         @shadcn_compatible_versions = [1, 2]
         @layout = false
+        @layout_stylesheets = [:app]
       end
     end
 
@@ -266,6 +288,10 @@ module Ruact
         # reference, but a caller probing `frozen?` would see the right answer.
         if value.is_a?(Proc)
           value.freeze
+        elsif value.is_a?(Array)
+          # Story 17.0b — `layout_stylesheets` holds Strings; freezing only the
+          # Array would leave `Ruact.config.layout_stylesheets.first << "x"` open.
+          instance_variable_set("@#{attr}", value.map { |item| item.frozen? ? item : item.dup.freeze }.freeze)
         else
           instance_variable_set("@#{attr}", value.dup.freeze)
         end
@@ -293,6 +319,7 @@ module Ruact
       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)
+      when :layout_stylesheets         then validate_layout_stylesheets!(value)
       end
     end
 
@@ -325,6 +352,31 @@ module Ruact
             "false uses ruact's built-in shell."
     end
 
+    # Story 17.0b — the arguments `layouts/ruact` passes to `stylesheet_link_tag`.
+    # Checked at boot because the layout splats them straight into a Rails
+    # helper, where a stray nil or Hash would surface as a first-render error
+    # instead of a legible configuration one.
+    #
+    # Propshaft reads `:app` / `:all` ONLY as the first item, and then ignores
+    # every other one (`case sources.first when :app then sources = …`): so
+    # `[:app, "theme"]` silently drops "theme", and `["reset", :app]` looks for
+    # a file named app.css and raises. Either is allowed only on its own.
+    def validate_layout_stylesheets!(value)
+      if value.is_a?(Array) && value.length > 1 && value.intersect?(%i[app all])
+        raise Ruact::ConfigurationError,
+              "Ruact::Configuration#layout_stylesheets: :app and :all stand alone — Propshaft reads " \
+              "them only as the whole list and drops anything next to them; got #{value.inspect}. " \
+              "Use [:app], or list the stylesheets by name."
+      end
+      return if value.is_a?(Array) && value.all? { |name| name.is_a?(Symbol) || (name.is_a?(String) && !name.empty?) }
+
+      raise Ruact::ConfigurationError,
+            "Ruact::Configuration#layout_stylesheets must be an Array of stylesheet names " \
+            "(Symbols or non-empty Strings, as you would pass to stylesheet_link_tag), " \
+            "e.g. [:app] or [\"application\"]; got #{value.inspect} (#{value.class.name}). " \
+            "Use [] to link none of your app's stylesheets."
+    end
+
     def validate_max_upload_bytes!(value)
       return if value.nil?
       return if value.is_a?(Integer) && value >= 0

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