ruact 0.0.1 → 0.0.3

data/lib/ruact/railtie.rb

@@ -6,10 +6,73 @@ module Ruact
   class Railtie < Rails::Railtie
     initializer "ruact.load_controller" do
       require_relative "controller"
+      # Story 9.1 — the v2 route-driven marker concern (`include Ruact::Server`).
+      require_relative "server"
+      require_relative "server_action"
+      # Story 9.4 (D8) — requiring ruact/routing installs the `ruact_queries`
+      # macro into ActionDispatch::Routing::Mapper (a Mapper extension, NOT a
+      # mounted route — the host's routes.rb explicitly mounts each query
+      # class). Initializers all run before the routes file is loaded, so the
+      # macro is in place for the first draw.
+      require_relative "routing"
     end
 
-    rake_tasks do
-      load File.expand_path("../tasks/rsc.rake", __dir__)
+    # Story 8.3 — register `app/server_actions/` as a Rails `paths` entry
+    # AND as an autoload + eager-load path so Zeitwerk discovers standalone
+    # `Ruact::ServerAction` modules the same way it discovers
+    # controllers/models/jobs. Registering via `config.paths.add` (vs.
+    # `config.autoload_paths <<` only) is what makes
+    # `Rails.application.config.paths["app/server_actions"].existent`
+    # work — that path enumerator is what
+    # {.server_actions_paths_for} consumes during force-load.
+    initializer "ruact.register_server_actions_path", before: :set_autoload_paths do |app|
+      app.config.paths.add "app/server_actions", with: "app/server_actions"
+      candidate = app.root.join("app/server_actions")
+      if candidate.directory?
+        app.config.autoload_paths   << candidate.to_s
+        app.config.eager_load_paths << candidate.to_s
+      end
+    end
+
+    rake_tasks { load File.expand_path("../tasks/ruact.rake", __dir__) }
+
+    # Story 8.1 — clear the action/query registries on every code reload so
+    # removed `ruact_action` declarations don't linger in the registry. We hook
+    # `before_class_unload` (BEFORE Zeitwerk tears down constants) rather than
+    # `to_prepare` (AFTER reload): controller class bodies re-evaluate during
+    # the reload itself, and clearing in `to_prepare` would wipe their fresh
+    # registrations.
+    #
+    # First-boot is naturally safe — registries start empty, so there's nothing
+    # to clear; the very first controller class-body evaluation populates them.
+    # In production this hook never fires (no reloads), which is correct.
+    initializer "ruact.attach_registry_clear_hook" do |app|
+      app.reloader.before_class_unload do
+        Ruact.action_registry.clear!
+        Ruact.query_registry.clear!
+      end
+    end
+
+    # Story 8.1 — mount the single gem-managed endpoint that dispatches all
+    # `ruact_action` calls. The route is `POST /__ruact/fn/:name`; the
+    # controller resolves `:name` against `Ruact.action_registry` (and, once
+    # Story 9.1 lands, `Ruact.query_registry`) and delegates execution to the
+    # entry's host controller class via Rails' normal `dispatch` flow.
+    #
+    # Story 8.1 Re-run-2 (2026-05-14) — `routes.prepend` (not `.append`) so
+    # the gem's reserved `/__ruact/fn/:name` endpoint wins ahead of any host
+    # catch-all (e.g. `match "*path", to: "errors#not_found"` or a wildcard
+    # POST handler) that would otherwise swallow every server-function call
+    # before Ruact saw it. The `/__ruact/fn/` URL prefix is the gem's
+    # documented reserved namespace; hosts that route under `/__ruact/` are
+    # using the same prefix at their own risk.
+    initializer "ruact.mount_server_functions_route" do |app|
+      app.routes.prepend do
+        post "/__ruact/fn/:name",
+             to: "ruact/server_functions/endpoint#dispatch_action",
+             as: :ruact_server_function,
+             constraints: { name: /[a-zA-Z_][a-zA-Z0-9_]*/ }
+      end
     end
 
     # Load the client manifest at boot (and on each code reload in development).
@@ -22,7 +85,7 @@ module Ruact
     # - production:  raises ManifestError; app does not start
     #
     # Also registers ActionView integration:
-    # - ViewHelper provides __rsc_component__ in every view context
+    # - ViewHelper provides __ruact_component__ in every view context
     # - ErbPreprocessorHook applies the RSC preprocessor to all ERB templates
     #   (layouts, views, partials) transparently via prepend.
     config.to_prepare do
