ruact 0.0.2 → 0.0.3

data/lib/ruact/controller.rb

@@ -17,11 +17,376 @@ 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
+
     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).
-    def rsc_manifest
+    def ruact_manifest
       Ruact.manifest
     end
 
@@ -29,8 +394,8 @@ module Ruact
     # JSON, XML, and other formats bypass RSC entirely so respond_to blocks
     # and explicit render calls work without interference.
     def default_render
-      if rsc_template_exists? && (request.format.html? || rsc_request?)
-        rsc_render
+      if ruact_template_exists? && (request.format.html? || ruact_request?)
+        ruact_render
       else
         super
       end
@@ -46,37 +411,77 @@ 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 rsc_render(template: nil, locals: {})
-      pipeline  = RenderPipeline.new(rsc_manifest, controller_path: controller_path, logger: logger)
-      streaming = rsc_request? && self.class.ancestors.include?(ActionController::Live)
-
-      # ComponentRegistry is started before ActionView renders the template.
-      # ViewHelper's __rsc_component__ registers components during rendering.
-      # from_html eagerly captures the registry before the ensure block resets it.
-      ComponentRegistry.start
-      enumerator = begin
+    def ruact_render(template: nil, locals: {})
+      pipeline  = RenderPipeline.new(ruact_manifest, controller_path: controller_path, logger: logger)
+      streaming = ruact_request? && self.class.ancestors.include?(ActionController::Live)
+
+      # Allocate a per-render context and expose it to the view via a normal
+      # (non-`@_`-prefixed) instance variable on the controller. Rails 8's
+      # `render_to_string` allocates a fresh `ActionView::Base` distinct from
+      # `controller.view_context`; setting the ivar on `view_context` does not
+      # reach that view. By contrast, controller ivars *not* matching
+      # `AbstractController::Base::DEFAULT_PROTECTED_INSTANCE_VARIABLES`
+      # (i.e. anything not prefixed with `@_`) are copied to the view via
+      # `_assigns_for_view_context`, so the view evaluated inside
+      # `render_to_string` receives `@ruact_render_context` populated.
+      # ViewHelper#__ruact_component__ reads it during ERB evaluation. The
+      # controller instance is per-request (Rails allocates a new one per
+      # action), so this is per-request safe under multi-threaded servers
+      # (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))
-        pipeline.from_html(html, streaming: streaming)
-      ensure
-        ComponentRegistry.reset
+        emit_ruact_response(pipeline, html, render_context, streaming: streaming)
       end
+    end
 
-      if rsc_request?
-        if streaming
-          response.headers["Content-Type"]      = "text/x-component; charset=utf-8"
-          response.headers["Cache-Control"]     = "no-cache"
-          response.headers["X-Accel-Buffering"] = "no"
-          begin
-            enumerator.each { |row| response.stream.write(row) }
-          ensure
-            response.stream.close
-          end
+    # Allocates a fresh `Ruact::RenderContext`, exposes it as the
+    # `@ruact_render_context` ivar for the duration of the block, then
+    # restores the controller's prior ivar state. When the ivar wasn't
+    # defined before this call, `remove_instance_variable` puts the
+    # controller back in its original state — restoring it as a defined
+    # `nil` would leak a phantom assignment into `view_assigns`
+    # (`{"ruact_render_context" => nil}`) on any subsequent error/rescue
+    # render in the same request.
+    def with_render_context
+      had_previous = instance_variable_defined?(:@ruact_render_context)
+      previous     = @ruact_render_context if had_previous
+      render_context = RenderContext.new
+      @ruact_render_context = render_context
+      begin
+        yield render_context
+      ensure
+        if had_previous
+          @ruact_render_context = previous
         else
-          render plain: enumerator.to_a.join, content_type: "text/x-component"
+          remove_instance_variable(:@ruact_render_context)
+        end
+      end
+    end
+
+    # Build the wire output and write it to the response. Streaming responses
+    # only fire after `pipeline.render` returns without raising — that way a
+    # missing-component error can still surface as a normal 500 response
+    # (matching the legacy `#from_html` ordering) before any streaming
+    # response headers are mutated.
+    def emit_ruact_response(pipeline, html, render_context, streaming:)
+      if ruact_request? && streaming
+        enumerator = pipeline.render({ html: html, render_context: render_context }, mode: :stream)
+        response.headers["Content-Type"]      = "text/x-component; charset=utf-8"
+        response.headers["Cache-Control"]     = "no-cache"
+        response.headers["X-Accel-Buffering"] = "no"
+        begin
+          enumerator.each { |row| response.stream.write(row) }
+        ensure
+          response.stream.close
         end
       else
