ruact 0.0.16 → 0.0.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc962c661c39c1c9905f3aee2ddb2c956dc196218f283ef5532bf8c9826fe98f
-  data.tar.gz: c3211a4a820d0ad77daebcd5ee071f91b5f10c2be9153f0bb6e62cc8153c61c9
+  metadata.gz: 78c8550850bcded6e5585918c33d4520131a019520f4def020e9e5701a47c7ae
+  data.tar.gz: ab49c696c75137128062c6f9c7fa8b2569b8f918818bcf50f209d3939675af59
 SHA512:
-  metadata.gz: 8dcd8f0f4988c3a3e0f9950e6210d68986d980256a2ff9463a2847107513ad8c3090c9949f728aaebc810ccf1937d7c52589f267dd60b5a12ae6a70f9e1ce95a
-  data.tar.gz: 4c7c1bf1221798c93d183456f07cb4d4549b8ec4bfa56ff091133edff176c77bd9709f303fcbf372ffea994530aaefcb92c069d66abe9e861578578b64f68c20
+  metadata.gz: a4dda8e8c229d941a6d8e852704837259a45653002b2c7465764ae219c58fbaa4188d4490745efe88327ceb736094ccc265b6e38f2cc38d008388bf7cb5d1e88
+  data.tar.gz: 976492c9e23c34d777071ec0fa313ae146d942ba1ade21d939de380e012a0cedc4028c9e997dabe96518ad9b7b00bbd48a4c162eef9270969ba9e2bf5ce4e3a6

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.17] - 2026-10-06
+
+### Changed
+
+- **The browser reads the page with React's own Flight client.** ruact had its own decoder, and most of the transport bugs fixed in 0.0.12–0.0.16 lived in it. The runtime now uses React's `react-server-dom-webpack` client (`client.browser`), which ships inside the gem: version 19.3.0, MIT, regenerated by `vendor/javascript/vite-plugin-ruact/scripts/vendor-flight-client.mjs`. Nothing is added to the app's `package.json`. The npm package would also install `webpack`, which this avoids. An app that needs a different version adds `react-server-dom-webpack` to its own `package.json`, and the Vite plugin uses that copy instead; a copy that is only installed as another package's dependency is not used. Vite's startup and build output and `rails ruact:doctor` say which copy is in use, and the doctor warns when the app's copy is built for another React minor than the app's `react`. Supported React: `^19.2.8`, checked in CI against 19.2.8 and 19.3.0. The bundle grows: the nav-islands example went from 74.35 kB to 80.82 kB gzipped (+6.47 kB), and the `.gem` from 373 KB to 427 KB.
+
+- **The Flight wire changed to the format React's client reads.** The server and the browser runtime change together; a page served by this version needs this version's runtime. **When you deploy it,** a tab still open on the previous version cannot read the new responses: its next in-place navigation fails and the user has to reload. Code that parses ruact's wire itself, rather than through `Ruact::Testing`, needs updating:
+  - import rows are `[id, chunks, name]`, with `chunks` always `[]` (the runtime registers every component up front);
+  - a string of 1024 bytes or more is referenced as `"$<hex>"`, not `"$T<hex>"`;
+  - a `<Suspense>` boundary's type is a `"$Sreact.suspense"` symbol row, and its deferred content is a lazy child, `"children":"$L<hex>"`, inside a boundary the runtime registers as `ruact:boundary`;
+  - an error row is an object, `{"digest","name","message","stack","env"}`, whose `digest` is a stable code (`ruact:suspense-timeout`): React's production client keeps only the digest, and the runtime turns it back into the message;
+  - in development only, elements carry React's three development slots, so React does not warn about keys on ERB siblings and loops. The test environment keeps the production wire.
+
+  `Ruact::Testing`'s matchers read the new wire, and `have_ruact_component` ignores the runtime's own boundary.
+
+- **An error in a `<Suspense>` child no longer risks the whole page.** React unmounts the page on a render error no component catches. Each Suspense child now sits inside a boundary that keeps the fallback on screen and passes the error to the router's `onError` as `[ruact] Server error: …`, in production too, as before. The same goes for a response that ends before the Suspense row arrives (a server error mid-stream, a dropped connection): `[ruact] Server error: the response ended before the whole page arrived`. The boundary handles only what the server or the stream produced; a crash in your own component still reaches your error boundaries. The next response for the page (a navigation, `revalidate()`) renders normally.
+
+- **A render error shows on the page instead of emptying it.** React's client looks a client component up when it renders, so a component missing from the registry (no `"use client"`, a stale build) fails then, and React would remove the whole page. The page now shows `[ruact] Error: client component not registered: …` in its place, as the first load did before; the next navigation replaces it.
+
 ## [0.0.16] - 2026-10-03
 
 ### Fixed
