ruact 0.0.2 → 0.0.3

data/lib/ruact/serializable.rb

@@ -3,18 +3,18 @@
 module Ruact
   # Include this module in any Ruby object you want to pass as a prop to a
   # client component. Declare which attributes are safe to serialize with
-  # +rsc_props+; only those attributes will be included in the wire payload.
+  # +ruact_props+; only those attributes will be included in the wire payload.
   #
   # @example
   #   class Post
   #     include Ruact::Serializable
   #     attr_reader :id, :title, :secret
-  #     rsc_props :id, :title   # :secret is never sent to the client
+  #     ruact_props :id, :title   # :secret is never sent to the client
   #   end
   module Serializable
     def self.included(base)
       base.extend(ClassMethods)
-      base.instance_variable_set(:@rsc_props, [])
+      base.instance_variable_set(:@ruact_props, [])
     end
 
     module ClassMethods
@@ -23,24 +23,24 @@ module Ruact
       # corresponding method defined on the class.
       #
       # @param attrs [Array<Symbol>]
-      def rsc_props(*attrs)
+      def ruact_props(*attrs)
         attrs.each do |attr|
           unless method_defined?(attr)
             raise ArgumentError,
-                  "rsc_props: method `#{attr}` is not defined on #{self}"
+                  "ruact_props: method `#{attr}` is not defined on #{self}"
           end
         end
-        @rsc_props = attrs
+        @ruact_props = attrs
       end
 
       # Returns the list of declared prop names as symbols.
       # Walks the ancestor chain so subclasses inherit parent declarations.
       #
       # @return [Array<Symbol>]
-      def rsc_props_list
+      def ruact_props_list
         klass = self
         while klass
-          return klass.instance_variable_get(:@rsc_props) if klass.instance_variable_defined?(:@rsc_props)
+          return klass.instance_variable_get(:@ruact_props) if klass.instance_variable_defined?(:@ruact_props)
 
           klass = klass.superclass
         end
@@ -48,11 +48,11 @@ module Ruact
       end
     end
 
-    # Serialize only the attributes declared with +rsc_props+.
+    # Serialize only the attributes declared with +ruact_props+.
     #
     # @return [Hash{String => Object}]
-    def rsc_serialize
-      self.class.rsc_props_list.to_h { |attr| [attr.to_s, public_send(attr)] }
+    def ruact_serialize
+      self.class.ruact_props_list.to_h { |attr| [attr.to_s, public_send(attr)] }
     end
   end
 end

data/lib/ruact/server.rb

