ruact 0.0.15 → 0.0.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab61a580bf64e964d0356fae822cc80a83d31eaaa38fdfb5398e6534158772f0
-  data.tar.gz: c66021ed18cba60a650a6f1f4e77fc60b848079e2c125aa4f34f2868f6af2101
+  metadata.gz: 78c8550850bcded6e5585918c33d4520131a019520f4def020e9e5701a47c7ae
+  data.tar.gz: ab49c696c75137128062c6f9c7fa8b2569b8f918818bcf50f209d3939675af59
 SHA512:
-  metadata.gz: 053037bfb91205f625613499e5b98c14da4e886be7a94ef60239a1da934d44a35dbf104208494cc951eb7048c9bedbf1b8792c46ed9428e2a455f18d6141f729
-  data.tar.gz: '0800f0c8d28ea88c91b7d40b488ac6931b7548811cbfa0bd56458dbc9d0d4a09ab8f2db5a0884217045072b9a3889fa168cd83d969cb9f778bf22aab0ddc1cc8'
+  metadata.gz: a4dda8e8c229d941a6d8e852704837259a45653002b2c7465764ae219c58fbaa4188d4490745efe88327ceb736094ccc265b6e38f2cc38d008388bf7cb5d1e88
+  data.tar.gz: 976492c9e23c34d777071ec0fa313ae146d942ba1ade21d939de380e012a0cedc4028c9e997dabe96518ad9b7b00bbd48a4c162eef9270969ba9e2bf5ce4e3a6

data/CHANGELOG.md

@@ -7,6 +7,45 @@ 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
+
+- **A quoted attribute on a component was dropped without a word.** `<PostCard title="Hello" />` reached the component with no `title`: only `title={…}` was read, and the quoted form is the first thing a JSX hand writes. Component tags now take the three JSX forms. `name={ruby}` is a Ruby expression, as before — except that a hyphenated name keeps its hyphen: `aria-label={…}` used to arrive as `label`. `name="text"` is the string; a quoted value never runs Ruby. A bare `name` is `true`. Anything else raises a template error that names the attribute, including ERB inside a quoted value (`title="<%= @t %>"`), which a component attribute cannot run: write `title={@t}`.
+
+- **The Getting Started page logged a React error.** Server-rendered siblings, such as an `<h1>` next to a component or the rows of an ERB loop, reached React as an array of elements with no keys, and React logged "Each child in a list should have a unique key" on the guide's own example. Siblings are now handed to React as separate children, the way JSX compiles them, so React does not check them for keys. That covers the page itself, any element's children and the content a `<Suspense>` boundary streams in. No key is invented, and a key the template gives still wins. A data array passed as a `children` prop is left as it is.
+
+- **A form React handles itself also got a router request.** The client router decided on clicks and form submits before the app's own handlers ran, so a form whose `onSubmit` calls `preventDefault()` was also fetched by the router: the scaffold's form sent a stray `GET` of its own page on every save. The router now decides after them, and an event the app prevented is left alone. The same holds for a link whose `onClick` prevents the default. A handler that stops the event's propagation now also keeps it from the router, which then leaves the browser to follow the link or submit the form, as Turbo does.
+
+- **The install message said a component works in any ERB view.** In island mode, the default, it works in the views of a controller that has `include Ruact::Controller`; the message now says so.
+
+### Changed
+
+- **A server function no longer returns what callbacks and auth libraries put on the controller, or answers 500 because of it.** A function call's JSON was the controller's whole `view_assigns`. An authentication library that memoizes the user in an instance variable (Devise's `current_user` sets `@current_user` on its first call) put that user in every response. Under `strict_serialization`, on by default in production, a user model without `ruact_props` then made every function call answer 500. Two rules now decide what the JSON holds:
+  - **What callbacks set stays out, unless the action assigns it a different object.** `@post = Post.find(...)` in the action is returned. A `before_action :set_post` whose `@post` the action only updates in place (`@post.update(...)`) is not: reassign it (`@post = @post.reload`) or `render json:`. This covers plain values too: a callback's `@current_user_id = 5` is not returned, and neither is a value the action sets to the very same object the callback stored (`@count = 0` after a callback did the same, or a memoized helper's result).
+  - **Authentication and authorization memos are never returned,** even when the action fills them by calling `current_user` or `authorize`. The names are in the new `config.server_function_hidden_ivars`, default `["current_user", "current_ability", "pundit"]` for Devise's `:user` scope, CanCanCan and Pundit. Every name starting with `_` is hidden too. Add the memo of any other scope or helper, such as Devise's `@current_admin` for `devise_for :admins`: `config.server_function_hidden_ivars += ["current_admin"]`.
+
+  A page render's view still sees every instance variable.
+
 ## [0.0.15] - 2026-10-03
 
 ### Security
@@ -416,7 +455,9 @@ 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.15...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
 [0.0.13]: https://github.com/luizcg/ruact/releases/tag/v0.0.13

data/lib/generators/ruact/install/install_generator.rb

