ruact 0.0.11 → 0.0.13

data/lib/ruact/controller.rb

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

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