@@ -40,6 +103,26 @@ module Ruact
       require_relative "erb_preprocessor_hook"
       ActionView::Base.include(Ruact::ViewHelper)
       ActionView::Template::Handlers::ERB.prepend(Ruact::ErbPreprocessorHook)
+
+      # Story 8.1 review-batch 3 (2026-05-14) — force-load all controller
+      # files BEFORE writing the snapshot so the registry sees every
+      # `ruact_action` declaration. Without this, lazy autoload (Rails dev's
+      # default for `eager_load = false`) means a controller that hasn't
+      # been requested yet isn't loaded, so its `ruact_action` calls don't
+      # populate the registry — the codegen would then emit a stale TS
+      # module missing those exports until the controller is hit at least
+      # once. The endpoint controller would also 404 those names.
+      #
+      # Story 8.3 — the force-loader was renamed from
+      # `force_load_controllers!` to `force_load_server_function_hosts!`
+      # and now walks BOTH `app/controllers/**/*_controller.rb` and
+      # `app/server_actions/**/*.rb` so standalone modules also register
+      # at boot. The old method name is kept as an alias for back-compat
+      # with anything outside the gem calling it.
+      Ruact::Railtie.force_load_server_function_hosts!
+
+      Ruact::Railtie.write_server_functions_snapshot!
+      Ruact::ServerFunctions.write_v2_snapshot!(route_set: Rails.application.routes, root: Rails.root)
     end
 
     # Detect streaming capability at boot and log the active mode (AC#1–3).
@@ -83,6 +166,140 @@ module Ruact
                         "— run npm run dev for HMR"
     end
 
