ruact 0.0.6 → 0.0.8

data/lib/ruact/server.rb

@@ -104,6 +104,28 @@ module Ruact
       before_action :__ruact_set_vary_on_accept!
       after_action  :__ruact_set_vary_on_accept!
 
+      # Story 15.0 (F6) — dev-only legibility warning: an action that registers
+      # validation errors (`ruact_errors(record)`) and then performs an EXPLICIT
+      # render on a function-call request bypasses `default_render`, so the
+      # registered errors silently vanish from the JSON body. The warning names
+      # the opt-out; it never fires on the documented-correct patterns (Bucket-1
+      # page render, redirect on either bucket, the fall-through itself, or an
+      # action that never touches the collector). Log-only — bodies and statuses
+      # are byte-identical in every environment.
+      after_action :__ruact_warn_errors_injection_opt_out!
+
+      # Story 15.5 (FR109) — dev-only response-shape legibility log: one
+      # `[ruact]` line per ruact-NEGOTIATED request naming the chosen bucket +
+      # the deciding signal (e.g. `Accept: application/json + POST →
+      # function-call JSON`), so the dual-bucket negotiation is observable at
+      # runtime without a debugger. Adjacent to the F6 warning above so the two
+      # dev-only legibility hooks read as a pair. Same dev gate
+      # (`__ruact_development?`), same log-only invariant — bodies, statuses,
+      # and headers are byte-identical in every environment. SILENT outside
+      # development and on a plain Rails action on the same controller (a
+      # response ruact did not negotiate).
+      after_action :__ruact_log_response_shape!
+
       # Story 8.4 salvage — same registration order as v1 (Pitfall #1): the
       # generic StandardError entry first, the explicit
       # InvalidAuthenticityToken entry second so it wins Rails'
@@ -201,6 +223,12 @@ module Ruact
       # one (see {Ruact::ValidationErrorsCollector::RESERVED_ASSIGN_KEYS}).
       assigns = view_assigns.except(*ValidationErrorsCollector::RESERVED_ASSIGN_KEYS)
 
+      # Story 15.0 (F6) — reaching this branch means ruact itself is producing
+      # the function-call response (fall-through: injection, plain JSON, or
+      # 204), so the opt-out warning must stay silent. Set AFTER `view_assigns`
+      # is captured above so the flag ivar never leaks into the serialized body.
+      @__ruact_function_response_owned = true
+
       # Story 13.3 (FR98, AC3) — when the host opted into the validation-error
       # round-trip (`ruact_errors(@record)` was called this request), inject the
       # collected errors under the reserved JSON key `"errors"` alongside the
@@ -249,6 +277,11 @@ module Ruact
       _ensure_url_is_http_header_safe(location)
       location = _enforce_open_redirect_protection(location, allow_other_host: allow_other_host)
 
+      # Story 15.0 (F6) — a Bucket-2 `redirect_to` is a ruact-owned response
+      # (`$redirect`; registered errors ride flash), not an injection opt-out.
+      @__ruact_function_response_owned = true
+      # Story 15.5 (FR109) — mark the `$redirect` sub-shape for the dev log.
+      @__ruact_function_redirect = true
       render json: { "$redirect" => __ruact_redirect_path(location) }
     end
 
@@ -290,6 +323,136 @@ module Ruact
       url
     end
 
