ruact 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ecde11a9eeeaa534f73c9aba3a1c15a1bb44bbe1035467dad11b6f8517085aa
-  data.tar.gz: 7b3077daa2fe5cef2189b40c575df223cc960b49e8ace3ce5cebf8b61afd9e29
+  metadata.gz: c3ae4065926e9ba0e05bc16a221311f82af38ec3968c38066d806e8c1af04b89
+  data.tar.gz: 67d36ca87ddd0bab244352b658784238d3a97abd6b955279d7f162d221c81313
 SHA512:
-  metadata.gz: 2696f4a816b237e124465604bc04a2d5a54804601d413bf907429376efb8b72d17ff876f013fb4491df47c4b231a696f7213c8e431e5924f4a504e7d2b7a1214
-  data.tar.gz: e1cf6a62a6e0d4e5d061b4dae97fe71d47df9137db0a3cc1581cb1056282a0b757a69eff7d1a7981ae3a419ee9d79be938871cb1f636d612e2a6affd026a809f
+  metadata.gz: 87af4e8c9df874d9d7f5d93c87144689c73d83b8cb5097696891042bdae284de2f40c7e783317aa429e2a9c97fe318668873754c41d739a2f76c333bb07dec87
+  data.tar.gz: fd3e4f768563a86f29b074fa8c894c0faf4718789dab950325f8c8aa7cbb51e38c34565ded5f99a5e536a01b7641929d23b74ec5cd9e2cb3540e08fa97d98fdc

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.7] - 2026-06-30
+
+### Fixed
+
+- **Boot-race that 500'd the first request in development — the manifest is now resolved from the Vite dev server over HTTP.** On a fresh app the Railtie's `config.to_prepare` read `public/react-client-manifest.json` **once at boot**, but Rails frequently booted (and read the still-missing file) **before** the Vite dev server wrote it — leaving `Ruact.manifest` `nil`. `public/` is not watched, so `to_prepare` never re-fired, and the first request to a view containing a component hit `nil.reference_for` → a cryptic 500. The bundled Vite plugin now **serves the live in-memory manifest at `GET <vite_dev_server>/__ruact/manifest`** (always fresh, reflects HMR rebuilds, internal `_sourceFile` field stripped), and in **development** the gem resolves the manifest through a new `Ruact::ManifestResolver`: it fetches that endpoint over `Net::HTTP` (~1s timeout, once per render/preprocess — not per component), **falls back** to `public/react-client-manifest.json` on disk when the dev server is down, and otherwise raises a **clear, actionable** error (`Vite dev server inacessível … rode bin/dev`) instead of a `NoMethodError`. **Production is untouched** — it still uses the boot-loaded `Ruact.manifest` (raising at boot if the build is missing); the HTTP fetch is dev-only. The Vite plugin continues to **write** `public/react-client-manifest.json` (prod build + the dev fallback). Both render and the FR100 contract validator resolve through the same path (the validator fails open to no-validation when the manifest is unreachable). The three hardcoded `http://localhost:5173` references in `ruact_js_assets` (the react-refresh preamble, `@vite/client`, and the bootstrap `<script src>`) now honor `Ruact.config.vite_dev_server` for consistency.
+
 ## [0.0.6] - 2026-06-30
 
 > **Server functions are route-driven.** A server **mutation** is a normal non-GET
@@ -162,5 +168,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **CI matrix** — GitHub Actions: RSpec across Ruby 3.2 × 3.3 × Rails 7.0 × 7.1 × 7.2 × 8.0; RuboCop; YARD docs; memory benchmark; E2E system tests against React 19.0.0 and 19.x (Capybara + Cuprite); non-blocking React@next job with auto-issue on failure.
 - **E2E test app** — `e2e/` Rails app (no DB, in-memory Post model) with full CRUD system tests validating the complete request cycle.
 
