ruact 0.0.20 → 0.0.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69c5f93d5a39e751e7f69b953ffd1101660e464df4397cadee932c12ba81b4fd
-  data.tar.gz: 518c3a0c1183cbc82fd13ca3d6d621502e28713b5d9dd21bd46beeca30ecc775
+  metadata.gz: 769b242b14222272ed72cf6fedeaf732de780ce3d57d4f6b916ecf8a4cd17faa
+  data.tar.gz: d639e44c10c4524ece71cebbb8d3e135484ec6715792492b17a986347937a6fd
 SHA512:
-  metadata.gz: 115756074639ab4849ae2982cf7d4e13176f20f383302f8961b1ed5f09148e1bec74560f2e1f42ef2aa26262449d6c0536c89ce205748176bad9aa0f5006fbfb
-  data.tar.gz: c55a816d7f40810470e42f86f8111ae3fc2e1e4ab150a31153626c26dedb8de1f76166483acb004722239d1696626bbe0bef218237bb34b665da7320e7e200c2
+  metadata.gz: 03f1a1c07dd0ee8594765e72f6e2d54762c6ac336a74929b2ce9fe531b6fff2c4ca15a2c87c81e7e4fada9dd645ab9e46c12e7f09b9b556c5055db76d3086f6f
+  data.tar.gz: '03931869edf24e89d2cf1f74eae2b434973859319434a12ec88840620359a1edfa5d473374f071b6a03620d5280e01f7936fc270f82fa11e2d5027e52de7e131'