-        render html: rsc_html_shell(enumerator.to_a.join).html_safe, layout: false
+        payload = pipeline.render({ html: html, render_context: render_context }, mode: :string)
+        if ruact_request?
+          render plain: payload, content_type: "text/x-component"
+        else
+          render html: ruact_html_shell(payload).html_safe, layout: false
+        end
       end
     end
 
@@ -86,7 +491,7 @@ module Ruact
     # HTTP round-trip.  Non-RSC requests and external-origin redirects fall through
     # to the standard Rails implementation.
     def redirect_to(options = {}, response_options = {})
-      return super unless rsc_request?
+      return super unless ruact_request?
 
       url = url_for(options)
 
@@ -111,12 +516,12 @@ module Ruact
              content_type: "text/x-component"
     end
 
-    def rsc_request?
+    def ruact_request?
       request.headers["Accept"]&.include?("text/x-component") ||
-        request.headers["RSC-Request"] == "1"
+        request.headers["Ruact-Request"] == "1"
     end
 
-    def rsc_template_exists?
+    def ruact_template_exists?
       File.exist?(default_template_path)
     end
 
@@ -126,7 +531,7 @@ module Ruact
       Rails.root.join("app", "views", controller, "#{action}.html.erb")
     end
 
-    def rsc_html_shell(flight_payload)
+    def ruact_html_shell(flight_payload)
       escaped_payload = flight_payload.gsub("</script>", '<\/script>')
       <<~HTML
         <!DOCTYPE html>
@@ -134,6 +539,7 @@ module Ruact
           <head>
             <meta charset="UTF-8" />
             <meta name="viewport" content="width=device-width, initial-scale=1" />
+            #{ruact_csrf_meta_tag}
             <title>Rails RSC</title>
             #{vite_tags}
           </head>
@@ -150,6 +556,27 @@ module Ruact
       HTML
     end
 
+    # 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.
+    #
+    # Returns an empty string when CSRF protection isn't available
+    # (non-Rails specs, or hosts that have deliberately stripped
+    # `form_authenticity_token` from the controller surface).
+    def ruact_csrf_meta_tag
+      return "" unless respond_to?(:form_authenticity_token, true)
+
+      token = form_authenticity_token
+      return "" if token.nil? || token.empty?
+
+      %(<meta name="csrf-token" content="#{ERB::Util.html_escape(token)}" />)
+    rescue StandardError
+      ""
+    end
+
     def vite_tags
       if Rails.env.development? && vite_dev_running?
         # @vitejs/plugin-react normally injects this preamble by processing index.html.

data/lib/ruact/doctor.rb

@@ -5,9 +5,17 @@ require "pathname"
 
 module Ruact
   # Runs a suite of installation health checks and prints ✓/✗ per check.
-  # Extracted from the rsc:doctor Rake task for direct testability (FR27).
+  # Extracted from the ruact:doctor Rake task for direct testability (FR27).
   class Doctor