+    # Story 8.1 review-batch 3 (2026-05-14) — force-loads every controller
+    # file under `Rails.application.config.paths["app/controllers"]` so the
+    # `ruact_action` registrations populate the registry on a clean boot.
+    #
+    # Without this, Rails' dev-mode lazy autoload only loads a controller
+    # when it's first referenced (typically the first request that routes
+    # to it). That means the codegen snapshot in `to_prepare` would miss
+    # any controller not yet touched.
+    #
+    # Implementation: glob the `app/controllers` directories listed in the
+    # Rails paths configuration and `require_dependency` each
+    # `*_controller.rb` file. `require_dependency` works in both Zeitwerk
+    # (Rails 7+) and the classic autoloader. On Zeitwerk it is implemented
+    # as `Rails.autoloaders.main.load_file(path)` under the hood.
+    #
+    # Errors are surfaced as `Ruact::Error` with a controller hint so the
+    # developer sees a meaningful boot failure instead of a silent skip.
+    #
+    # Re-run-6 (2026-05-15) — also walks every mounted `Rails::Engine`
+    # (and `Rails::Railtie` with `paths["app/controllers"]`) so engine-
+    # owned controllers that declare `ruact_action` populate the registry
+    # at boot. Without this an engine's `ruact_action` declarations would
+    # only register on first request that touches the engine controller —
+    # codegen + endpoint dispatch would lag behind boot.
+    #
+    # @return [Integer] number of controller files loaded.
+    def self.force_load_server_function_hosts!
+      loaded = 0
+
+      controller_paths_for(Rails.application).each do |dir|
+        loaded += force_load_dir(dir, glob: "**/*_controller.rb")
+      end
+      server_actions_paths_for(Rails.application).each do |dir|
+        loaded += force_load_dir(dir, glob: "**/*.rb")
+      end
+
+      if defined?(Rails::Engine)
+        Rails::Engine.subclasses.each do |engine_class|
+          # Skip the host app itself; `Rails.application.class` is a
+          # `Rails::Engine` subclass and was already covered above.
+          next if engine_class == Rails.application.class
+
+          engine = safe_engine_instance(engine_class)
+          next unless engine
+
+          controller_paths_for(engine).each { |dir| loaded += force_load_dir(dir, glob: "**/*_controller.rb") }
+          server_actions_paths_for(engine).each { |dir| loaded += force_load_dir(dir, glob: "**/*.rb") }
+        end
+      end
+
+      loaded
+    rescue LoadError, NameError => e
+      raise Ruact::Error,
+            "ruact: failed to force-load a server-function host while populating " \
+            "Ruact.action_registry: #{e.class}: #{e.message}. The gem " \
+            "force-loads `app/controllers/**/*_controller.rb` and " \
+            "`app/server_actions/**/*.rb` at `config.to_prepare` so " \
+            "registries are complete on first boot."
+    end
+
+    # Story 8.3 — back-compat alias. Older code paths (rake tasks shipped
+    # in previous gem versions, downstream tooling) may call the old
+    # name; the new name describes the wider behavior accurately.
+    class << self
+      alias force_load_controllers! force_load_server_function_hosts!
+    end
+
+    # @param engine [Rails::Engine] either `Rails.application` or a mounted engine
+    # @return [Array<String>] existing controller directory paths
+    def self.controller_paths_for(engine)
+      return [] unless engine.respond_to?(:config) && engine.config.respond_to?(:paths)
+
+      paths = engine.config.paths["app/controllers"]
+      return [] unless paths.respond_to?(:existent)
+
+      paths.existent
+    end
+
+    # @param dir [String]
+    # @param glob [String] glob pattern relative to +dir+; defaults to
+    #   `**/*_controller.rb` for back-compat with pre-Story-8.3 callers.
+    # @return [Integer] number of files loaded
+    def self.force_load_dir(dir, glob: "**/*_controller.rb")
+      Dir.glob("#{dir}/#{glob}").each do |file|
+        require_dependency(file)
+      end.length
+    end
+
+    # Story 8.3 — locates `app/server_actions/` for the host application
+    # or a mounted engine. Uses the Rails `paths` enumerator (populated by
+    # the Railtie initializer) when present, falling back to a direct
+    # `engine.root.join` lookup for engines that haven't registered the
+    # path. Returns an empty array when the directory doesn't exist —
+    # silent no-op for hosts that don't use standalone actions.
+    def self.server_actions_paths_for(engine)
+      if engine.respond_to?(:config) && engine.config.respond_to?(:paths)
+        paths = engine.config.paths["app/server_actions"]
+        if paths.respond_to?(:existent)
+          existent = paths.existent
+          return existent unless existent.empty?
+        end
+      end
+
+      return [] unless engine.respond_to?(:root) && engine.root
+
+      candidate = engine.root.join("app/server_actions")
+      candidate.directory? ? [candidate.to_s] : []
+    end
+
+    # Some engine subclasses are abstract (no `.instance` defined yet) or fail
+    # at `.instance` if their config block raises. Swallow those quietly —
+    # the gem's responsibility is to load whatever it can; engines whose
+    # `.instance` blows up will surface on first request anyway.
+    def self.safe_engine_instance(engine_class)
+      engine_class.instance
+    rescue StandardError
+      nil
+    end
+
+    # Writes the server-functions JSON snapshot to tmp/cache/ruact/ on every
+    # config.to_prepare. The write is short-circuited when the registry payload
+    # is unchanged (Story 8.0a — pitfall #1: dev mode fires to_prepare per
+    # request; a naive rewrite would burn IOPS and confuse the Vite plugin's
+    # chokidar watcher).
+    #
+    # @return [Boolean] true if a fresh file was written, false if unchanged.
+    def self.write_server_functions_snapshot!
+      Ruact::ServerFunctions::Snapshot.generate!(
+        action_registry: Ruact.action_registry,
+        query_registry: Ruact.query_registry,
+        path: Rails.root.join("tmp/cache/ruact/server-functions.json")
+      )
+    end
+
     # Checks whether the manifest exists and either warns (dev) or raises (prod).
     # Extracted as a class method for direct testability without a full Rails app.
     def self.check_manifest!(manifest_path)

data/lib/ruact/render_context.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Per-render mutable state holding the components encountered during ERB
+  # evaluation. One instance is allocated by the controller per render, passed
+  # explicitly through the pipeline, and discarded when the response is sent.
+  #
+  # No shared state, no thread-local lookup — the instance lives only as long
+  # as the render call. Satisfies NFR8 and the `Ruact/NoSharedState` cop with
+  # zero exceptions in `lib/`.
+  #
+  # Internal API: not part of the public compatibility contract.
+  class RenderContext
+    def initialize
+      @components = []
+    end
+
+    attr_reader :components
+
+    def register(name, props)
+      token = "__RUACT_#{@components.length}__"
+      @components << { token: token, name: name, props: props }
+      token
+    end
+
+    def by_token(token)
+      @components.find { |c| c[:token] == token }
+    end
+  end
+end

