ruact 0.0.5 → 0.0.7

data/lib/ruact/controller.rb

@@ -3,6 +3,8 @@
 require "json"
 require "socket"
 require "uri"
+require_relative "view_helper"
+require_relative "validation_errors_collector"
 
 module Ruact
   # Include in ApplicationController to enable RSC rendering.
@@ -17,390 +19,75 @@ module Ruact
   module Controller
     extend ActiveSupport::Concern
 
-    # Story 8.1 review-batch 1 (2026-05-14) — symbols a host MUST NOT use
-    # as `ruact_action` / `ruact_query` names because overriding them
-    # would corrupt request handling. Keep sorted; documented per name:
-    # `:params`, `:request`, `:response`, `:headers`, `:session`, `:flash`,
-    # `:cookies` — request/response accessors; overriding breaks reads
-    # `:render`, `:redirect_to`, `:head`, `:send_file`, `:send_data` —
-    #   response producers; overriding breaks the response path
-    # `:action_name`, `:controller_name`, `:controller_path` — routing
-    #   identification; overriding breaks `before_action :foo, only:` matching
-    # `:url_for`, `:url_options` — URL generation
-    # `:dispatch`, `:process`, `:process_action` — Rails dispatch internals
-    # `:form_authenticity_token`, `:verified_request?` — CSRF plumbing
-    # Re-run-4 (2026-05-15) — list expanded with the additional
-    # ActionController instance methods reviewers flagged as silently
-    # clobberable: `:render_to_string` / `:render_to_body` (response
-    # producers used by templating), `:send_action` (Rails dispatch
-    # internal), `:logger` / `:logger=` (clobbering breaks every log
-    # statement on the controller), `:default_render` (the gem hook
-    # method itself — overriding would disable RSC rendering).
-    FRAMEWORK_RESERVED_METHODS = %i[
-      __send__ action_name controller_name controller_path cookies
-      default_render dispatch flash form_authenticity_token head headers
-      instance_eval instance_exec logger logger= method params process
-      process_action protect_from_forgery public_send redirect_to render
-      render_to_body render_to_string request response send send_action
-      send_data send_file session skip_forgery_protection url_for
-      url_options verified_request? verify_authenticity_token
-    ].to_set.freeze
-
-    # Story 8.1 — class-level DSL surface. The `ruact_action` macro registers
-    # a server-callable symbol with `Ruact.action_registry` (so the Vite-plugin
-    # codegen from Story 8.0a picks it up at the next `config.to_prepare`) AND
-    # defines a matching public instance method that is reachable ONLY via the
-    # gem's `POST /__ruact/fn/:name` endpoint dispatch path. The defined method
-    # body checks a thread-local sentinel (`Thread.current[:__ruact_dispatching]`)
-    # set by `Ruact::ServerFunctions::EndpointController#dispatch_action` and
-    # raises `Ruact::Error` for any direct call from in-controller code, a
-    # wildcard route, or `host_class.action(...).call` — closing the
-    # GET-without-CSRF attack surface that a host's `get ":controller/:action"`
-    # route would otherwise create. If a developer needs the block body from
-    # another controller method, they should refactor the body into a PORO that
-    # both the action and the controller call.
-    #
-    # Validation (naming-bridge rule + within-registry / cross-registry
-    # collision detection) fires from {Ruact::ServerFunctions::Registry#register}
-    # at controller-class load time — the failure is loud at boot, not at
-    # request-dispatch time.
-    class_methods do
-      # @param symbol [Symbol] the action name (snake_case; bridged to JS
-      #   camelCase by {Ruact::ServerFunctions::NameBridge}).
-      # @yield [params] the block runs via `instance_exec` on a fresh
-      #   controller instance at dispatch time; `params` shadows the request's
-      #   `params` accessor and is an `ActionController::Parameters` instance
-      #   wrapping the action-call arguments (NOT the request's query/form params).
-      # @return [Ruact::ServerFunctions::RegistryEntry] the entry just registered.
-      # @raise [Ruact::ConfigurationError] when the symbol fails the
-      #   naming-bridge rule or collides with another `ruact_action` in this
-      #   registry (cross-registry collisions with `ruact_query` are caught
-      #   later by {Ruact::ServerFunctions::Snapshot.functions_payload}).
-      def ruact_action(symbol, &block)
-        # Re-run-2 (2026-05-14) — `ruact_action` strictly requires a Symbol.
-        # A String slips through the naming-bridge regex but stores a
-        # String key in `@entries`, while `EndpointController#dispatch_action`
-        # looks the entry up by `:name.to_sym` — net effect: silent 404 on
-        # every dispatch. Refuse Strings (and anything else) loudly.
-        unless symbol.is_a?(Symbol)
-          raise ArgumentError,
-                "ruact_action requires a Symbol argument, got " \
-                "#{symbol.inspect} (#{symbol.class}). Use " \
-                "`ruact_action :#{symbol}` not `ruact_action #{symbol.inspect}`."
-        end
-
-        unless block
-          raise ArgumentError,
-                "ruact_action :#{symbol} requires a block — declare the " \
-                "implementation with `ruact_action :#{symbol} do |params| ... end`"
-        end
-
-        # Re-run-4 (2026-05-15) — parameter-shape guard (replaces the
-        # earlier `block.arity` check). `block.arity` is negative for
-        # ALL signatures that include any optional/keyword/splat
-        # parameter — including footguns like `do |params, required:|`
-        # which would crash at dispatch time when the macro invokes the
-        # block with one positional argument and no keyword arguments.
-        # We use `block.parameters` for full inspection: the block must
-        # accept exactly one positional argument (`:req`, `:opt`, or
-        # `:rest`) AND have no required keyword parameters (`:keyreq`).
-        # Optional keyword params (`:key`) and double-splat (`:keyrest`)
-        # are fine.
-        # Re-run-5 (2026-05-15) — block must accept exactly one
-        # positional argument. The macro invokes the block with one
-        # positional arg (`instance_exec(args, &block)`), so:
-        #
-        #   - `do |a, b|` would have `b` silently set to `nil`.
-        #     Parameters report `[[:opt, :a], [:opt, :b]]` for blocks
-        #     (proc-arity-coercion). Reject `:opt+:req > 1`.
-        #   - `do |p, required:|` (kwarg case): block.arity stays
-        #     negative, dispatch later raises. Reject `:keyreq`.
-        #   - `do |*args|` accepts any count including 1; `:rest`
-        #     entry counts as 1.
-        #   - `do |params, opt: nil|` is fine (optional kwarg).
-        #
-        # Allowed shapes: `do |p|`, `do |*args|`, `do |p, key: nil|`.
-        # Rejected: `do ||`, `do |a, b|`, `do |p, required:|`.
-        req_count    = block.parameters.count { |kind, _| kind == :req }
-        opt_count    = block.parameters.count { |kind, _| kind == :opt }
-        rest_count   = block.parameters.count { |kind, _| kind == :rest }
-        named_positional = req_count + opt_count
-        positional_total = named_positional + rest_count
-        has_required_kwarg = block.parameters.any? { |kind, _| kind == :keyreq }
-        if positional_total.zero? || named_positional > 1 || has_required_kwarg
-          raise ArgumentError,
-                "ruact_action :#{symbol} block must accept exactly one " \
-                "positional parameter and no required keyword arguments " \
-                "(got parameters=#{block.parameters.inspect}). Use " \
-                "`ruact_action :#{symbol} do |params| ... end`."
-        end
-
-        # Review-batch 1 (2026-05-14) — framework-method-clobber guard.
-        # Refuse to define if the symbol matches one of the well-known
-        # ActionController instance methods that would corrupt request
-        # handling if overridden (the `:params`, `:render`, `:session`,
-        # `:redirect_to`, `:dispatch`, etc. footgun). The hardcoded list
-        # is the canonical set documented in the Rails Guides; it's used
-        # in place of a dynamic `ActionController::Base.method_defined?`
-        # check because (a) the gem can be loaded before ActionController
-        # (e.g., in a non-Rails context) and (b) the dynamic list would
-        # include too many low-risk inherited methods (`:object_id`,
-        # `:respond_to?`) and produce confusing error messages.
-        if FRAMEWORK_RESERVED_METHODS.include?(symbol)
-          raise Ruact::ConfigurationError,
-                "ruact_action :#{symbol} would clobber a framework method — " \
-                "#{symbol.inspect} is a reserved ActionController instance " \
-                "method. Pick a different symbol (e.g. :#{symbol}_action) so " \
-                "the host's CSRF / params / render plumbing remains intact."
-        end
-
-        # Re-run-6 (2026-05-15) — also reject ANY symbol that names a method
-        # inherited from `ActionController::Base` (or its ancestors UP TO but
-        # NOT INCLUDING `Object`). The hardcoded `FRAMEWORK_RESERVED_METHODS`
-        # list is the documented surface, but Rails keeps adding/renaming
-        # internal methods (`:status`, `:send_action`, `:render_to_string`,
-        # `:logger`, `:default_render`, …). Anything that lives on
-        # `ActionController::Base` but NOT on plain `Object` is, by
-        # definition, framework plumbing — overriding it is unsafe.
-        # We carve `Object`/`Kernel`/`BasicObject` off so genuinely-generic
-        # methods (`:object_id`, `:respond_to?`, `:hash`, `:tap`) don't
-        # trip the guard — those are safe to coexist with as block-arg
-        # shadow inside `instance_exec`.
-        baseline_class = defined?(ActionController::Base) ? ActionController::Base : nil
-        if baseline_class
-          object_methods = Object.instance_methods + Object.private_instance_methods
-          framework_methods = baseline_class.instance_methods + baseline_class.private_instance_methods
-          if (framework_methods - object_methods).include?(symbol)
-            raise Ruact::ConfigurationError,
-                  "ruact_action :#{symbol} would clobber an inherited " \
-                  "ActionController::Base method. Overriding framework " \
-                  "plumbing (`#{symbol.inspect}`) is unsafe — pick a " \
-                  "different symbol (e.g. :#{symbol}_action)."
-          end
-        end
-
-        # Re-run-2 (2026-05-14) — refuse to clobber a method ALREADY defined
-        # on the host controller class itself. Common case: a controller has
-        # a normal `def index` action and the dev mistakenly writes
-        # `ruact_action :index do ... end`. Pre-batch this silently
-        # overrode :index with the action body + thread-local guard — the
-        # standard `GET /widgets` would then raise the security guard, since
-        # it's not a /__ruact/fn/index call. We check `instance_methods(false)
-        # + private_instance_methods(false)` (own class only — inherited
-        # framework methods are already caught by FRAMEWORK_RESERVED_METHODS).
-        #
-        # A method previously defined BY `ruact_action` on this same class
-        # is NOT a clobber — re-registration is legitimate (dev-mode reload,
-        # test re-registration after registry reset). We track our own
-        # define_method calls in `@__ruact_defined_methods` and skip the
-        # guard for those.
-        @__ruact_defined_methods ||= Set.new
-        own_methods = instance_methods(false) + private_instance_methods(false)
-        if own_methods.include?(symbol) && !@__ruact_defined_methods.include?(symbol)
-          raise Ruact::ConfigurationError,
-                "ruact_action :#{symbol} would clobber an existing method " \
-                "on #{name || self}. If #{symbol.inspect} is meant to be " \
-                "a server action, remove the existing definition first; " \
-                "if it's a regular controller action, pick a different " \
-                "ruact_action symbol (e.g. :#{symbol}_remote)."
-        end
-
-        # Re-run-3 (2026-05-15) — refuse to clobber an INHERITED app helper.
-        # Common case: `ApplicationController` defines `current_user` /
-        # `authenticate_user!` / `authorize` and a subclass mistakenly
-        # writes `ruact_action :current_user`. The above own-class check
-        # misses these because the method lives on a superclass; the
-        # FRAMEWORK_RESERVED_METHODS check misses them because they are
-        # app-defined, not part of `ActionController::Base`. Detect by
-        # asking the class hierarchy MINUS the ActionController baseline:
-        # any method that responds on `self` but NOT on
-        # `ActionController::Base` is an app-defined helper inherited
-        # from `ApplicationController` (or a concern mixed in there).
-        baseline = defined?(ActionController::Base) ? ActionController::Base : nil
-        if baseline &&
-           (method_defined?(symbol) || private_method_defined?(symbol)) &&
-           !(baseline.method_defined?(symbol) || baseline.private_method_defined?(symbol)) &&
-           !@__ruact_defined_methods.include?(symbol)
-          raise Ruact::ConfigurationError,
-                "ruact_action :#{symbol} would clobber an inherited helper " \
-                "on #{name || self} (likely defined on " \
-                "ApplicationController or a concern). Overriding " \
-                "#{symbol.inspect} would break callers that rely on it — " \
-                "pick a different ruact_action symbol (e.g. :#{symbol}_remote)."
-        end
-
-        Ruact.action_registry.register(symbol, kind: :action, controller: self, &block)
-
-        # Review-batch 1 (2026-05-14) — define `<symbol>` directly (no
-        # separate `__ruact_action_*` wrapper). This makes `before_action
-        # :foo, only: :create_post` match the actual action name. The
-        # method is public so `ActionController#process` dispatches to it
-        # through the standard callback chain.
-        #
-        # Defense in depth: the method body raises unless invoked under the
-        # gem's endpoint dispatch path (a thread-local sentinel set by
-        # `Ruact::ServerFunctions::EndpointController#dispatch_action`).
-        # Without the sentinel, a wildcard route like `get ":controller/
-        # :action"` could otherwise reach `create_post` as a GET (no CSRF).
-        @__ruact_defined_methods << symbol
-
-        # Re-run-6 (2026-05-15) — install a `method_added` hook so a LATER
-        # `def #{symbol}; ...; end` in the same controller body (or a reopen)
-        # cannot silently override the macro-defined action method. Without
-        # this guard, the registry/codegen still export the symbol but
-        # `host_class.dispatch` would run the user's later definition,
-        # producing a confusing 500 (the sentinel check is gone) instead of
-        # a loud class-load-time error. The hook is installed once per class
-        # and ignores re-definitions performed by the macro itself
-        # (tracked via `@__ruact_being_defined_by_ruact_action`).
-        #
-        # Re-run-7 (2026-05-15) — install the hook by `prepend`-ing a Module
-        # into the host's singleton class instead of `define_method`-ing
-        # `:method_added` directly on it. `define_method` REPLACES any
-        # `def self.method_added` (or `class << self; def method_added`)
-        # the host or its concerns already defined; `super(meth)` would
-        # then chain to `Module#method_added` (the default no-op), not the
-        # original implementation — silently breaking instrumentation and
-        # DSL bookkeeping concerns. Prepending a hook module keeps the
-        # original `method_added` in the ancestor chain so `super(meth)`
-        # invokes it after our check.
-        unless @__ruact_method_added_hook_installed
-          @__ruact_method_added_hook_installed = true
-          ruact_class = self
-          hook = Module.new do
-            define_method(:method_added) do |meth|
-              defined_set = ruact_class.instance_variable_get(:@__ruact_defined_methods)
-              being_defined = ruact_class.instance_variable_get(:@__ruact_being_defined_by_ruact_action)
-              if defined_set&.include?(meth) && !being_defined
-                defined_set.delete(meth)
-                raise Ruact::ConfigurationError,
-                      "method :#{meth} on #{ruact_class.name || ruact_class} was " \
-                      "registered by `ruact_action :#{meth}` and then re-defined " \
-                      "in the same class body. The later definition would " \
-                      "silently shadow the macro-defined action and break " \
-                      "endpoint dispatch. Either remove the explicit `def " \
-                      "#{meth}` (the macro already defines it) or rename the " \
-                      "ruact_action."
-              end
-              super(meth)
-            end
-          end
-          singleton_class.prepend(hook)
-        end
-
-        @__ruact_being_defined_by_ruact_action = true
-        define_method(symbol) do
-          unless Thread.current[:__ruact_dispatching] == symbol
-            raise Ruact::Error,
-                  "ruact action :#{symbol} can only be invoked through " \
-                  "POST /__ruact/fn/:name. Direct method calls or wildcard " \
-                  "routes are rejected for security reasons."
-          end
-          begin
-            args = ruact_action_params
-          rescue JSON::ParserError => e
-            # Re-run-4 (2026-05-15) — return a structured 400 instead of
-            # surfacing the raw `JSON::ParserError`. The host's
-            # `rescue_from` chain may not have a handler for it (Rails'
-            # default is a 500), and even when it does the response
-            # shape is not the bad-request contract the JS runtime
-            # expects (`{error}` JSON body + 400 status).
-            return render(
-              json: { error: "ruact action :#{symbol} received malformed JSON body: #{e.message}" },
-              status: :bad_request
-            )
-          end
-          result = instance_exec(args, &block)
-          return if performed?
-
-          # AC2: a nil block return renders 204 No Content (no body). A non-nil
-          # return renders 200 + JSON.
-          if result.nil?
-            head(:no_content)
-          else
-            render(json: result)
-          end
-        end
-        @__ruact_being_defined_by_ruact_action = false
-
-        # ActionController caches `action_methods` lazily; clear the cache so
-        # the newly-defined action is dispatchable in the same boot cycle
-        # (matters in tests and in dev where `ruact_action` declarations
-        # accumulate after the controller class first loads).
-        clear_action_methods! if respond_to?(:clear_action_methods!, true)
-      end
-    end
+    include Ruact::ValidationErrorsCollector
+    # Story 14.2 (FR104) — the JS asset markup (entry `<script>` tags +
+    # `__FLIGHT_DATA`) lives in one place: `Ruact::ViewHelper#ruact_js_assets`.
+    # The controller mixes the helper in so `ruact_html_shell` delegates to that
+    # single implementation (controller↔helper parity — no duplicated tag logic),
+    # and so the shared `vite_dev_running?` / `vite_manifest_entry` helpers are
+    # reachable here without duplication.
+    include Ruact::ViewHelper
 
     private
 