@@ -0,0 +1,341 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+# Review patch (2026-06-07) — a direct `require "ruact/server"` (without the
+# host having required "ruact" first) must still resolve everything the
+# salvaged chains touch at request time: `Ruact.config` (defined in ruact.rb,
+# not configuration.rb), `Ruact::UploadTooLargeError`, the ErrorPayload
+# pipeline. The gem root never requires this file back (the bare
+# `require "ruact"` path stays ActionController-free; the Railtie loads the
+# concern), so this is acyclic by construction.
+require "uri"
+require_relative "../ruact"
+require_relative "server_functions/error_rendering"
+require_relative "server_functions/bucket_two_payload"
+require_relative "server_functions/name_bridge"
+
+module Ruact
+  # Story 9.1 (route-driven redesign, Phase A) — the v2 server-functions
+  # marker concern.
+  #
+  #   class PostsController < ApplicationController
+  #     include Ruact::Server        # the ONLY marker — no per-action DSL
+  #
+  #     def create                   # non-GET routed action → callable server function
+  #       @post = Post.create!(title: params[:title])
+  #       redirect_to @post
+  #     end
+  #   end
+  #
+  # Per the 2026-06-02 ADR addendum (Story 9-0,
+  # `docs/internal/decisions/server-functions-api.md`), exposure is decided by
+  # `routes.rb` — the Story 9.3 codegen reads `Rails.application.routes`
+  # filtered to non-GET routes on controllers that include this concern. The
+  # concern itself registers NOTHING and emits NOTHING; at this story it is a
+  # pure marker plus the new home of the two salvaged Epic-8 subsystems,
+  # running on the host controller's own callback chain:
+  #
+  # - **Story 8.4 structured-error chain** — `rescue_from StandardError` (+ an
+  #   explicit `ActionController::InvalidAuthenticityToken` registration that
+  #   preempts Rails' default `handle_unverified_request`, Pitfall #1). On
+  #   function-call requests ({#__ruact_function_call?}) an uncaught exception
+  #   renders the structured JSON payload (discriminator
+  #   `_ruact_server_action_error: true`, four baseline fields, dev/prod split
+  #   via `Ruact.config.dev_error_payload_enabled`, status mapping 422/403/
+  #   413/500). On every other request shape — including GET/HEAD requests
+  #   regardless of their Accept header — the handler re-raises, so GET
+  #   pages, `default_render`, and Phase-1 behavior stay byte-for-byte
+  #   untouched. Host `rescue_from` declarations — whether inherited from a
+  #   parent class or declared in the host's own body — keep precedence:
+  #   the chain only catches what the host did not.
+  # - **Story 8.5 upload guard** — `prepend_before_action` enforcing
+  #   `Ruact.config.max_upload_bytes` against the wire `Content-Length`
+  #   BEFORE Rack's multipart parser. The three carve-outs are preserved:
+  #   nil limit, non-multipart/urlencoded content type, absent
+  #   Content-Length. New here (D2): GET/HEAD requests skip the guard
+  #   entirely. The 413 renders structured for ALL request shapes (D1) —
+  #   a meaningful 413 beats a re-raised 500 for native form submits too.
+  #   Contract simplification: the concern assumes the host includes it after
+  #   `protect_from_forgery`; no runtime callback-order verifier runs here.
+  #
+  # Both bodies live in {Ruact::ServerFunctions::ErrorRendering}, shared with
+  # the v1 {Ruact::ServerFunctions::EndpointController} during the
+  # strangler-fig transition so the wire contract is identical by
+  # construction. Dual-bucket response negotiation (ivar serialization,
+  # `$redirect`, 204, `Vary: Accept`) is Story 9.2; this concern only
+  # contributes the discrimination predicate 9.2 will reuse.
+  module Server
+    extend ActiveSupport::Concern
+
+    include Ruact::ServerFunctions::ErrorRendering
+
+    included do
+      # Story 8.5 salvage — prepended so the size check wins the race against
+      # every other callback, including `verify_authenticity_token`.
+      prepend_before_action :__ruact_enforce_upload_limit!
+
+      # Story 9.2 AC6 — `Vary: Accept` on every non-GET SUCCESS shape. The same
+      # URL + verb serves two bodies discriminated solely on `Accept`, so a
+      # cache MUST vary on it (never serve Flight to a JSON caller or vice-versa).
+      # Set in BOTH a `before_action` and an `after_action` (review rounds 1–2),
+      # because either callback alone has a gap:
+      #   - the `after_action` APPENDS to a host-set `Vary` (preserving it), but
+      #     is skipped when a `before_action` performs the response (e.g. an auth
+      #     `before_action` that `redirect_to`s a Bucket-2 call);
+      #   - the `before_action` covers that halt case (it runs ahead of the
+      #     host's own before-callbacks), but a later `response.headers["Vary"] =`
+      #     in the action would clobber it.
+      # Together they cover the 200 ivar-JSON / 204 / `$redirect` / Bucket-1
+      # Flight shapes (incl. before-callback redirects). The method is
+      # idempotent. Error responses (413/403/500) may still omit it — they are
+      # non-cacheable, not dual representations.
+      #
+      # Documented limitation (accepted 2026-06-09): a host `before_action` that
+      # BOTH overwrites `Vary` AND performs the response (e.g.
+      # `response.headers["Vary"] = "Cookie"; redirect_to "/login"` in one
+      # before-callback) leaves the final response without `Accept` — the Ruact
+      # before-action set it first, the host clobbered it, and Rails skips the
+      # after-action on the before-halt. This combination is contrived (real
+      # auth callbacks don't reassign `Vary` while redirecting); a callback can't
+      # guarantee the final header unconditionally, and a Rack-level mechanism
+      # was judged not worth the complexity for this edge.
+      before_action :__ruact_set_vary_on_accept!
+      after_action  :__ruact_set_vary_on_accept!
+
+      # Story 8.4 salvage — same registration order as v1 (Pitfall #1): the
+      # generic StandardError entry first, the explicit
+      # InvalidAuthenticityToken entry second so it wins Rails'
+      # most-recently-registered handler walk for CSRF failures.
+      #
+      # Review patch (2026-06-07) — handlers the host INHERITED from a parent
+      # class must keep precedence too, not just ones declared after the
+      # include: Rails walks `rescue_handlers` most-recently-registered
+      # first, and a plain `rescue_from` here would land the concern's
+      # entries AFTER the inherited ones. The concern's entries are therefore
+      # moved to the FRONT of the array, so every host handler — inherited or
+      # declared later in the class body — stays more recent and wins.
+      inherited_handlers = rescue_handlers
+      rescue_from StandardError, with: :__ruact_render_action_error
+      rescue_from ActionController::InvalidAuthenticityToken, with: :__ruact_render_action_error
+      self.rescue_handlers = (rescue_handlers - inherited_handlers) + inherited_handlers
+    end
+
+    # Story 9.3 — the JS-identifier rename escape hatch (AC4). Naming is
+    # derived from the route table by default ({Ruact::ServerFunctions::RouteSource});
+    # when two routes collide in the merged JS namespace the codegen fails loudly
+    # at boot, and this macro is how a host breaks the tie (or simply prefers a
+    # different name):
+    #
+    #   class PostsController < ApplicationController
+    #     include Ruact::Server
+    #     ruact_function_name :publish_all, as: "publishEverything"
+    #   end
+    #
+    # The override is keyed by ACTION name (string) and read by the codegen via
+    # {#__ruact_function_name_overrides}. The target identifier is validated at
+    # class-load time against the same JS-identifier shape + reserved-word rules
+    # the codegen enforces, so a bad override fails at boot, never at codegen.
+    module ClassMethods
+      # JS identifier shape — mirror of {Ruact::ServerFunctions::Codegen::VALID_JS_IDENTIFIER}
+      # (kept local so the concern does not depend on the codegen module).
+      RUACT_VALID_JS_IDENTIFIER = /\A[A-Za-z_$][A-Za-z0-9_$]*\z/
+
+      # @param action [Symbol, String] the controller action whose generated
+      #   server-function name is being overridden.
+      # @param as [Symbol, String] the JS identifier to emit instead of the
+      #   derived one.
+      # @raise [Ruact::ConfigurationError] when +as+ is not a valid JS identifier
+      #   or collides with a reserved word / a name the runtime already binds.
+      def ruact_function_name(action, as:)
+        js = as.to_s
+        unless js.match?(RUACT_VALID_JS_IDENTIFIER)
+          raise Ruact::ConfigurationError,
+                "ruact_function_name :#{action}, as: #{as.inspect} — " \
+                "\"#{js}\" is not a valid JS identifier (must match #{RUACT_VALID_JS_IDENTIFIER.inspect})"
+        end
+        if Ruact::ServerFunctions::NameBridge::RESERVED_JS_IDENTIFIERS.include?(js) ||
+           Ruact::ServerFunctions::NameBridge::RESERVED_BY_RUACT.include?(js)
+          raise Ruact::ConfigurationError,
+                "ruact_function_name :#{action}, as: #{as.inspect} — " \
+                "\"#{js}\" is a reserved JS word or is already bound by the ruact runtime " \
+                "(`_makeRef` / `_makeServerFunction` / `revalidate`); pick another name"
+        end
+
+        __ruact_function_name_overrides[action.to_s] = js
+      end
+
+      # The action-name → js-identifier override map for this controller,
+      # consulted by {Ruact::ServerFunctions::RouteSource}. Per-controller (not
+      # inherited) — overrides describe the host's own actions.
+      #
+      # @return [Hash{String=>String}]
+      def __ruact_function_name_overrides
+        @__ruact_function_name_overrides ||= {}
+      end
+    end
+
+    # Story 9.2 AC2/AC4 (D1) — Bucket-2 success-path negotiation. When the
+    # action finished without an explicit render on a function-call request
+    # ({#__ruact_function_call?} — `Accept: application/json`, non-GET), serialize
+    # the action's exposed instance variables (Rails `view_assigns`, verbatim —
+    # the same set a view would see) as a JSON object keyed by ivar name, or
+    # `204 No Content` when none were set. Any other request shape falls through
+    # to `super` so Bucket-1 rendering — the host's `Ruact::Controller` Flight
+    # re-render, then Rails — is byte-for-byte unchanged (AC1).
+    #
+    # The exposed-ivar set is Rails' own `view_assigns` with no custom filtering:
+    # Rails already excludes its protected `@_`-prefixed internals (including the
+    # CSRF `@_marked_for_same_origin_verification` flag), so what remains is
+    # exactly what the action assigned. Each value is serialized through the
+    # `ruact_props` / `Ruact::Serializable` / `strict_serialization` rules
+    # ({Ruact::ServerFunctions::BucketTwoPayload}); a single ivar stays keyed
+    # (no magic unwrap).
+    def default_render(*)
+      return super unless __ruact_function_call?
+
+      assigns = view_assigns
+      return head(:no_content) if assigns.empty?
+
+      render json: ServerFunctions::BucketTwoPayload.build(
+        assigns, strict: Ruact.config.strict_serialization
+      )
+    end
+
+    # Story 9.2 AC3 (D2) — on a function-call request, `redirect_to` surfaces as
+    # a JSON redirect directive — body `"$redirect" => "<path>"` (the runtime
+    # follows it client-side; re-targeting/following is Story 9.3) instead of a
+    # 302 or a Flight redirect row. Any other request shape falls through to
+    # `super` so the Bucket-1 Flight redirect row / Rails 302 is unchanged (AC1).
+    #
+    # Review round 1 — reuses Rails' OWN redirect machinery
+    # (`_compute_redirect_to_location`, `_ensure_url_is_http_header_safe`,
+    # `_enforce_open_redirect_protection`) so the nil-check, header-safety, and
+    # open-redirect protection (`allow_other_host` / `raise_on_open_redirects`)
+    # match Bucket 1 / stock Rails exactly — a cross-host `redirect_to` raises
+    # `UnsafeRedirectError` instead of leaking an external `$redirect`. Same-
+    # origin targets collapse to a path; an allowed external origin keeps the
+    # absolute URL.
+    def redirect_to(options = {}, response_options = {})
+      return super unless __ruact_function_call?
+
+      raise ActionController::ActionControllerError, "Cannot redirect to nil!" unless options
+      raise AbstractController::DoubleRenderError if response_body
+
+      allow_other_host = response_options.delete(:allow_other_host)
+      location = _compute_redirect_to_location(request, options)
+      _ensure_url_is_http_header_safe(location)
+      location = _enforce_open_redirect_protection(location, allow_other_host: allow_other_host)
+
+      render json: { "$redirect" => __ruact_redirect_path(location) }
+    end
+
+    private
+
+    # AC6 — append `Accept` to the `Vary` response header for non-GET requests
+    # (idempotent, preserves any host-set `Vary`). A host `Vary: *` wildcard is
+    # left as-is (review round 2): per HTTP, `Vary` is either `*` (varies on
+    # everything) OR a field-name list — `*, Accept` is invalid/weaker.
+    def __ruact_set_vary_on_accept!
+      return if request.get? || request.head?
+
+      values = response.headers["Vary"].to_s.split(",").map(&:strip).reject(&:empty?)
+      return if values.include?("*")
+
+      values << "Accept" unless values.any? { |value| value.casecmp?("Accept") }
+      response.headers["Vary"] = values.join(", ")
+    end
+
+    # Collapse a (already open-redirect-validated) location to a path for
+    # same-origin URLs (the common `redirect_to @record` case); keep the
+    # absolute URL for an allowed external origin so a cross-origin redirect
+    # (e.g. a payment provider, with `allow_other_host: true`) survives. Mirrors
+    # the same-origin handling in {Ruact::Controller#redirect_to}.
+    def __ruact_redirect_path(url)
+      uri = ::URI.parse(url)
+      if uri.host &&
+         (uri.host != request.host ||
+          (uri.port && uri.port != request.port) ||
+          (uri.scheme && uri.scheme != request.scheme))
+        return url
+      end
+
+      path = uri.path.nil? || uri.path.empty? ? "/" : uri.path
+      path += "?#{uri.query}" if uri.query
+      path += "##{uri.fragment}" if uri.fragment
+      path
+    rescue ::URI::InvalidURIError
+      url
+    end
+
+    # Raw discriminator — does the request's `Accept` header equal
+    # `application/json`? This is exactly what the 8.1 runtime sends on every
+    # `_makeRef` fetch (Bucket 2 — imperative `await createPost(...)`).
+    # Browser navigation and `<form>` submits never use that exact header, and
+    # Flight requests send `text/x-component`.
+    #
+    # Deliberately NOT `request.format`: the Rails format negotiation is
+    # influenced by path extensions (`/posts.json`) and `params[:format]`,
+    # neither of which may flip the bucket. This is the verb-AGNOSTIC header
+    # check; the semantic predicate {#__ruact_function_call?} layers the verb
+    # rule on top.
+    def __ruact_json_accept?
+      request.headers["Accept"] == "application/json"
+    end
+
+    # Story 9.1 AC2 — THE discrimination point: "is this request a function
+    # call?". A function call is a JSON-Accept request that is ALSO non-GET/
+    # HEAD: function calls are non-GET by the verb rule (epic contract
+    # decision #1), so a GET/HEAD carrying `Accept: application/json` (a
+    # `fetch()` against a page action, an API probe) is NOT one.
+    #
+    # Review patch (2026-06-08) — the verb gate that used to live only in
+    # {#__ruact_render_structured_error?} now lives HERE, in the predicate
+    # itself, so Story 9.2 reuses the CORRECT contract verbatim as the
+    # dual-bucket discriminator (the raw header check is {#__ruact_json_accept?}).
+    # The predicate lives in one place only.
+    def __ruact_function_call?
+      __ruact_json_accept? && !(request.get? || request.head?)
+    end
+
+    # D1 (amended by the 2026-06-07 / 2026-06-08 review patches) — render the
+    # structured payload only for NON-GET/HEAD requests; within those, for a
+    # function call ({#__ruact_function_call?}) or any
+    # `Ruact::UploadTooLargeError`. Everything else re-raises so
+    # non-function-call requests keep Rails' default error behavior (AC1
+    # byte-for-byte).
+    #
+    # The verb gate is the FIRST thing checked so it covers the
+    # `UploadTooLargeError` branch too (2026-06-08 patch): the guard never
+    # produces that error on a GET/HEAD (it skips those — D2), so the only way
+    # one reaches this handler on a GET is a manual `raise` inside a page
+    # action — which must keep stock Rails behavior, not be swallowed into a
+    # structured 413. For the non-GET case the documented exception still
+    # holds: a `UploadTooLargeError` from a native multipart form submit
+    # (Bucket 1, no JSON Accept) renders a meaningful 413 rather than a
+    # re-raised 500.
+    # Review patch (2026-06-08, round 3) — `Ruact::ConfigurationError` is never
+    # rendered as a structured server-action error: configuration invariants
+    # (most notably the upload-guard ordering check) must stay LOUD setup
+    # failures. Folding one into an ordinary `_ruact_server_action_error` 500
+    # on a JSON function call would disguise a deploy-blocking misconfiguration
+    # as a transient runtime error. It re-raises so Rails' default error
+    # handling surfaces it.
+    def __ruact_render_structured_error?(error)
+      return false if request.get? || request.head?
+      return false if error.is_a?(Ruact::ConfigurationError)
+
+      error.is_a?(Ruact::UploadTooLargeError) || __ruact_function_call?
+    end
+
+    # D2 — the v1 endpoint was POST-only so the guard never saw GETs; on a
+    # host controller it must skip GET/HEAD so page actions stay
+    # byte-for-byte untouched (AC1) while every non-GET action — both
+    # buckets — is protected (AC4 says "non-GET action", not "function
+    # call": native multipart form submits are exactly where uploads come
+    # from).
+    def __ruact_upload_guard_applicable?
+      !(request.get? || request.head?)
+    end
+  end
+end