data/lib/ruact/render_pipeline.rb

@@ -3,47 +3,204 @@
 require "erb"
 
 module Ruact
-  # Orchestrates the full server component render:
+  # Internal — orchestrates the full server component render:
   #   ERB source → (preprocessor) → evaluated HTML → (HtmlConverter) → ReactElement tree
   #                                                                    → (Flight::Renderer) → wire bytes
   #
-  # Two entry points:
-  #   call/stream — full pipeline from ERB source (used in unit tests and legacy path)
-  #   from_html   — takes pre-rendered HTML from ActionView (used by Controller#rsc_render)
+  # External code should use `Ruact::Controller#ruact_render` instead. `Ruact::RenderPipeline`
+  # (and the rest of `Ruact::Flight::*` / `Ruact::Internal::*`) are not part of the public API
+  # and may change between minor versions.
+  #
+  # Single entry point: {#render}.
   class RenderPipeline
+    VALID_MODES = %i[string stream].freeze
+
     def initialize(manifest, controller_path: nil, logger: nil)
       @manifest         = manifest
       @controller_path  = controller_path
       @logger           = logger
     end
 
-    # Render ERB source within a given binding, return Flight wire format string.
-    # Deferred chunk delays are skipped — suitable for buffered responses (HTML shell).
-    def call(erb_source, binding_context)
-      _stream(erb_source, binding_context, streaming: false).to_a.join
+    # Render a server component tree to Flight wire format.
+    #
+    # **Internal API.** External code should call `Ruact::Controller#ruact_render` instead.
+    # `Ruact::RenderPipeline` is not part of the public API and may change between minor
+    # versions without deprecation. Reach into it only when extending the gem itself.
+    #
+    # @param input [Hash] selects the input shape — exactly one of:
+    #   - `{ erb: String, binding: Binding }` — render an ERB template within the given binding.
+    #     Both keys required; `:erb` must be a `String`, `:binding` must be a `Binding`.
+    #   - `{ html: String, render_context: Ruact::RenderContext }` — convert pre-rendered HTML
+    #     (from ActionView) using a render context populated during ERB evaluation.
+    #     Both keys required; `:html` must be a `String`, `:render_context` must be a
+    #     `Ruact::RenderContext`.
+    #   Extra keys beyond the two-key shapes above are rejected with `ArgumentError`.
+    # @param mode [Symbol] one of:
+    #   - `:string` — returns the full serialized `String`. Deferred chunks are inlined
+    #     eagerly (no Suspense delay). Suitable for buffered HTTP responses.
+    #   - `:stream` — returns an `Enumerator` that yields Flight rows one at a time.
+    #     Deferred chunks delay. Suitable for `ActionController::Live` streaming.
+    # @return [String, Enumerator] depending on `mode`.
+    # @raise [ArgumentError] when:
+    #   - `input` is not a `Hash`,
+    #   - `input` mixes `:erb` and `:html` keys,
+    #   - `input` omits both `:erb` and `:html`,
+    #   - the required sibling key is missing or has the wrong type
+    #     (`:binding` must be a `Binding`; `:render_context` must be a `Ruact::RenderContext`),
+    #   - `:erb` or `:html` is not a `String`,
+    #   - `input` contains extra keys beyond the documented shapes,
+    #   - `mode` is not in {VALID_MODES}.
+    #   All `ArgumentError` messages name the offending input and reference
+    #   `RenderPipeline#render` for the canonical contract.
+    #
+    # @example ERB source, buffered output
+    #   pipeline.render({ erb: "<NavBar />", binding: ctx.instance_eval { binding } }, mode: :string)
+    #   # => "0:[\"$\",\"div\",null,...]\n"
+    #
+    # @example Pre-rendered HTML, streaming output
+    #   ctx = Ruact::RenderContext.new
+    #   pipeline.render({ html: "<!-- __RUACT_0__ -->", render_context: ctx }, mode: :stream)
+    #   # => #<Enumerator: ...>  (yields Flight rows lazily)
+    def render(input, mode: :string)
+      validate_mode!(mode)
+      enum = build_enum(input, streaming: mode == :stream)
+      mode == :string ? enum.to_a.join : enum
     end
 