@@ -436,7 +455,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **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.16...HEAD
+[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.17...HEAD
+[0.0.17]: https://github.com/luizcg/ruact/releases/tag/v0.0.17
 [0.0.16]: https://github.com/luizcg/ruact/releases/tag/v0.0.16
 [0.0.15]: https://github.com/luizcg/ruact/releases/tag/v0.0.15
 [0.0.14]: https://github.com/luizcg/ruact/releases/tag/v0.0.14

data/lib/ruact/client_manifest.rb

@@ -38,13 +38,22 @@ module Ruact
   # Story 13.5 preprocess-time call-site validator; +nil+ means "no contract →
   # no validation" (fail open).
   class ClientManifest
+    # The +chunks+ of every import row (see {#resolve}). One shared frozen
+    # array: a render resolves each component once, and the allocation guard
+    # counts every array.
+    NO_CHUNKS = [].freeze
+
     # Used by Flight::Serializer to produce I rows.
-    # Returns the metadata array the client expects: [id, name, chunks]
+    # Returns the metadata array React's Flight client reads: [id, chunks, name]
+    # (Story 18-1). +chunks+ is always empty: the browser runtime registers
+    # every client component eagerly (`virtual:ruact/registry`), so there is
+    # nothing to load — and React reads +chunks+ as `[chunkId, filename]` pairs,
+    # which the manifest's one-URL list is not.
     def resolve(module_id, _export_name)
       entry = by_module_id(module_id)
       raise "ClientManifest: no entry for module_id=#{module_id.inspect}" unless entry
 
-      [entry["id"], entry["name"], entry["chunks"]]
+      [entry["id"], NO_CHUNKS, entry["name"]]
     end
 
     # Returns true if +name+ is a top-level key in the manifest data.

data/lib/ruact/controller.rb

@@ -168,7 +168,9 @@ module Ruact
       # its headers on the first row.
       self.status = status if status
 
-      pipeline  = RenderPipeline.new(ruact_manifest, controller_path: controller_path, logger: logger)
+      pipeline  = RenderPipeline.new(ruact_manifest,
+                                     controller_path: controller_path, logger: logger,
+                                     development: Flight::Renderer.development_default)
       streaming = ruact_request? && self.class.ancestors.include?(ActionController::Live)
 
       # Allocate a per-render context and expose it to the view via a normal

data/lib/ruact/doctor.rb

@@ -8,8 +8,8 @@ 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 # rubocop:disable Metrics/ClassLength
-    CHECKS = %i[manifest vite controller layout head_assets streaming legacy_constant serialize_only
-                flight_middleware].freeze
+    CHECKS = %i[manifest vite flight_client controller layout head_assets 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).
@@ -42,8 +42,8 @@ module Ruact
       /\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)
+      # React Flight reader entry points invoked from Ruby (NOT the browser
+      # runtime's own calls, which read the server's own trusted payload)
       /\b#{%w[create From].join}(?:NodeStream|ReadableStream|Fetch)\b/
     ].freeze
     DESERIALIZE_SIGNAL_RE = Regexp.union(DESERIALIZE_SIGNALS)
@@ -163,6 +163,66 @@ module Ruact
        "Run npm run dev (or bin/dev) to start the Vite dev server."]
     end
 
