ruact 0.0.12 → 0.0.14

data/lib/ruact/doctor.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "json"
 require "socket"
 require "pathname"
 
@@ -7,7 +8,8 @@ module Ruact
   # Runs a suite of installation health checks and prints ✓/✗ per check.
   # Extracted from the ruact:doctor Rake task for direct testability (FR27).
   class Doctor # rubocop:disable Metrics/ClassLength
-    CHECKS = %i[manifest vite controller layout streaming legacy_constant serialize_only flight_middleware].freeze
+    CHECKS = %i[manifest vite controller layout head_assets streaming legacy_constant serialize_only
+                flight_middleware].freeze
     # Built via Array#join so the gem-CI `name-propagation` guard does not
     # match these literals against itself (Story 5.1 review F4 — the doctor
     # file participates in the guard with no exclusion).
@@ -92,7 +94,7 @@ module Ruact
       # success. An unexpected status (rendered `✗`) fails loudly rather than
       # being silently treated as a pass (review finding R1).
       passed = passed?(computed)
-      puts "Run rails generate ruact:install to fix configuration issues" unless passed
+      puts "Run rails ruact:doctor -- --json for how to fix each failure" unless passed
       passed
     end
 
@@ -161,14 +163,99 @@ module Ruact
        "Run npm run dev (or bin/dev) to start the Vite dev server."]
     end
 
+    # Story 17.0g (FR116) — reports the ADOPTION MODE instead of demanding one.
+    #
+    # Whole-app (`ruact:install --app`): ApplicationController includes the
+    # concern, and every action with a template renders through ruact — the
+    # message says how many templates that is, which is the cost `--app` hides.
+    # Island (the install default): the concern is on the controllers that
+    # render ruact pages. It used to FAIL every island app, because it only
+    # looked at ApplicationController. With none yet, a warning: the install
+    # worked; there is simply no page.
+    #
+    # Mechanical, like the layout checks: it reads files, it never renders.
     def check_controller
-      path = Rails.root.join("app", "controllers", "application_controller.rb")
-      if File.exist?(path) && File.read(path).include?("Ruact::Controller")
-        [:pass, "Ruact::Controller included in ApplicationController"]
-      else
-        [:fail, "Ruact::Controller not included in ApplicationController",
-         "Run rails generate ruact:install to include Ruact::Controller in ApplicationController."]
+      application = Rails.root.join("app", "controllers", "application_controller.rb")
+      if File.exist?(application) && File.read(application).match?(Ruact::CONTROLLER_INCLUDE)
+        return [:pass, "whole-app mode: ApplicationController includes Ruact::Controller — " \
+                       "#{pluralize_count(ruact_page_templates, 'template')} in app/views render through ruact"]
       end
