ruact 0.0.16 → 0.0.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc962c661c39c1c9905f3aee2ddb2c956dc196218f283ef5532bf8c9826fe98f
-  data.tar.gz: c3211a4a820d0ad77daebcd5ee071f91b5f10c2be9153f0bb6e62cc8153c61c9
+  metadata.gz: afeffed3bf00af43d750b220dbffbdd62758269d578bb649912d7fbee157df86
+  data.tar.gz: 2bae60da180b2a5b6c85fe49c3adc42d3431c1cfee7666c9fdbf79b92815049b
 SHA512:
-  metadata.gz: 8dcd8f0f4988c3a3e0f9950e6210d68986d980256a2ff9463a2847107513ad8c3090c9949f728aaebc810ccf1937d7c52589f267dd60b5a12ae6a70f9e1ce95a
-  data.tar.gz: 4c7c1bf1221798c93d183456f07cb4d4549b8ec4bfa56ff091133edff176c77bd9709f303fcbf372ffea994530aaefcb92c069d66abe9e861578578b64f68c20
+  metadata.gz: 79f5785e73237b512b1fce27e9b085538c57954921bf92544fc8d4f80c2646f27e5e46baa23b1a565beb567b8e4762a108a0f2885b3ec85f9b822216889afadd
+  data.tar.gz: 3421862773a8f0669533bd70e39aed531b9ae2c4ce42205bc6939bc6311d76f5c45e4527d39752793bebc343af29ba96ebffd3fd58a6f414bb16fba879cfcbeb

data/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.18] - 2026-10-07
+
+### Added
+
+- **Client components take children from ERB.** Content between a component's opening and closing tags reaches it as `children`, evaluated on the server like the rest of the template: HTML, `<%= %>` output (escaped as usual), loops, conditionals, partials, and other components, the same one included.
+
+  ```erb
+  <Card title={@post.title}>
+    <p><%= @post.body %></p>
+    <LikeButton postId={@post.id} />
+  </Card>
+  ```
+
+  A component that declares a contract (`__ruactContract`) has to list `children` among its `props` or `slots` to take them. `<Suspense>` works inside a component and around one.
+
+- **A misspelled component name is caught where it is written.** When a manifest is available, a template naming a component that does not exist now fails while it compiles, with `Ruact::UnknownComponentError` naming the tag, the template's file and line, and the closest component (`Did you mean "LikeButton"?`). It used to fail at render with no location. Without a manifest the render reports it, as before.
+
+### Changed
+
+- **Every component tag must close.** `<Dialog open={true}>` with no closing tag used to render as a component without children. It now raises `Ruact::ComponentTagError` at file:line: write `<Dialog open={true} />`, or close it with `</Dialog>`. The same error names a closing tag that closes nothing, and a tag given both content and a `children={...}` prop.
+
+### Removed
+
+- **`Ruact::ChildrenNotSupportedError`.** It was raised for content between a component's tags, which is now supported. Rescue `Ruact::ComponentTagError` for tags that do not pair, or `Ruact::PreprocessorError` for any template error.
+
+## [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 +480,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.16...HEAD
+[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.18...HEAD
+[0.0.18]: https://github.com/luizcg/ruact/releases/tag/v0.0.18
+[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/README.md

@@ -11,7 +11,7 @@
      scripted and live with the project's other capture harnesses, and the message the demo
      shows is pinned here by `spec/readme_demo_message_spec.rb`. -->
 <img src="https://ruact.dev/readme-write-verify.gif" width="800"
-     alt="An ERB template holding a &lt;LikeButton likes=&#123;@likes&#125; /&gt; tag, and the &quot;use client&quot; React component that tag resolves to. The component renders in a browser and its count changes when it is clicked. Children are then put inside the tag — the JSX habit — and the next request stops server-side with Ruact::ChildrenNotSupportedError, which names the component, the template file and line, and the fix. The children come out again and the page renders." />
+     alt="An ERB template holding a &lt;LikeButton likes=&#123;@likes&#125; /&gt; tag, and the &quot;use client&quot; React component that tag resolves to. The component renders in a browser and its count changes when it is clicked. The tag&#39;s name is then misspelled, and the next request stops server-side with Ruact::UnknownComponentError, which names the tag, the template file and line, and the component it was probably meant to be. The name is corrected and the page renders." />
 
 ## Quick start
 

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

@@ -77,14 +77,14 @@ READ IT instead of simulating the name generation. Regenerate after routes/queri
 
 ## Five traps
 
-1. **Component tags take no children.** Client component tags are self-closing
-   ONLY: `<Card content={@body} />`, never `<Card>...</Card>`. Children (a
-   matching closing tag) fail LOUDLY with a `PreprocessorError` at preprocess
-   time — pass content as a prop instead. Sole exception: the built-in
-   `<Suspense fallback="...">...</Suspense>` pair.
+1. **Every component tag closes.** `<Badge label={@x} />` has no children;
+   `<Card title={@t}>...</Card>` passes the ERB between its tags — HTML, loops,
+   partials, other components — to the component as `children`. An opening tag
+   that never closes, or a closing tag with no opening, fails LOUDLY with a
+   `PreprocessorError` naming file:line. `<Suspense fallback="...">` pairs too.
 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. A quoted value (`title="Hi"`) is a
+   no `{...spread}`. 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}` —

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.
@@ -80,6 +89,24 @@ module Ruact
       end
     end
 
+    # Story 18-2 — whether +name+ resolves for SOME controller: the shared key,
+    # or a co-located one in any folder (`posts/_like_button`). The ERB
+    # preprocessor asks while it compiles a template, before it knows which
+    # controller will render it, so a co-located component is never refused
+    # for being looked up from a shared partial.
+    def component?(name)
+      return true if include?(name)
+
+      suffix = "/_#{pascal_to_snake_case(name)}"
+      entries_by_name.keys.any? { |key| key.end_with?(suffix) }
+    end
+
+    # Story 18-2 — the "not found" message {#reference_for} raises, for the
+    # preprocessor to put the template's file:line in front of.
+    def unknown_component_message(name, controller_path: nil)
+      build_unknown_component_message(name, controller_path)
+    end
+
     # Story 13.5 (FR100) — return the optional component +contract+ Hash for
     # +name+, or +nil+ when the component declared none (or is absent from the
     # manifest). Honors the same co-located/shared +resolve_key+ precedence as

data/lib/ruact/component_contract.rb

@@ -103,8 +103,10 @@ module Ruact
     # @param detail [String] the violation clause
     # @param where [Hash] keys +component+, +file+, +line+, +snippet+
     def self.raise_error(detail, where)
-      location = [where[:file], where[:line]].compact.join(":")
-      location = "(unknown location)" if location.empty?
+      location = if where[:file] then [where[:file], where[:line]].compact.join(":")
+                 elsif where[:line] then "line #{where[:line]}"
+                 else "(unknown location)"
+                 end
       message = "ruact: <#{where[:component]}> at #{location} #{detail}."
       message += "\n  in: #{where[:snippet]}" if where[:snippet] && !where[:snippet].empty?
       raise ComponentContractError, message

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