+    # Story 15.0 (F6) — the dev-only opt-out warning. Fires when ALL hold:
+    # development environment, the request is a function call
+    # ({#__ruact_function_call?}), the collector was touched
+    # (`ruact_errors(record)` ran this request), and the response was produced
+    # by an EXPLICIT host render — i.e. neither {#default_render}'s
+    # function-call branch nor the Bucket-2 {#redirect_to} set
+    # `@__ruact_function_response_owned`. In that shape the registered errors
+    # were silently dropped from the JSON body (the F6 finding).
+    #
+    # The four MUST-NOT-warn guardrails fall out of the predicate:
+    #   (a) Bucket-1 `render :new` — not a function call;
+    #   (b) `redirect_to` on either bucket — Bucket-2 sets the owned flag,
+    #       Bucket-1 is not a function call;
+    #   (c) the fall-through — `default_render` sets the owned flag;
+    #   (d) an untouched collector — `__ruact_errors_touched?` is false.
+    # The exception path never reaches here either: a raise aborts the
+    # after_action chain before this hook runs (`rescue_from` renders outside
+    # it), so a structured error payload is not misread as an opt-out.
+    def __ruact_warn_errors_injection_opt_out!
+      return unless __ruact_development?
+      return unless __ruact_function_call?
+      return unless __ruact_errors_touched?
+      return if @__ruact_function_response_owned
+
+      Rails.logger&.warn(
+        "[ruact] #{self.class.name}##{action_name} called `ruact_errors` and then rendered " \
+        "explicitly on a function-call request — the registered validation errors were NOT " \
+        "injected into the JSON response. Remove the explicit render and let the action fall " \
+        "through (ruact injects `errors` into the body), or surface them on a page render with " \
+        "`errors={ruact_errors}` / carry them through a `redirect_to` (flash)."
+      )
+    end
+
+    # Story 15.5 (FR109) — the dev-only response-shape log. Emits exactly one
+    # `[ruact]` line per ruact-negotiated request naming the chosen bucket and
+    # the deciding signal (Accept + verb), mirroring the vocabulary of the
+    # canonical caller→shape table in `server-actions.md`. Log-only: the
+    # response body, status, and headers are byte-identical to before in every
+    # environment.
+    #
+    # Coverage (D1, `Ruact::Server`-only for 15.5): the function-call-JSON
+    # bucket (incl. the `204` and `$redirect` sub-shapes) plus, for a page
+    # render on a controller that also includes {Ruact::Controller}, the
+    # Flight-page and HTML-shell shapes. A GET query (separate dispatch
+    # controller) and a page-only controller (includes `Ruact::Controller` but
+    # not `Ruact::Server`) are NOT covered — the table documents those shapes;
+    # extending the log to them is deferred (see deferred-work.md).
+    #
+    # SILENT (returns nil message) outside development and on a plain Rails
+    # action on the same controller — a response ruact did not negotiate
+    # (no function-call Accept and no ruact page render). A raise / before_action
+    # halt that skips the after_action chain is an accepted, documented log gap
+    # (identical to the F6 warning).
+    def __ruact_log_response_shape!
+      return unless __ruact_development?
+
+      message = __ruact_response_shape_log_message
+      return unless message
+
+      Rails.logger&.info(message)
+    end
+
+    # Classify the negotiated response shape from the request signals
+    # (`__ruact_function_call?`, Accept, verb) and the ruact-owned outcome flags
+    # (`@__ruact_function_redirect` set by the Bucket-2 {#redirect_to};
+    # `@__ruact_negotiated_page` set by {Ruact::Controller#emit_ruact_response} /
+    # its Flight `redirect_to`). Returns nil when ruact did not negotiate the
+    # response, so the log stays silent on plain Rails actions.
+    #
+    # @return [String, nil] the `[ruact] Ctrl#action — <signal> → <bucket>`
+    #   line, or nil for a non-negotiated response.
+    def __ruact_response_shape_log_message
+      shape, signal = __ruact_negotiated_shape_and_signal
+      return unless shape
+
+      "[ruact] #{self.class.name}##{action_name} — #{signal} → #{shape}"
+    end
+
+    # @return [Array(String, String), nil] `[bucket, deciding_signal]` for a
+    #   ruact-negotiated response, or nil for one ruact did not own.
+    def __ruact_negotiated_shape_and_signal
+      if __ruact_function_call?
+        [__ruact_function_call_shape, "Accept: application/json + #{request.request_method}"]
+      else
+        __ruact_page_shape_and_signal
+      end
+    end
+
+    # The function-call (Bucket-2) sub-shape, distinguished by the ruact-owned
+    # outcome: a `$redirect` directive, a `204 No Content` (no exposed ivars),
+    # or the ordinary serialized-ivars JSON.
+    def __ruact_function_call_shape
+      return "function-call $redirect" if @__ruact_function_redirect
+      return "function-call JSON (204, no ivars)" if response.status == 204
+
+      "function-call JSON"
+    end
+
+    # The page-render (Bucket-1 / HTML-shell) shape, keyed on the flag
+    # {Ruact::Controller#emit_ruact_response} set when ruact rendered the page.
+    # nil for a plain Rails render (the flag was never set) → the log stays
+    # silent on a non-negotiated response.
+    def __ruact_page_shape_and_signal
+      case @__ruact_negotiated_page
+      when :flight
+        ["Flight page", __ruact_flight_signal]
+      when :flight_redirect
+        ["Flight redirect", __ruact_flight_signal]
+      when :html_shell
+        ["HTML shell", "HTML-acceptable Accept, no Flight header"]
+      end
+    end
+
+    # The Flight deciding signal, faithful to how the request announced itself:
+    # the `Accept: text/x-component` header, or the `Ruact-Request: 1` header.
+    def __ruact_flight_signal
+      if request.headers["Accept"].to_s.include?("text/x-component")
+        "Accept: text/x-component"
+      else
+        "Ruact-Request: 1"
+      end
+    end
+
+    # @return [Boolean] true only in a real Rails development environment
+    #   (mirrors {Ruact::ManifestResolver.development?}).
+    def __ruact_development?
+      defined?(Rails) && Rails.respond_to?(:env) && Rails.env.respond_to?(:development?) &&
+        Rails.env.development?
+    end
+
     # Raw discriminator — does the request's `Accept` header equal
     # `application/json`? This is exactly what the 8.1 runtime sends on every
     # `_makeRef` fetch (Bucket 2 — imperative `await createPost(...)`).