+    # Story 18-1 — which copy of React's Flight client the browser runtime
+    # uses, decided as the Vite plugin decides it (`resolveFlightClient`): the
+    # app's `react-server-dom-webpack` when the app's package.json declares it
+    # and Node finds it from the app (a workspace may hoist it to a parent
+    # directory), otherwise the one vendored in the gem. The plugin prints the
+    # same line when Vite starts. The client is built for one React minor; the
+    # app's copy is checked against the app's `react`.
+    def check_flight_client
+      vendored = [:pass, "Flight client: react-server-dom-webpack #{vendored_flight_client_version} vendored in ruact"]
+      return vendored unless app_declares?("react-server-dom-webpack")
+
+      app_package = node_package_json("react-server-dom-webpack")
+      return vendored unless app_package
+
+      version = JSON.parse(app_package.read)["version"]
+      react_package = node_package_json("react")
+      react = react_package && JSON.parse(react_package.read)["version"]
+      message = "Flight client: react-server-dom-webpack #{version} from the app (replaces the copy in ruact)"
+      return [:pass, message] if react.nil? || minor(react) == minor(version)
+
+      [:warn, "#{message}, but the app's react is #{react}",
+       "Install the react-server-dom-webpack matching your react (npm install react-server-dom-webpack@#{react}), " \
+       "or uninstall it to use the copy vendored in ruact."]
+    rescue JSON::ParserError => e
+      [:warn, "Flight client: a package.json under node_modules is not valid JSON (#{e.message})",
+       "Reinstall it (npm install), or remove react-server-dom-webpack to use the copy vendored in ruact."]
+    end
+
+    # As the Vite plugin reads it: a non-empty entry in dependencies or
+    # devDependencies; an unreadable package.json declares nothing.
+    def app_declares?(name)
+      manifest = Rails.root.join("package.json")
+      return false unless manifest.exist?
+
+      json = JSON.parse(manifest.read)
+      [json["dependencies"], json["devDependencies"]].any? { |deps| deps.is_a?(Hash) && !deps[name].to_s.empty? }
+    rescue JSON::ParserError
+      false
+    end
+
+    # The first `node_modules/<name>/package.json` from Rails.root upward, the
+    # way Node resolves a package.
+    def node_package_json(name)
+      Pathname(Rails.root).expand_path.ascend do |dir|
+        candidate = dir.join("node_modules", name, "package.json")
+        return candidate if candidate.exist?
+      end
+      nil
+    end
+
+    def minor(version)
+      version.to_s.split(".").first(2).join(".")
+    end
+
+    def vendored_flight_client_version
+      path = File.join(File.dirname(Ruact.vite_plugin_path), "runtime", "vendor", "react-server-dom-webpack",
+                       "VERSION.json")
+      JSON.parse(File.read(path))["version"]
+    end
+
     # Story 17.0g (FR116) — reports the ADOPTION MODE instead of demanding one.
     #
     # Whole-app (`ruact:install --app`): ApplicationController includes the

data/lib/ruact/flight/renderer.rb

@@ -14,17 +14,30 @@ module Ruact
         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, &)
+      # Keyword options other than +streaming:+ go to {#initialize}
+      # (strict_serialization:, on_as_json_warning:, development:).
+      def self.each(model, bundler_config, streaming: true, **, &)
+        new(model, bundler_config, **).each(streaming: streaming, &)
       end
 
-      def initialize(model, bundler_config, strict_serialization: false, on_as_json_warning: nil)
+      # Whether rows carry the slots React's development client reads (see
+      # Serializer#element_tuple): in Rails' development environment only. The
+      # test environment keeps the production wire, so what a request spec
+      # asserts is what production sends.
+      def self.development_default
+        return false unless defined?(Rails) && Rails.respond_to?(:env)
+
+        Rails.env.development?
+      rescue StandardError
+        false
+      end
+
+      def initialize(model, bundler_config, strict_serialization: false, on_as_json_warning: nil,
+                     development: false)
         @request = Request.new(model, bundler_config,
                                strict_serialization: strict_serialization,
-                               on_as_json_warning: on_as_json_warning)
+                               on_as_json_warning: on_as_json_warning,
+                               development: development)
       end
 
       # Yields Flight rows one at a time.
@@ -50,7 +63,8 @@ module Ruact
           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"))
+              error = RowEmitter.error_payload("Suspense timeout exceeded", digest: "ruact:suspense-timeout")
+              yield RowEmitter.error(deferred[:id], JSON.generate(error))
               next
             end
             sleep(deferred[:delay])
@@ -58,7 +72,7 @@ module Ruact
 
           # Serialize deferred content — may produce new import rows, and new
           # regular rows (a string of 1024+ bytes becomes a `T` row the deferred
-          # model row references as `$T<id>`).
+          # model row references as `$<id>`).
           import_count_before  = @request.completed_import_chunks.length
           regular_count_before = @request.completed_regular_chunks.length
           deferred_value = serializer.serialize_model(deferred[:element])