+
+      count = island_controllers.length
+      return island_without_pages_result if count.zero?
+
+      verb = count == 1 ? "renders" : "render"
+      [:pass, "island mode: #{pluralize_count(count, 'controller')} #{verb} ruact pages (include Ruact::Controller)"]
+    end
+
+    # Controller files that include the concern themselves. Approximate by
+    # design — it reads source, it does not load classes: a controller that
+    # gets the concern through a base controller counts through the base.
+    # `concerns/` holds modules, not controllers; only the app's ROOT
+    # ApplicationController is whole-app mode (an `Admin::ApplicationController`
+    # is an island base like any other).
+    def island_controllers
+      root = Rails.root.join("app", "controllers")
+      Dir.glob(root.join("**", "*.rb").to_s).select do |file|
+        next false if file == root.join("application_controller.rb").to_s
+        next false if file.start_with?("#{root.join('concerns')}/")
+
+        File.read(file).match?(Ruact::CONTROLLER_INCLUDE)
+      end
+    end
+
+    # Page templates: `.html.erb` under app/views — not layouts, partials or
+    # mailer views. Approximate: `ruact_pages` narrowing is not read.
+    def ruact_page_templates
+      Dir.glob(Rails.root.join("app", "views", "**", "*.html.erb").to_s).count do |file|
+        !file.include?("/app/views/layouts/") && !File.basename(file).start_with?("_") &&
+          !File.dirname(file).end_with?("_mailer")
+      end
+    end
+
+    def pluralize_count(count, noun)
+      "#{count} #{noun}#{'s' unless count == 1}"
+    end
+
+    def island_without_pages_result
+      [:warn,
+       "island mode: no controller renders ruact pages yet — add include Ruact::Controller to one, " \
+       "or run rails generate ruact:scaffold",
+       "The install changes no controller (island mode). A page renders through ruact when its " \
+       "controller has `include Ruact::Controller`; narrow it with `ruact_pages only: %i[show]`. " \
+       "`rails generate ruact:install --app` puts it on ApplicationController instead (every page)."]
+    end
+
+    # Which document a ruact page actually renders into, decided from
+    # `Ruact.config.layout` and the files on disk — never by rendering.
+    #
+    # - `false`  → `[:shell, application.html.erb]`: ruact's built-in shell. The
+    #   application layout is still read, to report a layout that is wired but
+    #   switched off.
+    # - a String → the app's `app/views/layouts/<name>.html.erb` when it exists
+    #   (an ejected `ruact` layout included), otherwise the gem's own
+    #   (`layouts/ruact`, Story 17.0b), otherwise `:missing`. The same order the
+    #   view paths give Rails: the app's views first, the gem's appended last.
+    #   The `layouts/` prefix Rails accepts is stripped rather than doubled.
+    # - `true`   → `application.html.erb`. It cannot resolve a controller's own
+    #   `layout "admin"`, and every message names the file it read so that
+    #   limit stays visible.
+    #
+    # @return [Array(Symbol, Pathname)] `[:shell | :app | :gem | :missing, path]`
+    def rendering_layout
+      layout = Ruact.config.layout
+      application = Rails.root.join("app", "views", "layouts", "application.html.erb")
+      return [:shell, application] if layout == false
+      return [File.exist?(application) ? :app : :missing, application] unless layout.is_a?(String)
+
+      name = layout.delete_prefix("layouts/")
+      app_file = Rails.root.join("app", "views", "layouts", "#{name}.html.erb")
+      return [:app, app_file] if File.exist?(app_file)
+
+      gem_file = Pathname(Ruact.views_path).join("layouts", "#{name}.html.erb")
+      return [:gem, gem_file] if gem_file.exist?
+
+      [:missing, app_file]
     end
 
     # Two independent halves have to line up, and BOTH are silent when wrong:
@@ -178,39 +265,160 @@ module Ruact
     # errors. Reporting each half separately is the point: "add one line" and
     # "flip one setting" are different fixes.
     #
+    # Story 17.0b — it reads the layout that RENDERS (see #rendering_layout). It
+    # used to read application.html.erb always, which failed a correct fresh
+    # install: that one renders through the gem's layout and leaves the app's
+    # own untouched, with no React root in it.
+    #
     # `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")
-      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."]
+      kind, path = rendering_layout
+      return [:pass, "ruact pages render through ruact's layout (config.layout = \"#{Ruact::GEM_LAYOUT}\")"] if
+        kind == :gem
+      return layout_missing_result(path) unless File.exist?(path)
+
+      missing = missing_layout_pieces(File.read(path))
+      return layout_unwired_result(path, missing) unless missing.empty?
+      return layout_not_opted_in_result if kind == :shell
+
+      [:pass, "#{path.basename} owns the document (React root + ruact_js_assets, config.layout on)"]
+    end
+
+    def layout_missing_result(path)
+      if Ruact.config.layout.is_a?(String)
+        [:fail, "config.layout names #{path.basename}, which exists neither in your app nor in ruact",
+         "Create #{path} (with <div id=\"root\"></div>, <%= ruact_js_assets %> and <%= ruact_head_assets %>), " \
+         "or set config.layout = \"#{Ruact::GEM_LAYOUT}\" to use the layout ruact ships."]
+      else
+        [:fail, "React shell missing from #{path.basename}",
+         "Create #{path}, or set config.layout = \"#{Ruact::GEM_LAYOUT}\" in config/initializers/ruact.rb " \
+         "to render ruact pages through the layout ruact ships."]
       end