data/lib/ruact/server_functions/introspection.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Ruact
+  module ServerFunctions
+    # Story 15.3 (FR107) — the machine-readable `ruact:routes --json` document:
+    # a read-only, side-effect-free view of the accessor/route table for headless
+    # agents and CI gates. Reuses the SAME collectors codegen consumes (via
+    # {Ruact::ServerFunctions.introspect}), so the introspection can never fork a
+    # parallel derivation and never writes the codegen bridge / TS module.
+    #
+    # ## Shape
+    #
+    #     { "schema_version" => Integer,
+    #       "accessors" => [
+    #         { "accessor" => String,   # the JS identifier (js_identifier)
+    #           "kind"     => String,   # "action" | "query"
+    #           "verb"     => String,   # HTTP method
+    #           "path"     => String,   # cleaned route path
+    #           "segments" => Array<String>,
+    #           "params"   => [{ "name" => String, "required" => Boolean }] } ] }
+    #
+    # Queries carry their declared kwargs as `params` (Story 13.4); actions carry
+    # their required path segments, uniformly shaped as `{ name, required: true }`.
+    # Per Story 15.3 decision D3 there is NO per-accessor component-contract link
+    # (accessors are server functions, not components) — the table reports
+    # accessors faithfully and omits the "target component contract" clause.
+    module Introspection
+      # Version of the `ruact:routes --json` document. **EXPERIMENTAL / UNSTABLE**:
+      # `0` signals the shape may change without a major version bump while the
+      # agent-facing surface is iterated — gate any parser on it. Distinct from
+      # {Ruact::Doctor::SCHEMA_VERSION} (a separate, independently-versioned
+      # document) and from {Snapshot::VERSION_V2} (the internal codegen bridge).
+      SCHEMA_VERSION = 0
+
+      class << self
+        # Builds the `ruact:routes --json` document from +route_set+. The resolver
+        # callables default to real constant resolution; specs inject lambdas.
+        #
+        # @param route_set [#routes] the Rails route set.
+        # @param host_predicate [#call, nil] forwarded to {ServerFunctions.introspect}.
+        # @param overrides_for [#call, nil] forwarded to {ServerFunctions.introspect}.
+        # @param query_class_for [#call, nil] forwarded to {ServerFunctions.introspect}.
+        # @return [Hash] the schema-versioned introspection document.
+        # @raise [Ruact::ConfigurationError] on any naming collision.
+        def as_json(route_set:, host_predicate: nil, overrides_for: nil, query_class_for: nil)
+          entries = ServerFunctions.introspect(
+            route_set: route_set,
+            host_predicate: host_predicate,
+            overrides_for: overrides_for,
+            query_class_for: query_class_for
+          )
+          {
+            "schema_version" => SCHEMA_VERSION,
+            "accessors" => entries.map { |entry| shape(entry) }
+          }
+        end
+
+        private
+
+        def shape(entry)
+          {
+            "accessor" => entry["js_identifier"],
+            "kind" => entry["kind"],
+            "verb" => entry["http_method"],
+            "path" => entry["path"],
+            "segments" => entry["segments"],
+            "params" => params_for(entry)
+          }
+        end
+
+        # Queries declare their params as kwargs (Story 13.4 → `params`); actions
+        # derive them from required path segments. Uniform `{ name, required }`.
+        def params_for(entry)
+          return entry["params"] if entry["kind"] == "query"
+
+          entry["segments"].map { |segment| { "name" => segment, "required" => true } }
+        end
+      end
+    end
+  end
+end