data/lib/ruact/flight/request.rb

@@ -16,11 +16,15 @@ module Ruact
       # 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
+                  :strict_serialization, :on_as_json_warning, :development
 
-      def initialize(model, bundler_config, strict_serialization: false, on_as_json_warning: nil)
+      def initialize(model, bundler_config, strict_serialization: false, on_as_json_warning: nil,
+                     development: false)
         @strict_serialization = strict_serialization
         @on_as_json_warning   = on_as_json_warning
+        @development          = development
+        @suspense_symbol_ref  = nil
+        @boundary_ref         = nil
         @next_chunk_id = 0
         @pending_chunks = 0
         @bundler_config = bundler_config
@@ -42,6 +46,31 @@ module Ruact
         id
       end
 
+      # The `"$<hex>"` reference to this response's `"$Sreact.suspense"` symbol
+      # row, emitted once, before the first row that uses it.
+      def suspense_symbol_ref
+        @suspense_symbol_ref ||= begin
+          id = allocate_id
+          @completed_regular_chunks << RowEmitter.model(id, JSON.generate("$Sreact.suspense"))
+          "$#{id.to_s(16)}"
+        end
+      end
+
+      # The runtime's own client component that catches an error in a Suspense
+      # child (runtime/suspense-boundary.js). Not in the app's manifest: the
+      # runtime registers it under this id.
+      BOUNDARY_METADATA = ["ruact:boundary", [], "SuspenseBoundary"].freeze
+
+      # The `"$L<hex>"` reference to {BOUNDARY_METADATA}'s import row, emitted
+      # once per response.
+      def boundary_ref
+        @boundary_ref ||= begin
+          id = allocate_id
+          @completed_import_chunks << RowEmitter.import(id, JSON.generate(BOUNDARY_METADATA))
+          "$L#{id.to_s(16)}"
+        end
+      end
+
       def increment_pending
         @pending_chunks += 1
       end

data/lib/ruact/flight/row_emitter.rb

@@ -22,6 +22,15 @@ module Ruact
         "#{id.to_s(16)}:E#{error_json}\n"
       end
 
+      # The error object React's Flight client reads from an E row. Its
+      # development build reads `stack` and `env`; a bare string crashes it.
+      # Its production build drops the message and keeps `digest`, so the
+      # digest is a stable code the runtime turns back into the message
+      # (runtime/suspense-boundary.js, DIGEST_MESSAGES).
+      def self.error_payload(message, digest:)
+        { "digest" => digest, "name" => "Error", "message" => message, "stack" => [], "env" => "Server" }
+      end
+
       # A large text row (binary framing, no trailing newline)
       def self.text(id, text)
         byte_length = text.bytesize

data/lib/ruact/flight/serializer.rb

@@ -64,7 +64,9 @@ module Ruact
           @request.increment_pending
           row = RowEmitter.text(id, value)
           @request.completed_regular_chunks << row
-          return "$T#{id.to_s(16)}"
+          # A plain "$<hex>" reference: React reads "$T" as a temporary
+          # reference (Story 18-1).
+          return "$#{id.to_s(16)}"
         end
 
         # Escape leading $ so the client doesn't misinterpret it.
@@ -131,7 +133,16 @@ module Ruact
         key   = element.key
         props = serialize_hash(element.props)
 
-        ["$", resolved_type, key, props]
+        element_tuple(resolved_type, key, props)
+      end
+
+      # In development, React's client reads three more slots — owner, debug
+      # stack, and whether the children were validated. ERB has no `key`, so
+      # without the last one every element with sibling children or rendered in
+      # a loop logs React's "unique key" warning. Production reads four slots.
+      def element_tuple(type, key, props)
+        tuple = ["$", type, key, props]
+        @request.development ? tuple.push(nil, nil, 1) : tuple
       end
 
       # --- Suspense Boundary ---
@@ -143,11 +154,15 @@ module Ruact
 
         fallback_value = element.fallback ? serialize_model(element.fallback) : nil
 
