ruact 0.0.1

data/lib/ruact/controller.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "uri"
+
+module Ruact
+  # Include in ApplicationController to enable RSC rendering.
+  #
+  #   class ApplicationController < ActionController::Base
+  #     include Ruact::Controller
+  #   end
+  #
+  # After that, any action whose view is a .html.erb file will automatically:
+  # - Respond to text/x-component requests with a raw Flight payload
+  # - Respond to text/html requests with an HTML shell + inline Flight payload
+  module Controller
+    extend ActiveSupport::Concern
+
+    private
+
+    # Returns the boot-time cached manifest (set by Railtie#config.to_prepare).
+    # No per-request file I/O (AC#6).
+    def rsc_manifest
+      Ruact.manifest
+    end
+
+    # Only activate RSC rendering for HTML-like requests (AC FR26).
+    # JSON, XML, and other formats bypass RSC entirely so respond_to blocks
+    # and explicit render calls work without interference.
+    def default_render
+      if rsc_template_exists? && (request.format.html? || rsc_request?)
+        rsc_render
+      else
+        super
+      end
+    end
+
+    # Render the RSC view for the current action using ActionView's full pipeline.
+    # ActionView handles layouts, partials, and helpers — the ErbPreprocessorHook
+    # ensures all PascalCase tags are transformed before template compilation.
+    #
+    # Called automatically when no explicit render is performed and a matching
+    # .html.erb template exists. Can also be called explicitly with options.
+    #
+    # +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
+        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
+      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
+        else
+          render plain: enumerator.to_a.join, content_type: "text/x-component"
+        end
+      else
+        render html: rsc_html_shell(enumerator.to_a.join).html_safe, layout: false
+      end
+    end
+
+    # Overrides Rails redirect_to for RSC requests: emits a Flight redirect row
+    # (`0:{"redirectUrl":"...","redirectType":"push"}`) instead of a 302 response.
+    # This allows the client-side router to handle the navigation without an extra
+    # 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?
+
+      url = url_for(options)
+
+      begin
+        uri = ::URI.parse(url)
+        # External origin: fall back to standard 302 so the browser follows it normally.
+        # Compare host, port, and scheme to avoid treating same-host-different-port as same-origin.
+        if uri.host
+          return super if uri.host != request.host
+          return super if uri.port && uri.port != request.port
+          return super if uri.scheme && uri.scheme != request.scheme
+        end
+
+        redirect_url  = uri.path.nil? || uri.path.empty? ? "/" : uri.path
+        redirect_url += "?#{uri.query}"    if uri.query
+        redirect_url += "##{uri.fragment}" if uri.fragment
+      rescue ::URI::InvalidURIError
+        return super
+      end
+
+      render plain: "0:#{JSON.generate({ 'redirectUrl' => redirect_url, 'redirectType' => 'push' })}\n",
+             content_type: "text/x-component"
+    end
+
+    def rsc_request?
+      request.headers["Accept"]&.include?("text/x-component") ||
+        request.headers["RSC-Request"] == "1"
+    end
+
+    def rsc_template_exists?
+      File.exist?(default_template_path)
+    end
+
+    def default_template_path
+      action = action_name
+      controller = self.class.name.underscore.sub("_controller", "")
+      Rails.root.join("app", "views", controller, "#{action}.html.erb")
+    end
+
+    def rsc_html_shell(flight_payload)
+      escaped_payload = flight_payload.gsub("</script>", '<\/script>')
+      <<~HTML
+        <!DOCTYPE html>
+        <html lang="en">
+          <head>
+            <meta charset="UTF-8" />
+            <meta name="viewport" content="width=device-width, initial-scale=1" />
+            <title>Rails RSC</title>
+            #{vite_tags}
+          </head>
+          <body>
+            <div id="root"></div>
+            <script>
+              (function() {
+                var d = (self.__FLIGHT_DATA = self.__FLIGHT_DATA || []);
+                d.push(#{escaped_payload.inspect});
+              })();
+            </script>
+          </body>
+        </html>
+      HTML
+    end
+
+    def vite_tags
+      if Rails.env.development? && vite_dev_running?
+        # @vitejs/plugin-react normally injects this preamble by processing index.html.
+        # Since our HTML is generated by Rails (not Vite), we inject it manually.
+        # Without it, every JSX file throws "can't detect preamble" at runtime.
+        react_preamble = <<~JS
+          <script type="module">
+            import RefreshRuntime from 'http://localhost:5173/@react-refresh';
+            RefreshRuntime.injectIntoGlobalHook(window);
+            window.$RefreshReg$ = () => {};
+            window.$RefreshSig$ = () => (type) => type;
+            window.__vite_plugin_react_preamble_installed__ = true;
+          </script>
+        JS
+
+        react_preamble + <<~HTML
+          <script type="module" src="http://localhost:5173/@vite/client"></script>
+          <script type="module" src="http://localhost:5173/app/javascript/application.jsx"></script>
+        HTML
+      else
+        # Production: read hashed URL from Vite manifest
+        entry = vite_manifest_entry("app/javascript/application.jsx")
+        src   = entry ? "/assets/#{entry['file']}" : "/assets/application.js"
+        %(<script type="module" src="#{src}"></script>)
+      end
+    end
+
+    def vite_dev_running?
+      require "socket"
+      Socket.tcp("localhost", 5173, connect_timeout: 1).close
+      true
+    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ETIMEDOUT, SocketError
+      false
+    end
+
+    def vite_manifest_entry(src_path)
+      manifest_path = Rails.root.join("public", "assets", ".vite", "manifest.json")
+      return nil unless File.exist?(manifest_path)
+
+      JSON.parse(File.read(manifest_path))[src_path]
+    end
+  end
+end

data/lib/ruact/doctor.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "socket"
+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).
+  class Doctor
+    CHECKS = %i[manifest vite controller layout streaming].freeze
+
+    # Runs all checks, prints results, returns true if all pass.
+    def self.run
+      new.run
+    end
+
+    def run
+      results = CHECKS.map { |check| send(:"check_#{check}") }
+      results.each { |status, message| puts format_result(status, message) }
+      passed = results.all? { |status, _| status == :pass }
+      puts "Run rails generate ruact:install to fix configuration issues" unless passed
+      passed
+    end
+
+    private
+
+    def check_manifest
+      path = manifest_path
+      if Pathname(path).exist?
+        [:pass, "Manifest found at #{path}"]
+      else
+        [:fail, "Manifest not found — run vite build"]
+      end
+    end
+
+    def check_vite
+      TCPSocket.new("localhost", 5173).close
+      [:pass, "Vite accessible at localhost:5173"]
+    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
+      [:fail, "Vite not accessible at localhost:5173 — run npm run dev"]
+    end
+
+    def check_controller
+      path = Rails.root.join("app", "controllers", "application_controller.rb")
+      if File.exist?(path) && File.read(path).include?("Ruact::Controller")
+        [:pass, "Ruact::Controller included in ApplicationController"]
+      else
+        [:fail, "Ruact::Controller not included in ApplicationController"]
+      end
+    end
+
+    def check_layout
+      path = Rails.root.join("app", "views", "layouts", "application.html.erb")
+      if File.exist?(path) && File.read(path).include?("ruact: root")
+        [:pass, "React shell present in application.html.erb"]
+      else
+        [:fail, "React shell missing from application.html.erb"]
+      end
+    end
+
+    def check_streaming
+      mode  = Ruact.streaming_mode || :buffered
+      label = mode == :enabled ? "enabled" : "buffered"
+      [:pass, "streaming: #{label} (#{streaming_server_hint})"]
+    end
+
+    def streaming_server_hint
+      return "Puma"      if defined?(::Puma)
+      return "Unicorn"   if defined?(::Unicorn)
+      return "Passenger" if defined?(::PhusionPassenger)
+
+      "unknown"
+    end
+
+    def manifest_path
+      Ruact.config.manifest_path ||
+        Rails.root.join("public", "react-client-manifest.json")
+    end
+
+    def format_result(status, message)
+      status == :pass ? "✓ #{message}" : "✗ #{message}"
+    end
+  end
+end

