ruact 0.0.11 → 0.0.13

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/packaging.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Ruact
+  # What goes inside the published `.gem`, as a predicate rather than a list.
+  #
+  # There is exactly one writer of this rule. `ruact.gemspec` calls it to build
+  # `spec.files`, and `bin/release-gate` calls it to decide whether a pull
+  # request changed the bytes a consumer installs. A hand-kept path list on
+  # either side would be a second copy of the packaging rule, and it would drift
+  # from this one the first time the rule changed — which is the whole reason
+  # the gate does not carry its own.
+  #
+  # This file is **not** required from `lib/ruact.rb`. It is build-time code
+  # that happens to live under `lib/` so the gemspec can `require_relative` into
+  # it; nothing at runtime loads it, and nothing at runtime may come to depend
+  # on it.
+  #
+  # WHAT IT DOES NOT PROMISE
+  #
+  #   That the path exists, is tracked, or is readable. It answers a question
+  #   about a path's shape and nothing else; both callers hand it paths that
+  #   `git` has already vouched for.
+  module Packaging
+    # Directory trees a consumer of the installed gem actually reaches:
+    # `lib/` is the library, `sig/` is its RBS surface, and
+    # `vendor/javascript/` is public surface too — the bundled Vite plugin and
+    # browser runtime are resolved by filesystem path off the installed gem, so
+    # a release that left them out would generate imports to files that do not
+    # exist on the consumer's disk.
+    TREES = %w[lib/ sig/ vendor/javascript/].freeze
+
+    # `vendor/bundle/` is the local Bundler install directory. It is not under
+    # any of {TREES} today; the exclusion is here so that widening a tree above
+    # cannot quietly start packaging it.
+    EXCLUDED_TREES = %w[vendor/bundle/].freeze
+
+    # The documents that ship beside the code, expressed as a shape rather than
+    # a roster: a tracked file at the top level whose extension is `.md` or
+    # `.txt`. That covers the readme, the changelog, the licence, the security
+    # policy and both guides, and it keeps covering the next one without anyone
+    # remembering to add it here.
+    #
+    # It also decides the near misses by construction. `ruact.gemspec`,
+    # `Gemfile`, `Gemfile.lock`, `Rakefile`, `.rubocop.yml` and `.gitignore` are
+    # all top-level and none of them is a document, so none of them ships.
+    ROOT_DOCUMENT = %r{\A[^/]+\.(?:md|txt)\z}i
+
+    # Does this repository-relative path go inside the published gem?
+    #
+    # @param path [String] a repository-relative path, as `git ls-files` and
+    #   `git diff --name-only` both emit it (forward slashes, no leading `./`)
+    # @return [Boolean] true when the path is part of what a consumer installs
+    def self.packaged?(path)
+      return false if EXCLUDED_TREES.any? { |tree| path.start_with?(tree) }
+
+      TREES.any? { |tree| path.start_with?(tree) } || path.match?(ROOT_DOCUMENT)
+    end
+
+    # The packaged subset of a list of repository-relative paths, order
+    # preserved.
+    #
+    # @param paths [Enumerable<String>] repository-relative paths
+    # @return [Array<String>] those of them that go inside the published gem
+    def self.packaged_paths(paths)
+      paths.select { |path| packaged?(path) }
+    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).

data/lib/ruact/server.rb

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

data/lib/ruact/version.rb

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

data/lib/ruact/view_helper.rb

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

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

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

data/lib/ruact.rb

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