-[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.6...HEAD
+[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.7...HEAD
+[0.0.7]: https://github.com/luizcg/ruact/releases/tag/v0.0.7
 [0.0.6]: https://github.com/luizcg/ruact/releases/tag/v0.0.6

data/lib/ruact/controller.rb

@@ -36,10 +36,16 @@ module Ruact
     # only ever invoked internally by `ruact_html_shell`).
     private :ruact_js_assets, :__ruact_component__
 
-    # Returns the boot-time cached manifest (set by Railtie#config.to_prepare).
-    # No per-request file I/O (AC#6).
+    # Resolves the manifest for this render. In PRODUCTION this is the boot-time
+    # cached +Ruact.manifest+ (set by Railtie#config.to_prepare) — no per-request
+    # I/O. In DEVELOPMENT it fetches the live manifest from the Vite dev server
+    # (falling back to the on-disk file, then a clear error), killing the
+    # boot-race where Rails read the missing file before Vite wrote it and every
+    # first request 500'd on +nil.reference_for+. Called once per render; the
+    # returned manifest is held by RenderPipeline for the whole render (not
+    # re-fetched per component). See {Ruact::ManifestResolver}.
     def ruact_manifest
-      Ruact.manifest
+      ManifestResolver.resolve
     end
 
     # Only activate RSC rendering when the matching .html.erb template exists AND

data/lib/ruact/erb_preprocessor.rb

@@ -74,7 +74,13 @@ module Ruact
         line           = result[0...match_start].count("\n") + 1
 
         begin
-          registry = Ruact.manifest if registry == :default # lazy — only when a tag exists
+          # lazy — only when a tag exists. `resolve_soft` returns the dev-fetched
+          # manifest (same source the render path uses, so the boot-race doesn't
+          # silence FR100 contract checks in dev) and FAILS OPEN to nil when the
+          # manifest is unresolvable (contract validation is opt-in/fail-open;
+          # the render path surfaces the clear error). In prod this is the
+          # boot-loaded Ruact.manifest, unchanged.
+          registry = ManifestResolver.resolve_soft if registry == :default
           pairs = parse_prop_pairs(attrs_string)
           validate_contract(registry, component_name, pairs.map(&:first),
                             at: { file: identifier, line: line, snippet: match.strip })

data/lib/ruact/manifest_resolver.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ruact
+  # Resolves the {Ruact::ClientManifest} to use for the current render /
+  # ERB-preprocess.
+  #
+  # PRODUCTION (unchanged): returns the boot-loaded +Ruact.manifest+ (set once by
+  # the Railtie's +config.to_prepare+; the Railtie raises at boot when the file is
+  # absent). No per-request I/O.
+  #
+  # DEVELOPMENT (the fix): the boot-time +to_prepare+ read of
+  # +public/react-client-manifest.json+ RACES the Vite dev server's first write —
+  # on a fresh app Rails can boot (and read the missing file) BEFORE Vite writes
+  # it, leaving +Ruact.manifest+ nil even though Vite is running and serving a
+  # current manifest. +public/+ is not watched, so +to_prepare+ never re-fires and
+  # the first request to a view with a component hits +nil.reference_for+ → 500.
+  #
+  # To kill that race, dev resolution fetches the LIVE manifest the Vite plugin
+  # serves in memory at +GET {vite_dev_server}/__ruact/manifest+ (always fresh,
+  # reflects HMR rebuilds), with graceful fallbacks:
+  #
+  #   1. HTTP fetch from the Vite dev server (short timeout).
+  #   2. Fallback: read +public/react-client-manifest.json+ from disk (the Vite
+  #      plugin still writes it — prod needs it for the build, and it is the
+  #      fallback when the dev server is down).
+  #   3. Neither available → a clear, actionable error (never a cryptic
+  #      +NoMethodError+ on nil).
+  #
+  # Memoization grain: the resolver fetches ONCE PER CALL. The two call sites each
+  # invoke it once per their scope and reuse the result for every component —
+  # +RenderPipeline+ holds the returned manifest in +@manifest+ for the whole
+  # render, and +ErbPreprocessor#transform+ resolves it lazily into a local that
+  # is reused across every tag in the template. So a render does NOT re-fetch per
+  # component (the bug was many +reference_for+ calls all needing a manifest); at
+  # most one fetch for the render and one for a (re)compiled template.
+  module ManifestResolver
+    DEV_MANIFEST_PATH = "/__ruact/manifest"
+    # Dev is localhost; fail fast to the file/clear-error fallback. A refused
+    # connection (Vite simply down) raises immediately, so this timeout only
+    # bounds the pathological "listening but not answering" case.
+    HTTP_OPEN_TIMEOUT = 1
+    HTTP_READ_TIMEOUT = 1
+
+    # Resolve the manifest for a render. In dev, raises a clear
+    # {Ruact::ManifestError} when neither the dev server nor the on-disk file is
+    # available. In any non-development environment, returns +Ruact.manifest+
+    # verbatim (production behaviour is untouched).
+    #
+    # @return [Ruact::ClientManifest, nil]
+    def self.resolve
+      return Ruact.manifest unless development?
+
+      dev_manifest(soft: false)
+    end
+
+    # Like {.resolve} but FAIL-OPEN in dev: returns +nil+ (rather than raising)
+    # when nothing is resolvable. Used by the ERB preprocessor's opt-in FR100
+    # contract validation, which is fail-open by design — a missing manifest must
+    # not crash template compilation; the render path then surfaces the clear
+    # error from {.resolve}.
+    #
+    # @return [Ruact::ClientManifest, nil]
+    def self.resolve_soft
+      return Ruact.manifest unless development?
+
+      dev_manifest(soft: true)
+    end
+
+    # @return [Ruact::ClientManifest, nil]
+    def self.dev_manifest(soft:)
+      manifest = fetch_over_http
+      return manifest if manifest
+
+      manifest = load_from_file
+      return manifest if manifest
+
+      return nil if soft
+
+      raise ManifestError, <<~MSG.strip
+        [ruact] Vite dev server inacessível em #{base_url} e nenhum \
+        react-client-manifest.json encontrado em #{file_path} — rode `bin/dev`.
+      MSG
+    end
+
+    # Fetch + parse the live manifest from the Vite dev server, or +nil+ when the
+    # server is unreachable / returns a non-200 / unparseable body. Never raises:
+    # any failure degrades to the file fallback.
+    #
+    # @return [Ruact::ClientManifest, nil]
+    def self.fetch_over_http
+      require "net/http"
+      require "uri"
+
+      # `chomp("/")` so a base configured WITH a trailing slash
+      # ("http://localhost:5173/") does not yield a double-slashed
+      # "//__ruact/manifest" that misses the Vite middleware mount.
+      uri = URI.parse("#{base_url.chomp('/')}#{DEV_MANIFEST_PATH}")
+      response = Net::HTTP.start(
+        uri.host, uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: HTTP_OPEN_TIMEOUT, read_timeout: HTTP_READ_TIMEOUT
+      ) { |http| http.get(uri.request_uri) }
+
+      return nil unless response.is_a?(Net::HTTPSuccess)
+
+      ClientManifest.from_hash(JSON.parse(response.body))
+    rescue StandardError
+      nil
+    end
+
+    # Fallback: load the on-disk manifest the Vite plugin also writes, or +nil+
+    # when it is absent (the boot-race window) / unreadable.
+    #
+    # @return [Ruact::ClientManifest, nil]
+    def self.load_from_file
+      path = file_path
+      return nil unless path && File.exist?(path)
+
+      ClientManifest.load(path)
+    rescue StandardError
+      nil
+    end
+
+    # @return [String] the configured Vite dev-server base URL.
+    def self.base_url
+      Ruact.config.vite_dev_server
+    end
+
+    # @return [String, nil] the on-disk manifest path (config override or default).
+    def self.file_path
+      configured = Ruact.config.manifest_path
+      return configured.to_s if configured
+
+      return nil unless defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
+      Rails.root.join("public", "react-client-manifest.json").to_s
+    end
+
+    # @return [Boolean] true only in a real Rails development environment. Any
+    #   other env (production, test, or no Rails at all) takes the untouched
+    #   +Ruact.manifest+ path.
+    def self.development?
+      defined?(Rails) && Rails.respond_to?(:env) && Rails.env.respond_to?(:development?) &&
+        Rails.env.development?
+    end
+  end
+end

data/lib/ruact/railtie.rb

@@ -100,9 +100,20 @@ module Ruact
     # Extracted as a class method for direct testability without a full Rails app.
     def self.check_vite!
       require "socket"
-      TCPSocket.new("localhost", 5173).close
-    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
-      Rails.logger.warn "[ruact] Vite dev server not detected at localhost:5173 " \
+      require "uri"
+      uri  = URI.parse(Ruact.config.vite_dev_server)
+      host = uri.host || "localhost"
+      port = uri.port || 5173
+      # `connect_timeout` so a blackholed/remote configured host can't stall dev
+      # boot from `after_initialize` until the OS TCP timeout (matches
+      # ViewHelper#vite_dev_running?).
+      TCPSocket.new(host, port, connect_timeout: 1).close
+    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ETIMEDOUT, SocketError
+      # Broad rescue (incl. SocketError) because the host is now configurable: a
+      # misconfigured/unresolvable `vite_dev_server` must downgrade to this dev
+      # warning, never crash boot from `after_initialize`. `host`/`port` are
+      # assigned before the connect attempt, so they are always in scope here.
+      Rails.logger.warn "[ruact] Vite dev server not detected at #{host}:#{port} " \
                         "— run npm run dev for HMR"
     end
 

data/lib/ruact/render_pipeline.rb

@@ -166,7 +166,14 @@ module Ruact
     def render_erb_enum(erb_source, binding_context, streaming:)
       Enumerator.new do |y|
         render_context = RenderContext.new
-        transformed    = ErbPreprocessor.transform(erb_source)
+        # `registry: nil` → fail-open, no FR100 contract validation for this
+        # low-level programmatic render path (contract checking lives on the
+        # ActionView preprocessor hook used by real controllers). This keeps the
+        # path off `Ruact::ManifestResolver` entirely — historically it read the
+        # global `Ruact.manifest` (typically nil here, so already no validation),
+        # so passing nil is byte-for-byte equivalent while avoiding any dev HTTP
+        # fetch / test-double dispatch inside callers that measure this path.
+        transformed    = ErbPreprocessor.transform(erb_source, registry: nil)
         receiver       = binding_context.eval("self")
         prev_ctx       = receiver.instance_variable_get(:@__ruact_render_context__)
         inject_helper!(binding_context, render_context)

data/lib/ruact/version.rb

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

data/lib/ruact/view_helper.rb

@@ -83,9 +83,10 @@ module Ruact
         # @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.
+        dev_server = Ruact.config.vite_dev_server.chomp("/")
         react_preamble = <<~JS
           <script type="module">
-            import RefreshRuntime from 'http://localhost:5173/@react-refresh';
+            import RefreshRuntime from '#{dev_server}/@react-refresh';
             RefreshRuntime.injectIntoGlobalHook(window);
             window.$RefreshReg$ = () => {};
             window.$RefreshSig$ = () => (type) => type;
@@ -94,7 +95,7 @@ module Ruact
         JS
 
         react_preamble + <<~HTML
-          <script type="module" src="http://localhost:5173/@vite/client"></script>
+          <script type="module" src="#{dev_server}/@vite/client"></script>
           <script type="module" src="#{ruact_bootstrap_dev_url}"></script>
         HTML
       else
@@ -112,12 +113,18 @@ module Ruact
     # `/@id/__x00__virtual:ruact/bootstrap`. A plain `/virtual:...` URL falls
     # through to the dev server's HTML fallback, so this encoding is required.
     def ruact_bootstrap_dev_url
-      "http://localhost:5173/@id/__x00__#{Ruact.bootstrap_virtual_id}"
+      "#{Ruact.config.vite_dev_server.chomp('/')}/@id/__x00__#{Ruact.bootstrap_virtual_id}"
     end
 
+    # Probe the CONFIGURED dev server (host:port parsed from
+    # `Ruact.config.vite_dev_server`), not a hardcoded localhost:5173 — so a
+    # custom `vite_dev_server` and the emitted dev `<script>` URLs always agree
+    # on whether the server is up.
     def vite_dev_running?
       require "socket"
-      Socket.tcp("localhost", 5173, connect_timeout: 1).close
+      require "uri"
+      uri = URI.parse(Ruact.config.vite_dev_server)
+      Socket.tcp(uri.host || "localhost", uri.port || 5173, connect_timeout: 1).close
       true
     rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ETIMEDOUT, SocketError
       false

data/lib/ruact.rb

@@ -12,6 +12,7 @@ require_relative "ruact/erb_preprocessor"
 require_relative "ruact/render_context"
 require_relative "ruact/html_converter"
 require_relative "ruact/client_manifest"
+require_relative "ruact/manifest_resolver"
 require_relative "ruact/render_pipeline"
 require_relative "ruact/view_helper"
 require_relative "ruact/erb_preprocessor_hook"

data/spec/ruact/controller_spec.rb

@@ -39,10 +39,15 @@ module Ruact
     let(:controller)   { test_class.new(fake_request) }
 
     describe "#ruact_manifest" do
-      it "reads from Ruact.manifest (AC#6)" do
+      # Opt OUT of spec_helper's suite-wide resolver stub here so this proves the
+      # actual delegation: `#ruact_manifest` resolves through ManifestResolver
+      # (prod returns the boot-loaded Ruact.manifest; dev fetches over HTTP).
+      it "delegates manifest resolution to ManifestResolver.resolve" do
         test_manifest = ClientManifest.from_hash({})
-        allow(Ruact).to receive(:manifest).and_return(test_manifest)
+        allow(ManifestResolver).to receive(:resolve).and_return(test_manifest)
+
         expect(controller.send(:ruact_manifest)).to be test_manifest
+        expect(ManifestResolver).to have_received(:resolve)
       end
     end
 

data/spec/ruact/manifest_resolver_spec.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "net/http"
+require "tmpdir"
+
+module Ruact
+  RSpec.describe ManifestResolver do
+    # spec_helper pins resolve/resolve_soft to the boot manifest suite-wide for
+    # hermeticity; this spec is the one place that exercises the REAL paths.
+    before do
+      allow(described_class).to receive(:resolve).and_call_original
+      allow(described_class).to receive(:resolve_soft).and_call_original
+    end
+
+    let(:manifest_hash) do
+      {
+        "LikeButton" => {
+          "id" => "/LikeButton.jsx",
+          "name" => "LikeButton",
+          "chunks" => ["/LikeButton.jsx"]
+        }
+      }
+    end
+    let(:manifest_json) { JSON.generate(manifest_hash) }
+
+    # A real Net::HTTPSuccess (HTTPOK < HTTPSuccess) whose body we override, so
+    # the resolver's `response.is_a?(Net::HTTPSuccess)` branch is exercised for
+    # real without touching the network.
+    def http_ok(body)
+      response = Net::HTTPOK.new("1.1", "200", "OK")
+      response.define_singleton_method(:body) { body }
+      response
+    end
+
+    def in_dev
+      allow(Rails).to receive(:env).and_return(ActiveSupport::StringInquirer.new("development"))
+    end
+
+    describe ".resolve in development (the boot-race)" do
+      before do
+        in_dev
+        # Simulate the race: boot read the missing file, so the cached manifest is nil.
+        allow(Ruact).to receive(:manifest).and_return(nil)
+      end
+
+      it "resolves from the Vite dev server over HTTP (no 500, ref resolvable)" do
+        allow(Net::HTTP).to receive(:start).and_return(http_ok(manifest_json))
+
+        manifest = described_class.resolve
+
+        expect(manifest).to be_a(ClientManifest)
+        ref = manifest.reference_for("LikeButton")
+        expect(ref.module_id).to eq("/LikeButton.jsx")
+      end
+
+      it "fetches the manifest from the configured vite_dev_server URL" do
+        allow(Net::HTTP).to receive(:start).and_return(http_ok(manifest_json))
+
+        described_class.resolve
+
+        expect(Net::HTTP).to have_received(:start).with(
+          "localhost", 5173, hash_including(:open_timeout, :read_timeout)
+        )
+      end
+
+      it "does not double-slash the path when vite_dev_server has a trailing slash" do
+        allow(described_class).to receive(:base_url).and_return("http://localhost:5173/")
+        http = instance_double(Net::HTTP)
+        allow(http).to receive(:get).and_return(http_ok(manifest_json))
+        allow(Net::HTTP).to receive(:start).and_yield(http).and_return(http_ok(manifest_json))
+
+        described_class.resolve
+
+        expect(http).to have_received(:get).with("/__ruact/manifest")
+      end
+
+      it "speaks TLS when vite_dev_server is https" do
+        allow(described_class).to receive(:base_url).and_return("https://localhost:5173")
+        allow(Net::HTTP).to receive(:start).and_return(http_ok(manifest_json))
+
+        described_class.resolve
+
+        expect(Net::HTTP).to have_received(:start).with(
+          "localhost", 5173, hash_including(use_ssl: true)
+        )
+      end
+
+      it "falls back to the on-disk file when the dev server is unreachable" do
+        allow(Net::HTTP).to receive(:start).and_raise(Errno::ECONNREFUSED)
+
+        Dir.mktmpdir do |dir|
+          path = File.join(dir, "react-client-manifest.json")
+          File.write(path, manifest_json)
+          allow(described_class).to receive(:file_path).and_return(path)
+
+          manifest = described_class.resolve
+          expect(manifest).to be_a(ClientManifest)
+          expect(manifest.reference_for("LikeButton").module_id).to eq("/LikeButton.jsx")
+        end
+      end
+
+      it "raises a clear, actionable error (not NoMethodError) when neither HTTP nor file is available" do
+        allow(Net::HTTP).to receive(:start).and_raise(Errno::ECONNREFUSED)
+        allow(described_class).to receive(:file_path).and_return("/no/such/manifest.json")
+
+        expect { described_class.resolve }.to raise_error(ManifestError, %r{Vite dev server.*bin/dev}m)
+      end
+
+      it "ignores a non-2xx dev-server response and falls back" do
+        allow(Net::HTTP).to receive(:start).and_return(Net::HTTPNotFound.new("1.1", "404", "Not Found"))
+        allow(described_class).to receive(:file_path).and_return("/no/such/manifest.json")
+
+        expect { described_class.resolve }.to raise_error(ManifestError)
+      end
+    end
+
+    describe ".resolve_soft in development (fail-open for FR100)" do
+      before do
+        in_dev
+        allow(Ruact).to receive(:manifest).and_return(nil)
+      end
+
+      it "returns nil (no raise) when nothing is resolvable" do
+        allow(Net::HTTP).to receive(:start).and_raise(Errno::ECONNREFUSED)
+        allow(described_class).to receive(:file_path).and_return("/no/such/manifest.json")
+
+        expect(described_class.resolve_soft).to be_nil
+      end
+
+      it "returns the dev manifest when the server is up" do
+        allow(Net::HTTP).to receive(:start).and_return(http_ok(manifest_json))
+        expect(described_class.resolve_soft).to be_a(ClientManifest)
+      end
+    end
+
+    describe "production / non-development (untouched)" do
+      it "returns Ruact.manifest verbatim without any HTTP call" do
+        allow(Rails).to receive(:env).and_return(ActiveSupport::StringInquirer.new("production"))
+        allow(Net::HTTP).to receive(:start)
+        boot_manifest = ClientManifest.from_hash(manifest_hash)
+        allow(Ruact).to receive(:manifest).and_return(boot_manifest)
+
+        expect(described_class.resolve).to be(boot_manifest)
+        expect(Net::HTTP).not_to have_received(:start)
+      end
+
+      it "returns Ruact.manifest in the test environment too (no dev fetch)" do
+        allow(Rails).to receive(:env).and_return(ActiveSupport::StringInquirer.new("test"))
+        allow(Net::HTTP).to receive(:start)
+        boot_manifest = ClientManifest.from_hash(manifest_hash)
+        allow(Ruact).to receive(:manifest).and_return(boot_manifest)
+
+        expect(described_class.resolve).to be(boot_manifest)
+        expect(Net::HTTP).not_to have_received(:start)
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -58,5 +58,20 @@ RSpec.configure do |config|
     # before every example so no leaked double survives — examples that need a
     # specific logger set their own in their own `before` (which runs after this).
     Rails.logger = Logger.new(IO::NULL) if defined?(Rails) && Rails.respond_to?(:logger=)
+
+    # Manifest-over-HTTP fix: the gem suite runs with `Rails.env == development`
+    # by default, where `Ruact::ManifestResolver` would otherwise fetch the live
+    # manifest from the Vite dev server (localhost:5173) on every ActionView
+    # render — making the suite hit the network and go flaky on a dev machine
+    # that happens to run a foreign Vite there. Pin the pre-fix behaviour (return
+    # the boot-loaded `Ruact.manifest`) so the whole suite is hermetic. The
+    # resolver's own spec re-stubs these `.and_call_original` to exercise the real
+    # HTTP/fallback paths with `Net::HTTP` mocked. (The programmatic
+    # `RenderPipeline#render({erb:})` path passes `registry: nil` and never
+    # touches the resolver, so the benchmark measures the real render cost.)
+    if defined?(Ruact::ManifestResolver)
+      allow(Ruact::ManifestResolver).to receive(:resolve) { Ruact.manifest }
+      allow(Ruact::ManifestResolver).to receive(:resolve_soft) { Ruact.manifest }
+    end
   end
 end

data/vendor/javascript/vite-plugin-ruact/index.js

@@ -171,6 +171,26 @@ export default function ruact(options = {}) {
     configureServer(server) {
       const dir = path.resolve(root, componentsDir);
       server.watcher.add(dir);
+
+      // Serve the LIVE in-memory manifest over HTTP so the Rails gem can
+      // resolve components in dev without depending on the on-disk
+      // public/react-client-manifest.json — whose first write races Rails's
+      // boot-time read (Rails can boot, and config.to_prepare read the file,
+      // BEFORE Vite writes it → Ruact.manifest nil → 500 on the first request).
+      // This endpoint always reflects the current `manifest` (rebuilt by the
+      // watcher below + buildStart), and omits the internal `_sourceFile` field
+      // so the wire shape matches the file the gem already knows how to parse.
+      server.middlewares.use("/__ruact/manifest", (req, res, next) => {
+        if (req.method !== "GET") return next();
+        const out = {};
+        for (const [name, entry] of Object.entries(manifest)) {
+          const { _sourceFile, ...rest } = entry;
+          out[name] = rest;
+        }
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify(out));
+      });
+
       const rebuild = (file) => {
         if (!file.startsWith(dir)) return;
         manifest = buildManifest(dir);

data/vendor/javascript/vite-plugin-ruact/manifest-http.test.mjs

@@ -0,0 +1,125 @@
+// Fix (manifest-over-HTTP) — the dev server exposes the live in-memory manifest
+// at GET /__ruact/manifest so the Rails gem can resolve components without
+// racing the on-disk react-client-manifest.json write at boot. This file
+// covers the configureServer middleware:
+//
+//   1. responds with the current manifest (no internal `_sourceFile` field);
+//   2. reflects a rebuild when a "use client" component is added/changed.
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import ruact from "./index.js";
+
+let dir;
+beforeEach(() => {
+  dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "ruact-manifest-http-")));
+});
+afterEach(() => {
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function write(rel, body) {
+  const full = path.join(dir, rel);
+  fs.mkdirSync(path.dirname(full), { recursive: true });
+  fs.writeFileSync(full, body);
+  return full;
+}
+
+const COMPONENT = (name) =>
+  `"use client";\nexport function ${name}() { return null; }\n`;
+
+// A minimal connect-style server harness: captures the path-mounted middleware
+// and the watcher callbacks the plugin registers in configureServer.
+function makeServer() {
+  const middlewares = new Map();
+  const watcherHandlers = { change: [], add: [], unlink: [] };
+  return {
+    middlewares: { use: (route, fn) => middlewares.set(route, fn) },
+    moduleGraph: { getModuleById: () => null, invalidateModule: () => {} },
+    ws: { send: () => {} },
+    watcher: {
+      add: () => {},
+      on: (event, fn) => {
+        (watcherHandlers[event] ||= []).push(fn);
+      },
+    },
+    _invokeMiddleware(route, method = "GET") {
+      const fn = middlewares.get(route);
+      let body = "";
+      let nextCalled = false;
+      const headers = {};
+      const res = {
+        setHeader: (k, v) => {
+          headers[k] = v;
+        },
+        end: (chunk) => {
+          body = chunk;
+        },
+      };
+      fn({ url: route, method }, res, () => {
+        nextCalled = true;
+      });
+      return { body, headers, nextCalled };
+    },
+    _fireChange(file) {
+      for (const fn of watcherHandlers.change) fn(file);
+    },
+  };
+}
+
+async function bootPlugin() {
+  const plugin = ruact();
+  await plugin.configResolved({ root: dir });
+  await plugin.buildStart({});
+  const server = makeServer();
+  await plugin.configureServer(server);
+  return server;
+}
+
+describe("GET /__ruact/manifest (dev server middleware)", () => {
+  it("serves the current manifest as JSON without the internal _sourceFile field", async () => {
+    write("app/javascript/components/LikeButton.jsx", COMPONENT("LikeButton"));
+    const server = await bootPlugin();
+
+    const { body, headers } = server._invokeMiddleware("/__ruact/manifest");
+    expect(headers["Content-Type"]).toBe("application/json");
+
+    const manifest = JSON.parse(body);
+    expect(manifest).toHaveProperty("LikeButton");
+    expect(manifest.LikeButton).toMatchObject({
+      id: "/LikeButton.jsx",
+      name: "LikeButton",
+      chunks: ["/LikeButton.jsx"],
+    });
+    // The internal field used only during the prod build must never go on the wire.
+    expect(manifest.LikeButton).not.toHaveProperty("_sourceFile");
+  });
+
+  it("reflects a rebuild when a new component is added", async () => {
+    write("app/javascript/components/LikeButton.jsx", COMPONENT("LikeButton"));
+    const server = await bootPlugin();
+
+    expect(JSON.parse(server._invokeMiddleware("/__ruact/manifest").body)).not.toHaveProperty(
+      "CommentBox"
+    );
+
+    const added = write("app/javascript/components/CommentBox.jsx", COMPONENT("CommentBox"));
+    server._fireChange(added);
+
+    const manifest = JSON.parse(server._invokeMiddleware("/__ruact/manifest").body);
+    expect(manifest).toHaveProperty("LikeButton");
+    expect(manifest).toHaveProperty("CommentBox");
+    expect(manifest.CommentBox).not.toHaveProperty("_sourceFile");
+  });
+
+  it("falls through (calls next) for non-GET methods", async () => {
+    write("app/javascript/components/LikeButton.jsx", COMPONENT("LikeButton"));
+    const server = await bootPlugin();
+
+    const { body, nextCalled } = server._invokeMiddleware("/__ruact/manifest", "POST");
+    expect(nextCalled).toBe(true);
+    expect(body).toBe("");
+  });
+});

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruact
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors:
 - Luiz Garcia
@@ -85,6 +85,7 @@ files:
 - lib/ruact/flight/row_emitter.rb
 - lib/ruact/flight/serializer.rb
 - lib/ruact/html_converter.rb
+- lib/ruact/manifest_resolver.rb
 - lib/ruact/query.rb
 - lib/ruact/railtie.rb
 - lib/ruact/render_context.rb
@@ -159,6 +160,7 @@ files:
 - spec/ruact/flight/serializer_spec.rb
 - spec/ruact/html_converter_spec.rb
 - spec/ruact/install_generator_spec.rb
+- spec/ruact/manifest_resolver_spec.rb
 - spec/ruact/query_request_spec.rb
 - spec/ruact/query_spec.rb
 - spec/ruact/railtie_spec.rb
@@ -204,6 +206,7 @@ files:
 - vendor/javascript/vite-plugin-ruact/bootstrap.test.mjs
 - vendor/javascript/vite-plugin-ruact/index.js
 - vendor/javascript/vite-plugin-ruact/manifest-contract.test.mjs
+- vendor/javascript/vite-plugin-ruact/manifest-http.test.mjs
 - vendor/javascript/vite-plugin-ruact/package-lock.json
 - vendor/javascript/vite-plugin-ruact/package.json
 - vendor/javascript/vite-plugin-ruact/registry.test.mjs