data/lib/ruact/erb_preprocessor.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Transforms ERB source before Ruby evaluation.
+  #
+  # It handles one thing: PascalCase component tags with +{expr}+ props.
+  #
+  #   <LikeButton postId={@post.id} initialCount={5} />
+  #
+  # becomes a placeholder that evaluates the props as Ruby:
+  #
+  #   <%= __rsc_component__("LikeButton", { "postId" => @post.id, "initialCount" => 5 }) %>
+  #
+  # The placeholder is replaced by an HTML comment with a unique token:
+  #   <!-- __RSC_COMPONENT_0__ -->
+  #
+  # The actual ClientReference + props are registered in the binding and
+  # collected by HtmlConverter after the ERB renders.
+  class ErbPreprocessor
+    # Matches a PascalCase opening tag with optional attributes and optional self-closing.
+    # Examples:
+    #   <Button />
+    #   <LikeButton postId={@post.id} initialCount={5} />
+    #   <Dialog open={true}>
+    COMPONENT_TAG_RE = %r{<([A-Z][A-Za-z0-9]*)(\s[^>]*)?\s*/?>}
+
+    # Matches <Suspense ...> opening tags (handled before general PascalCase processing).
+    SUSPENSE_OPEN_RE  = /<Suspense\b([^>]*?)>/m
+    SUSPENSE_CLOSE_RE = %r{</Suspense>}
+
+    # Matches a +{ruby_expr}+ attribute value — captures everything between the braces.
+    # We use a simple bracket-depth counter approach during scanning instead of regex
+    # because expressions can contain nested braces: {foo.bar({ a: 1 })}.
+    PROP_RE = /\b([a-zA-Z_][a-zA-Z0-9_]*)=\{/
+
+    # Transform ERB source, replacing component tags with ERB placeholders.
+    # Returns the transformed source string.
+    def self.transform(source)
+      new.transform(source)
+    end
+
+    def transform(source)
+      # Step 1: transform <Suspense> paired tags into <rsc-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}">)
+               end
+        .gsub(SUSPENSE_CLOSE_RE, "</rsc-suspense>")
+
+      # Step 2: transform remaining PascalCase self-closing / opening component tags.
+      result.gsub(COMPONENT_TAG_RE) do |match|
+        component_name = ::Regexp.last_match(1)
+        attrs_string   = ::Regexp.last_match(2).to_s.strip
+        match_start    = ::Regexp.last_match.begin(0)
+        line           = result[0...match_start].count("\n") + 1
+
+        begin
+          props_ruby = parse_props(attrs_string)
+          props_hash = props_ruby.empty? ? "{}" : "{ #{props_ruby} }"
+          %(<%= __rsc_component__(#{component_name.inspect}, #{props_hash}) %>)
+        rescue PreprocessorError => e
+          raise PreprocessorError, "#{e.message} at line #{line}: #{match.strip}"
+        end
+      end
+    end
+
+    private
+
+    # Extract a string attribute value (double or single quoted) from an attrs string.
+    def extract_string_attr(attrs, name)
+      m = attrs.match(/\b#{Regexp.escape(name)}\s*=\s*"([^"]*)"/) ||
+          attrs.match(/\b#{Regexp.escape(name)}\s*=\s*'([^']*)'/)
+      m&.[](1)
+    end
+
+    # Parses the attributes string of a component tag and returns a Ruby
+    # fragment representing a Hash literal, e.g.:
+    #   "postId" => @post.id, "initialCount" => 5
+    def parse_props(attrs_string)
+      return "" if attrs_string.empty?
+
+      pairs = []
+      remaining = attrs_string.dup
+
+      while (m = PROP_RE.match(remaining))
+        prop_name = m[1]
+        # Find the matching closing brace, respecting nesting
+        value_start = m.end(0)
+        value_expr  = extract_braced_expr(remaining, value_start)
+        pairs << "#{prop_name.inspect} => #{value_expr}"
+        # Advance past this prop
+        remaining = remaining[(value_start + value_expr.length + 1)..] # +1 for closing }
+        break if remaining.nil?
+      end
+
+      pairs.join(", ")
+    end
+
+    # Given a string and a start position (just after the opening '{'),
+    # returns the content up to the matching '}'.
+    def extract_braced_expr(str, start)
+      depth = 1
+      i = start
+      while i < str.length && depth.positive?
+        case str[i]
+        when "{" then depth += 1
+        when "}" then depth -= 1
+        end
+        i += 1
+      end
+      raise PreprocessorError, "unclosed brace in prop expression" if depth.positive?
+
+      str[start...(i - 1)]
+    end
+  end
+end

data/lib/ruact/erb_preprocessor_hook.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Module prepended into ActionView::Template::Handlers::ERB via Railtie.
+  # Applies the RSC preprocessor to every ERB template source before
+  # ActionView compiles it — transparent to views, layouts, and partials.
+  #
+  # ErbPreprocessor.transform has a fast-path O(1) return when the source
+  # contains no PascalCase tags, so non-RSC templates pay essentially no cost.
+  #
+  # Idempotent: prepend is a no-op if this module is already in the ancestor
+  # chain, so reloads in development mode are safe.
+  module ErbPreprocessorHook
+    # Called by ActionView for every ERB template. +source+ is the raw ERB
+    # text; the return value is Ruby code that ActionView will eval.
+    def call(template, source)
+      super(template, ErbPreprocessor.transform(source))
+    end
+  end
+end

data/lib/ruact/errors.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Ruact
+  class Error < StandardError; end
+
+  # Raised when react-client-manifest.json is absent or a component is not found in it.
+  class ManifestError < Error; end
+
+  # Raised when a Ruby value cannot be serialized as a React prop.
+  class SerializationError < Error; end
+
+  # Raised when the ERB preprocessor encounters a malformed component tag.
+  class PreprocessorError < Error; end
+end

data/lib/ruact/flight/react_element.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Ruact
+  module Flight
+    # Represents a React element: <div>, <Component>, etc.
+    # Wire format: ["$", type, key, props]
+    class ReactElement
+      attr_reader :type, :key, :props
+
+      def initialize(type:, key: nil, props: {})
+        @type = type
+        @key = key
+        @props = props
+      end
+    end
+
+    # Represents a React Suspense boundary.
+    # `fallback` is a ReactElement shown while the deferred content is loading.
+    # `children` is the actual content (emitted as a deferred row after `delay` seconds).
+    class SuspenseElement
+      attr_reader :fallback, :children, :delay
+
+      def initialize(fallback:, children:, delay: 1.5)
+        @fallback  = fallback
+        @children  = children
+        @delay     = delay
+      end
+    end
+
+    # Points to a "use client" module — will become an I row + $L<id> reference.
+    class ClientReference
+      attr_reader :module_id, :export_name
+
+      def initialize(module_id:, export_name: "default")
+        @module_id = module_id
+        @export_name = export_name
+      end
+    end
+  end
+end

data/lib/ruact/flight/renderer.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ruact
+  module Flight
+    # Renders a React element tree to a Flight wire format string.
+    #
+    # Usage:
+    #   output = Renderer.render(root_element, bundler_config)
+    #   # => "1:I[...]\n0:[\"$\",\"div\",...]\n"
+    class Renderer
+      def self.render(model, bundler_config, **)
+        each(model, bundler_config, streaming: false, **).to_a.join
+      end
+
+      def self.each(model, bundler_config, strict_serialization: false, on_as_json_warning: nil,
+                    streaming: true, &)
+        new(model, bundler_config,
+            strict_serialization: strict_serialization,
+            on_as_json_warning: on_as_json_warning).each(streaming: streaming, &)
+      end
+
+      def initialize(model, bundler_config, strict_serialization: false, on_as_json_warning: nil)
+        @request = Request.new(model, bundler_config,
+                               strict_serialization: strict_serialization,
+                               on_as_json_warning: on_as_json_warning)
+      end
+
+      # Yields Flight rows one at a time.
+      # Flush order: imports → regular → root → deferred (with optional delay) → errors.
+      # When streaming: false (initial HTML shell), deferred delays are skipped.
+      def each(streaming: true, &block)
+        return enum_for(:each, streaming: streaming) unless block_given?
+
+        root_id = @request.allocate_id # => 0
+
+        serializer = Serializer.new(@request)
+        root_value = serializer.serialize_model(@request.root_model)
+        root_json  = JSON.generate(root_value)
+        root_row   = RowEmitter.model(root_id, root_json)
+
+        @request.completed_import_chunks.each(&block)
+        @request.completed_regular_chunks.each(&block)
+        yield root_row
+
+        # Deferred chunks: emitted after root, optionally delayed (Suspense streaming).
+        # When the chunk delay exceeds suspense_timeout, an E-type error row is emitted instead.
+        @request.deferred_chunks.each do |deferred|
+          if streaming && deferred[:delay]&.positive?
+            timeout = Ruact.config.suspense_timeout
+            if timeout&.positive? && deferred[:delay] > timeout
+              yield RowEmitter.error(deferred[:id], JSON.generate("Suspense timeout exceeded"))
+              next
+            end
+            sleep(deferred[:delay])
+          end
+
+          # Serialize deferred content — may produce new import rows
+          import_count_before = @request.completed_import_chunks.length
+          deferred_value = serializer.serialize_model(deferred[:element])
+
+          # Yield any import rows discovered during deferred serialization
+          @request.completed_import_chunks[import_count_before..].each(&block)
+
+          yield RowEmitter.model(deferred[:id], JSON.generate(deferred_value))
+        end
+
+        @request.completed_error_chunks.each(&block)
+      end
+    end
+  end
+end

data/lib/ruact/flight/request.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Ruact
+  module Flight
+    # Central state for a single Flight render.
+    # Owns the ID allocator, chunk queues, and dedup tracker.
+    class Request
+      # I rows — flushed first
+      attr_reader :completed_import_chunks
+      # model rows
+      attr_reader :completed_regular_chunks
+      # E rows — flushed last
+      attr_reader :completed_error_chunks
+      # { id:, element:, delay: } — emitted after root row
+      attr_reader :deferred_chunks
+      # object_id => "$L<hex>" reference (dedup)
+      attr_reader :written_objects
+      attr_reader :next_chunk_id, :pending_chunks, :bundler_config, :root_model,
+                  :strict_serialization, :on_as_json_warning
+
+      def initialize(model, bundler_config, strict_serialization: false, on_as_json_warning: nil)
+        @strict_serialization = strict_serialization
+        @on_as_json_warning   = on_as_json_warning
+        @next_chunk_id = 0
+        @pending_chunks = 0
+        @bundler_config = bundler_config
+
+        @completed_import_chunks  = []
+        @completed_regular_chunks = []
+        @completed_error_chunks   = []
+        @deferred_chunks          = []
+
+        @written_objects = {}.compare_by_identity
+
+        # Root task is always ID 0
+        @root_model = model
+      end
+
+      def allocate_id
+        id = @next_chunk_id
+        @next_chunk_id += 1
+        id
+      end
+
+      def increment_pending
+        @pending_chunks += 1
+      end
+
+      def decrement_pending
+        @pending_chunks -= 1
+      end
+    end
+  end
+end

data/lib/ruact/flight/row_emitter.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Ruact
+  module Flight
+    # Formats Flight wire format rows.
+    #
+    # Text rows:   <hex_id>:<tag><json_payload>\n
+    # Binary rows: <hex_id>:<tag><hex_byte_length>,<binary_data>   (no newline)
+    module RowEmitter
+      # A plain model row (most elements, objects, arrays)
+      def self.model(id, json)
+        "#{id.to_s(16)}:#{json}\n"
+      end
+
+      # An import row — tells the client where to load a "use client" module
+      def self.import(id, metadata_json)
+        "#{id.to_s(16)}:I#{metadata_json}\n"
+      end
+
+      # An error row
+      def self.error(id, error_json)
+        "#{id.to_s(16)}:E#{error_json}\n"
+      end
+
+      # A large text row (binary framing, no trailing newline)
+      def self.text(id, text)
+        byte_length = text.bytesize
+        "#{id.to_s(16)}:T#{byte_length.to_s(16)},#{text}"
+      end
+
+      # A hint row — no ID, fire-and-forget preload signal
+      def self.hint(code, model_json)
+        ":H#{code}#{model_json}\n"
+      end
+    end
+  end
+end