data/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.22] - 2026-10-15
+
+### Added
+
+- **The app says when the page's JavaScript was built by another ruact.** A server updated without its JavaScript breaks the pages that stream: 0.0.19's runtime, for one, reads only the shell's rows of a streamed document and its `<Suspense>` fallbacks stay, with "the response ended before the whole page arrived". The Vite plugin now records which ruact built the JavaScript, in `react-client-manifest.json` (`"__ruact__": { "version": … }` — never a component; a server of 0.0.21 or before reads the file as before). When that is not the server's version, or the build records none — every build by 0.0.21 and before: the first build after upgrading to this version is needed for the warning to go —
+  - in development, a banner across the top of the page says so, with what to do, and the log says it once;
+  - at boot, in every environment, the log says it once, as an error (the app still boots);
+  - `rails ruact:doctor` fails its manifest check (and `-- --json` reports it, the fix as the remediation); a manifest that is not valid JSON fails it too.
+
+  **Rebuilding was not always enough.** Up to 0.0.21 the `vite.config.js` that `rails generate ruact:install` wrote imported the plugin by the absolute path of the gem installed then, so after `bundle update ruact` the build kept the old plugin; when `vite.config.*` imports the plugin from a path that is not this gem's, the message names it and says to run `rails generate ruact:install` (see Changed, below). The comparison is by version only: two builds of the same version are not told apart. The version read is the manifest's, which the Vite dev server writes too: in development without it, after `bin/dev` ran with the new plugin over an older `public/assets` build, nothing is said while the old build is served — `npm run build` again.
+
+### Changed
+
+- **The `vite.config.js` that `rails generate ruact:install` writes asks Bundler where the ruact gem is, each time Vite starts** (`bundle exec ruby -e "require 'ruact'; print Ruact.vite_plugin_path"`), and loads ruact's Vite plugin from there. After `bundle update ruact`, the next build or `bin/dev` uses the new gem's plugin, with nothing to edit; and the file names no path, so it works in a checkout elsewhere or on CI. It costs about 0.6 s each time Vite starts (measured on macOS) — not per page, nor per module reloaded. Vite has to run where `bundle exec` works — the app's root, as `bin/dev` and `npm run build` do; otherwise it stops and says so. Where Bundler cannot run (a build stage without Ruby), `RUACT_VITE_PLUGIN_PATH` names the plugin's `index.js` instead — a fixed path, to update with the gem. The config is now an `async` function (`export default defineConfig(async () => …)`), so it works whether or not `package.json` says `"type": "module"`. It also sets `publicDir: false`: ruact puts nothing in Vite's public dir, and without it every build copied `public/` into `public/assets/`, with a warning.
+
+  **An app installed before:** run `rails generate ruact:install` again. A `vite.config.js` it generated and you never edited is replaced (it says which gem's path it held). One you edited is left as it is, and the install prints the lines to change: the `import ruact from '…'` line becomes the `ruactPluginPath()` function, and the config an `async` function that imports the plugin first. `--force` overwrites the file, as before. An app whose config is another `vite.config.*` (`vite.config.ts`, say) gets no `vite.config.js` beside it — Vite would read that one instead — only the lines to change in its own; with `--force` it gets one, and the install says Vite now reads it instead. `--skip` leaves a generated one as it is, and `rails destroy ruact:install` removes `vite.config.js` only when it is exactly what the install writes.
+
+## [0.0.21] - 2026-10-15
+
+### Changed
+
+- **Leaving a page whose document is still arriving stops loading it.** A page that streams keeps its document open until its last `<Suspense>`; when the router leaves the page (a link, a form) before that, it now calls `window.stop()` first, so the connection closes and the server, which asks before each block, starts no further block for a page nobody will see. Only a document that streams and still has rows to come: the server marks it. Stopping it also stops what that document was still loading — measured in Chrome: an image still loading stays broken, a `fetch` in flight fails with `TypeError`, and a module `import()` in flight fails (importing it again works). The boundaries of the page being left stay quiet, as for a navigation that replaced another: no "response ended before the whole page arrived" error is reported for them. Only while the document itself is loading — a page that has finished is not touched. `revalidate()` stays on the page and does not stop it: stopping would fail the page's other requests in flight, a server function or a `useQuery` among them. When the navigation that stopped it ends without replacing the page — the network, a 403 or a 500 to a form, a redirect that fails, or a second click that superseded the first and failed — the router fetches the page it is still on again, once, so its boundaries do not keep their fallback.
+- **A link or Back/Forward to an `#anchor` of the page on screen is left to the browser.** The client router fetched and rendered the same page again for `/posts/1#comments` while on `/posts/1`; now the browser scrolls, nothing is fetched, and a page still streaming is not stopped. A link to another page with an anchor is the router's, as before.
+- **`content_for` inside a `<Suspense>` that runs later is an error of that boundary, in development.** The layout was sent before the block ran, so what it declared never showed. Reading (`content_for?`, `yield :name`) still works.
+- **The development overlay shows every `<Suspense>` that failed**, one under the other, instead of only the last; a click closes it, and the next failure opens it again.
+- **A streamed Flight response is `Cache-Control: no-store`** (it was `no-cache`). A response the browser may store holds its cache entry while it streams, and Chrome then held a second request for the same URL — `revalidate()` on a page still streaming, the same link clicked again — until the first one ended. The streamed document keeps `no-cache`, so the page can still enter the back/forward cache.
+
+- **An action declared with `ruact_streaming` that got a request over HTTP/1.0 now says so.** Live answers HTTP/1.0 with an ordinary response, so the page is sent whole — and nginx talks HTTP/1.0 to the app unless told `proxy_http_version 1.1;`, so in production a page that should stream silently did not. The app now logs a warning the first time it happens in the process, in every environment, naming the action and the nginx line (Rack::Test, in an app's request specs, speaks HTTP/1.0 too, so it shows there once). `rails ruact:doctor` (and `--json`) adds the same hint to its streaming check when a controller declares `ruact_streaming` or includes `ActionController::Live`.
+
+- **Every script ruact writes carries the request's CSP nonce.** An app whose Content Security Policy allows scripts by nonce (`config.content_security_policy_nonce_generator`, no `'unsafe-inline'`) blocked the inline `__FLIGHT_DATA` script, the development module that loads Vite, and — on a page that streams — each `<Suspense>`'s rows: the page never mounted, or its fallbacks never resolved. The nonce is now on all of them, and on the entry `<script src>`. Without a nonce generator not a byte changes. In development React's own Flight client tries `eval()` for its debugging features and goes on without it; a policy without `'unsafe-eval'` reports that refusal in development only.
+
+- **The `AGENTS.md` that `rails generate ruact:install` writes names what a `<Suspense>` that streams cannot hold.** Besides status, redirect, cookies, session and flash: `content_for`, and the locale, tenant or database role a middleware scopes (they belong in an `around_action`); and a `cache` block goes inside a `<Suspense>`, never around one.
+
+### Fixed
+
+- **On Rack 2, a page that streams was held until its last `<Suspense>`.** Rack 2's `Rack::ETag` (in every Rails app's middleware) reads a 200 body whole to digest it, unless the response already has an `ETag` or a `Last-Modified` — `Cache-Control: no-cache` does not stop it, contrary to what ruact assumed. Rails 7.2 through 8.1 accept Rack 2.2, so an app on it got no streaming at all: no shell, no fallback, the page at the end. On Rack 2 a streamed response now carries a weak `ETag` of its own, new for every response, so no `If-None-Match` ever matches it — unless the action set its own `ETag` or `Last-Modified` (`fresh_when`), which already keeps `Rack::ETag` away and is left as it is. Measured with Rack 2.2.24. Rack 3 is unchanged.
+- **A client component or a `<Suspense>` inside a `cache` block no longer comes back as another one.** A fragment cache stores the HTML a render produced, with the markers that render gave its components and blocks; read back in another render, a marker could name one of *that* render's components (the page showed the wrong component, with its props) or another boundary's block (a `<Suspense>` showed another one's content). Every marker now carries the id of the render that wrote it. A client component read from the cache raises `Ruact::HtmlConverterError`, naming the `cache` and what to do (keep the component outside it); a `<Suspense>` read from the cache gets an error row for that boundary only, saying the same, and the rest of the page renders; the server logs it and reports it to `Rails.error` (`source: "ruact.suspense"`), whether the page streams or not. A marker cached by 0.0.20 or before, read after the upgrade, is taken for one of another render too.
+- **A `<Suspense>` that runs later sees its local variables as they were at the tag.** In an action that streams, the block ran after the rest of the template and read a local as it was then: every block of a `for` loop showed the last item, and a local reassigned below the tag showed the new value. Locals are now kept when the tag is met and given back to the block when it runs. What is kept is the variable, not a copy of its object: a list appended to below the tag shows the item appended. A local an earlier `<Suspense>` reassigns is not seen by the ones after it. Instance variables are still read when the block runs.
+- **A query still running when a `<Suspense>` passes `suspense_timeout` is cancelled (PostgreSQL).** The timeout gave the response back, but the query went on running on the server, and its connection — back in the pool — made the next query on it wait until it ended (seconds). At the limit ruact now cancels the queries in flight on the connections the block holds or just gave back (`PG::Connection#cancel`; the block's fiber under `isolation_level = :fiber`); the connection is free again at once, and the boundary gets the timeout. A query `load_async` started is not cancelled: the async executor's thread holds its connection. Other adapters are unchanged. For those queries, and with any other adapter, the database's statement timeout stays the limit.
+- **Error lines below a component tag written over several lines are right.** The preprocessor put a multi-line tag on one line, so Rails named a line too early for any error below it (an error page, a backtrace) — since component tags existed. The tag's line breaks are kept.
+- **The development overlay's backtrace names the right template lines.** React's development client reads each server frame as six fields; ruact sent four, and every frame came out at line 2.
+- **An exception raised after a streamed page was sent (an `after_action`) reaches `Rails.error`.** `ActionController::Live` only logs what is raised once the response has started, so an app's error reporting never heard of it; ruact reports it (`source: "ruact.stream"`). The page in the browser is unchanged.
+
 ## [0.0.20] - 2026-10-14
 
 ### Added
@@ -518,7 +561,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.20...HEAD
+[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.22...HEAD
+[0.0.22]: https://github.com/luizcg/ruact/releases/tag/v0.0.22
+[0.0.21]: https://github.com/luizcg/ruact/releases/tag/v0.0.21
 [0.0.20]: https://github.com/luizcg/ruact/releases/tag/v0.0.20
 [0.0.19]: https://github.com/luizcg/ruact/releases/tag/v0.0.19
 [0.0.18]: https://github.com/luizcg/ruact/releases/tag/v0.0.18

data/CONTRIBUTING.md

@@ -14,8 +14,8 @@ request, and everything it asks you to run, you can run — with this repository
 | `vendor/javascript/ruact-server-functions-runtime/` | the browser-side runtime those generated accessors call |
 
 The two JavaScript packages are **bundled, not published**. A host app never installs them from npm:
-`rails generate ruact:install` writes a `vite.config.js` that imports the plugin by absolute path off the
-installed gem. That has one consequence worth stating up front, because it is what makes the rest of this
+`rails generate ruact:install` writes a `vite.config.js` that asks Bundler where the ruact gem is, each time
+Vite starts, and loads the plugin from there. That has one consequence worth stating up front, because it is what makes the rest of this
 document short — **pointing a Rails app at your checkout of the gem points it at your checkout of the Vite
 plugin too.** There is nothing to link separately, and nothing else to clone. This repository has no
 submodules.

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

@@ -20,7 +20,9 @@ module Ruact
     #    (`config.layout = true` or another name) gets the missing lines PRINTED,
     #    never written. See Ruact::Configuration#layout.
     # 4. Creates app/javascript/components/.keep
-    # 5. Creates vite.config.js (or shows manual instructions if one exists)
+    # 5. Creates vite.config.js, which asks Bundler for the plugin (Story 19.4);
+    #    replaces one it generated before 19.4 and the app never edited, and
+    #    shows manual instructions for any other existing one
     # 6. Creates package.json (react/react-dom/vite/@vitejs/plugin-react) so a
     #    fresh app has JS deps to install (Story 14.6, FR101).
     # 7. Creates Procfile.dev + bin/dev (foreman) so the single `bin/dev`
@@ -247,23 +249,37 @@ module Ruact
         rake "ruact:server_functions:generate"
       end
 
+      # Story 19.4 — what the install wrote from Story 14.2 to 0.0.21, with
+      # the plugin's import as a placeholder: an existing vite.config.js equal
+      # to it, but for that import, was generated and never edited.
+      PINNED_VITE_CONFIG = File.expand_path("legacy/vite.config.pinned.js", __dir__)
+      PINNED_VITE_CONFIG_IMPORT = "import ruact from '__RUACT_VITE_PLUGIN_PATH__';"
+      PINNED_IMPORT_LINE = %r{^import ruact from '([^'\n]*vite-plugin-ruact/index\.js)';$}
+
+      # Story 19.4 — the vite.config.js the install writes asks Bundler where
+      # the ruact gem is each time Vite starts, so it names no path. An existing
+      # file is replaced only when it is one this generator wrote before 19.4,
+      # never edited (it imported the plugin by the path of the gem installed
+      # then, so after `bundle update ruact` the build kept the old plugin);
+      # any other file is left as it is and the change is printed. `--force`
+      # overwrites, as before (and says so when it sets another `vite.config.*`
+      # of the app's aside); `--skip` leaves a generated one; `rails destroy`
+      # removes only the file exactly as the install writes it.
       def create_vite_config
-        vite_config_file = Pathname(destination_root).join("vite.config.js")
+        return revoke_vite_config if behavior == :revoke
 
-        # `--force` must actually regenerate (the message below promises it). The
-        # guard skips the template ONLY when the file exists AND force was not
-        # passed; with --force we fall through to `template`, which overwrites.
-        if vite_config_file.exist? && !options[:force]
-          say_status "notice", "vite.config.js already exists — add the plugin manually:", :yellow
-          say "  1. At the top of vite.config.js, add:"
-          say "       import ruact from '#{Ruact.vite_plugin_path}';"
-          say "  2. In the plugins array, add: ruact()"
-          say "  3. Set build.rollupOptions.input to '#{Ruact.bootstrap_virtual_id}'"
-          say ""
-          say "  Re-run `rails generate ruact:install --force` to overwrite vite.config.js."
-        else
-          template "vite.config.js.tt", "vite.config.js"
+        vite_config_file = Pathname(destination_root).join("vite.config.js")
+        other = other_vite_config unless vite_config_file.exist?
+        if other && !options[:force]
+          # Vite reads vite.config.js first: writing one would set the app's aside.
+          say_status "notice", "#{other} exists — vite.config.js is not written, Vite would read it " \
+                               "instead of yours.", :yellow
+          return show_vite_config_instructions(other)
         end
+        return refresh_vite_config(vite_config_file) if vite_config_file.exist? && !options[:force]
+
+        template "vite.config.js.tt", "vite.config.js"
+        say_status "warn", "vite.config.js — Vite reads it first: #{other} is no longer used", :yellow if other
       end
 
       # Story 14.6 (FR101, Epic 14 DoD) — a fresh ruact app needs a package.json
@@ -271,7 +287,7 @@ module Ruact
       # plugin) so the `npm install` that Story 14.1 runs has something to
       # resolve and `bin/dev`'s `npm run dev` (Vite) has a `dev` script. The
       # bundled ruact Vite plugin is NOT a package.json dependency — vite.config
-      # imports it by the absolute `Ruact.vite_plugin_path` and it uses only
+      # loads it from the gem Bundler has (`Ruact.vite_plugin_path`) and it uses only
       # `node:` builtins. Guarded like vite.config.js: an existing package.json
       # is left untouched (the app may already have one) unless --force.
       #
@@ -429,13 +445,99 @@ module Ruact
         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"
-        say "the bundled Vite plugin path in vite.config.js."
-        say ""
       end
 
       private
 
+      # The path a vite.config.js generated before Story 19.4 imports the
+      # plugin from, when the file is otherwise as generated; nil for any
+      # other file. Only whitespace at the end of the file may differ.
+      def pinned_vite_config_path(content)
+        return nil unless content.valid_encoding?
+
+        match = content.match(PINNED_IMPORT_LINE)
+        return nil unless match
+
+        generated = File.read(PINNED_VITE_CONFIG, encoding: Encoding::UTF_8)
+        normalized = content.sub(PINNED_IMPORT_LINE) { PINNED_VITE_CONFIG_IMPORT }
+        normalized.rstrip == generated.rstrip ? match[1] : nil
+      end
+
+      # vite.config.js as this version of the template renders it.
+      def rendered_vite_config
+        source = File.read(File.join(self.class.source_root, "vite.config.js.tt"), encoding: Encoding::UTF_8)
+        ERB.new(source, trim_mode: "-").result(binding)
+      end
+
+      # An existing vite.config.js the install does not touch: how to make it
+      # ask Bundler for the plugin, with the template's own lines.
+      def show_vite_config_instructions(name = "vite.config.js")
+        rendered = rendered_vite_config
+        head = rendered[0...rendered.index("export default")]
+        say "  In #{name}, to load ruact's Vite plugin from the gem Bundler has (so a `bundle update ruact`"
+        say "  needs no edit there):"
+        say "  1. Replace the `import ruact from '…'` line, if there is one, with (beside your other imports):"
+        say ""
+        head.each_line do |line|
+          next if line.match?(/^import (\{ defineConfig \}|react) from /)
+
+          say "       #{line}".rstrip
+        end
+        say "  2. Wrap the config in an async function that imports the plugin first:"
+        say ""
+        say "       export default defineConfig(async () => {"
+        say "         const { default: ruact } = await import(pathToFileURL(ruactPluginPath()).href);"
+        say "         return { /* your config, with ruact() in plugins */ };"
+        say "       });"
+        say ""
+        say "  3. In it: ruact() in plugins, build.rollupOptions.input '#{Ruact.bootstrap_virtual_id}',"
+        say "     and (optional) publicDir: false, so a build does not copy public/ into public/assets/."
+        say ""
+        return unless name == "vite.config.js"
+
+        say "  Re-run `rails generate ruact:install --force` to write vite.config.js instead."
+      end
+
+      # A `vite.config.*` of the app's other than vite.config.js, which Vite
+      # would no longer read once a vite.config.js exists.
+      def other_vite_config
+        (Ruact::BuildSkew::VITE_CONFIGS - ["vite.config.js"])
+          .find { |name| Pathname(destination_root).join(name).exist? }
+      end
+
+      # An existing vite.config.js: replaced when the install generated it
+      # before Story 19.4 and the app never edited it (not under --skip),
+      # left as it is otherwise.
+      def refresh_vite_config(vite_config_file)
+        existing = vite_config_file.binread.force_encoding(Encoding::UTF_8)
+        pinned = pinned_vite_config_path(existing)
+        if pinned && options[:skip]
+          say_status "skip", "vite.config.js — it imports ruact's Vite plugin from #{pinned}, the gem " \
+                             "installed then (--skip leaves it)", :yellow
+        elsif pinned
+          say_status "update", "vite.config.js — it imported ruact's Vite plugin from #{pinned}, " \
+                               "the gem installed then; it now asks Bundler", :green
+          template "vite.config.js.tt", "vite.config.js", force: true, verbose: false
+        elsif existing == rendered_vite_config
+          say_status "identical", "vite.config.js", :blue
+        else
+          say_status "notice", "vite.config.js already exists and has edits of yours — it is left as it is.", :yellow
+          show_vite_config_instructions
+        end
+      end
+
+      # `rails destroy ruact:install`: removes vite.config.js only when it is
+      # exactly what the install writes; any other one is the app's.
+      def revoke_vite_config
+        vite_config_file = Pathname(destination_root).join("vite.config.js")
+        return unless vite_config_file.exist?
+        unless vite_config_file.binread.force_encoding(Encoding::UTF_8) == rendered_vite_config
+          return say_status("skip", "vite.config.js — not the one the install writes, left as it is", :yellow)
+        end
+
+        template "vite.config.js.tt", "vite.config.js"
+      end
+
       # What the post-install message says about the layout — true for the
       # setting actually in effect, not just for a fresh install.
       def layout_summary

data/lib/generators/ruact/install/legacy/vite.config.pinned.js

@@ -0,0 +1,28 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+// Bundled Vite plugin — path resolved from the installed ruact gem.
+// Re-run `rails generate ruact:install` after gem upgrades to refresh this path.
+import ruact from '__RUACT_VITE_PLUGIN_PATH__';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    ruact(), // scans app/javascript/components/ for "use client", emits react-client-manifest.json
+  ],
+
+  build: {
+    outDir: 'public/assets',
+    manifest: true,
+    rollupOptions: {
+      // ruact's bootstrap entry is a virtual module served by the plugin above
+      // (Story 14.2) — there is no app/javascript/application.jsx to point at.
+      input: 'virtual:ruact/bootstrap',
+    },
+  },
+
+  server: {
+    port: 5173,
+    strictPort: true,
+    origin: 'http://localhost:5173',
+  },
+});

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