-    # Story 8.1 — extracts the action-call arguments from the request body for
-    # a `ruact_action` invocation. The result becomes the `params` block-arg
-    # the dev wrote in `ruact_action :foo do |params| ... end`, shadowing the
-    # request's own `params` accessor. Returns an `ActionController::Parameters`
-    # so `params.require(:title).permit(...)` continues to work inside the block.
-    #
-    # Wire shape (from the JS runtime):
-    #   - `Content-Type: application/json` → `JSON.parse(request.body)` as a Hash
-    #   - `Content-Type: multipart/form-data` or `application/x-www-form-urlencoded`
-    #     → Rails has already parsed `request.request_parameters` for us
-    #   - Other / missing → empty Hash (callers must validate themselves)
-    def ruact_action_params
-      raw = ruact_action_raw_args
-      ActionController::Parameters.new(raw)
-    end
-
-    def ruact_action_raw_args
-      content_type = request.content_mime_type&.to_s ||
-                     request.headers["Content-Type"]&.split(";")&.first
-      case content_type
-      when "application/json"
-        # Re-run-3 (2026-05-15) — use `request.raw_post` instead of
-        # `request.body.read`. Rack caches `raw_post` after the first
-        # read of the request body, so a host `before_action` that
-        # already touched `request.body` would otherwise leave the
-        # IO at EOF and our `.read` would return `""` — silently
-        # coercing the action call to an empty hash. `raw_post` is
-        # safe to call multiple times and returns the full POST body.
-        body = request.raw_post
-        return {} if body.nil? || body.empty?
-
-        # Review-batch 2 (2026-05-14) — raise on malformed JSON instead of
-        # silently coercing to {}. A request with `Content-Type:
-        # application/json` and an unparseable body is corrupted; running
-        # the action on `{}` would mask real client bugs. Rails' standard
-        # 400 handler surfaces this as a clean error response.
-        parsed = JSON.parse(body)
-        parsed.is_a?(Hash) ? parsed : { "_value" => parsed }
-      when "multipart/form-data", "application/x-www-form-urlencoded"
-        # Review-batch 2 (2026-05-14) — `request.request_parameters` is the
-        # POST body ONLY (routing params like `:name`, `:action`,
-        # `:controller` live in `request.path_parameters`, NOT here). The
-        # earlier `.except(:name, :action, :controller)` was a bug — it
-        # would silently drop legitimate body fields named `name`,
-        # `action`, or `controller` from forms.
-        request.request_parameters
-      else
-        {}
-      end
-    end
-
-    # Returns the boot-time cached manifest (set by Railtie#config.to_prepare).
-    # No per-request file I/O (AC#6).
+    # `ruact_js_assets` / `__ruact_component__` are public VIEW helpers, but on a
+    # 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__
+
+    # 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
+    # I/O. In DEVELOPMENT it fetches the live manifest from the Vite dev server
+    # (falling back to the on-disk file, then a clear error), killing the
+    # boot-race where Rails read the missing file before Vite wrote it and every
+    # first request 500'd on +nil.reference_for+. Called once per render; the
+    # returned manifest is held by RenderPipeline for the whole render (not
+    # re-fetched per component). See {Ruact::ManifestResolver}.
     def ruact_manifest
