ruact 0.0.5 → 0.0.7

data/lib/ruact/doctor.rb

@@ -7,7 +7,7 @@ module Ruact
   # Runs a suite of installation health checks and prints ✓/✗ per check.
   # Extracted from the ruact:doctor Rake task for direct testability (FR27).
   class Doctor
-    CHECKS = %i[manifest vite controller layout streaming legacy_constant].freeze
+    CHECKS = %i[manifest vite controller layout streaming legacy_constant serialize_only flight_middleware].freeze
     # Built via Array#join so the gem-CI `name-propagation` guard does not
     # match these literals against itself (Story 5.1 review F4 — the doctor
     # file participates in the guard with no exclusion).
@@ -17,7 +17,61 @@ module Ruact
     LEGACY_SCAN_GLOBS = ["config/initializers/**/*.rb", "app/**/*.rb"].freeze
     RENAME_DOC_URL = "https://github.com/luizcg/ruact/blob/main/CHANGELOG.md#renamed"
 
-    # Runs all checks, prints results, returns true if all pass.
+    # --- Story 13.1: serialize-only invariant tripwire (FR97) ---------------
+    #
+    # ruact EMITS React Flight (`text/x-component`) but must never DESERIALIZE
+    # externally-supplied Flight into live Ruby objects — that keeps it outside
+    # the React2Shell / CVE-2025-55182 class (a Flight-deserialization RCE). See
+    # the ADR addendum in docs/internal/decisions/server-functions-api.md.
+    #
+    # The signal literals are assembled from fragments via Array#join so this
+    # file does NOT itself contain the matched strings (mirrors the LEGACY_CONST
+    # F4 lesson). `doctor.rb` is also excluded from the scan as defense in depth.
+    # Only structural inbound-deserialization signals are used; the raw
+    # `text/x-component` token is deliberately NOT a signal because the gem
+    # legitimately EMITS that media type (controller.rb / server.rb) — matching
+    # it would false-fail the current, invariant-holding tree.
+    DESERIALIZE_SIGNALS = [
+      # a `Deserializer` constant reference (FlightDeserializer, Flight::Deserializer, …);
+      # matched as a substring so both the joined and namespaced forms trip it
+      /#{%w[Deser ializer].join}/,
+      # methods that turn inbound Flight into Ruby objects
+      /\b#{%w[deserialize flight].join('_')}\b/,
+      /\b#{%w[from flight].join('_')}\b/,
+      /\b#{%w[parse flight].join('_')}\b/,
+      /\b#{%w[decode flight].join('_')}\b/,
+      # React Flight reader entry points invoked from Ruby (NOT createFromFlightPayload,
+      # which is the client/browser deserializing the server's own trusted payload)
+      /\b#{%w[create From].join}(?:NodeStream|ReadableStream|Fetch)\b/
+    ].freeze
+    DESERIALIZE_SIGNAL_RE = Regexp.union(DESERIALIZE_SIGNALS)
+    # A line carrying this annotation is a deliberate, reviewed deserializer and
+    # is treated as guarded (the check is a guard, not a blanket ban).
+    ALLOW_FLIGHT_DESERIALIZATION = ["# ruact:allow", "flight", "deserialization"].join("-")
+    # Exclude THIS file by its exact path (not basename) — its comments contain
+    # the literal `Deserializer` example, so it must not match its own scan; but
+    # a differently-located future file also named `doctor.rb` must still be
+    # scanned (review finding R1 — basename exclusion was too broad).
+    DOCTOR_FILE = File.expand_path(__FILE__)
+    SERIALIZE_ONLY_DOC = "docs/internal/decisions/server-functions-api.md (serialize-only invariant, FR97)"
+
+    # Response-transforming middleware that can mutate/recompress a streamed
+    # `text/x-component` Flight body and break the wire contract (React-on-Rails
+    # ops lesson). Matched by class name so the check needs no hard dependency.
+    RESPONSE_TRANSFORMING_MIDDLEWARE = %w[Rack::Deflater].freeze
+
+    # Statuses that do NOT fail the run. Anything else (including a malformed /
+    # future status) is treated as a failure (review finding R1).
+    SUCCESS_STATUSES = %i[pass warn].freeze
+
+    # @param serialize_only_root [String] directory whose `**/*.rb` is scanned
+    #   for the serialize-only tripwire. Defaults to the gem's own `lib/`;
+    #   injectable so specs can point it at a fixture tree.
+    def initialize(serialize_only_root: File.join(Ruact.gem_path, "lib"))
+      @serialize_only_root = serialize_only_root
+    end
+
+    # Runs all checks, prints results, returns true if none FAIL.
     def self.run
       new.run
     end