+    end
+
+    # Story 17.0b — the CSS half of the asset contract.
+    #
+    # Vite records client-component stylesheets on the bootstrap manifest entry.
+    # If the build produced CSS and the layout never calls `ruact_head_assets`,
+    # that CSS is served and never referenced: styling that works in development
+    # and silently disappears in production.
+    #
+    # The decision is MECHANICAL — read the config, the manifest and the layout
+    # that renders — and never an inference at render time. Layout auto-detection
+    # was removed deliberately (see Ruact::Configuration#layout) and this must not
+    # reintroduce it: `LayoutSource.head_wired?` runs through `without_comments`,
+    # so a mention inside a comment does not read as wired.
+    def check_head_assets
+      entry = doctor_manifest_entry
+      return head_assets_unreadable_result if entry == :unreadable
+
+      kind, path = rendering_layout
+      return head_assets_unbuilt_result(path) if entry.nil? && kind == :app && !head_wired_file?(path)
+
+      css = Array(entry && entry["css"])
+      return [:pass, "no client-component CSS in the build (nothing to link)"] if css.empty?
+
+      return [:pass, "client-component CSS present; the built-in shell links it"] if kind == :shell
+      return [:pass, "client-component CSS is linked by ruact's layout"] if kind == :gem
+      return head_assets_no_layout_result(path) if kind == :missing
+      return head_assets_missing_result(css.length, path) unless head_wired_file?(path)
+
+      [:pass, "client-component CSS is linked (ruact_head_assets in #{path.basename})"]
+    end
+
+    def head_wired_file?(path)
+      Ruact::LayoutSource.head_wired?(File.read(path))
+    end
+
+    # No build yet — the normal state in development with the Vite dev server,
+    # which injects component CSS itself. A layout of the app's own that never
+    # calls the helper passes there and loses that CSS in production, which is
+    # exactly what this check exists to catch: a warning, not a pass.
+    def head_assets_unbuilt_result(path)
+      [:warn,
+       "#{path.basename} does not call ruact_head_assets — client-component CSS will not reach production",
+       "Add <%= ruact_head_assets %> as the first thing inside <head> in #{path}, above your " \
+       "stylesheet_link_tag. There is no production build to check yet, so this is a warning; with " \
+       "a build that emits component CSS it is a failure."]
+    end
 
-      content    = File.read(path)
-      has_root   = Ruact::LayoutSource.root?(content)
-      has_assets = Ruact::LayoutSource.wired?(content)
-      opted_in   = Ruact.config.layout != false
+    def head_assets_no_layout_result(path)
+      [:fail,
+       "the build emits client-component CSS but #{path.basename} does not exist " \
+       "(Ruact.config.layout points at it)",
+       "Ruact.config.layout points at #{path}, which is not there. Create it (or set " \
+       "config.layout = \"#{Ruact::GEM_LAYOUT}\") and add <%= ruact_head_assets %> inside its <head> — " \
+       "otherwise the stylesheets Vite built for your client components are served and never referenced."]
+    end
 
-      return layout_unwired_result unless has_root && has_assets
-      return layout_not_opted_in_result unless opted_in
+    # An unreadable manifest is NOT "nothing to link": the same file is parsed at
+    # render time, where a parse error raises. Reporting :pass here would mean the
+    # doctor is green on an app that 500s.
+    def head_assets_unreadable_result
+      [:fail,
+       "public/assets/.vite/manifest.json exists but is not valid JSON — rebuild your assets",
+       "Rebuild your assets (npm run build). ruact reads this file at render time, so a " \
+       "truncated or corrupt manifest raises there rather than degrading."]
+    end
 
-      [:pass, "layout owns the document (React root + ruact_js_assets, config.layout on)"]
+    # The file goes in the MESSAGE, not only in the remediation: `Doctor#run`
+    # prints `message` alone, so anything a reader needs in the terminal has to
+    # be there. (Story 5.4 found the same asymmetry; the remediation reaches
+    # `-- --json` only.)
+    def head_assets_missing_result(count, path)
+      [:fail,
+       "the build emits #{count} client-component stylesheet(s) that nothing links " \
+       "— add <%= ruact_head_assets %> to #{path.basename}",
+       "Add <%= ruact_head_assets %> as the first thing inside <head> in #{path}, " \
+       "ABOVE your stylesheet_link_tag so your own CSS is loaded last and wins ties " \
+       "(ruact never edits your layout). " \
+       "Without it that CSS is built and served but never referenced - styling that works in " \
+       "development and vanishes in production."]
     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."]