-      Ruact.manifest
+      ManifestResolver.resolve
     end
 
-    # Only activate RSC rendering for HTML-like requests (AC FR26).
-    # JSON, XML, and other formats bypass RSC entirely so respond_to blocks
-    # and explicit render calls work without interference.
+    # Only activate RSC rendering when the matching .html.erb template exists AND
+    # the client will accept an HTML response (AC FR26; Story 10.0).
+    # `request.format.html?` is false for a `*/*` wildcard (curl/bots/
+    # health-checks), so checking it alone routed those requests through `super`,
+    # which compiled+rendered the `.html.erb` outside a `ruact_render` flow and
+    # 500'd with "__ruact_component__ called outside a ruact_render flow".
+    # Checking HTML acceptability instead serves `*/*` the same HTML shell a
+    # browser gets. Concrete non-HTML formats (application/json, application/xml)
+    # carry no html/wildcard accept → still bypass to `super` so respond_to
+    # blocks and explicit render calls work without interference.
     def default_render
-      if ruact_template_exists? && (request.format.html? || ruact_request?)
+      if ruact_template_exists? && (ruact_request? || ruact_html_acceptable?)
         ruact_render
       else
         super
       end
     end
 
+    # True when the client will accept an HTML response: an absent Accept (Rails
+    # defaults to HTML) or any acceptable type that is HTML or the `*/*` wildcard.
+    # `Mime::ALL.html?` is false, so the explicit `== Mime::ALL` check is required
+    # to recognize the wildcard (`*/*`) alongside concrete `text/html`. A nil
+    # entry (from an empty/unparseable Accept token) is treated as "accept
+    # anything" so a blank Accept degrades to HTML rather than raising.
+    #
+    # This is a MEMBERSHIP test, not a priority/quality negotiation: a mixed
+    # `application/json, text/html` (HTML listed alongside a concrete API format)
+    # activates the HTML shell, because `default_render` is only ever reached on
+    # an action that did NOT explicitly render — there is no JSON representation
+    # to prefer, and the client did say it accepts HTML. A purely concrete
+    # non-HTML Accept (`application/json`, `application/json, application/xml`)
+    # has no html/wildcard member and still bypasses to `super` (AC4).
+    # `Mime::Type.parse` discards `q` values, so an exotic `text/html;q=0` is
+    # treated as acceptable rather than as an explicit rejection — out of scope
+    # for the implicit-render contract (see story 10.0 deferred note).
+    def ruact_html_acceptable?
+      accepts = request.accepts
+      accepts.blank? || accepts.any? { |type| type.nil? || type == Mime::ALL || type.html? }
+    end
+
     # Render the RSC view for the current action using ActionView's full pipeline.
     # ActionView handles layouts, partials, and helpers — the ErbPreprocessorHook
     # ensures all PascalCase tags are transformed before template compilation.