@@ -26,7 +80,10 @@ module Ruact
       puts "[ruact] Health check"
       results = CHECKS.map { |check| send(:"check_#{check}") }
       results.each { |status, message| puts format_result(status, message) }
-      passed = results.all? { |status, _| status == :pass }
+      # A :warn must NOT fail the run (Story 13.1 AC3); only :pass / :warn are
+      # success. An unexpected status (rendered `✗`) fails loudly rather than
+      # being silently treated as a pass (review finding R1).
+      passed = results.all? { |status, _| SUCCESS_STATUSES.include?(status) }
       puts "Run rails generate ruact:install to fix configuration issues" unless passed
       passed
     end
@@ -96,6 +153,74 @@ module Ruact
        "See #{RENAME_DOC_URL}."]
     end
 
+    # Story 13.1 (AC2) — fails when ruact's OWN Ruby source introduces an
+    # inbound Flight-deserialization entry point that is not explicitly
+    # annotated `# ruact:allow-flight-deserialization <reason>`. Passes silently
+    # when none exists (the current tree). Scans `@serialize_only_root/**/*.rb`,
+    # excluding this file and the generators' client-side templates.
+    def check_serialize_only
+      offenses = Dir[File.join(@serialize_only_root, "**", "*.rb")].flat_map do |file|
+        next [] if File.expand_path(file) == DOCTOR_FILE
+        next [] if file.match?(%r{/generators/.+/templates/})
+
+        File.foreach(file).with_index(1).filter_map do |line, lineno|
+          next unless DESERIALIZE_SIGNAL_RE.match?(line)
+          next if line.include?(ALLOW_FLIGHT_DESERIALIZATION)
+
+          "#{file}:#{lineno}"
+        end
+      end
+
+      if offenses.empty?
+        return [:pass, "Serialize-only invariant holds — no inbound Flight deserializer in ruact's Ruby source"]
+      end
+
+      [:fail,
+       "Inbound Flight deserializer entry point found in #{offenses.length} location(s) " \
+       "(first: #{offenses.first}). ruact is serialize-only: it may emit `text/x-component` " \
+       "but must never deserialize externally-supplied Flight into live Ruby objects " \
+       "(React2Shell / CVE-2025-55182 class). Remove it, or — if deliberate and reviewed — " \
+       "annotate the line with `#{ALLOW_FLIGHT_DESERIALIZATION} <reason>`. See #{SERIALIZE_ONLY_DOC}."]
+    end
+
+    # Story 13.1 (AC3) — WARNS (never fails) when a response-transforming
+    # middleware is mounted in the app's stack, since it may recompress/mutate a
+    # streamed `text/x-component` Flight body and break the wire contract.
+    def check_flight_middleware
+      stack = flight_middleware_stack
+      return [:pass, "No response-transforming middleware on the Flight wire path"] if stack.nil?
+
+      present = stack.filter_map { |mw| middleware_name(mw) }
+                     .select { |name| RESPONSE_TRANSFORMING_MIDDLEWARE.include?(name) }
+                     .uniq
+      return [:pass, "No response-transforming middleware on the Flight wire path"] if present.empty?
+
+      [:warn,
+       "#{present.join(', ')} is mounted and may transform `text/x-component` (Flight) responses, " \
+       "breaking the wire contract / streaming. Exclude Flight responses from compression " \
+       "(don't compress `text/x-component`) or mount it so it does not wrap the Flight routes."]
+    end
+
+    # Returns the app middleware stack to scan, or nil when unavailable (no
+    # Rails application present — e.g. the non-Rails / full-stub edge context).
+    # At real `rails ruact:doctor` time the `:environment` task has booted the
+    # app, so `app.middleware` is the enumerable `ActionDispatch::MiddlewareStack`.
+    # Before `initialize!` it is a `Rails::Configuration::MiddlewareStackProxy`
+    # (not enumerable) — skip it rather than crash on `filter_map`.
+    def flight_middleware_stack
+      return nil unless defined?(Rails) && Rails.respond_to?(:application)
+
+      app = Rails.application
+      return nil unless app.respond_to?(:middleware)
+
+      stack = app.middleware
+      stack.respond_to?(:each) ? stack : nil
+    end
+
+    def middleware_name(middleware)
+      middleware.respond_to?(:name) ? middleware.name : middleware.to_s
+    end
+
     def streaming_server_hint
       return "Puma"      if defined?(::Puma)
       return "Unicorn"   if defined?(::Unicorn)