-    # Render ERB source and return an Enumerator that yields Flight rows one at a time.
-    # Deferred chunk delays ARE applied — suitable for ActionController::Live streaming.
-    def stream(erb_source, binding_context)
-      _stream(erb_source, binding_context, streaming: true)
+    private
+
+    ALLOWED_INPUT_KEYS = %i[erb binding html render_context].freeze
+    private_constant :ALLOWED_INPUT_KEYS
+
+    DOCSTRING_REF = "see RenderPipeline#render docstring for the canonical contract"
+    private_constant :DOCSTRING_REF
+
+    def validate_mode!(mode)
+      return if VALID_MODES.include?(mode)
+
+      raise ArgumentError,
+            "ruact: unknown render mode #{mode.inspect}; expected one of #{VALID_MODES.inspect} " \
+            "(#{DOCSTRING_REF})"
     end
 
-    # Convert pre-rendered HTML (from ActionView) to Flight wire rows.
-    #
-    # IMPORTANT — Eager registry capture: ComponentRegistry.components is read
-    # immediately when this method is called, before the Enumerator is returned.
-    # This allows the caller to call ComponentRegistry.reset right after from_html
-    # returns (inside an ensure block) without affecting the captured registry.
+    def build_enum(input, streaming:)
+      unless input.is_a?(Hash)
+        raise ArgumentError,
+              "ruact: render input must be a Hash; got #{input.class} (#{DOCSTRING_REF})"
+      end
+
+      extra = input.keys - ALLOWED_INPUT_KEYS
+      unless extra.empty?
+        raise ArgumentError,
+              "ruact: render input contains unsupported keys: #{extra.inspect}; " \
+              "expected only #{ALLOWED_INPUT_KEYS.inspect} (#{DOCSTRING_REF})"
+      end
+
+      has_erb  = input.key?(:erb)
+      has_html = input.key?(:html)
+
+      if has_erb && has_html
+        raise ArgumentError,
+              "ruact: render input cannot mix :erb and :html keys (got both); choose one source shape " \
+              "(#{DOCSTRING_REF})"
+      end
+
+      unless has_erb || has_html
+        raise ArgumentError,
+              "ruact: render input must include either :erb (with sibling :binding) " \
+              "or :html (with sibling :render_context) (#{DOCSTRING_REF})"
+      end
+
+      if has_erb
+        validate_erb_shape!(input)
+        render_erb_enum(input[:erb], input[:binding], streaming: streaming)
+      else
+        validate_html_shape!(input)
+        render_html_enum(input[:html], input[:render_context], streaming: streaming)
+      end
+    end
+
+    def validate_erb_shape!(input)
+      erb = input[:erb]
+      unless erb.is_a?(String)
+        raise ArgumentError,
+              "ruact: render input :erb must be a String; got #{erb.class} (#{DOCSTRING_REF})"
+      end
+      unless input.key?(:binding)
+        raise ArgumentError,
+              "ruact: render input { erb: ... } requires sibling :binding (Binding) (#{DOCSTRING_REF})"
+      end
+      bnd = input[:binding]
+      return if bnd.is_a?(Binding)
+
+      raise ArgumentError,
+            "ruact: render input :binding must be a Binding; got #{bnd.class} (#{DOCSTRING_REF})"
+    end
+
+    def validate_html_shape!(input)
+      html = input[:html]
+      unless html.is_a?(String)
+        raise ArgumentError,
+              "ruact: render input :html must be a String; got #{html.class} (#{DOCSTRING_REF})"
+      end
+      unless input.key?(:render_context)
+        raise ArgumentError,
+              "ruact: render input { html: ... } requires sibling :render_context " \
+              "(Ruact::RenderContext) (#{DOCSTRING_REF})"
+      end
+      ctx = input[:render_context]
+      return if ctx.is_a?(RenderContext)
+
+      raise ArgumentError,
+            "ruact: render input :render_context must be a Ruact::RenderContext; " \
+            "got #{ctx.class} (#{DOCSTRING_REF})"
+    end
+
+    # ERB-source path: evaluate ERB, collect components into a fresh RenderContext via
+    # injected `__ruact_component__` helper, then convert + serialize.
     #