-        # Children is an element tuple using the lazy ref as its type
-        lazy_ref = "$L#{deferred_id.to_s(16)}"
-        children_el = ["$", lazy_ref, nil, {}]
-
-        ["$", "$SS", nil, { "fallback" => fallback_value, "children" => children_el }]
+        # React's shape (Story 18-1): the type is a reference to a
+        # `"$Sreact.suspense"` symbol row, and the deferred content is a lazy
+        # child the client resolves when its row arrives. The lazy child sits
+        # inside the runtime's error boundary: an error row for it (a Suspense
+        # timeout) keeps the fallback on screen and reaches the router's
+        # `onError`, where an unhandled render error would unmount the page.
+        boundary = element_tuple(@request.boundary_ref, nil,
+                                 { "fallback" => fallback_value, "children" => "$L#{deferred_id.to_s(16)}" })
+        element_tuple(@request.suspense_symbol_ref, nil, { "fallback" => fallback_value, "children" => boundary })
       end
 
       # --- Unknown type fallback ---

data/lib/ruact/render_pipeline.rb

@@ -15,10 +15,15 @@ module Ruact
   class RenderPipeline
     VALID_MODES = %i[string stream].freeze
 
-    def initialize(manifest, controller_path: nil, logger: nil)
+    # @param development [Boolean] emit the element slots React's development
+    #   client reads (see Flight::Serializer#element_tuple). The controller
+    #   passes {Flight::Renderer.development_default}; everything else gets the
+    #   production wire.
+    def initialize(manifest, controller_path: nil, logger: nil, development: false)
       @manifest         = manifest
       @controller_path  = controller_path
       @logger           = logger
+      @development      = development
     end
 
     # Render a server component tree to Flight wire format.
@@ -194,7 +199,8 @@ module Ruact
         Flight::Renderer.each(root_element, @manifest,
                               strict_serialization: Ruact.config.strict_serialization,
                               on_as_json_warning: as_json_warning_callback,
-                              streaming: streaming) { |row| y << row }
+                              streaming: streaming,
+                              development: @development) { |row| y << row }
       end
     end
 
@@ -215,7 +221,8 @@ module Ruact
         Flight::Renderer.each(root_element, @manifest,
                               strict_serialization: strict,
                               on_as_json_warning: warning_cb,
-                              streaming: streaming) { |row| y << row }
+                              streaming: streaming,
+                              development: @development) { |row| y << row }
       end
     end
 

data/lib/ruact/testing/component_query.rb

@@ -10,7 +10,9 @@ module Ruact
     #
     # A component is TWO wire rows (Story 7.5 / FR108 semantics):
     #
-    #   * an `:import` row — `["<module path>", "<export name>", [chunks…]]` —
+    #   * an `:import` row — `["<module path>", [chunks…], "<export name>"]`
+    #     (React's order since Story 18-1; the older `[path, name, chunks]` is
+    #     still read) —
     #     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
@@ -27,8 +29,10 @@ module Ruact
       # A client-component element's type is "$L" followed by the import's hex id.
       CLIENT_REF = /\A\$L(?<hex>\h+)\z/
       # A string of 1024+ bytes travels as a `T` row, and the props hold a
-      # `"$T<hex>"` reference to it (Story 17-0d).
-      TEXT_REF = /\A\$T(?<hex>\h+)\z/
+      # `"$<hex>"` reference to it (Story 17-0d; `$T<hex>` before 18-1). A
+      # string that really starts with `$` travels escaped as `$$`, so this
+      # cannot match one.
+      TEXT_REF = /\A\$T?(?<hex>\h+)\z/
 
       # @param wire [String] the raw Flight wire byte string.
       def initialize(wire)
@@ -69,7 +73,10 @@ module Ruact
           next unless payload.is_a?(Array)
 
           module_path = payload[0]