-    CHECKS = %i[manifest vite controller layout streaming].freeze
+    CHECKS = %i[manifest vite controller layout streaming legacy_constant].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).
+    LEGACY_CONST = %w[Rails Rsc].join
+    LEGACY_GEM   = %w[rails rsc].join("_")
+    LEGACY_CONSTANT_RE = /(?<![A-Za-z_])(?:#{LEGACY_CONST}|#{LEGACY_GEM})(?![A-Za-z_])/
+    LEGACY_SCAN_GLOBS = ["config/initializers/**/*.rb", "app/**/*.rb"].freeze
+    RENAME_DOC_URL = "https://github.com/luizcg/ruact/blob/main/CHANGELOG.md#renamed"
 
     # Runs all checks, prints results, returns true if all pass.
     def self.run
@@ -15,6 +23,7 @@ module Ruact
     end
 
     def run
+      puts "[ruact] Health check"
       results = CHECKS.map { |check| send(:"check_#{check}") }
       results.each { |status, message| puts format_result(status, message) }
       passed = results.all? { |status, _| status == :pass }
@@ -64,6 +73,29 @@ module Ruact
       [:pass, "streaming: #{label} (#{streaming_server_hint})"]
     end
 
+    # Detects host-app references to the legacy gem constant or require path
+    # left over from the rename to `ruact`. Literal names are interpolated
+    # from LEGACY_CONST / LEGACY_GEM so this file passes the gem-CI
+    # `name-propagation` guard without an exclusion (Story 5.1 review F4).
+    def check_legacy_constant
+      offenses = LEGACY_SCAN_GLOBS.flat_map do |glob|
+        Dir[Rails.root.join(glob)].flat_map do |file|
+          File.foreach(file).with_index(1).filter_map do |line, lineno|
+            next unless LEGACY_CONSTANT_RE.match?(line)
+
+            "#{file}:#{lineno}"
+          end
+        end
+      end
+      return [:pass, "No legacy `#{LEGACY_CONST}` / `#{LEGACY_GEM}` references found"] if offenses.empty?
+
+      [:fail,
+       "Legacy `#{LEGACY_CONST}` / `#{LEGACY_GEM}` references found in #{offenses.length} location(s) " \
+       "(first: #{offenses.first}). Replace `#{LEGACY_CONST}` with `Ruact` and " \
+       "`require \"#{LEGACY_GEM}\"` with `require \"ruact\"` (gem renamed in v0.0.x). " \
+       "See #{RENAME_DOC_URL}."]
+    end
+
     def streaming_server_hint
       return "Puma"      if defined?(::Puma)
       return "Unicorn"   if defined?(::Unicorn)

data/lib/ruact/erb_preprocessor.rb

@@ -9,10 +9,10 @@ module Ruact
   #
   # becomes a placeholder that evaluates the props as Ruby:
   #
-  #   <%= __rsc_component__("LikeButton", { "postId" => @post.id, "initialCount" => 5 }) %>
+  #   <%= __ruact_component__("LikeButton", { "postId" => @post.id, "initialCount" => 5 }) %>
   #
   # The placeholder is replaced by an HTML comment with a unique token:
-  #   <!-- __RSC_COMPONENT_0__ -->
+  #   <!-- __RUACT_0__ -->
   #
   # The actual ClientReference + props are registered in the binding and
   # collected by HtmlConverter after the ERB renders.
@@ -40,16 +40,16 @@ module Ruact
     end
 
     def transform(source)
-      # Step 1: transform <Suspense> paired tags into <rsc-suspense> HTML elements.
+      # Step 1: transform <Suspense> paired tags into <ruact-suspense> HTML elements.
       # This runs before the general component regex so Suspense isn't treated as a component.
       result = source
                .gsub(SUSPENSE_OPEN_RE) do
                  attrs    = ::Regexp.last_match(1)
                  fallback = extract_string_attr(attrs, "fallback") || ""
                  escaped  = fallback.gsub('"', "&quot;")
-                 %(<rsc-suspense data-rsc-fallback="#{escaped}">)
+                 %(<ruact-suspense data-ruact-fallback="#{escaped}">)
                end
-        .gsub(SUSPENSE_CLOSE_RE, "</rsc-suspense>")
+        .gsub(SUSPENSE_CLOSE_RE, "</ruact-suspense>")
 
       # Step 2: transform remaining PascalCase self-closing / opening component tags.
       result.gsub(COMPONENT_TAG_RE) do |match|
@@ -61,7 +61,7 @@ module Ruact
         begin
           props_ruby = parse_props(attrs_string)
           props_hash = props_ruby.empty? ? "{}" : "{ #{props_ruby} }"
-          %(<%= __rsc_component__(#{component_name.inspect}, #{props_hash}) %>)
+          %(<%= __ruact_component__(#{component_name.inspect}, #{props_hash}) %>)
         rescue PreprocessorError => e
           raise PreprocessorError, "#{e.message} at line #{line}: #{match.strip}"
         end