-    # The returned Enumerator does NOT reference ComponentRegistry at all —
-    # only the eagerly-captured +registry+ local variable.
-    def from_html(html, streaming: false)
-      registry = ComponentRegistry.components.map do |entry|
+    # NB: `Ruact.config.strict_serialization` and the `as_json` warning callback are read
+    # inside the Enumerator block (consumption time), preserving the legacy `_stream`
+    # behavior — config changes between `#render` returning and the Enumerator being
+    # consumed are observable.
+    def render_erb_enum(erb_source, binding_context, streaming:)
+      Enumerator.new do |y|
+        render_context = RenderContext.new
+        transformed    = ErbPreprocessor.transform(erb_source)
+        receiver       = binding_context.eval("self")
+        prev_ctx       = receiver.instance_variable_get(:@__ruact_render_context__)
+        inject_helper!(binding_context, render_context)
+        html =
+          begin
+            ERB.new(transformed).result(binding_context)
+          ensure
+            receiver.instance_variable_set(:@__ruact_render_context__, prev_ctx)
+          end
+
+        registry = render_context.components.map do |entry|
+          ref = @manifest.reference_for(entry[:name], controller_path: @controller_path)
+          { token: entry[:token], name: entry[:name], ref: ref, props: entry[:props] }
+        end
+
+        root_element = HtmlConverter.convert(html, registry)
+
+        Flight::Renderer.each(root_element, @manifest,
+                              strict_serialization: Ruact.config.strict_serialization,
+                              on_as_json_warning: as_json_warning_callback,
+                              streaming: streaming) { |row| y << row }
+      end
+    end
+
+    # HTML path: input HTML is already rendered by ActionView; the supplied RenderContext
+    # holds the components encountered during ERB evaluation. Registry is captured eagerly so
+    # the caller may discard the RenderContext immediately after `render` returns — the
+    # returned Enumerator does not reference the RenderContext.
+    def render_html_enum(html, render_context, streaming:)
+      registry = render_context.components.map do |entry|
         ref = @manifest.reference_for(entry[:name], controller_path: @controller_path)
         { token: entry[:token], name: entry[:name], ref: ref, props: entry[:props] }
       end
-      strict = Ruact.config.strict_serialization
+      strict     = Ruact.config.strict_serialization
       warning_cb = as_json_warning_callback
 
       Enumerator.new do |y|
@@ -55,33 +212,6 @@ module Ruact
       end
     end
 
-    private
-
-    def _stream(erb_source, binding_context, streaming: false)
-      Enumerator.new do |y|
-        ComponentRegistry.start
-        begin
-          transformed = ErbPreprocessor.transform(erb_source)
-          inject_helper!(binding_context)
-          html = ERB.new(transformed).result(binding_context)
-
-          registry = ComponentRegistry.components.map do |entry|
-            ref = @manifest.reference_for(entry[:name], controller_path: @controller_path)
-            { token: entry[:token], name: entry[:name], ref: ref, props: entry[:props] }
-          end
-
-          root_element = HtmlConverter.convert(html, registry)
-
-          Flight::Renderer.each(root_element, @manifest,
-                                strict_serialization: Ruact.config.strict_serialization,
-                                on_as_json_warning: as_json_warning_callback,
-                                streaming: streaming) { |row| y << row }
-        ensure
-          ComponentRegistry.reset
-        end
-      end
-    end
-
     def as_json_warning_callback
       return nil if @logger.nil?
 
@@ -89,19 +219,31 @@ module Ruact
         @logger.warn(
           "[ruact] WARNING: #{class_name} serialized via as_json — " \
           "ALL attributes exposed to client: #{attrs}. " \
-          "Use `include Ruact::Serializable` with `rsc_props` for explicit control"
+          "Use `include Ruact::Serializable` with `ruact_props` for explicit control"
         )
       end
     end
 
-    # Define __rsc_component__ in the ERB binding so it can be called.
-    def inject_helper!(binding_context)
-      binding_context.eval(<<~RUBY)
-        def __rsc_component__(name, props = {})
-          token = ::Ruact::ComponentRegistry.register(name, props)
-          "<!-- \#{token} -->"
-        end
-      RUBY
+    # Install __ruact_component__ on the binding's receiver and stash the active
+    # render context on the receiver as @__ruact_render_context__. The singleton
+    # method reads the ivar dynamically, so nested renders sharing the same
+    # receiver (e.g., inner pipeline.render from inside ERB) see whatever context
+    # is current at invocation time — render_erb_enum wraps ERB evaluation in a
+    # save/restore block so the outer render's context is restored afterward.
+    # Defining the singleton method is idempotent — re-defining on a nested
+    # call would not change behaviour, but skipping it avoids needless work.
+    def inject_helper!(binding_context, render_context)
+      receiver = binding_context.eval("self")
+      receiver.instance_variable_set(:@__ruact_render_context__, render_context)
+      return if receiver.respond_to?(:__ruact_component__)
+
+      receiver.define_singleton_method(:__ruact_component__) do |name, props = {}|
+        ctx = instance_variable_get(:@__ruact_render_context__)
+        raise Ruact::Error, "ruact: __ruact_component__ called outside an active render context" if ctx.nil?
+
+        token = ctx.register(name, props)
+        "<!-- #{token} -->"
+      end
     end
   end
 end