data/lib/ruact/server_functions.rb

@@ -29,6 +29,7 @@ module Ruact
     autoload :ValidationErrors,   "ruact/server_functions/validation_errors"
     autoload :QueryContext, "ruact/server_functions/query_context"
     autoload :QueryDispatch, "ruact/server_functions/query_dispatch"
+    autoload :Introspection, "ruact/server_functions/introspection"
 
     # Story 9.3 / 9.9 — orchestrates the route-driven (v2) codegen. Reads the
     # route table via {RouteSource} + {QuerySource}, writes the version-2 bridge
@@ -55,10 +56,7 @@ module Ruact
     #   `Rails.logger` when Rails is loaded, else nil.
     # @return [Array<Hash>] the exposed v2 entries (actions + queries).
     def self.write_v2_snapshot!(route_set:, root:, logger: default_logger)
-      actions = RouteSource.collect(route_set)
-      queries = QuerySource.collect(route_set)
-      entries = (actions + queries).sort_by { |entry| entry["js_identifier"] }
-      detect_merged_namespace_collisions!(entries)
+      entries = introspect(route_set: route_set)
 
       json_path = root.join("tmp/cache/ruact/server-functions.json")
       ts_path   = root.join("app/javascript/.ruact/server-functions.ts")
@@ -75,6 +73,30 @@ module Ruact
       entries
     end
 
+    # Story 15.3 (FR107) — the read-only, side-effect-free combine point:
+    # collect mutation actions ({RouteSource}) + read queries ({QuerySource}),
+    # sort by `js_identifier`, and run the merged-namespace collision check —
+    # WITHOUT writing the bridge/TS. Both {.write_v2_snapshot!} (codegen) and
+    # {Ruact::ServerFunctions::Introspection} (`ruact:routes --json`) call THIS,
+    # so what an agent verifies against can never drift from what codegen emits
+    # (single source of truth), and a CI gate can introspect without mutating the
+    # tree. The resolver callables default to real constant resolution; specs
+    # inject lambdas to exercise the derivation without booting controllers.
+    #
+    # @param route_set [#routes] the Rails route set.
+    # @param host_predicate [#call, nil] forwarded to {RouteSource.collect}.
+    # @param overrides_for [#call, nil] forwarded to {RouteSource.collect}.
+    # @param query_class_for [#call, nil] forwarded to {QuerySource.collect}.
+    # @return [Array<Hash>] merged action + query entries (string keys), sorted.
+    # @raise [Ruact::ConfigurationError] on any naming collision.
+    def self.introspect(route_set:, host_predicate: nil, overrides_for: nil, query_class_for: nil)
+      actions = RouteSource.collect(route_set, host_predicate: host_predicate, overrides_for: overrides_for)
+      queries = QuerySource.collect(route_set, query_class_for: query_class_for)
+      entries = (actions + queries).sort_by { |entry| entry["js_identifier"] }
+      detect_merged_namespace_collisions!(entries)
+      entries
+    end
+
     def self.default_logger
       defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : nil
     end