@@ -425,7 +425,8 @@ module Ruact
 
         show_shadcn_next_steps if shadcn?
 
-        say "\nThen add <MyComponent /> to any ERB view."
+        say "\nThen add <MyComponent /> to an ERB view of a ruact page:" unless whole_app?
+        say "\nThen add <MyComponent /> to any ERB view." if whole_app?
         say layout_summary
         say ""
         say "Note: re-run this generator after updating the ruact gem to refresh"

data/lib/generators/ruact/install/templates/AGENTS.md.tt

@@ -84,8 +84,8 @@ READ IT instead of simulating the name generation. Regenerate after routes/queri
    `<Suspense fallback="...">...</Suspense>` pair.
 2. **`{}` props are Ruby, not JavaScript.** `<Badge label={@post.title} />`
    evaluates `@post.title` as a Ruby expression in the ERB. No JS ternaries,
-   no `{...spread}`, no JSX children. Plain unbraced string props are not
-   supported either — always use braces.
+   no `{...spread}`, no JSX children. A quoted value (`title="Hi"`) is a
+   plain string and a bare attribute is `true`, as in JSX.
 3. **One action, two response shapes.** A `Ruact::Server` non-GET action
    answers JSON — its instance variables, or `204`, or `{"$redirect": path}` —
    when the request's `Accept` header is exactly `application/json`, which is

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/component_attributes.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Ruact
+  # The attributes of a PascalCase component tag in ERB, read the way JSX
+  # reads them (see {ErbPreprocessor}). Returns ordered
+  # +[name, ruby_expr]+ pairs for the props Hash the template renders.
+  module ComponentAttributes
+    ATTR_NAME_RE = /\A[a-zA-Z_][\w-]*/
+
+    # Parses the attributes string of a component tag into ordered
+    # +[name, ruby_expr]+ pairs, e.g. [["postId", "@post.id"], ["title", "\"Hi\""]].
+    # The names feed the Story 13.5 contract check; the pairs render the props
+    # Hash. The three JSX attribute forms:
+    #
+    #   name={ruby}   — the Ruby expression (nested braces honored)
+    #   name="text"   — the string, as JSX passes it (single quotes too)
+    #   name          — +true+, as JSX passes a bare attribute
+    #
+    # Anything else raises instead of being dropped: an unbraced attribute used
+    # to vanish without a word, and it is the first thing a JSX hand writes.
+    def self.parse(attrs_string)
+      attrs = attrs_string.sub(%r{\s*/\z}, "")
+      pairs = []
+      i = 0
+      while i < attrs.length
+        if attrs[i].match?(/\s/)
+          i += 1
+          next
+        end
+        name = attrs[i..][ATTR_NAME_RE] ||
+               raise(PreprocessorError, "unexpected #{attrs[i, 20].inspect} in the component's attributes")
+        i += name.length
+        i += 1 while attrs[i]&.match?(/\s/)
+        if attrs[i] == "="
+          i += 1
+          i += 1 while attrs[i]&.match?(/\s/)
+          value, i = parse_value(attrs, i, name)
+          pairs << [name, value]
+        else
+          pairs << [name, "true"]
+        end
+      end
+      pairs
+    end
+
+    # One attribute value at +attrs[i]+ → [ruby_expr, index after it].
+    def self.parse_value(attrs, pos, name)
+      case attrs[pos]
+      when "{"
+        expr = extract_braced_expr(attrs, pos + 1)
+        raise PreprocessorError, "#{name}={} is empty: put a Ruby expression in the braces" if expr.strip.empty?
+
+        [expr, pos + expr.length + 2]
+      when '"', "'"
+        close = attrs.index(attrs[pos], pos + 1)
+        text = attrs[(pos + 1)...(close || attrs.length)]
+        if text.include?("<%")
+          raise PreprocessorError, "#{name}= holds ERB, which a component attribute cannot run. " \
+                                   "Pass the Ruby in braces instead: #{name}={...}"
+        end
+        unless close
+          raise PreprocessorError, "unclosed quote in #{name}= (a component tag cannot contain `>`, " \
+                                   "even inside a quoted value: pass the text from Ruby instead)"
+        end
+
+        [text.inspect, close + 1]
+      else
+        raise PreprocessorError, "#{name}= needs a value: #{name}={ruby} or #{name}=\"text\""
+      end
+    end
+
+    # Given a string and a start position (just after the opening '{'),
+    # returns the content up to the matching '}'.
+    def self.extract_braced_expr(str, start)
+      depth = 1
+      i = start
+      while i < str.length && depth.positive?
+        case str[i]
+        when "{" then depth += 1
+        when "}" then depth -= 1
+        end
+        i += 1
+      end
+      raise PreprocessorError, "unclosed brace in prop expression" if depth.positive?
+
+      str[start...(i - 1)]
+    end
+
+    private_class_method :parse_value, :extract_braced_expr
+  end
+end

data/lib/ruact/configuration.rb

@@ -26,6 +26,7 @@ module Ruact
       shadcn_compatible_versions
       layout
       layout_stylesheets