@@ -412,6 +99,11 @@ module Ruact
     #             the current action's default template.
     # +locals+:   hash of local variables to pass to the template.
     def ruact_render(template: nil, locals: {})
+      # 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
+
       pipeline  = RenderPipeline.new(ruact_manifest, controller_path: controller_path, logger: logger)
       streaming = ruact_request? && self.class.ancestors.include?(ActionController::Live)
 
@@ -512,6 +204,11 @@ module Ruact
         return super
       end
 
+      # 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).
+      __ruact_stash_errors_in_flash
+
       render plain: "0:#{JSON.generate({ 'redirectUrl' => redirect_url, 'redirectType' => 'push' })}\n",
              content_type: "text/x-component"
     end
@@ -532,7 +229,12 @@ module Ruact
     end
 
     def ruact_html_shell(flight_payload)
-      escaped_payload = flight_payload.gsub("</script>", '<\/script>')
+      # Story 14.2 — the JS asset block (entry `<script>` tags + `__FLIGHT_DATA`)
+      # is delegated to the single `Ruact::ViewHelper#ruact_js_assets`
+      # implementation. The bootstrap entry script is a deferred ES module, so it
+      # runs after the inline `__FLIGHT_DATA` classic script has populated the
+      # queue regardless of source order — emitting the whole block in `<body>`
+      # is correct.
       <<~HTML
         <!DOCTYPE html>
         <html lang="en">