@@ -110,7 +235,11 @@ module Ruact
     end
 
     def format_result(status, message)
-      status == :pass ? "✓ #{message}" : "✗ #{message}"
+      case status
+      when :pass then "✓ #{message}"
+      when :warn then "⚠ #{message}"
+      else            "✗ #{message}"
+      end
     end
   end
 end

data/lib/ruact/erb_preprocessor.rb

@@ -35,11 +35,22 @@ module Ruact
 
     # Transform ERB source, replacing component tags with ERB placeholders.
     # Returns the transformed source string.
-    def self.transform(source)
-      new.transform(source)
+    #
+    # +identifier+ is the template path (forwarded by {ErbPreprocessorHook} as
+    # +template.identifier+) so a Story 13.5 contract violation can name the
+    # call site's file:line. +registry+ is the component contract source — an
+    # injectable seam (Story 7.1 explicit-context grain); it defaults to the
+    # process-loaded {Ruact.manifest}. Pass +registry: nil+ (or a stub) in
+    # specs to control contract lookup; +nil+ forces fail-open (no validation).
+    def self.transform(source, identifier: nil, registry: :default)
+      new.transform(source, identifier: identifier, registry: registry)
     end
 
-    def transform(source)
+    def transform(source, identifier: nil, registry: :default)
+      # NOTE: +registry+ stays the +:default+ sentinel here. It is resolved to
+      # +Ruact.manifest+ LAZILY, only inside the component-tag block below — a
+      # source with no PascalCase tags must touch the registry not at all
+      # (AC2/AC6 fast-path invariant).
       # Step 1: transform <Suspense> paired tags into <ruact-suspense> HTML elements.
       # This runs before the general component regex so Suspense isn't treated as a component.
       result = source
@@ -47,7 +58,11 @@ module Ruact
                  attrs    = ::Regexp.last_match(1)
                  fallback = extract_string_attr(attrs, "fallback") || ""
                  escaped  = fallback.gsub('"', "&quot;")