data/lib/ruact/testing/component_query.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "flight_wire_parser"
+
+module Ruact
+  module Testing
+    # Resolves "was component <name> rendered, and with what props?" out of a
+    # decoded Flight tree. Pure — no RSpec, no I/O. The public
+    # `have_ruact_component` matcher is a thin RSpec wrapper over this.
+    #
+    # A component is TWO wire rows (Story 7.5 / FR108 semantics):
+    #
+    #   * an `:import` row — `["<module path>", "<export name>", [chunks…]]` —
+    #     sourced from the client manifest (`reference_for`); its `:id` is the
+    #     integer the model rows reference; AND
+    #   * one or more `:model` rows carrying a React element
+    #     `["$", "$L<hex id>", key, {props}]` whose type references that import.
+    #
+    # `have_ruact_component("PostList")` matches the import row's DECLARED name
+    # (D3): its export name OR its module basename (`/PostList.jsx` → `PostList`)
+    # — honest to what the wire actually contains, not the ERB tag or a mapping
+    # the wire does not carry. Props are read from the model element's 4th slot
+    # in their SERIALIZED wire form (D4: string keys, serialized values).
+    class ComponentQuery
+      # A React element on the wire is a 4-tuple whose head is the sentinel "$".
+      ELEMENT_HEAD = "$"
+      # A client-component element's type is "$L" followed by the import's hex id.
+      CLIENT_REF = /\A\$L(?<hex>\h+)\z/
+
+      # @param wire [String] the raw Flight wire byte string.
+      def initialize(wire)
+        @rows = FlightWireParser.parse(wire)
+        @imports = index_imports(@rows)
+        @instances = collect_instances(@rows)
+      end
+
+      # @return [Boolean] whether any instance of `name` was rendered.
+      def rendered?(name)
+        !props_for(name).empty?
+      end
+
+      # @return [Array<Hash>] the serialized props hash of every rendered
+      #   instance of `name`, in wire order. Empty when `name` was not rendered.
+      def props_for(name)
+        ids = import_ids_for(name)
+        return [] if ids.empty?
+
+        @instances.select { |inst| ids.include?(inst[:ref_id]) }.map { |inst| inst[:props] }
+      end
+
+      # @return [Array<String>] every distinct component name present in the
+      #   wire (by declared export name), for a legible failure message.
+      def rendered_names
+        rendered_ids = @instances.map { |inst| inst[:ref_id] }.uniq
+        @imports.slice(*rendered_ids).map { |_, meta| meta[:export_name] }.uniq
+      end
+
+      private
+
+      def index_imports(rows)
+        rows.each_with_object({}) do |row, acc|
+          next unless row[:class] == :import
+
+          payload = row[:payload]
+          next unless payload.is_a?(Array)
+
+          module_path = payload[0]
+          export_name = payload[1]
+          acc[row[:id]] = {
+            module_path: module_path,
+            export_name: export_name,
+            basename: module_path.is_a?(String) ? File.basename(module_path, ".*") : nil
+          }
+        end
+      end
+
+      def import_ids_for(name)
+        @imports.select do |_id, meta|
+          meta[:export_name] == name || meta[:basename] == name
+        end.keys
+      end
+
+      # Walk every model row's payload, collecting each client-component element
+      # `["$", "$L<hex>", key, props]` as `{ ref_id:, props: }`.
+      def collect_instances(rows)
+        instances = []
+        rows.each do |row|
+          next unless row[:class] == :model
+
+          walk(row[:payload], instances)
+        end
+        instances
+      end
+
+      def walk(node, instances)
+        if element?(node)
+          ref = node[1].match(CLIENT_REF)
+          instances << { ref_id: ref[:hex].to_i(16), props: node[3] } if ref
+          # An element's props/children may themselves contain nested elements.
+          walk(node[3], instances)
+        elsif node.is_a?(Array)
+          node.each { |child| walk(child, instances) }
+        elsif node.is_a?(Hash)
+          node.each_value { |child| walk(child, instances) }
+        end
+      end
+
+      def element?(node)
+        node.is_a?(Array) && node.length >= 4 && node[0] == ELEMENT_HEAD && node[1].is_a?(String)
+      end
+    end
+  end
+end