data/lib/ruact/routing.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "action_dispatch"
+
+module Ruact
+  # Story 9.4 (D8) — the `ruact_queries` routing macro. Included into
+  # `ActionDispatch::Routing::Mapper` by the Railtie, so it is available
+  # inside `Rails.application.routes.draw`:
+  #
+  #   Rails.application.routes.draw do
+  #     ruact_queries CatalogQuery        # GET /q/categories, GET /q/searchUsers, …
+  #     resources :posts
+  #   end
+  #
+  # For each `public_instance_methods(false)` of the query class — methods
+  # inherited from `Ruact::Query` / `ApplicationQuery` or mixed in from user
+  # modules are NOT mounted (AC1) — one NAMED GET route is drawn at
+  # `GET <Ruact.config.query_route_prefix>/<jsIdentifier>` (default `/q`,
+  # contract decision #7), pointing at the query class's generated internal
+  # dispatch controller ({Ruact::ServerFunctions::QueryDispatch}). Every query
+  # is visible in `rails routes` — no hidden endpoint; the route table stays
+  # the single source of truth.
+  #
+  # The path segment reuses {Ruact::ServerFunctions::NameBridge} verbatim
+  # (D4): `def search_users` → `GET /q/searchUsers`, named
+  # `ruact_query_searchUsers`. Invalid or JS-reserved method names raise
+  # {Ruact::ConfigurationError} at route-draw time; two query classes mounting
+  # the same method name collide on the route NAME / path and fail Rails' own
+  # duplicate checks — both are loud boot failures, never request-time
+  # surprises.
+  #
+  # The generated dispatch controller PRESERVES the query class's namespace
+  # (review round 4) — `Admin::CatalogQuery` →
+  # `Ruact::ServerFunctions::QueryDispatch::Admin::CatalogQueryController` — so
+  # the controller constant is an injective function of the query class's
+  # fully-qualified name: two distinct query classes can never map to the same
+  # constant, and there is no flatten collision to detect (across any number
+  # of RouteSets / mounted engines sharing the global dispatch namespace).
+  module Routing
+    # Draws the named GET routes for one or more {Ruact::Query} subclasses.
+    #
+    # @param query_classes [Array<Class>] `Ruact::Query` subclasses to mount.
+    # @return [void]
+    def ruact_queries(*query_classes)
+      query_classes.each { |query_class| Ruact::Routing.draw_query_routes(self, query_class) }
+      nil
+    end
+
+    class << self
+      # @api private — the macro body, kept off the Mapper instance so the only
+      # method `ruact_queries` adds to the routing DSL surface is itself.
+      def draw_query_routes(mapper, query_class)
+        ServerFunctions::QueryDispatch.controller_for(query_class)
+        target = ServerFunctions::QueryDispatch.route_target_for(query_class)
+        prefix = Ruact.config.query_route_prefix
+
+        query_class.public_instance_methods(false).each do |query_method|
+          js_identifier = ServerFunctions::NameBridge.to_js_identifier(query_method)
+          mapper.get("#{prefix}/#{js_identifier}",
+                     to: "#{target}##{query_method}",
+                     as: :"ruact_query_#{js_identifier}")
+        end
+      end
+    end
+  end
+end
+
+# D8 — installed at require time (the Railtie requires this file from its
+# `ruact.load_controller` initializer; a direct `require "ruact/routing"`
+# in a non-Railtie context gets the same one-shot, idempotent install).
+# Written as a class reopening (rather than
+# `ActionDispatch::Routing::Mapper.include Ruact::Routing`) so YARD's static
+# MixinHandler resolves the named namespace instead of choking on the external
+# constant receiver under `--fail-on-warning`.
+module ActionDispatch # rubocop:disable Style/OneClassPerFile -- deliberate Mapper extension install (D8)
+  module Routing
+    class Mapper
+      include Ruact::Routing
+    end
+  end
+end