ruact 0.0.15 → 0.0.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab61a580bf64e964d0356fae822cc80a83d31eaaa38fdfb5398e6534158772f0
-  data.tar.gz: c66021ed18cba60a650a6f1f4e77fc60b848079e2c125aa4f34f2868f6af2101
+  metadata.gz: cc962c661c39c1c9905f3aee2ddb2c956dc196218f283ef5532bf8c9826fe98f
+  data.tar.gz: c3211a4a820d0ad77daebcd5ee071f91b5f10c2be9153f0bb6e62cc8153c61c9
 SHA512:
-  metadata.gz: 053037bfb91205f625613499e5b98c14da4e886be7a94ef60239a1da934d44a35dbf104208494cc951eb7048c9bedbf1b8792c46ed9428e2a455f18d6141f729
-  data.tar.gz: '0800f0c8d28ea88c91b7d40b488ac6931b7548811cbfa0bd56458dbc9d0d4a09ab8f2db5a0884217045072b9a3889fa168cd83d969cb9f778bf22aab0ddc1cc8'
+  metadata.gz: 8dcd8f0f4988c3a3e0f9950e6210d68986d980256a2ff9463a2847107513ad8c3090c9949f728aaebc810ccf1937d7c52589f267dd60b5a12ae6a70f9e1ce95a
+  data.tar.gz: 4c7c1bf1221798c93d183456f07cb4d4549b8ec4bfa56ff091133edff176c77bd9709f303fcbf372ffea994530aaefcb92c069d66abe9e861578578b64f68c20

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +436,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.15...HEAD
+[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.16...HEAD
+[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/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/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/server.rb

@@ -14,6 +14,7 @@ require_relative "../ruact"
 require_relative "server_functions/error_rendering"
 require_relative "server_functions/bucket_two_payload"
 require_relative "server_functions/name_bridge"
+require_relative "server_functions/action_assigns"
 require_relative "redirect_path"
 require_relative "validation_errors_collector"
 
@@ -69,6 +70,9 @@ module Ruact
   module Server
     extend ActiveSupport::Concern
 
+    # A function call returns the action's own ivars, not its callbacks'.
+    include Ruact::ServerFunctions::ActionAssigns
+
     include Ruact::ServerFunctions::ErrorRendering
     include Ruact::ValidationErrorsCollector
 
@@ -202,16 +206,16 @@ module Ruact
     # Story 9.2 AC2/AC4 (D1) — Bucket-2 success-path negotiation. When the
     # action finished without an explicit render on a function-call request
     # ({#__ruact_function_call?} — `Accept: application/json`, non-GET), serialize
-    # the action's exposed instance variables (Rails `view_assigns`, verbatim —
-    # the same set a view would see) as a JSON object keyed by ivar name, or
+    # the instance variables the ACTION assigned (Rails `view_assigns` minus
+    # what callbacks set and the action left alone — see
+    # {Ruact::ServerFunctions::ActionAssigns}) as a JSON object keyed by ivar name, or
     # `204 No Content` when none were set. Any other request shape falls through
     # to `super` so Bucket-1 rendering — the host's `Ruact::Controller` Flight
     # re-render, then Rails — is byte-for-byte unchanged (AC1).
     #
-    # The exposed-ivar set is Rails' own `view_assigns` with no custom filtering:
-    # Rails already excludes its protected `@_`-prefixed internals (including the
-    # CSRF `@_marked_for_same_origin_verification` flag), so what remains is
-    # exactly what the action assigned. Each value is serialized through the
+    # Rails' `view_assigns` already excludes its protected `@_`-prefixed
+    # internals (including the CSRF `@_marked_for_same_origin_verification`
+    # flag); ActionAssigns then drops what callbacks set. Each value is serialized through the
     # `ruact_props` / `Ruact::Serializable` / `strict_serialization` rules
     # ({Ruact::ServerFunctions::BucketTwoPayload}); a single ivar stays keyed
     # (no magic unwrap).
@@ -222,7 +226,7 @@ module Ruact
       # dev `@errors`) are dropped from the serialized assigns; Rails' own
       # `view_assigns` only filters a fixed set of `@_` ivars, not every `@__`
       # one (see {Ruact::ValidationErrorsCollector::RESERVED_ASSIGN_KEYS}).
-      assigns = view_assigns.except(*ValidationErrorsCollector::RESERVED_ASSIGN_KEYS)
+      assigns = __ruact_action_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

data/lib/ruact/server_functions/action_assigns.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Ruact
+  module ServerFunctions
+    # What a server function's JSON is made of (decision, 2026-10-03): the
+    # ivars the ACTION assigned, not everything a view would see.
+    #
+    # Two filters. Callbacks run before `send_action`, so what they put on the
+    # controller (a `set_post`, a `set_current_user`) is recorded there and
+    # left out of the JSON unless the action assigns it again. And some ivars
+    # are filled DURING the action without the action naming them — Devise's
+    # `current_user` memoizes `@current_user` on first call, Pundit's
+    # `authorize` sets `@pundit` — so names in
+    # `Ruact.config.server_function_hidden_ivars`, and every name starting
+    # with `_`, are never returned. Without these, a function call carried the
+    # signed-in user, and under `strict_serialization` (production's default)
+    # a user model without `ruact_props` made every call a 500. A page
+    # render's view still sees every ivar; only the function-call JSON
+    # narrows.
+    module ActionAssigns
+      # The snapshot's own name, kept out of what it filters.
+      CALLBACK_IVARS_KEY = "__ruact_callback_ivars"
+
+      private
+
+      def send_action(...)
+        if __ruact_function_call?
+          @__ruact_callback_ivars = instance_variables.to_h do |name|
+            [name.to_s.delete_prefix("@"), instance_variable_get(name)]
+          end
+        end
+        super
+      end
+
+      # +assigns+ minus what callbacks set and the action left holding the
+      # same object. Only a DIFFERENT object makes it the action's: setting
+      # the same value again (`@ok = false` after a callback did, a memoized
+      # helper returning what the callback already stored) leaves it out.
+      # Security first — a callback's `@current_user_id = 5` must not ride
+      # every response — at the price of a key that is absent when callback
+      # and action happen to agree.
+      def __ruact_action_assigns(assigns)
+        before = @__ruact_callback_ivars || {}
+        hidden = Ruact.config.server_function_hidden_ivars
+        assigns.reject do |name, value|
+          name == CALLBACK_IVARS_KEY || name.start_with?("_") || hidden.include?(name) ||
+            (before.key?(name) && before[name].equal?(value))
+        end
+      end
+    end
+  end
+end

data/lib/ruact/server_functions/bucket_two_payload.rb

@@ -7,7 +7,7 @@ require_relative "../errors"
 module Ruact
   module ServerFunctions
     # Story 9.2 — pure serializer for the Bucket-2 (imperative `await fn()`)
-    # response body. Takes the host action's exposed instance variables (Rails
+    # response body. Takes the instance variables the action returns (Rails
     # `view_assigns`, resolved by the caller) and produces a JSON-ready Ruby
     # Hash, keyed by ivar name, applying the SAME prop-exposure policy as the
     # Flight serializer ({Ruact::Flight::Serializer#serialize_unknown}):

data/lib/ruact/version.rb

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

data/lib/ruact.rb

@@ -9,6 +9,7 @@ require_relative "ruact/flight"
 require_relative "ruact/string_distance"
 require_relative "ruact/layout_source"
 require_relative "ruact/component_contract"
+require_relative "ruact/component_attributes"
 require_relative "ruact/erb_preprocessor"
 require_relative "ruact/render_context"
 require_relative "ruact/html_converter"

data/vendor/javascript/vite-plugin-ruact/flight-client.test.mjs

@@ -31,6 +31,7 @@
 // against shuffling being turned on later.
 
 import { describe, it, expect, beforeEach } from "vitest";
+import { Fragment } from "react";
 import fs from "node:fs";
 import path from "node:path";
 import {
@@ -450,3 +451,49 @@ describe("dates and big integers (Story 17-0c)", () => {
     expect(tree.literal).toBe("$D2026-01-01 is a string");
   });
 });
+
+// A server-rendered tree has unkeyed siblings (an <h1> beside a component, the
+// rows of an ERB loop). Handed to React as an array they made it log "Each
+// child in a list should have a unique key" on the Getting Started page. They
+// are passed as separate children instead — static, like JSX — and no key is
+// invented (an invented index key can collide with a template's own key and
+// duplicate a row, or reset state when a sibling comes or goes).
+describe("sibling children", () => {
+  const payload = [
+    '1:I["/TaskList.jsx","TaskList"]',
+    '0:[["$","h1",null,{"children":"Hello"}],["$","$L1",null,{"tasks":[]}],["$","ul",null,{"children":[["$","li",null,{"children":"a"}],["$","li","explicit",{"children":"b"}]]}]]',
+    "",
+  ].join("\n");
+
+  it("wraps several root siblings in a Fragment, without inventing keys", () => {
+    const tree = createFromFlightPayload(payload, MODULE_REGISTRY);
+    expect(tree.type).toBe(Fragment);
+    expect(tree.props.children.map((el) => el.key)).toEqual([null, null, null]);
+  });
+
+  it("keeps the template's own key and invents none for the others", () => {
+    const tree = createFromFlightPayload(payload, MODULE_REGISTRY);
+    const ul = tree.props.children[2];
+    expect(ul.props.children.map((el) => el.key)).toEqual([null, "explicit"]);
+    expect(ul.props.children).toHaveLength(2);
+  });
+
+  it("wraps a Suspense boundary's deferred siblings the same way", () => {
+    const deferred = buildTree([["$", "h2", null, { children: "A" }], ["$", "p", null, { children: "B" }]], EMPTY_ROWS, MODULE_REGISTRY);
+    expect(deferred.type).toBe(Fragment);
+    expect(deferred.props.children).toHaveLength(2);
+  });
+
+  it("does not spread a data array passed as children (it stays mutable)", () => {
+    const tree = createFromFlightPayload(payloadWithProps({ children: ["a", "b", "c"] }), MODULE_REGISTRY);
+    expect(tree.props.children).toEqual(["a", "b", "c"]);
+    expect(Object.isFrozen(tree.props.children)).toBe(false);
+  });
+
+  it("leaves a single root, data arrays and one-element children as they were", () => {
+    const tree = createFromFlightPayload(payloadWithProps({ tasks: [{ id: 1 }, { id: 2 }] }), MODULE_REGISTRY);
+    expect(tree.key).toBeNull();
+    expect(tree.props.tasks).toEqual([{ id: 1 }, { id: 2 }]);
+    expect(createFromFlightPayload('0:[1,2]\n', MODULE_REGISTRY)).toEqual([1, 2]);
+  });
+});

data/vendor/javascript/vite-plugin-ruact/runtime/flight-client.js

@@ -26,7 +26,7 @@
  *   - "$L{hex}" referencing a missing row → React.lazy() that resolves when the row arrives
  */
 
-import { createElement, Fragment, lazy, Suspense } from "react";
+import { createElement, Fragment, isValidElement, lazy, Suspense } from "react";
 
 // ---------------------------------------------------------------------------
 // Pending chunk registry — used for streaming Suspense deferred rows
@@ -273,7 +273,7 @@ export function buildTreeFromRows(rows, moduleRegistry) {
  * @param {Object} moduleRegistry
  */
 export function buildTree(value, rows, moduleRegistry) {
-  return _buildTree(value, rows, moduleRegistry);
+  return rootTree(_buildTree(value, rows, moduleRegistry));
 }
 
 /**
@@ -341,7 +341,7 @@ function _buildTree(value, rows, moduleRegistry) {
       }
       // Model row — deferred content already arrived (non-streaming path).
       // Wrap in a function component so it can be used as a type in createElement.
-      const content = _buildTree(row.value, rows, moduleRegistry);
+      const content = rootTree(_buildTree(row.value, rows, moduleRegistry));
       return () => content;
     }
     return value;
@@ -355,7 +355,7 @@ function _buildTree(value, rows, moduleRegistry) {
       const type   = resolveType(rawType, rows, moduleRegistry);
       const props  = buildProps(rawProps, rows, moduleRegistry);
       if (key != null) props.key = key;
-      return createElement(type, props);
+      return createWithChildren(type, props);
     }
 
     // Plain array — fragment children OR a data array sitting in a prop.
@@ -384,6 +384,34 @@ function _buildTree(value, rows, moduleRegistry) {
   return value;
 }
 
+// A server-rendered tree is static: siblings (an <h1> beside a component, the
+// rows of an ERB loop) carry no key on the wire. Handed to React as an ARRAY,
+// they made it log "Each child in a list should have a unique key" — on the
+// Getting Started page itself. Passed as separate arguments, the way JSX
+// compiles `<div><h1/><p/></div>`, they are static children React does not
+// key-check, and nothing is invented: a key the template gave still wins, and
+// reconciliation is the one React does for JSX. Two or more only — a single
+// child or an explicit one-element array keeps its shape (Story 17-0a).
+function createWithChildren(type, props) {
+  const { children } = props;
+  if (!Array.isArray(children) || children.length < 2 || !children.some(isValidElement)) {
+    return createElement(type, props); // a data array passed as `children` stays a plain array
+  }
+  const rest = { ...props };
+  delete rest.children;
+  return createElement(type, rest, ...children);
+}
+
+// The page's root — or a Suspense boundary's deferred content — when it is
+// several siblings: a Fragment of them, for the same reason as above (React
+// logged the warning against <App>).
+function rootTree(tree) {
+  if (Array.isArray(tree) && tree.length >= 2 && tree.some(isValidElement)) {
+    return createElement(Fragment, null, ...tree);
+  }
+  return tree;
+}
+
 function resolveType(rawType, rows, moduleRegistry) {
   if (typeof rawType === "string") {
     if (rawType === "$SS")        return Suspense;                                    // React.Suspense

data/vendor/javascript/vite-plugin-ruact/runtime/ruact-router.js

@@ -33,8 +33,13 @@ export function setupRouter({ onNavigate, moduleRegistry, onError = null }) {
   _moduleRegistry = moduleRegistry;
   _onError        = onError;
 
-  document.addEventListener("click",  handleClick,  { capture: true });
-  document.addEventListener("submit", handleSubmit, { capture: true });
+  // Bubble phase, on the document: the app's own handlers (React's, which
+  // listen on the root container, and any other) run first, so an
+  // `onSubmit`/`onClick` that calls preventDefault() keeps the event. In the
+  // capture phase the router decided before them: a React form that handles
+  // its own submit (the scaffold's) also got a router fetch of its URL.
+  document.addEventListener("click",  handleClick);
+  document.addEventListener("submit", handleSubmit);
   window.addEventListener("popstate", handlePopstate);
 
   // Story 8.2 — publish the revalidate handle the runtime helper reads.
@@ -56,8 +61,8 @@ export function setupRouter({ onNavigate, moduleRegistry, onError = null }) {
 }
 
 export function teardownRouter() {
-  document.removeEventListener("click",  handleClick,  { capture: true });
-  document.removeEventListener("submit", handleSubmit, { capture: true });
+  document.removeEventListener("click",  handleClick);
+  document.removeEventListener("submit", handleSubmit);
   window.removeEventListener("popstate", handlePopstate);
   _onNavigate     = null;
   _moduleRegistry = null;

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruact
 version: !ruby/object:Gem::Version
-  version: 0.0.15
+  version: 0.0.16
 platform: ruby
 authors:
 - Luiz Garcia
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-03 00:00:00.000000000 Z
+date: 2026-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -72,6 +72,7 @@ files:
 - lib/generators/ruact/scaffold/templates/views/show.html.erb.tt
 - lib/ruact.rb
 - lib/ruact/client_manifest.rb
+- lib/ruact/component_attributes.rb
 - lib/ruact/component_contract.rb
 - lib/ruact/configuration.rb
 - lib/ruact/controller.rb
@@ -105,6 +106,7 @@ files:
 - lib/ruact/serializable.rb
 - lib/ruact/server.rb
 - lib/ruact/server_functions.rb
+- lib/ruact/server_functions/action_assigns.rb
 - lib/ruact/server_functions/backtrace_cleaner.rb
 - lib/ruact/server_functions/bucket_two_payload.rb
 - lib/ruact/server_functions/codegen.rb