+      server_function_hidden_ivars
     ].freeze
 
     # @!attribute [r] manifest_path
@@ -125,6 +126,19 @@ module Ruact
     #   @example Set an app-wide default expiry
     #     Ruact.configure { |c| c.signed_global_id_default_expires_in = 1.hour }
     #
+    # @!attribute [r] server_function_hidden_ivars
+    #   @return [Array<String>] Instance-variable names (no `@`) a server
+    #     function's JSON never returns, even when the action set them: the
+    #     memoization ivars of authentication and authorization libraries,
+    #     which an action fills just by calling `current_user` or `authorize`.
+    #     Names starting with `_` are always hidden. Default
+    #     `["current_user", "current_ability", "pundit"]` (Devise's `:user`
+    #     scope, CanCanCan, Pundit); another Devise scope memoizes its own
+    #     `@current_<scope>` — add it. Assign to replace the list; to keep the
+    #     defaults, add to them.
+    #   @example Also hide an app's own memoized account
+    #     Ruact.configure { |c| c.server_function_hidden_ivars += ["current_account"] }
+    #
     # @!attribute [r] shadcn_compatible_versions
     #   @return [Array<Integer>] Story 10.5 — the shadcn/ui MAJOR versions the
     #     `ruact:scaffold` generator is regression-tested against. When the
@@ -255,6 +269,7 @@ module Ruact
         @shadcn_compatible_versions = [1, 2, 4]
         @layout = false
         @layout_stylesheets = [:app]
+        @server_function_hidden_ivars = %w[current_user current_ability pundit]
       end
     end
 
@@ -278,6 +293,9 @@ module Ruact
     # @api private
     # @return [Ruact::Configuration] self, frozen
     def seal!
+      # An Array attribute mutated in place inside the block (`list << x`)
+      # never passed through its writer; validate it here, before publication.
+      validate_attribute_value!(:server_function_hidden_ivars, server_function_hidden_ivars)
       ATTRIBUTES.each do |attr|
         value = public_send(attr)
         next if value.nil? || value.frozen?
@@ -322,6 +340,7 @@ module Ruact
       when :shadcn_compatible_versions then validate_shadcn_compatible_versions!(value)
       when :layout                     then validate_layout!(value)
       when :layout_stylesheets         then validate_layout_stylesheets!(value)
+      when :server_function_hidden_ivars then validate_server_function_hidden_ivars!(value)
       end
     end
 
@@ -440,6 +459,15 @@ module Ruact
             "major versions (e.g. [1, 2]); got #{value.inspect}."
     end
 
+    # An Array of ivar names; a leading `@` is a typo that would hide nothing.
+    def validate_server_function_hidden_ivars!(value)
+      return if value.is_a?(Array) && value.all? { |name| name.is_a?(String) && !name.start_with?("@") }
+
+      raise Ruact::ConfigurationError,
+            "Ruact::Configuration#server_function_hidden_ivars must be an Array of instance-variable " \
+            "names without the @ (e.g. [\"current_user\"]); got #{value.inspect}."
+    end
+
     def build_error_message(attr, location)
       <<~MSG.strip
         ruact: cannot mutate Ruact::Configuration##{attr} after initialization.

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/erb_preprocessor.rb

@@ -51,11 +51,6 @@ module Ruact
     # unrelated `<% "</Dialog>" %>` appears later).
     ERB_ISLAND_RE = /<%.*?%>/m
 
-    # Matches a +{ruby_expr}+ attribute value — captures everything between the braces.
-    # We use a simple bracket-depth counter approach during scanning instead of regex
-    # because expressions can contain nested braces: {foo.bar({ a: 1 })}.
-    PROP_RE = /\b([a-zA-Z_][a-zA-Z0-9_]*)=\{/
-
     # Transform ERB source, replacing component tags with ERB placeholders.
     # Returns the transformed source string.
     #
@@ -114,7 +109,7 @@ module Ruact
           # 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)
+          pairs = ComponentAttributes.parse(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(", ")
@@ -247,46 +242,5 @@ module Ruact
       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
-
-      while (m = PROP_RE.match(remaining))
-        prop_name = m[1]
-        # Find the matching closing brace, respecting nesting
-        value_start = m.end(0)
-        value_expr  = extract_braced_expr(remaining, value_start)
-        pairs << [prop_name, value_expr]
-        # Advance past this prop
-        remaining = remaining[(value_start + value_expr.length + 1)..] # +1 for closing }
-        break if remaining.nil?
-      end
-
-      pairs
-    end
-
-    # Given a string and a start position (just after the opening '{'),
-    # returns the content up to the matching '}'.
-    def extract_braced_expr(str, start)
-      depth = 1
-      i = start
-      while i < str.length && depth.positive?
-        case str[i]
-        when "{" then depth += 1
-        when "}" then depth -= 1
-        end
-        i += 1
-      end
-      raise PreprocessorError, "unclosed brace in prop expression" if depth.positive?
-
-      str[start...(i - 1)]
-    end
   end
 end

data/lib/ruact/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 ---