-                 %(<ruact-suspense data-ruact-fallback="#{escaped}">)
+                 # Optional `delay="2.5"` — the server-side wait (seconds) before
+                 # the deferred chunk streams. Forwarded to SuspenseElement#delay.
+                 delay      = extract_string_attr(attrs, "delay")
+                 delay_attr = delay ? %( data-ruact-delay="#{delay.gsub('"', '&quot;')}") : ""
+                 %(<ruact-suspense data-ruact-fallback="#{escaped}"#{delay_attr}>)
                end
         .gsub(SUSPENSE_CLOSE_RE, "</ruact-suspense>")
 
@@ -59,9 +74,23 @@ module Ruact
         line           = result[0...match_start].count("\n") + 1
 
         begin
-          props_ruby = parse_props(attrs_string)
+          # 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 })
+          props_ruby = pairs.map { |name, expr| "#{name.inspect} => #{expr}" }.join(", ")
           props_hash = props_ruby.empty? ? "{}" : "{ #{props_ruby} }"
           %(<%= __ruact_component__(#{component_name.inspect}, #{props_hash}) %>)
+        rescue ComponentContractError
+          # Already carries file:line + offending prop + suggestion — re-raise
+          # AS-IS (do NOT append the generic "at line N: snippet" tail).
+          raise
         rescue PreprocessorError => e
           raise PreprocessorError, "#{e.message} at line #{line}: #{match.strip}"
         end
@@ -77,11 +106,41 @@ module Ruact
       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?
+    # Story 13.5 — run the opt-in contract check for +component_name+ against
+    # the parsed call-site prop +names+. Looks the contract up through the
+    # injected +registry+ seam and SKIPS ENTIRELY when there is none (no
+    # registry, registry without +contract_for+, or no contract for this
+    # component) — that is the AC2/AC6 fail-open path that keeps a contract-less
+    # component byte-identical. Invoked ONLY inside the component-tag block, so
+    # the no-tag fast path never reads the registry.
+    def validate_contract(registry, component_name, names, at:)
+      return unless registry.respond_to?(:contract_for)
+
+      contract = registry.contract_for(component_name, controller_path: controller_path_from(at[:file]))
+      return if contract.nil?
+
+      ComponentContract.validate(
+        component_name: component_name, prop_names: names, contract: contract, at: at
+      )
+    end
+
+    # Best-effort controller_path from a template identifier so a co-located
+    # component's contract resolves (e.g. ".../app/views/posts/show.html.erb"
+    # → "posts"). A wrong/absent guess is harmless: {ClientManifest#resolve_key}
+    # falls back to the shared PascalCase key.
+    def controller_path_from(identifier)
+      return nil unless identifier
+
+      m = identifier.to_s.match(%r{app/views/(.+)/[^/]+\z})
+      m && m[1]
+    end
+
+    # Parses the attributes string of a component tag into ordered
+    # +[name, ruby_expr]+ pairs, e.g. [["postId", "@post.id"], ["count", "5"]].
+    # Honors nested braces in values (via {#extract_braced_expr}). The names
+    # feed the Story 13.5 contract check; the pairs render the props Hash.
+    def parse_prop_pairs(attrs_string)
+      return [] if attrs_string.empty?
 
       pairs = []
       remaining = attrs_string.dup
@@ -91,13 +150,13 @@ module Ruact
         # 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}"
+        pairs << [prop_name, value_expr]
         # Advance past this prop
         remaining = remaining[(value_start + value_expr.length + 1)..] # +1 for closing }
         break if remaining.nil?
       end
 
-      pairs.join(", ")
+      pairs
     end
 
     # Given a string and a start position (just after the opening '{'),

data/lib/ruact/erb_preprocessor_hook.rb

@@ -14,7 +14,10 @@ module Ruact
     # 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))
+      # Story 13.5 — forward +template.identifier+ (the template file path) so a
+      # component-contract violation can name the call site's file:line. The
+      # contract registry defaults to the process-loaded +Ruact.manifest+.
+      super(template, ErbPreprocessor.transform(source, identifier: template.identifier))
     end
   end
 end

data/lib/ruact/errors.rb

@@ -12,6 +12,16 @@ module Ruact
   # Raised when the ERB preprocessor encounters a malformed component tag.
   class PreprocessorError < Error; end
 
+  # Story 13.5 (FR100) — raised by {Ruact::ComponentContract} at ERB
+  # preprocess-time when a `<Component .../>` call site violates the component's
+  # opt-in contract: a missing required prop/slot or an unknown prop name.
+  # Subclasses {PreprocessorError} so it flows through the same dev error
+  # overlay (NFR30 lineage) and the hook treats it uniformly — but the distinct
+  # class lets the preprocessor re-raise it AS-IS (its message already carries
+  # file:line + the offending prop + a "did you mean?" suggestion) instead of
+  # re-wrapping it with the generic "at line N: snippet" tail.
+  class ComponentContractError < PreprocessorError; end
+
   # Raised when application code attempts to mutate Ruact::Configuration outside
   # of a Ruact.configure block. The configuration is frozen after initialization
   # to prevent runtime drift; see Story 7.3 for the rationale and the decision
@@ -26,43 +36,6 @@ module Ruact
   # buried under a Nokogiri stack. See Story 7.4 for the rationale.
   class HtmlConverterError < Error; end
 
-  # Story 8.3 — raised by a standalone server-action block (a module that
-  # `extend`s {Ruact::ServerAction}) when its body invokes
-  # {Ruact::ServerFunctions::StandaloneContext#current_user} but no
-  # {Ruact::Configuration#current_user_resolver} has been configured. The
-  # message names both worked examples (Devise + hand-rolled session) so
-  # the developer can wire the resolver without leaving the stack trace.
-  class CurrentUserNotConfiguredError < Error
-    DEFAULT_MESSAGE = "Ruact.current_user requires Ruact.config.current_user_resolver to be set. " \
-                      "Example (Devise): Ruact.configure { |c| c.current_user_resolver = ->(env) { env['warden']&.user } }. " \
-                      "Example (hand-rolled session): Ruact.configure { |c| c.current_user_resolver = " \
-                      "->(env) { User.find_by(id: env['rack.session'][:user_id]) } }."
-
-    def initialize(message = DEFAULT_MESSAGE)
-      super
-    end
-  end
-
-  # Story 8.3 — raised inside a standalone server-action block to surface a
-  # non-2xx response without calling `render` (which the StandaloneContext
-  # does not expose). The endpoint dispatcher rescues this exception class
-  # and renders `status` + `body` verbatim, mirroring how a controller-hosted
-  # action would call `render(json: ..., status: ...)`.
-  class ActionError < Error
-    attr_reader :status, :body
-
-    # @param status [Symbol, Integer] HTTP status (e.g. :unprocessable_entity, 422).
-    # @param body [Object] the response payload. Hash/Array/scalar values are
-    #   rendered as JSON; nil renders an empty body.
-    # @param message [String] optional message; defaults to "ruact action error
-    #   (status=<status>)" so the exception is still legible in logs.
-    def initialize(status:, body: nil, message: nil)
-      @status = status
-      @body = body
-      super(message || "ruact action error (status=#{status.inspect})")
-    end
-  end
-
   # Story 9.5 (FR88) — raised by the query dispatch controller when a
   # `useQuery` request's parameters violate the kwargs allowlist: a complex
   # value (array / object) where only `string | number | boolean | null` is
@@ -74,14 +47,27 @@ module Ruact
   # fix the call site without reading the server source.
   class BadRequestError < Error; end
 
-  # Story 8.5 — raised by `EndpointController#__ruact_enforce_upload_limit!`
-  # when an inbound multipart / urlencoded request's `Content-Length` exceeds
+  # Story 13.2 (FR96) — raised by `Ruact.locate_signed` when a SignedGlobalID
+  # token fails verification: a tampered signature, an expired token, or a token
+  # scoped to a different `for:` purpose (`GlobalID::Locator.locate_signed`
+  # returns `nil`). Inherits from `Ruact::Error` so the Story 8.4
+  # `rescue_from StandardError` chain catches it cleanly; `__ruact_status_for`
+  # maps it to HTTP 400 (Bad Request) — a forged/expired reference is an
+  # invalid credential the client supplied, NOT a missing record. This keeps
+  # `ActiveRecord::RecordNotFound` from leaking and never reveals whether the
+  # target record exists (verification fails before any DB lookup). A *valid*
+  # token whose record was since deleted is NOT this error — the underlying
+  # finder (`ActiveRecord::RecordNotFound`) propagates and is the host's normal
+  # not-found concern, exactly as a raw `Model.find` would be.
+  class InvalidSignedGlobalIDError < Error; end
+
+  # Story 8.5 — raised by the `Ruact::Server` upload guard when an inbound
+  # multipart / urlencoded request's `Content-Length` exceeds
   # `Ruact.config.max_upload_bytes`. The exception inherits from
-  # `Ruact::Error` so the Story 8.4 `rescue_from StandardError` chain on
-  # `EndpointController` catches it cleanly; the endpoint controller's
-  # `__ruact_status_for` maps it to HTTP 413, and `ErrorPayload.build`
-  # extracts the `received_bytes` / `limit_bytes` pair into a dev-only
-  # `upload_limit` block alongside the four baseline keys.
+  # `Ruact::Error` so the Story 8.4 `rescue_from StandardError` chain catches
+  # it cleanly; `__ruact_status_for` maps it to HTTP 413, and
+  # `ErrorPayload.build` extracts the `received_bytes` / `limit_bytes` pair
+  # into a dev-only `upload_limit` block alongside the four baseline keys.
   #
   # The pair is exposed as `attr_reader` so the structured payload (and host
   # log lines) can show both numbers without re-parsing the message string.

data/lib/ruact/html_converter.rb

@@ -201,7 +201,28 @@ module Ruact
       child_nodes = convert_children(node)
       children = child_nodes.length == 1 ? child_nodes.first : child_nodes
 
-      Flight::SuspenseElement.new(fallback: fallback, children: children)
+      # Optional `delay="2.5"` from the ERB → SuspenseElement#delay (the
+      # server-side wait, in seconds, before the deferred chunk streams). When
+      # absent, blank, unparseable, or non-finite, SuspenseElement falls back to
+      # its default.
+      delay_attr = node["data-ruact-delay"]
+      delay = begin
+        if delay_attr && !delay_attr.to_s.strip.empty?
+          # A string overflow like "1e309" parses to Infinity (Float() does not
+          # raise) — guard finiteness so a non-finite delay can't reach the
+          # renderer's sleep(delay) and raise RangeError.
+          parsed = Float(delay_attr)
+          parsed.finite? ? parsed : nil
+        end
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      if delay
+        Flight::SuspenseElement.new(fallback: fallback, children: children, delay: delay)
+      else
+        Flight::SuspenseElement.new(fallback: fallback, children: children)
+      end
     end
 
     def convert_children(node)

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