@@ -78,14 +78,15 @@ READ IT instead of simulating the name generation. Regenerate after routes/queri
    `<Card title={@t}>...</Card>` passes the ERB between its tags to the
    component as `children`. An unclosed or stray tag fails LOUDLY with a
    `PreprocessorError` naming file:line. `<Suspense fallback="...">` pairs too;
-   under `ruact_streaming` its content runs AFTER the page is sent, so status,
-   redirect, cookies, session and flash belong in the controller, not inside it.
+   under `ruact_streaming` its content runs AFTER the page is sent: status,
+   redirect, cookies, session, flash, `content_for` and locale/tenant/DB-role
+   scopes belong in the controller (`around_action`), not inside it or in a
+   middleware; a `cache` block goes inside a `<Suspense>`, never around one.
    In a loop of items holding components, give each item a `data-react-key`
    (the record's id): React matches them by position otherwise, silently.
 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}`. A quoted value (`title="Hi"`) is a
-   plain string and a bare attribute is `true`, as in JSX.
+   evaluates `@post.title` as a Ruby expression: no JS ternaries, no `{...spread}`.
+   A quoted value (`title="Hi"`) is a plain string; a bare attribute is `true`.
 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
@@ -139,13 +140,12 @@ duration, or a deliberate `expires_in: nil` for a non-expiring token.
 
 ## Verify your work
 
-- `bin/rails ruact:doctor` — checks install/config health; exits 1 on failure.
-  Append `-- --json` for the same checks as a machine-readable report.
+- `bin/rails ruact:doctor` — install/config health, and that the JS was built by
+  this ruact (run it after a gem upgrade); exits 1 on failure. Append `-- --json` for JSON.
 - `bin/rails ruact:routes -- --json` — the accessor/route table (each accessor's
   name, kind, verb, path, params) as JSON, from the same route table codegen
   reads; bare `ruact:routes` prints a compact human table.
-- Both `--json` outputs are EXPERIMENTAL — the shape may change; gate on their
-  `schema_version` field (currently `0`), do not treat it as a stable contract.
+- Both `--json` outputs are EXPERIMENTAL: gate on `schema_version` (now `0`).
 - `bin/rails ruact:server_functions:generate` — regenerates the TS module;
   exits 1 on a naming collision or an invalid name.
 - `bin/dev` — boots Rails AND Vite (both required: Vite serves the client components).

data/lib/generators/ruact/install/templates/vite.config.js.tt

@@ -1,28 +1,63 @@
+import { execSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
 import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
-// Bundled Vite plugin — path resolved from the installed ruact gem.
-// Re-run `rails generate ruact:install` after gem upgrades to refresh this path.
-import ruact from '<%= Ruact.vite_plugin_path %>';
 
-export default defineConfig({
-  plugins: [
-    react(),
-    ruact(), // scans app/javascript/components/ for "use client", emits react-client-manifest.json
-  ],
+// ruact's Vite plugin ships inside the ruact gem. Bundler is asked where that
+// gem is each time Vite starts, so after `bundle update ruact` the next build
+// (or bin/dev) uses the new plugin: no path to refresh in this file.
+// Where Bundler cannot run (a build stage without Ruby), RUACT_VITE_PLUGIN_PATH
+// names the plugin's index.js instead — a fixed path, to update with the gem.
+function ruactPluginPath() {
+  const pinned = process.env.RUACT_VITE_PLUGIN_PATH;
+  if (pinned) return pinned;
 
-  build: {
-    outDir: 'public/assets',
-    manifest: true,
-    rollupOptions: {
-      // ruact's bootstrap entry is a virtual module served by the plugin above
-      // (Story 14.2) — there is no app/javascript/application.jsx to point at.
-      input: '<%= Ruact.bootstrap_virtual_id %>',
+  let out;
+  try {
+    out = execSync(`bundle exec ruby -e "require 'ruact'; print Ruact.vite_plugin_path"`, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (error) {
+    throw new Error(
+      "[ruact] could not ask Bundler where the ruact gem is. Run Vite from the app's root, " +
+        'where `bundle exec` works (bin/dev, npm run build), or set RUACT_VITE_PLUGIN_PATH.\n' +
+        (error.stderr || error.message),
+    );
+  }
+  // The last line only: anything a gem prints while loading comes before it.
+  const path = out.trim().split(/\r?\n/).pop();
+  if (!path) throw new Error('[ruact] Bundler gave no path for the ruact gem.');
+  return path;
+}
+
+export default defineConfig(async () => {
+  const { default: ruact } = await import(pathToFileURL(ruactPluginPath()).href);
+
+  return {
+    // ruact puts nothing in Vite's public dir, and Rails serves public/: without
+    // this, every build copies public/ into public/assets/.
+    publicDir: false,
+
+    plugins: [
+      react(),
+      ruact(), // scans app/javascript/components/ for "use client", emits react-client-manifest.json
+    ],
+
+    build: {
+      outDir: 'public/assets',
+      manifest: true,
+      rollupOptions: {
+        // ruact's bootstrap entry is a virtual module served by the plugin above
+        // (Story 14.2) — there is no app/javascript/application.jsx to point at.
+        input: '<%= Ruact.bootstrap_virtual_id %>',
+      },
     },
-  },
 
-  server: {
-    port: 5173,
-    strictPort: true,
-    origin: 'http://localhost:5173',
-  },
+    server: {
+      port: 5173,
+      strictPort: true,
+      origin: 'http://localhost:5173',
+    },
+  };
 });

data/lib/ruact/build_skew.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Ruact
+  # Story 19-3 — the page's JavaScript built by another ruact than the server's.
+  #
+  # The Vite plugin records which ruact built the JavaScript in
+  # `react-client-manifest.json` ({ClientManifest#build_version}). When that is
+  # not this gem's version — or the build records none, as every build by 0.0.21
+  # and before — the browser runs another release's runtime against this
+  # server, and a page that streams keeps its `<Suspense>` fallbacks forever
+  # (measured with 0.0.19's: `spec/browser/deferred_suspense`, `./run skew`).
+  #
+  # Said loudly in development (a banner on the page, {ViewHelper}), once in
+  # the log at boot in any environment ({Railtie}), and as a failure of
+  # `rails ruact:doctor`'s manifest check ({Doctor}) — all with {.message}.
+  #
+  # The usual cause after `bundle update ruact` is not a forgotten build: the
+  # `vite.config.js` that `ruact:install` wrote up to 0.0.21 imports the plugin
+  # by the absolute path of the gem installed then, so the build and the dev
+  # server keep using the old plugin while that version stays installed.
+  # {.message} names it when it reads such an import, and the fix: the install
+  # replaces that file with one that asks Bundler for the plugin (Story 19.4).
+  module BuildSkew
+    # The `vite.config` files Vite looks for, in its order.
+    VITE_CONFIGS = %w[vite.config.js vite.config.mjs vite.config.ts vite.config.cjs vite.config.mts
+                      vite.config.cts].freeze
+    # A string literal naming ruact's plugin entry, as `ruact:install` writes it
+    # (no template interpolation: a path built in JavaScript is not read).
+    PLUGIN_IMPORT = %r{(["'`])([^"'`$\n]*vite-plugin-ruact/index\.js)\1}
+    LOCK = Mutex.new
+    private_constant :LOCK
+
+    # Whether a build that recorded +build_version+ is another ruact's.
+    #
+    # @param build_version [String, nil] {ClientManifest#build_version}
+    # @return [Boolean]
+    def self.skewed?(build_version)
+      build_version != Ruact::VERSION
+    end
+
+    # What happened and what to do, in one paragraph without the `[ruact]`
+    # prefix.
+    #
+    # @param build_version [String, nil] {ClientManifest#build_version}
+    # @param root [Pathname, String, nil] the app's root, where `vite.config.*` is read
+    # @return [String]
+    def self.message(build_version, root: default_root)
+      built = build_version ? "ruact #{build_version}" : "an older ruact, one that did not record its version"
+      "The page's JavaScript was built by #{built}, and this server is ruact #{Ruact::VERSION}: " \
+        "pages that stream keep their <Suspense> fallbacks, and other pages may break. " \
+        "#{remedy(root)}"
+    end
+
+    # {.message}'s fix only: the `vite.config` import when it names another
+    # ruact's plugin, then the rebuild.
+    #
+    # @param root [Pathname, String, nil]
+    # @return [String]
+    def self.remedy(root = default_root)
+      rebuild = "Rebuild the JavaScript with this ruact (npm run build, or restart bin/dev in development) " \
+                "and deploy it together with the server."
+      imported = foreign_plugin_import(root)
+      return rebuild unless imported
+
+      config = imported[:config]
+      fix = if config == "vite.config.js"
+              "run `rails generate ruact:install`, which replaces a vite.config.js it generated with one that " \
+                "asks Bundler for the plugin (for one you edited, it prints the change to make)"
+            else
+              "load it from the gem Bundler has — `rails generate ruact:install` prints the change to make in #{config}"
+            end
+      "#{config} imports ruact's Vite plugin from #{imported[:path]}, another installation of ruact: " \
+        "#{fix}, then: #{rebuild}"
+    end
+
+    # The message as a banner across the top of the page, in development.
+    # Plain HTML with inline style, as the warning that the Vite dev server is
+    # down: it cannot depend on the JavaScript that is the problem.
+    #
+    # @param message [String] {.message}
+    # @return [String]
+    def self.banner(message)
+      <<~HTML
+        <div role="alert" data-ruact-build-skew style="position:fixed;inset:0 0 auto 0;z-index:2147483647;padding:12px 16px;background:#7f1d1d;color:#fff;font:14px/1.4 system-ui,sans-serif">
+          <strong>[ruact]</strong> #{ERB::Util.html_escape(message)}
+        </div>
+      HTML
+    end
+
+    # Logs {.message} once per process for each version a build recorded, so a
+    # development server reloading its code does not repeat it, and keeps the
+    # message: `vite.config.*` is read once per version, not on every page.
+    #
+    # @param build_version [String, nil]
+    # @param logger [#warn, #error, nil]
+    # @param level [Symbol] the logger method
+    # @return [String, nil] the message, or nil when the build is this ruact's
+    def self.note(build_version, logger:, level: :warn)
+      return unless skewed?(build_version)
+
+      key = build_version.to_s
+      text, first = LOCK.synchronize do
+        @noted ||= {}
+        @noted.key?(key) ? [@noted[key], false] : [@noted[key] = message(build_version), true]
+      end
+      logger&.public_send(level, "[ruact] #{text}") if first
+      text
+    end
+
+    # Forgets what it logged (specs).
+    #
+    # @api private
+    def self.reset!
+      LOCK.synchronize { @noted = nil }
+    end
+
+    # The first `vite.config.*` under +root+ whose ruact plugin import names a
+    # file other than this gem's, or nil — none found, no such import, or the
+    # import is this gem's. Read only for the message, never to decide.
+    #
+    # @api private
+    # @return [Hash{Symbol => String}, nil] `{ config:, path: }`
+    def self.foreign_plugin_import(root)
+      return nil unless root
+
+      VITE_CONFIGS.each do |name|
+        config = File.join(root.to_s, name)
+        next unless File.file?(config)
+
+        match = File.binread(config).force_encoding(Encoding::UTF_8).scrub.match(PLUGIN_IMPORT)
+        return nil unless match
+
+        imported = match[2]
+        resolved = imported.start_with?(".") ? File.expand_path(imported, root.to_s) : imported
+        return nil if same_file?(resolved, Ruact.vite_plugin_path)
+
+        return { config: name, path: imported }
+      end
+      nil
+    rescue StandardError
+      # Read only for the message: whatever goes wrong, the message goes
+      # without the sentence.
+      nil
+    end
+
+    def self.same_file?(one, other)
+      real(one) == real(other)
+    end
+
+    def self.real(path)
+      File.realpath(path)
+    rescue SystemCallError
+      File.expand_path(path)
+    end
+
+    def self.default_root
+      Rails.root if defined?(Rails) && Rails.respond_to?(:root)
+    end
+
+    private_class_method :same_file?, :real, :default_root
+  end
+end

data/lib/ruact/cached_blocks.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Story 19-2 — a render that renders `<Suspense>` content in place writes no
+  # block marker: one in its HTML came out of a `cache` block a render that
+  # streamed wrote. Its boundary gets an error row ({Flight::Renderer}); this
+  # says so on the server, as {DeferredRender} does for a render that streams.
+  #
+  # Internal API: not part of the public compatibility contract.
+  module CachedBlocks
+    # Only the attribute as written in a tag (`="`): text that mentions it is
+    # escaped.
+    MARKER = %( #{Markers::BLOCK_ATTR}=").freeze
+    private_constant :MARKER
+
+    # Logs and reports a block marker in +html+.
+    #
+    # @param html [String]
+    # @param logger [Logger, nil]
+    # @return [void]
+    def self.report(html, logger)
+      return unless html.include?(MARKER)
+
+      error = Ruact::Error.new(Flight::DeferredContent::STALE)
+      logger&.error("[ruact] #{error.message}")
+      Rails.error.report(error, handled: true, severity: :error, source: "ruact.suspense") if
+        defined?(Rails) && Rails.respond_to?(:error)
+    end
+  end
+end