+    # The bootstrap manifest entry, or nil when there is no build to read. Kept
+    # here rather than reaching into the view helper's private lookup.
+    def doctor_manifest_entry
+      manifest_path = Rails.root.join("public", "assets", ".vite", "manifest.json")
+      return nil unless File.exist?(manifest_path)
+
+      JSON.parse(File.read(manifest_path))[Ruact.bootstrap_virtual_id]
+    rescue JSON::ParserError
+      :unreadable
+    end
+
+    # The exact lines the layout lacks, named in the MESSAGE (`Doctor#run` prints
+    # only the message; the remediation reaches `-- --json` alone).
+    def missing_layout_pieces(content)
+      missing = []
+      missing << %(<div id="root"></div>) unless Ruact::LayoutSource.root?(content)
+      missing << "<%= ruact_js_assets %>" unless Ruact::LayoutSource.wired?(content)
+      missing
+    end
+
+    def layout_unwired_result(path, missing)
+      [:fail, "#{path.basename} is missing #{missing.join(' and ')}",
+       "Add #{missing.join(' and ')} to #{path} (the root div in <body>, the helper right after it). " \
+       "#{layout_alternative(path)}Without both, ruact renders its built-in shell and your app's CSS never " \
+       "reaches the page."]
+    end
+
+    # Suggesting `config.layout = "ruact"` to an app whose file IS the ejected
+    # `ruact` layout would be advice to change nothing.
+    def layout_alternative(path)
+      return "" if path.basename.to_s == "#{Ruact::GEM_LAYOUT}.html.erb"
+
+      "Or set config.layout = \"#{Ruact::GEM_LAYOUT}\" to use the layout ruact ships. "
     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."]
+       "(which has none of your stylesheets). Set `config.layout = true` in config/initializers/ruact.rb " \
+       "to render through it, or `config.layout = \"#{Ruact::GEM_LAYOUT}\"` for the layout ruact ships."]
     end
 
     def check_streaming

data/lib/ruact/layout_source.rb

@@ -3,10 +3,11 @@
 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
+  # Three 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
+  # render through the host layout), `ruact:install` (reading an app-owned
+  # layout to print the lines it lacks — it never writes one) and
+  # `ruact:doctor`. 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
@@ -20,6 +21,9 @@ module Ruact
     # an earlier version of this pattern missed.
     ERB_COMMENT = /<%-?#.*?-?%>/m
 
+    # Either comment syntax, matched in one left-to-right pass.
+    ANY_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 —
@@ -28,6 +32,12 @@ module Ruact
     # merely follows some other tag.
     ASSETS_CALL = /<%=+(?:(?!%>).)*?\bruact_js_assets\b/m
 
+    # Story 17.0b — the `<head>` half. A sibling recogniser, not a second
+    # mechanism: it runs through the same `without_comments` as the others,
+    # because a mention inside a comment reading as "already wired" is the exact
+    # failure that got layout auto-detection removed.
+    HEAD_ASSETS_CALL = /<%=+(?:(?!%>).)*?\bruact_head_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
@@ -35,15 +45,17 @@ module Ruact
     # 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
 