@@ -541,16 +243,10 @@ module Ruact
             <meta name="viewport" content="width=device-width, initial-scale=1" />
             #{ruact_csrf_meta_tag}
             <title>Rails RSC</title>
-            #{vite_tags}
           </head>
           <body>
             <div id="root"></div>
-            <script>
-              (function() {
-                var d = (self.__FLIGHT_DATA = self.__FLIGHT_DATA || []);
-                d.push(#{escaped_payload.inspect});
-              })();
-            </script>
+            #{ruact_js_assets(flight_payload)}
           </body>
         </html>
       HTML
@@ -558,10 +254,10 @@ module Ruact
 
     # Story 8.3 review R7 — emits `<meta name="csrf-token" content="...">`
     # into the shell so the JS runtime's `<meta>` lookup can forward a
-    # valid `X-CSRF-Token` on every `_makeRef` call. Without this, hosts
-    # that route `ruact_render` through the gem's HTML shell (the
-    # standard path) have no token in the document and standalone
-    # actions' gem-side CSRF check (Story 8.3 AC5) always rejects.
+    # valid `X-CSRF-Token` on every server-function (mutation) call. Without
+    # this, hosts that route `ruact_render` through the gem's HTML shell (the
+    # standard path) have no token in the document and the host's
+    # `protect_from_forgery` rejects every non-GET server function.
     #
     # Returns an empty string when CSRF protection isn't available
     # (non-Rails specs, or hosts that have deliberately stripped
@@ -576,47 +272,5 @@ module Ruact
     rescue StandardError
       ""
     end
-
-    def vite_tags
-      if Rails.env.development? && vite_dev_running?
-        # @vitejs/plugin-react normally injects this preamble by processing index.html.
-        # Since our HTML is generated by Rails (not Vite), we inject it manually.
-        # Without it, every JSX file throws "can't detect preamble" at runtime.
-        react_preamble = <<~JS
-          <script type="module">
-            import RefreshRuntime from 'http://localhost:5173/@react-refresh';
-            RefreshRuntime.injectIntoGlobalHook(window);
-            window.$RefreshReg$ = () => {};
-            window.$RefreshSig$ = () => (type) => type;
-            window.__vite_plugin_react_preamble_installed__ = true;
-          </script>
-        JS
-
-        react_preamble + <<~HTML
-          <script type="module" src="http://localhost:5173/@vite/client"></script>
-          <script type="module" src="http://localhost:5173/app/javascript/application.jsx"></script>
-        HTML
-      else
-        # Production: read hashed URL from Vite manifest
-        entry = vite_manifest_entry("app/javascript/application.jsx")
-        src   = entry ? "/assets/#{entry['file']}" : "/assets/application.js"
-        %(<script type="module" src="#{src}"></script>)
-      end
-    end
-
-    def vite_dev_running?
-      require "socket"
-      Socket.tcp("localhost", 5173, connect_timeout: 1).close
-      true
-    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ETIMEDOUT, SocketError
-      false
-    end
-
-    def vite_manifest_entry(src_path)
-      manifest_path = Rails.root.join("public", "assets", ".vite", "manifest.json")
-      return nil unless File.exist?(manifest_path)
-
-      JSON.parse(File.read(manifest_path))[src_path]
-    end
   end
 end