data/lib/ruact/server_action.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Story 8.3 — host module for STANDALONE server actions. The Ruby
+  # equivalent of React's `"use server"` directive: a module under
+  # `app/server_actions/` that `extend`s {Ruact::ServerAction} and declares
+  # one action body per file with the `ruact_action` macro.
+  #
+  #   # app/server_actions/create_post.rb
+  #   module CreatePost
+  #     extend Ruact::ServerAction
+  #
+  #     ruact_action :create_post do |params|
+  #       Post.create!(title: params[:title], body: params[:body])
+  #     end
+  #   end
+  #
+  # The React side cannot tell standalone-hosted actions apart from
+  # controller-hosted ones — both export under the same accessor at
+  # `app/javascript/.ruact/server-functions.ts` (Story 8.0a codegen).
+  #
+  # Differences from {Ruact::Controller#ruact_action} (the controller-hosted
+  # path from Story 8.1):
+  #
+  #   - NO instance method is defined on the host module. There is no
+  #     `host.public_send(action_name)` call shape — the dispatcher
+  #     ({Ruact::ServerFunctions::EndpointController}) detects the standalone
+  #     host shape and routes through {Ruact::ServerFunctions::StandaloneDispatcher}
+  #     instead of `host_class.dispatch`. Standalone modules are reachable
+  #     ONLY through the gem's `POST /__ruact/fn/:name` endpoint; there is
+  #     no public Ruby surface to invoke them, by design.
+  #   - NO controller `before_action` chain runs. The dev opts out of the
+  #     controller-DSL ergonomic by picking the standalone path; the
+  #     trade-off is no implicit auth/scoping. The dev calls `current_user`
+  #     (resolved via {Ruact::Configuration#current_user_resolver}) and
+  #     Pundit / ActionPolicy directly inside the block when needed.
+  #   - NO `method_added` hook, NO `Thread.current[:__ruact_dispatching]`
+  #     sentinel. The standalone path has no routing surface that could
+  #     reach the action body outside of the gem-managed endpoint, so the
+  #     controller-only security guards are unnecessary (and would be
+  #     misleading — the block is stored in the registry, not on the
+  #     module as an instance method).
+  #
+  # Shared with {Ruact::Controller#ruact_action}:
+  #
+  #   - {Ruact::ServerFunctions::Registry} via `Ruact.action_registry`.
+  #     Symbols declared by standalone modules and by controller hosts live
+  #     in the same registry instance; the existing collision detector
+  #     ({Ruact::ServerFunctions::Registry#detect_collision!}) catches
+  #     same-symbol-different-host collisions across both host shapes.
+  #   - The naming-bridge rule ({Ruact::ServerFunctions::NameBridge}) and
+  #     reserved-identifier sets (`RESERVED_JS_IDENTIFIERS`,
+  #     `RESERVED_BY_RUACT`).
+  #   - The block-parameter shape guard (one positional argument, no
+  #     required keyword arguments) — same regex as Story 8.1 Re-run-5.
+  module ServerAction
+    # @param symbol [Symbol] the action name; same naming-bridge rule as
+    #   {Ruact::Controller#ruact_action}.
+    # @yield [params] the block runs via `instance_exec` on a fresh
+    #   {Ruact::ServerFunctions::StandaloneContext} at dispatch time.
+    # @return [Ruact::ServerFunctions::RegistryEntry] the entry just registered.
+    # @raise [ArgumentError] when +symbol+ is not a Symbol, the block is
+    #   missing, or the block's parameter shape is rejected.
+    # @raise [Ruact::ConfigurationError] when the symbol fails the
+    #   naming-bridge rule or collides with another `ruact_action` in the
+    #   registry (mixed-host collisions are caught here too — see AC4).
+    def ruact_action(symbol, &block)
+      # Story 8.3 review R4 — reject Class hosts loudly. `extend Ruact::ServerAction`
+      # on a Class would work at extend time (Class < Module), but the
+      # endpoint dispatcher's `standalone_host?` predicate returns false for
+      # Class hosts (it requires Module-NOT-Class), and the controller-DSL
+      # branch would then try `host_class.dispatch(...)` against a class
+      # that has NO Rails dispatch surface — crashing at request time.
+      # Catch this at declaration time so the failure is visible at boot.
+      if is_a?(Class)
+        raise Ruact::ConfigurationError,
+              "Ruact::ServerAction is intended for standalone HOST MODULES under " \
+              "`app/server_actions/`. You extended it onto #{name || self} which " \
+              "is a Class — that's a controller-shape host. For controller-hosted " \
+              "actions use `include Ruact::Controller` and declare `ruact_action` " \
+              "inside the controller class body; for standalone actions declare a " \
+              "`module Foo; extend Ruact::ServerAction; ...; end` instead."
+      end
+
+      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} (standalone) requires a block — declare the " \
+              "implementation with `ruact_action :#{symbol} do |params| ... end`"
+      end
+
+      # Mirror the block-parameter shape guard from Story 8.1 Re-run-5
+      # (controller.rb:125-137). The standalone dispatcher invokes the
+      # block with one positional argument (the params shadow); blocks
+      # with wrong arity / required kwargs would crash at dispatch time.
+      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} (standalone) 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
+
+      # NOTE: no `FRAMEWORK_RESERVED_METHODS` check — standalone modules
+      # have no ActionController surface to clobber. NameBridge +
+      # RESERVED_JS_IDENTIFIERS + RESERVED_BY_RUACT still fire via the
+      # registry's `register` path below.
+      #
+      # NOTE: no `own_methods` / inherited-helper guard — there is no
+      # `define_method` step that could shadow anything; the block lives
+      # in the registry, not on the module.
+      #
+      # NOTE: no `method_added` hook — standalone modules don't define
+      # instance methods at all, so a same-name `def` cannot shadow
+      # anything (Pitfall #2 in the story spec).
+      Ruact.action_registry.register(symbol, kind: :action, controller: self, &block)
+    end
+  end
+end