data/lib/ruact/testing/flight_extractor.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Ruact
+  module Testing
+    # Raised by {FlightExtractor.extract} when the given response/String is not
+    # a Flight page render — most importantly when it is a plain-JSON
+    # function-call/query response. The message tells the spec author what they
+    # were handed and how to assert on it instead. Public: hosts may rescue it.
+    class NotAFlightResponseError < StandardError; end
+
+    # Pulls the Flight wire byte string out of whatever a host request spec
+    # hands the `have_ruact_component` matcher: an ActionDispatch/Rack response
+    # object (read via `.body`) or a raw String, in either of the two page
+    # shapes ruact emits —
+    #
+    #   1. a raw `text/x-component` body (RSC/navigation request), OR
+    #   2. a full HTML document embedding the payload in the `__FLIGHT_DATA`
+    #      bootstrap `<script>` (a plain browser GET).
+    #
+    # A `Ruact::Server` function-call/query answer is plain JSON, not Flight —
+    # feeding it here raises {NotAFlightResponseError} pointing at `JSON.parse`,
+    # rather than silently failing to parse. Pure: no I/O, no global state.
+    module FlightExtractor
+      # Matches the `<local>.push("<ruby-inspected literal>")` line the
+      # `__FLIGHT_DATA` bootstrap script emits (see
+      # `Ruact::ViewHelper#ruact_flight_data_script`). ANCHORED to the queue
+      # assignment (`self.__FLIGHT_DATA = self.__FLIGHT_DATA || [])`) so an
+      # unrelated earlier script on the page (analytics `dataLayer.push(…)`,
+      # etc.) can never be mistaken for the Flight payload. The captured group
+      # is the full double-quoted Ruby string literal (quotes included),
+      # honoring escaped quotes so a `\"` inside the payload does not end it.
+      FLIGHT_DATA_PUSH = /
+        self\.__FLIGHT_DATA\s*=\s*self\.__FLIGHT_DATA\s*\|\|\s*\[\]\)\s*;   # queue assignment
+        \s*[A-Za-z_$][\w$]*\.push\(                                        # <local>.push(
+        (?<literal>"(?:\\.|[^"\\])*")
+        \)\s*;
+      /mx
+
+      # A Flight wire body always starts with a row header: `<hex>:` (id + colon)
+      # or a hint row `:H`. JSON bodies start with `{`/`[`/`"`; HTML with `<`.
+      FLIGHT_ROW_START = /\A\s*(?:\h+:|:H)/
+
+      # Reverses `String#inspect` on the captured `__FLIGHT_DATA` literal.
+      # `JSON.parse` is unsafe here: Ruby's inspect escapes sequences JSON
+      # rejects (`\#` before `{`/`$`/`@`, `\e`, `\a`, …). These are the common
+      # single-char escapes; an unrecognized `\c` yields the literal `c`.
+      SIMPLE_ESCAPES = {
+        "n" => "\n", "t" => "\t", "r" => "\r", "s" => " ", "0" => "\0",
+        "a" => "\a", "b" => "\b", "e" => "\e", "f" => "\f", "v" => "\v",
+        '"' => '"', "\\" => "\\"
+      }.freeze
+
+      class << self
+        # @param response_or_string [#body, String] a response object or a raw
+        #   body String.
+        # @return [String] the extracted Flight wire byte string.
+        # @raise [NotAFlightResponseError] when the input is a JSON function-call
+        #   response, an empty body, or otherwise not a Flight page render.
+        def extract(response_or_string)
+          body, content_type = read(response_or_string)
+          return extract_by_content_type(body, content_type) if content_type
+
+          extract_by_sniffing(body)
+        end
+
+        private
+
+        # Reads `[body, content_type]` from a response object or String. A bare
+        # String has no content type; a response object may expose one via
+        # `content_type`/`media_type` (rack-test, ActionDispatch) — read
+        # defensively so any duck-typed `.body` object still works.
+        def read(response_or_string)
+          return [response_or_string, nil] if response_or_string.is_a?(String)
+
+          unless response_or_string.respond_to?(:body)
+            raise NotAFlightResponseError,
+                  "have_ruact_component expects a response object (responds to #body) or a String, " \
+                  "got #{response_or_string.class}."
+          end
+
+          [response_or_string.body.to_s, content_type_of(response_or_string)]
+        end
+
+        def content_type_of(response)
+          %i[media_type content_type].each do |m|
+            next unless response.respond_to?(m)
+
+            value = response.public_send(m)
+            return value.to_s.split(";").first&.strip unless value.nil? || value.to_s.empty?
+          end
+          nil
+        rescue StandardError
+          nil
+        end
+
+        def extract_by_content_type(body, content_type)
+          case content_type
+          when "text/x-component"
+            ensure_present!(body)
+            body
+          when "text/html", "application/xhtml+xml"
+            from_html(body)
+          when "application/json"
+            raise_json_error(body)
+          else
+            # Unknown content type — fall back to sniffing the bytes.
+            extract_by_sniffing(body)
+          end
+        end
+
+        def extract_by_sniffing(body)
+          ensure_present!(body)
+
+          return from_html(body) if body.include?("__FLIGHT_DATA")
+          return body if body.match?(FLIGHT_ROW_START)
+          # An HTML document that rendered no component reaches `from_html`,
+          # which raises the actionable "no `__FLIGHT_DATA` payload" error.
+          return from_html(body) if html_body?(body)
+
+          raise_json_error(body) if json_body?(body)
+
+          raise NotAFlightResponseError,
+                "have_ruact_component could not find a Flight payload in the response. " \
+                "The body is neither a raw `text/x-component` Flight body nor an HTML shell " \
+                "embedding `__FLIGHT_DATA`. First bytes: #{body[0, 80].inspect}"
+        end
+
+        def from_html(html)
+          match = html.match(FLIGHT_DATA_PUSH)
+          unless match
+            raise NotAFlightResponseError,
+                  "have_ruact_component received an HTML document with no `__FLIGHT_DATA` payload. " \
+                  "This response did not render a ruact component (no Flight data was inlined)."
+          end
+
+          decode_ruby_string_literal(match[:literal])
+        end
+
+        def json_body?(body)
+          stripped = body.lstrip
+          stripped.start_with?("{", "[", "\"")
+        end
+
+        def html_body?(body)
+          stripped = body.lstrip
+          stripped.start_with?("<") && /<(?:!doctype\b|html\b|body\b|div\b|head\b)/i.match?(stripped)
+        end
+
+        def raise_json_error(body)
+          raise NotAFlightResponseError,
+                "have_ruact_component received a plain-JSON response, not a Flight page. " \
+                "`Ruact::Server` function-call and query responses answer JSON — assert on them with " \
+                "`JSON.parse(response.body)` and a status check, not `have_ruact_component`. " \
+                "First bytes: #{body[0, 80].inspect}"
+        end
+
+        def ensure_present!(body)
+          return unless body.nil? || body.empty?
+
+          raise NotAFlightResponseError,
+                "have_ruact_component received an empty response body — nothing was rendered. " \
+                "(A 204/no-content function-call response has no Flight payload.)"
+        end
+
+        def decode_ruby_string_literal(literal)
+          inner = literal[1..-2] # strip surrounding quotes
+          out = +""
+          pos = 0
+          len = inner.length
+          while pos < len
+            ch = inner[pos]
+            if ch == "\\" && pos + 1 < len
+              decoded, consumed = decode_escape(inner, pos + 1)
+              out << decoded
+              pos += 1 + consumed
+            else
+              out << ch
+              pos += 1
+            end
+          end
+          out
+        end
+
+        # Decodes the escape sequence that begins at `inner[pos]` (the char right
+        # after the backslash). Returns `[decoded_string, input_chars_consumed]`
+        # where `input_chars_consumed` counts only the chars AFTER the
+        # backslash, so the caller can advance its cursor precisely.
+        def decode_escape(inner, pos)
+          ch = inner[pos]
+          case ch
+          when "u" then decode_unicode(inner, pos)
+          when "x" then decode_hex(inner, pos)
+          else
+            [SIMPLE_ESCAPES.fetch(ch, ch), 1]
+          end
+        end
+
+        # `\u{XXXX}` (braced, possibly multiple code points) or `\uXXXX`.
+        def decode_unicode(inner, pos)
+          if inner[pos + 1] == "{"
+            close = inner.index("}", pos + 2) || (return ["u", 1])
+            hex = inner[(pos + 2)...close]
+            decoded = hex.split.map { |cp| cp.to_i(16) }.pack("U*")
+            [decoded, (close - pos) + 1]
+          else
+            hex = inner[(pos + 1), 4].to_s
+            [[hex.to_i(16)].pack("U"), 1 + hex.length]
+          end
+        end
+
+        # `\xHH` (one or two hex digits).
+        def decode_hex(inner, pos)
+          hex = inner[(pos + 1)..].to_s[/\A\h{1,2}/].to_s
+          return ["x", 1] if hex.empty?
+
+          [[hex.to_i(16)].pack("C").force_encoding(inner.encoding), 1 + hex.length]
+        end
+      end
+    end
+  end
+end