+      # Whether the layout calls `ruact_head_assets` (Story 17.0b).
+      def head_wired?(source)
+        without_comments(source).match?(HEAD_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.
@@ -51,8 +63,18 @@ module Ruact
         markup.to_s.match?(ROOT_ATTRIBUTE)
       end
 
+      # Strips BOTH comment syntaxes a layout can hide a call in.
+      #
+      # This used to strip only the ERB form, which left `<!-- <%= ruact_js_assets %> -->`
+      # reading as a live call: the generator skipped the migration and the doctor
+      # passed, on a layout emitting nothing. Story 17.0b found it on the new
+      # `head_wired?` and it was equally true of `wired?`.
+      #
+      # ONE alternation rather than two passes, so a left-to-right scan closes
+      # whichever comment opened first — running the HTML pass first let a `<!--`
+      # living inside `<%# ... %>` swallow through to a later `-->`.
       def without_comments(source)
-        source.to_s.gsub(ERB_COMMENT, "")
+        source.to_s.gsub(ANY_COMMENT, "")
       end
     end
   end

data/lib/ruact/navigation_boundary.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Ruact
+  # Story 17.0f (FR117) — the document belongs to whoever rendered it.
+  #
+  # The ruact router intercepts every same-origin link and form: it cannot know,
+  # from the browser, whether the destination is a ruact page. Asked with
+  # `Accept: text/x-component`, an ordinary Rails action answers 200 HTML, which
+  # the router cannot render — a dead click, silently (spike 2026-09-12, S2). And
+  # a form that crossed to an ordinary action had already RUN it by the time the
+  # router saw the HTML, so it could not be retried (S9b).
+  #
+  # The server can know, before anything runs. For a request the router sent
+  # (`Ruact-Request: 1`, a header only the router sends), {Middleware} asks
+  # {Classifier} whether the route it would reach is a ruact page. If not, it
+  # answers `Ruact-Boundary: native` WITHOUT calling the app, and the router
+  # hands the navigation — or the form submission — to the browser. The action
+  # then runs exactly once, natively, and its real response (a 422 with the
+  # validation errors included) reaches the user.
+  #
+  # Measured in the 2026-09-16 spike (playgrounds/nav-islands): ~0.1 ms median
+  # per router request; every fixture below held.
+  module NavigationBoundary
+    # Response header the router reads.
+    HEADER = "ruact-boundary"
+    # Its only value today: "not a ruact page — let the browser do it".
+    NATIVE = "native"
+
+    # The Rack middleware the Railtie installs. Remove it with
+    # `config.middleware.delete Ruact::NavigationBoundary::Middleware`.
+    class Middleware
+      def initialize(app, classifier: Classifier.new)
+        @app = app
+        @classifier = classifier
+      end
+
+      def call(env)
+        return @app.call(env) unless env["HTTP_RUACT_REQUEST"] == "1"
+        return native_response if @classifier.classify(env) == :native
+
+        @app.call(env)
+      end
+
+      private
+
+      # `Vary`, because the same URL answers differently with and without the
+      # router's header; `no-store`, because this answer is about routing, not
+      # content, and must never be served from a cache to a browser navigation.
+      #
+      # Built through Rack's own header class so a later middleware looking up
+      # `Cache-Control` finds this one on Rack 2 (Rails 7.0) as well as Rack 3.
+      def native_response
+        [200, native_headers, []]
+      end
+
+      def native_headers
+        headers = defined?(Rack::Headers) ? Rack::Headers.new : Rack::Utils::HeaderHash.new
+        headers[HEADER] = NATIVE
+        headers["content-type"] = "text/plain; charset=utf-8"
+        headers["cache-control"] = "no-store"
+        headers["vary"] = "Ruact-Request"
+        headers
+      end
+    end
+
+    # Decides, from the route table alone, where a request would land.
+    #
+    # Mirrors what Rails' own router does on `serve` — not just `recognize`:
+    # lambda and object constraints are evaluated IN ROUTE ORDER, with the same
+    # cascade to the next matching route (`recognize` alone skips them; they
+    # live on `Mapper::Constraints` and only run on `serve`). Descends into
+    # mounted engines. Nothing it calls executes an action.
+    #
+    # Ties break towards letting the request through: a wrong :native would
+    # skip ruact on a ruact page, a wrong :ruact would bring the dead click back,
+    # but :pass only costs what ruact cost before this existed.
+    class Classifier
+      # @param router [ActionDispatch::Journey::Router, nil] defaults to the
+      #   application's, resolved lazily (routes reload in development)
+      def initialize(router = nil)
+        @router = router
+      end
+
+      # @param env [Hash] the Rack env
+      # @return [Symbol] `:ruact`, `:native`, or `:pass` (could not tell)
+      def classify(env)
+        request = ActionDispatch::Request.new(env.dup)
+        verdict_in(@router || application_router, request) || :pass
+      rescue Ruact::ConfigurationError => e
+        # A misdeclared `ruact_pages` is the app's bug to see, not a routing
+        # doubt: say so where it shows, then let the request through.
+        Rails.logger&.warn("[ruact] #{e.message}")
+        :pass
+      rescue StandardError => e
+        Rails.logger&.debug do
+          "[ruact] navigation boundary could not classify #{env['PATH_INFO']}: #{e.class}: #{e.message}"
+        end
+        :pass
+      end
+
+      private
+
+      # Rails 8 routes load lazily in development and test: the route set loads
+      # itself on `call`, but not when its `router` is read — and this runs
+      # BEFORE the app is called, so the first request after a boot could see
+      # an empty table.
+      def application_router
+        app = Rails.application
+        app.reload_routes_unless_loaded if app.respond_to?(:reload_routes_unless_loaded)
+        app.routes.router
+      end
+
+      # @return [Symbol, nil] nil when nothing in THIS router answers — the
+      #   caller keeps scanning, the way Rails cascades past an engine (or a Rack
+      #   app at "/") whose own routes do not match
+      def verdict_in(router, request, in_engine: false)
+        root_app = false
+        router.recognize(request) do |route, params|
+          app = route.app
+          if app.is_a?(ActionDispatch::Routing::Mapper::Constraints)
+            request.path_parameters = params
+            next unless app.matches?(request) # `serve` would cascade to the next route
+
+            app = app.app
+          end
+
+          if mounted_rack_app?(route, app)
+            # A Rack app mounted at "/" (Grape, Sinatra) passes on what it does
+            # not know with `X-Cascade: pass`, and Rails moves on: keep looking.
+            # Mounted anywhere else, it owns its prefix — Sidekiq at /sidekiq is
+            # not reclassified by a catch-all route drawn after it.
+            if route.path.spec.to_s == "/"
+              root_app = true
+              next
+            end
+            return :native
+          end
+
+          verdict = verdict_for(route, app, request, params, in_engine: in_engine)
+          return verdict if verdict # an engine with no matching route cascades: keep looking
+        end
+        root_app ? :native : nil
+      end
+
+      def mounted_rack_app?(route, app)
+        !route.dispatcher? && !app.is_a?(ActionDispatch::Routing::Redirect) && !engine?(app)
+      end
+
+      def engine?(app)
+        app.respond_to?(:routes) && app.routes.respond_to?(:router)
+      end
+
+      def verdict_for(route, app, request, params, in_engine:)
+        return action_verdict(request, params[:controller], params[:action], in_engine) if route.dispatcher?
+        # A route that redirects answers the router itself; there is no "no
+        # match" for it, so an unclassifiable one passes rather than cascading.
+        return redirect_verdict(app, request, params) || :pass if app.is_a?(ActionDispatch::Routing::Redirect)
+
+        # Inside `recognize`'s block the request's path_info is already relative
+        # to the mount point, which is what the engine's own router expects.
+        verdict_in(app.routes.router, request, in_engine: true)
+      end
+
+      # Same origin: the fetch follows the redirect and the target is
+      # classified when it arrives. Another origin: the fetch cannot follow it
+      # (CORS), so the browser has to — native.
+      #
+      # A 307/308 on a form re-sends the POST to the target; if that target is
+      # not ruact, the router could only answer with a GET there and the POST
+      # would never run. The browser's own submit follows it correctly: native.
+      #
+      # A `redirect { |params, req| … }` BLOCK is application code — it may
+      # query the database — and is never run here: it passes through.
+      EVALUATED_REDIRECTS = %w[ActionDispatch::Routing::PathRedirect ActionDispatch::Routing::OptionRedirect].freeze
+      private_constant :EVALUATED_REDIRECTS
+
+      def redirect_verdict(redirect, request, params)
+        return :native if [307, 308].include?(redirect.status) && !(request.get? || request.head?)
+        return :pass unless EVALUATED_REDIRECTS.include?(redirect.class.name)
+
+        target = URI.parse(redirect.path(params, request).to_s)
+        same_origin = target.host == request.host && (target.port || request.port) == request.port
+        return :pass if target.host.nil? || same_origin
+
+        :native
+      rescue StandardError
+        :pass
+      end
+
+      # GET/HEAD: ruact renders the page only when `default_render` would —
+      # the same class-level predicate, never a copy of it. That is what keeps a
+      # Devise-like controller (it inherits the app's ruact controller, its
+      # templates live in the engine) native.
+      #
+      # Anything else: including the concern is enough — unless the controller
+      # declares its pages (`ruact_pages`, Story 17.0g), and then only for the
+      # declared actions. A `create` has no template, and answers the router
+      # with a Flight redirect row (Ruact::Controller#redirect_to) — the Story
+      # 13.3 redirect-back has to stay in place, not become a full page load.
+      #
+      # Inside a mounted ENGINE, a non-GET is native even when its controller
+      # inherits the app's ruact controller: that is Devise's shape, and its
+      # `destroy` answers a non-navigational request with a bare 204 — the user
+      # is signed out and the router has nothing to render. An engine's actions
+      # speak the engine's protocol, not ruact's. Its GET pages still count when
+      # the APP provides the template (the way apps override engine views).
+      #
+      # The same holds for a controller a GEM defines even when its routes are
+      # drawn into the app's own table — `devise_for` mounts no engine, and
+      # `Devise::SessionsController#destroy` is the sign-out the rule exists
+      # for. So a non-GET is ruact only when the controller is the app's own:
+      # defined under `Rails.root/app`.
+      def action_verdict(request, controller, action, in_engine)
+        klass = "#{controller.to_s.camelize}Controller".safe_constantize
+        return :pass unless klass.is_a?(Class)
+        return :native unless klass.include?(Ruact::Controller)
+        return non_get_verdict(klass, action, in_engine) unless request.get? || request.head?
+
+        klass.ruact_page?(action) ? :ruact : :native
+      end
+
+      # Story 17.0g — a controller that DECLARED its pages (`ruact_pages`) is ruact
+      # only for those: a `create` whose `new` is a plain Rails page re-renders
+      # plain HTML on a validation error, which the router could not show.
+      def non_get_verdict(klass, action, in_engine)
+        return :native if in_engine || !app_owned?(klass)
+        return :native if klass.__ruact_pages && !klass.ruact_page_action?(action)
+
+        :ruact
+      end
+
+      def app_owned?(klass)
+        file = Object.const_source_location(klass.name)&.first
+        !file.nil? && File.expand_path(file).start_with?("#{Rails.root.join('app')}/")
+      end
+    end
+  end
+end

data/lib/ruact/railtie.rb

@@ -16,6 +16,36 @@ module Ruact
       require_relative "routing"
     end
 
+    # Story 17.0b — make the gem's own layout (`layouts/ruact`) findable by name.
+    #
+    # APPEND, not prepend: the gem's views go BEHIND the app's and every
+    # engine's, so an app that ejects the layout (`rails generate ruact:layout`)
+    # wins by view-path order and `layouts/application` always stays the app's.
+    # Shadowing the app's layout was measured and rejected (spike 2026-09-10:
+    # every page loaded React and lost the app's <title>), and the prepend
+    # version failed SILENTLY from this very hook — which is why the order this
+    # produces is asserted by a spec that boots a real app through this Railtie
+    # (spec/ruact/gem_layout_boot_spec.rb), in development and production.
+    #
+    # `respond_to?` mirrors Rails' own `add_view_paths`: the hook also fires for
+    # controller classes that carry no view paths.
+    initializer "ruact.view_paths" do
+      ActiveSupport.on_load(:action_controller) do
+        append_view_path(Ruact.views_path) if respond_to?(:append_view_path)
+      end
+    end
+
+    # Story 17.0f (FR117) — answer the ruact router before any action runs when
+    # the route it asked for is not a ruact page. See Ruact::NavigationBoundary.
+    #
+    # `use` appends: the middleware sits after Rack::MethodOverride when the app
+    # has it, so a form's `_method=delete` is already DELETE when the verb is
+    # read, and an app without it (API-shaped) does not fail to boot the way
+    # `insert_after Rack::MethodOverride` would.
+    initializer "ruact.navigation_boundary" do |app|
+      app.config.middleware.use Ruact::NavigationBoundary::Middleware
+    end
+
     rake_tasks { load File.expand_path("../tasks/ruact.rake", __dir__) }
 
     # Load the client manifest at boot (and on each code reload in development).