data/lib/ruact/server_functions/backtrace_cleaner.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Ruact
+  module ServerFunctions
+    # Story 8.4 — Splits an exception backtrace into application frames and
+    # gem-internal frames so the dev overlay can hide gem frames behind a
+    # toggle by default while still capturing them for the "Copy to clipboard"
+    # affordance.
+    #
+    # Pure function, no I/O. Anchors classification on {Ruact.gem_path} which
+    # is memoised at gem load time; the per-frame `start_with?` check is
+    # therefore constant-time.
+    #
+    # Deliberately NOT a thin wrapper over `ActiveSupport::BacktraceCleaner` —
+    # that class's silencer/filter API is heavyweight for this single-purpose
+    # need; this module is ~10 LoC with zero ActiveSupport dependency so it
+    # loads cleanly in AR-less specs (see Pitfall #4 in the story).
+    module BacktraceCleaner
+      # Split a raw backtrace into app and gem buckets.
+      #
+      # @param backtrace [Array<String>, nil] frames from `Exception#backtrace`
+      # @return [Hash{Symbol=>Array<String>}] `{ app: [...], gem: [...] }`
+      def self.split(backtrace)
+        return { app: [], gem: [] } if backtrace.nil? || backtrace.empty?
+
+        gem_prefix = Ruact.gem_path
+        gem_frames, app_frames = backtrace.partition { |frame| frame.start_with?(gem_prefix) }
+        { app: app_frames, gem: gem_frames }
+      end
+    end
+  end
+end