ruact 0.0.2 → 0.0.3

data/lib/ruact/server_functions/standalone_dispatcher.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ruact
+  module ServerFunctions
+    # Story 8.3 — execution path for STANDALONE server actions (host
+    # modules that `extend Ruact::ServerAction`). Invoked by
+    # {Ruact::ServerFunctions::EndpointController#dispatch_action} when
+    # the resolved registry entry's host is a Module rather than an
+    # `ActionController::Base` subclass.
+    #
+    # Differences from the controller-hosted path (Story 8.1):
+    #   - No `host_class.dispatch` — no Rails `process_action` callback
+    #     chain, no `before_action` filters, no `rescue_from` on the host.
+    #     The dispatcher is in charge of the entire response cycle.
+    #   - The block runs via `instance_exec` on a fresh
+    #     {Ruact::ServerFunctions::StandaloneContext}, not on a controller
+    #     instance. The context exposes `params` / `session` /
+    #     `current_user` / `request` / `cookies` / `headers`; it does NOT
+    #     expose `render` / `redirect_to` / `head` (the block's return
+    #     value IS the response).
+    #
+    # Same contract for response shape (parity with Story 8.1):
+    #   - `nil` block return                          → 204 No Content
+    #   - Hash / Array / scalar block return          → 200 + JSON body
+    #   - `raise Ruact::ActionError.new(status:, body:)` → that status + JSON body
+    class StandaloneDispatcher
+      # Plain value object returned by {.dispatch}. The caller — typically
+      # {EndpointController#dispatch_action} when running inside the Rails
+      # request cycle — applies these directives via `render` / `head` so
+      # Rails' `ImplicitRender` does not overwrite the response. In test
+      # / benchmark contexts the value can be applied to a bare response
+      # via {.apply_to_response}.
+      Result = Struct.new(:status, :body, :content_type)
+
+      class << self
+        # @param entry [Ruact::ServerFunctions::RegistryEntry]
+        # @param request [ActionDispatch::Request]
+        # @param response [ActionDispatch::Response, nil] when non-nil, the
+        #   dispatcher writes directives onto the response and marks it
+        #   committed. Tests typically pass nil and apply the Result manually.
+        # @return [Result] render directive describing the response.
+        def dispatch(entry, request, response = nil)
+          begin
+            raw_args = extract_args(request)
+          rescue JSON::ParserError => e
+            # Story 8.3 review R3 — mirror the controller-DSL path's
+            # structured 400 contract (see `Ruact::Controller#ruact_action`,
+            # Re-run-4 2026-05-15). A malformed `application/json` body
+            # is a client bug; surface it as JSON {error} + 400 so the
+            # runtime's RuactActionError surface reports it cleanly.
+            result = build_malformed_json_result(entry, e)
+            apply_to_response(result, response) if response
+            return result
+          end
+
+          params = ActionController::Parameters.new(raw_args)
+          context = StandaloneContext.new(params: params, request: request)
+
+          result =
+            begin
+              raw = context.instance_exec(params, &entry.block)
+              build_success_result(raw)
+            rescue Ruact::ActionError => e
+              build_error_result(e)
+            end
+
+          maybe_warn_unread_current_user(entry, context)
+          apply_to_response(result, response) if response
+          result
+        end
+
+        # Writes a {Result} onto an `ActionDispatch::Response`. Used by
+        # tests/benches that drive the dispatcher directly (the
+        # request-cycle path goes through `EndpointController#dispatch_action`
+        # which calls `render` / `head` so Rails' `ImplicitRender` does
+        # not interfere).
+        def apply_to_response(result, response)
+          response.status = result.status
+          if result.body.nil? || result.body.empty?
+            response.headers.delete("Content-Type")
+            response.body = ""
+          else
+            response.headers["Content-Type"] = result.content_type if result.content_type
+            response.body = result.body
+          end
+        end
+
+        private
+
+        # Mirrors {Ruact::Controller#ruact_action_raw_args}'s content-type
+        # routing so the block's `params` shadow looks identical regardless
+        # of host shape.
+        def extract_args(request)
+          content_type = request.content_mime_type&.to_s ||
+                         request.headers["Content-Type"]&.to_s&.split(";")&.first
+          case content_type
+          when "application/json"
+            body = request.raw_post
+            return {} if body.nil? || body.empty?
+
+            parsed = JSON.parse(body)
+            parsed.is_a?(Hash) ? parsed : { "_value" => parsed }
+          when "multipart/form-data", "application/x-www-form-urlencoded"
+            request.request_parameters
+          else
+            {}
+          end
+        end
+
+        # Story 8.3 review R3 — structured 400 for malformed JSON bodies,
+        # parity with the controller-DSL path (controller.rb:301-313).
+        def build_malformed_json_result(entry, parse_error)
+          Result.new(
+            status: 400,
+            body: JSON.generate(
+              error: "ruact action :#{entry.ruby_symbol} received malformed JSON body: #{parse_error.message}"
+            ),
+            content_type: "application/json; charset=utf-8"
+          )
+        end
+
+        def build_success_result(raw)
+          if raw.nil?
+            Result.new(status: 204, body: nil, content_type: nil)
+          else
+            Result.new(
+              status: 200,
+              body: JSON.generate(raw),
+              content_type: "application/json; charset=utf-8"
+            )
+          end
+        end
+
+        def build_error_result(action_error)
+          status = action_error.status.is_a?(Symbol) ? status_code_for(action_error.status) : action_error.status
+          body = action_error.body
+          if body.nil?
+            Result.new(status: status, body: nil, content_type: nil)
+          else
+            Result.new(
+              status: status,
+              body: JSON.generate(body),
+              content_type: "application/json; charset=utf-8"
+            )
+          end
+        end
+
+        def status_code_for(symbol)
+          if defined?(Rack::Utils::SYMBOL_TO_STATUS_CODE)
+            Rack::Utils::SYMBOL_TO_STATUS_CODE.fetch(symbol)
+          else
+            symbol
+          end
+        end
+
+        # Pitfall #4 — dev-only warning when a standalone action never
+        # reads `current_user` even though a resolver IS configured. The
+        # warning is gated on `Rails.env.development?` so production hosts
+        # that deliberately expose unauthenticated actions don't see spam.
+        def maybe_warn_unread_current_user(entry, context)
+          return unless defined?(Rails) && Rails.respond_to?(:env) && Rails.env.respond_to?(:development?)
+          return unless Rails.env.development?
+          return if Ruact.config.current_user_resolver.nil?
+          return if context.__ruact_current_user_read?
+
+          host_name = entry.controller.respond_to?(:name) ? entry.controller.name : entry.controller.inspect
+          Rails.logger&.warn(
+            "[ruact] WARNING — standalone action :#{entry.ruby_symbol} on #{host_name} returned " \
+            "without ever reading `current_user`. Standalone actions have NO implicit authorization; " \
+            "ensure the block calls `current_user` (or equivalent) before exposing protected data."
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruact/server_functions.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# Namespace for the server-functions subsystem (Story 8.0a — codegen surface that
+# emits app/javascript/.ruact/server-functions.ts from the gem-side registries).
+#
+# - {Ruact::ServerFunctions::NameBridge} — Ruby symbol → JS identifier translation
+#   (single source of truth; the Vite plugin reads the already-translated identifier
+#   from the JSON snapshot and emits it as-is).
+# - {Ruact::ServerFunctions::RegistryEntry} — immutable record for a single
+#   registered server function.
+# - {Ruact::ServerFunctions::Registry} — storage + register/clear + collision
+#   detection. Populated by Story 8.1 (`ruact_action`) and Story 9.1 (`ruact_query`).
+# - {Ruact::ServerFunctions::Snapshot} — pure function: registries → JSON-shaped Hash.
+# - {Ruact::ServerFunctions::SnapshotWriter} — atomic, write-if-changed file I/O.
+# - {Ruact::ServerFunctions::Codegen} — snapshot Hash → TypeScript module string.
+#
+# Empty registries are valid (Story 8.0a ships them empty; 8.1 and 9.1 populate).
+require "json"
+
+module Ruact
+  module ServerFunctions
+    autoload :NameBridge,         "ruact/server_functions/name_bridge"
+    autoload :RegistryEntry,      "ruact/server_functions/registry_entry"
+    autoload :Registry,           "ruact/server_functions/registry"
+    autoload :Snapshot,           "ruact/server_functions/snapshot"
+    autoload :SnapshotWriter,     "ruact/server_functions/snapshot_writer"
+    autoload :Codegen,            "ruact/server_functions/codegen"
+    autoload :RouteSource,        "ruact/server_functions/route_source"
+    autoload :ErrorRendering,     "ruact/server_functions/error_rendering"
+    autoload :EndpointController, "ruact/server_functions/endpoint_controller"
+    autoload :StandaloneContext, "ruact/server_functions/standalone_context"
+    autoload :StandaloneDispatcher, "ruact/server_functions/standalone_dispatcher"
+    autoload :QueryContext, "ruact/server_functions/query_context"
+    autoload :QueryDispatch, "ruact/server_functions/query_dispatch"
+
+    # Story 9.3 — orchestrates the route-driven (v2) codegen target. Reads the
+    # route table via {RouteSource}, writes the version-2 bridge to the PARALLEL
+    # `.next` path (write-if-changed), and renders the inspection TS via the
+    # Ruby {Codegen} (Vite does not watch `.next`). Per AC5 the `.next` target is
+    # for parity tests + inspection only — never imported by application code —
+    # so the real `server-functions.ts` (v1, rendered by Vite) is untouched
+    # (AC6). The Decision-#6 ownership flip (zero v1 declarations → v2 owns the
+    # real file) is Story 9.8's job.
+    #
+    # AC2 — transparency over silence: the exposed names are ALWAYS logged so a
+    # routed non-GET action never becomes a callable server function silently.
+    #
+    # @param route_set [#routes] the Rails route set.
+    # @param root [Pathname] the app root (for `tmp/cache` + `app/javascript`).
+    # @param logger [#info, nil] logger for the exposure line; defaults to
+    #   `Rails.logger` when Rails is loaded, else nil.
+    # @return [Array<Hash>] the exposed v2 entries.
+    def self.write_v2_snapshot!(route_set:, root:, logger: default_logger)
+      entries = RouteSource.collect(route_set)
+
+      json_path = root.join("tmp/cache/ruact/server-functions.next.json")
+      ts_path   = root.join("app/javascript/.ruact/server-functions.next.ts")
+
+      # Read back from the on-disk bridge (not a fresh dump) so a stable route
+      # table never churns the timestamp baked into the rendered TS header.
+      Snapshot.generate_v2!(entries: entries, path: json_path)
+      Codegen.generate_ts!(snapshot: JSON.parse(File.read(json_path)), output_path: ts_path)
+
+      # AC2 — ALWAYS log what is exposed (even "(none)"), so a routed non-GET
+      # action never becomes a callable server function silently.
+      names = entries.empty? ? "(none)" : entries.map { |e| e["js_identifier"] }.join(", ")
+      logger&.info "[ruact] codegen: exposing #{names}"
+      entries
+    end
+
+    def self.default_logger
+      defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : nil
+    end
+  end
+end

data/lib/ruact/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ruact
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/ruact/view_helper.rb

@@ -2,21 +2,29 @@
 
 module Ruact
   # ActionView helper module included in ActionView::Base via Railtie.
-  # Provides the +__rsc_component__+ method that ERB templates call after the
-  # preprocessor transforms PascalCase tags into +<%= __rsc_component__(...) %>+.
+  # Provides the +__ruact_component__+ method that ERB templates call after the
+  # preprocessor transforms PascalCase tags into +<%= __ruact_component__(...) %>+.
   #
-  # Thread-safe: ActionView creates a fresh view context per request, so there
-  # is no shared state between concurrent requests.
+  # Thread-safe: ActionView creates a fresh view context per request, so the
+  # render context (set by Ruact::Controller#ruact_render on the controller as
+  # +@ruact_render_context+ and copied to the view by Rails's view_assigns
+  # plumbing — see Story 7.9 / Bug 7.8-B) is per-request — no shared state.
   module ViewHelper
-    # Registers +name+ with +props+ in the per-request ComponentRegistry and
-    # returns an HTML comment placeholder that HtmlConverter later replaces with
-    # a ReactElement node.
+    # Registers +name+ with +props+ in the per-render RenderContext (set by
+    # Ruact::Controller#ruact_render on the controller as +@ruact_render_context+;
+    # Rails copies it to the view via +_assigns_for_view_context+ because the
+    # name does not match +DEFAULT_PROTECTED_INSTANCE_VARIABLES+'s +/\A@_/+
+    # filter) and returns an HTML comment placeholder that HtmlConverter later
+    # replaces with a ReactElement node.
     #
     # The returned string MUST be html_safe so ActionView does not escape the
     # angle brackets — if it were escaped, HtmlConverter would not find the
     # placeholder in the HTML output.
-    def __rsc_component__(name, props = {})
-      token = ComponentRegistry.register(name, props)
+    def __ruact_component__(name, props = {})
+      ctx = @ruact_render_context
+      raise Ruact::Error, "ruact: __ruact_component__ called outside a ruact_render flow" if ctx.nil?
+
+      token = ctx.register(name, props)
       "<!-- #{token} -->".html_safe
     end
   end

data/lib/ruact.rb

@@ -6,12 +6,15 @@ require_relative "ruact/configuration"
 require_relative "ruact/serializable"
 require_relative "ruact/flight"
 require_relative "ruact/erb_preprocessor"
-require_relative "ruact/component_registry"
+require_relative "ruact/render_context"
 require_relative "ruact/html_converter"
 require_relative "ruact/client_manifest"
 require_relative "ruact/render_pipeline"
 require_relative "ruact/view_helper"
 require_relative "ruact/erb_preprocessor_hook"
+require_relative "ruact/server_functions"
+require_relative "ruact/server_action"
+require_relative "ruact/query"
 # Railtie loads ruact/controller when inside a Rails app
 require_relative "ruact/railtie" if defined?(Rails)
 
@@ -19,6 +22,35 @@ module Ruact
   class << self
     attr_accessor :manifest, :streaming_mode
 
+    # Registry of `ruact_action` declarations. Populated by Story 8.1's
+    # controller macro; consumed by {Ruact::ServerFunctions::Snapshot} when
+    # writing the Rails↔Vite bridge JSON.
+    #
+    # @return [Ruact::ServerFunctions::Registry] lazy-initialized singleton.
+    def action_registry
+      @action_registry ||= ServerFunctions::Registry.new
+    end
+
+    # Registry of `ruact_query` declarations. Populated by Story 9.1's
+    # controller macro; consumed by {Ruact::ServerFunctions::Snapshot} when
+    # writing the Rails↔Vite bridge JSON.
+    #
+    # @return [Ruact::ServerFunctions::Registry] lazy-initialized singleton.
+    def query_registry
+      @query_registry ||= ServerFunctions::Registry.new
+    end
+
+    # Story 8.4 — Absolute path to the gem's `lib/` root. Used by
+    # {Ruact::ServerFunctions::BacktraceCleaner} to classify backtrace frames as
+    # APP or GEM. Memoised at first call so the per-frame `start_with?` check
+    # stays constant-time. Anchors on this file's directory: `lib/ruact.rb`
+    # resolves to `lib/` after `expand_path("..", __dir__)`.
+    #
+    # @return [String] absolute path to the gem's `lib/` directory
+    def gem_path
+      @gem_path ||= File.expand_path("..", __dir__)
+    end
+
     # Returns the absolute path to the Vite plugin bundled inside this gem.
     # Use this in vite.config.js: import ruact from '<%= Ruact.vite_plugin_path %>'
     # Re-run `rails generate ruact:install` after gem upgrades to refresh the path.
@@ -28,21 +60,68 @@ module Ruact
       File.expand_path("../vendor/javascript/vite-plugin-ruact/index.js", __dir__)
     end
 
-    # Yields the configuration object for block-style setup.
+    # Yields a mutable Configuration draft for block-style setup. The draft is
+    # frozen and atomically swapped into `Ruact.config` when the block returns.
+    # Mutating `Ruact.config` outside this block raises
+    # `Ruact::ConfigurationError` (Story 7.3).
+    #
+    # When called a second time after boot, this method emits a `[ruact]`
+    # warning advising that runtime re-configuration is unusual.
     #
     # @example
     #   Ruact.configure do |config|
     #     config.strict_serialization = true
     #   end
+    # @yieldparam [Ruact::Configuration] mutable draft cloned from the current
+    #   configuration (or built from defaults on first call)
     def configure
-      yield config
+      draft = if defined?(@config) && @config
+                Configuration.new(template: @config)
+              else
+                Configuration.new
+              end
+
+      yield draft
+
+      warn_if_re_configuration!
+      @config = draft.__send__(:seal!)
     end
 
-    # Returns the singleton configuration instance.
+    # Returns the singleton configuration instance, frozen on first access so
+    # that mutation outside `Ruact.configure` always raises (Story 7.3).
+    # First-access publication counts as the boot configuration, so a later
+    # `Ruact.configure` call after default reads triggers the AC3 warning
+    # (otherwise the warning would be silently bypassed in apps that never
+    # call `Ruact.configure` at boot but reconfigure later).
     #
-    # @return [Ruact::Configuration]
+    # @return [Ruact::Configuration] frozen
     def config
-      @config ||= Configuration.new
+      return @config if defined?(@config) && @config
+
+      @config = Configuration.new.__send__(:seal!)
+      @configured_at_least_once = true
+      @config
+    end
+
+    private
+
+    def warn_if_re_configuration!
+      return unless @configured_at_least_once
+
+      caller_loc = caller_locations(2, 1).first
+      message = "[ruact] Ruact.configure called after boot at #{caller_loc.path}:#{caller_loc.lineno}. " \
+                "Re-configuration at runtime is unusual and may indicate that configuration is being " \
+                "driven by request state, environment, or feature flags rather than initializer-time invariants. " \
+                "If this is intentional (e.g. test setup), ignore this warning; otherwise, consolidate " \
+                "configuration into config/initializers/ruact.rb."
+
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.warn(message)
+      else
+        warn(message)
+      end
+    ensure
+      @configured_at_least_once = true
     end
   end
 end

data/lib/rubocop/cop/ruact/no_shared_state.rb

@@ -10,7 +10,7 @@ module RuboCop
       # @example
       #   # bad
       #   @@manifest = nil
-      #   Thread.current[:rsc_request] = req
+      #   Thread.current[:ruact_request] = req
       #
       #   # good
       #   def serialize(value, request:)

data/lib/tasks/benchmark.rake

@@ -7,16 +7,16 @@ namespace :benchmark do
   desc "Run speed benchmark with benchmark-ips (development reporting)"
   task :speed do
     require "benchmark/ips"
-    require "rails_rsc"
+    require "ruact"
 
-    manifest = RailsRsc::ClientManifest.from_hash(
+    manifest = Ruact::ClientManifest.from_hash(
       (1..20).to_h do |i|
         ["Component#{i}", { "id" => "/assets/Component#{i}.js",
                             "name" => "Component#{i}",
                             "chunks" => ["/assets/Component#{i}.js"] }]
       end
     )
-    pipeline = RailsRsc::RenderPipeline.new(manifest)
+    pipeline = Ruact::RenderPipeline.new(manifest)
     erb_typical = "<div>\n#{(1..20).map { |i| "<Component#{i} index={#{i}} />" }.join("\n")}\n</div>"
 
     ctx = Object.new
@@ -24,7 +24,9 @@ namespace :benchmark do
 
     Benchmark.ips do |x|
       x.config(time: 5, warmup: 2)
-      x.report("render 20 components") { pipeline.call(erb_typical, binding_ctx) }
+      x.report("render 20 components") do
+        pipeline.render({ erb: erb_typical, binding: binding_ctx }, mode: :string)
+      end
       x.compare!
     end
   end
@@ -32,22 +34,24 @@ namespace :benchmark do
   desc "Run memory allocation benchmark; exits 1 if allocations exceed baseline × 1.20"
   task :memory do
     require "memory_profiler"
-    require "rails_rsc"
+    require "ruact"
 
-    manifest = RailsRsc::ClientManifest.from_hash(
+    manifest = Ruact::ClientManifest.from_hash(
       (1..20).to_h do |i|
         ["Component#{i}", { "id" => "/assets/Component#{i}.js",
                             "name" => "Component#{i}",
                             "chunks" => ["/assets/Component#{i}.js"] }]
       end
     )
-    pipeline = RailsRsc::RenderPipeline.new(manifest)
+    pipeline = Ruact::RenderPipeline.new(manifest)
     erb_typical = "<div>\n#{(1..20).map { |i| "<Component#{i} index={#{i}} />" }.join("\n")}\n</div>"
     ctx = Object.new
     binding_ctx = ctx.instance_eval { binding }
 
     baseline_path = File.expand_path("../../spec/benchmarks/baseline.json", __dir__)
-    report = MemoryProfiler.report { pipeline.call(erb_typical, binding_ctx) }
+    report = MemoryProfiler.report do
+      pipeline.render({ erb: erb_typical, binding: binding_ctx }, mode: :string)
+    end
     current = report.total_allocated
 
     if File.exist?(baseline_path)
@@ -56,15 +60,15 @@ namespace :benchmark do
       puts "Memory allocations: #{current} (baseline: #{baseline['typical_allocations']}, limit: #{limit})"
 
       if current > limit
-        warn "[rails_rsc] FAIL: allocations #{current} exceed baseline limit #{limit}"
+        warn "[ruact] FAIL: allocations #{current} exceed baseline limit #{limit}"
         exit 1
       else
-        puts "[rails_rsc] PASS: allocations within 120% of baseline"
+        puts "[ruact] PASS: allocations within 120% of baseline"
       end
     else
       baseline_data = { "typical_allocations" => current, "heavy_allocations" => nil }
       File.write(baseline_path, JSON.generate(baseline_data))
-      puts "[rails_rsc] Baseline established: #{current} allocations. Re-run to compare."
+      puts "[ruact] Baseline established: #{current} allocations. Re-run to compare."
     end
   end
 end

data/lib/tasks/ruact.rake

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+namespace :ruact do
+  desc "Check ruact installation and configuration (FR27)"
+  task doctor: :environment do
+    require "ruact/doctor"
+    exit 1 unless Ruact::Doctor.run
+  end
+
+  namespace :server_functions do
+    # Story 8.0a — manual / CI / production codegen entry point. Mirrors the
+    # Railtie hook (config.to_prepare) for environments where the dev server
+    # is not running (CI, deploy pipelines, container build steps).
+    #
+    # Pipeline:
+    #   1. `Snapshot.generate!` writes the JSON bridge IF its registry
+    #      payload differs from the on-disk version (write-if-changed by
+    #      payload, not by timestamp).
+    #   2. `Snapshot.read_for_codegen` re-loads the persisted JSON — this is
+    #      the on-disk source of truth that the Vite plugin consumes, and
+    #      reusing it (instead of freshly dumping with a new timestamp)
+    #      keeps the TS module byte-stable on unchanged registries.
+    #   3. `Codegen.generate_ts!` writes the TS module via the same write-
+    #      if-changed guard.
+    #
+    # Exit codes: 0 on success or no-op rewrites; 1 on
+    # `Ruact::ConfigurationError` (invalid symbol shape per AC7, cross-
+    # registry collision, invalid kind, or a corrupted snapshot rejected by
+    # the codegen's identifier guard).
+    desc "Regenerate app/javascript/.ruact/server-functions.ts from the gem registries (Story 8.0a)"
+    task generate: :environment do
+      require "ruact/server_functions"
+      require "json"
+
+      json_path = Rails.root.join("tmp/cache/ruact/server-functions.json")
+      ts_path   = Rails.root.join("app/javascript/.ruact/server-functions.ts")
+
+      begin
+        Ruact::ServerFunctions::Snapshot.generate!(
+          action_registry: Ruact.action_registry,
+          query_registry: Ruact.query_registry,
+          path: json_path
+        )
+        # Pass-2 patch 2026-05-14 — the JSON can disappear OR be partially
+        # written between `generate!` and `File.read` (a concurrent rake
+        # invocation flushing mid-write, a tmpdir wipe by Spring, an
+        # externally-managed `tmp/cache` cleaner). Both `Errno::ENOENT` AND
+        # `JSON::ParserError` indicate the same TOCTOU window — re-invoke
+        # `generate!` once with the same registries; if the second read
+        # still fails we surface the error with a clear "[ruact] error"
+        # envelope so the caller sees a real failure rather than an
+        # unwrapped Errno / parser backtrace.
+        snapshot = begin
+          JSON.parse(File.read(json_path)).transform_keys(&:to_sym)
+        rescue Errno::ENOENT, JSON::ParserError
+          Ruact::ServerFunctions::Snapshot.generate!(
+            action_registry: Ruact.action_registry,
+            query_registry: Ruact.query_registry,
+            path: json_path
+          )
+          JSON.parse(File.read(json_path)).transform_keys(&:to_sym)
+        end
+        Ruact::ServerFunctions::Codegen.generate_ts!(
+          snapshot: snapshot,
+          output_path: ts_path
+        )
+
+        # Story 9.3 — also emit the route-driven (v2) parallel target
+        # (`server-functions.next.{json,ts}`). Vite does not render the `.next`
+        # bridge, so the rake is the production/CI path that materializes it for
+        # parity + inspection. The real `server-functions.ts` above stays v1.
+        Ruact::ServerFunctions.write_v2_snapshot!(
+          route_set: Rails.application.routes, root: Rails.root, logger: Rails.logger
+        )
+      rescue Ruact::ConfigurationError, Errno::ENOENT, JSON::ParserError => e
+        warn "[ruact] error: #{e.message}"
+        exit 1
+      end
+    end
+  end
+end

data/spec/benchmarks/render_pipeline_benchmark_spec.rb

@@ -32,7 +32,7 @@ RSpec.describe "RenderPipeline benchmark" do
 
   def render_erb(erb_source, active_pipeline = pipeline)
     ctx = Object.new
-    active_pipeline.call(erb_source, ctx.instance_eval { binding })
+    active_pipeline.render({ erb: erb_source, binding: ctx.instance_eval { binding } }, mode: :string)
   end
 
   describe "typical view (20 components)" do