-          export_name = payload[1]
+          # The runtime's own components (`ruact:boundary`) are not the app's.
+          next if module_path.is_a?(String) && module_path.start_with?("ruact:")
+
+          export_name = payload[1].is_a?(Array) ? payload[2] : payload[1]
           acc[row[:id]] = {
             module_path: module_path,
             export_name: export_name,

data/lib/ruact/testing/flight_wire_parser.rb

@@ -24,10 +24,10 @@ module Ruact
     # `Thread.current`.
     #
     # @example
-    #   wire = "1:I[\"/L.jsx\",\"L\",[\"/L.jsx\"]]\n0:[\"$\",\"$L1\",null,{}]\n"
+    #   wire = "1:I[\"/L.jsx\",[],\"L\"]\n0:[\"$\",\"$L1\",null,{}]\n"
     #   Ruact::Testing::FlightWireParser.parse(wire)
     #   # => [
-    #   #      { id: 1, class: :import, payload: ["/L.jsx", "L", ["/L.jsx"]], raw: "1:I...\n" },
+    #   #      { id: 1, class: :import, payload: ["/L.jsx", [], "L"], raw: "1:I...\n" },
     #   #      { id: 0, class: :model,  payload: ["$", "$L1", nil, {}],       raw: "0:[\"$\"...\n" }
     #   #    ]
     class FlightWireParser

data/lib/ruact/version.rb

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

data/vendor/javascript/vite-plugin-ruact/bootstrap.test.mjs

@@ -21,6 +21,8 @@ import ruact, {
   BOOTSTRAP_VIRTUAL_ID,
   REGISTRY_VIRTUAL_ID,
   generateBootstrapSource,
+  resolveFlightClient,
+  flightClientSource,
 } from "./index.js";
 
 const RESOLVED = "\0" + BOOTSTRAP_VIRTUAL_ID;
@@ -53,10 +55,13 @@ describe("virtual:ruact/bootstrap — load (Story 14.2)", () => {
   });
 
   it("imports the runtime modules via ABSOLUTE fs specifiers, not relative", () => {
-    expect(src).toMatch(/from '\/.*\/runtime\/flight-client\.js'/);
+    expect(src).toMatch(/from '\/.*\/runtime\/flight-modules\.js'/);
+    expect(src).toMatch(/import '\/.*\/runtime\/suspense-boundary\.js'/);
     expect(src).toMatch(/from '\/.*\/runtime\/ruact-router\.js'/);
+    // Story 18-1 — React's Flight client, through the plugin's virtual id.
+    expect(src).toContain("from 'virtual:ruact/flight-client'");
     // No `\0virtual:`-unresolvable relative import survives.
-    expect(src).not.toMatch(/from\s+['"]\.\/flight-client\.js['"]/);
+    expect(src).not.toMatch(/(from|import)\s+['"]\.\/[\w.-]+\.js['"]/);
     expect(src).not.toMatch(/from\s+['"]\.\/ruact-router\.js['"]/);
   });
 
@@ -94,3 +99,40 @@ describe("generateBootstrapSource — rewrites imports only (Story 14.2)", () =>
     fs.rmSync(dir, { recursive: true, force: true });
   });
 });
+
+// Story 18-1 — option C: which copy of React's Flight client answers.
+describe("resolveFlightClient", () => {
+  const make = (pkg, installed) => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ruact-rfc-"));
+    if (pkg) fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify(pkg));
+    if (installed) {
+      const mod = path.join(dir, "node_modules", "react-server-dom-webpack");
+      fs.mkdirSync(mod, { recursive: true });
+      fs.writeFileSync(path.join(mod, "package.json"), JSON.stringify({ name: "react-server-dom-webpack", version: installed }));
+    }
+    return dir;
+  };
+
+  it("uses the copy vendored in the gem when the app declares none", () => {
+    expect(resolveFlightClient(make({ dependencies: {} }), "development")).toMatchObject({ source: "vendored" });
+  });
+
+  it("uses the app's copy when the app declares and installs it", () => {
+    const dir = make({ dependencies: { "react-server-dom-webpack": "19.2.8" } }, "19.2.8");
+    expect(resolveFlightClient(dir, "production")).toEqual({ source: "app", version: "19.2.8", mode: "production" });
+  });
+
+  it("ignores a copy that is installed but not declared (another package's, hoisted)", () => {
+    expect(resolveFlightClient(make({ dependencies: {} }, "19.0.0"), "development")).toMatchObject({ source: "vendored" });
+  });
+
+  it("falls back to the vendored copy when declared but not installed yet", () => {
+    const dir = make({ devDependencies: { "react-server-dom-webpack": "19.2.8" } });
+    expect(resolveFlightClient(dir, "development")).toMatchObject({ source: "vendored" });
+  });
+
+  it("serves the app's copy behind the webpack globals, imported first", () => {
+    const src = flightClientSource({ source: "app", mode: "development" });
+    expect(src.indexOf("flight-webpack-globals.js")).toBeLessThan(src.indexOf("react-server-dom-webpack/client.browser"));
+  });
+});