ruact 0.0.21 → 0.0.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e96181a35f53a1a25da4cd4db1ca655aeff15cdd5190f56aaafb97f1a2a19361
-  data.tar.gz: e9034d5a9f16dee7a5a319483364dbbf049a6b0aecf63073c3efcfe66ce6baa4
+  metadata.gz: 769b242b14222272ed72cf6fedeaf732de780ce3d57d4f6b916ecf8a4cd17faa
+  data.tar.gz: d639e44c10c4524ece71cebbb8d3e135484ec6715792492b17a986347937a6fd
 SHA512:
-  metadata.gz: c90a2671ac0774bd51f726af1dc22ab58ba048ee6354b1078888ad2704289214caa6b6189b8909c72ab074546a37dc80676fb49576e630d09d1629eb09ff22ba
-  data.tar.gz: e71ea90b4a5ee1450fd5c772fe7a99c9641b5febb8465ea0e7649fc1ab00db670fcdd3333b34bffbcc870bb0d719deb9b236f40769e6277097f0a3cdaa0bc115
+  metadata.gz: 03f1a1c07dd0ee8594765e72f6e2d54762c6ac336a74929b2ce9fe531b6fff2c4ca15a2c87c81e7e4fada9dd645ab9e46c12e7f09b9b556c5055db76d3086f6f
+  data.tar.gz: '03931869edf24e89d2cf1f74eae2b434973859319434a12ec88840620359a1edfa5d473374f071b6a03620d5280e01f7936fc270f82fa11e2d5027e52de7e131'

data/CHANGELOG.md

@@ -7,6 +7,23 @@ 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
@@ -544,7 +561,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.21...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

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

@@ -140,8 +140,8 @@ 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.

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

@@ -37,7 +37,19 @@ module Ruact
   # existing manifest + reader is unaffected). {#contract_for} reads it for the
   # Story 13.5 preprocess-time call-site validator; +nil+ means "no contract →
   # no validation" (fail open).
+  #
+  # Story 19-3 — the Vite plugin also records which ruact built the page's
+  # JavaScript, under a key no component can have (a component's is PascalCase
+  # or +folder/_snake+):
+  #
+  #   "__ruact__": { "version": "0.0.22" }
+  #
+  # {#build_version} reads it; it is not a component, for any lookup. A manifest
+  # written by 0.0.21 or before has no such key.
   class ClientManifest
+    # The manifest key of the build's record (Story 19-3).
+    BUILD_KEY = "__ruact__"
+
     # 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.
@@ -129,6 +141,13 @@ module Ruact
       entry && entry["contract"]
     end
 
+    # Story 19-3 — the ruact version whose Vite plugin wrote this manifest, or
+    # +nil+ when it records none (a build by 0.0.21 or before, or a plugin that
+    # could not read its gem's version).
+    #
+    # @return [String, nil]
+    attr_reader :build_version
+
     # Load from a file path (JSON).
     # Pre-warms the reference cache and freezes the manifest so it cannot be
     # mutated at runtime (AC#5). Pre-warming is required because Ruby's freeze
@@ -138,7 +157,7 @@ module Ruact
       raw      = File.read(path)
       data     = JSON.parse(raw)
       manifest = from_hash(data)
-      data.each_key { |name| manifest.reference_for(name) }
+      data.each_key { |name| manifest.reference_for(name) unless name == BUILD_KEY }
       manifest.freeze
     end
 
@@ -147,9 +166,16 @@ module Ruact
     # first-lookup path works even when +data+ is empty (otherwise
     # +reference_for+ would raise +FrozenError+ trying to memoize on a
     # frozen instance).
+    #
+    # Story 19-3 — the build's record ({BUILD_KEY}) is taken out of the entries
+    # (without changing the Hash given) and kept as {#build_version}.
     def self.from_hash(data)
       manifest = new
+      recorded = data.is_a?(Hash) && data.key?(BUILD_KEY)
+      build = data[BUILD_KEY] if recorded
+      data = data.except(BUILD_KEY) if recorded
       manifest.instance_variable_set(:@data, data)
+      manifest.instance_variable_set(:@build_version, build.is_a?(Hash) ? build["version"]&.to_s : nil)
       manifest.instance_variable_set(:@reference_cache, {})
       manifest
     end

data/lib/ruact/controller.rb

@@ -106,6 +106,15 @@ module Ruact
       ManifestResolver.resolve
     end
 
+    # Story 19-3 — {BuildSkew.note} for the manifest this render resolved: the
+    # message when its build is another ruact's (logged once per version),
+    # else nil.
+    def __ruact_build_skew(manifest)
+      return unless manifest.respond_to?(:build_version)
+
+      BuildSkew.note(manifest.build_version, logger: logger)
+    end
+
     # Only activate RSC rendering when the matching .html.erb template exists AND
     # the client will accept an HTML response (AC FR26; Story 10.0).
     # `request.format.html?` is false for a `*/*` wildcard (curl/bots/
@@ -177,7 +186,12 @@ module Ruact
       # its headers on the first row.
       self.status = status if status
 
-      pipeline = RenderPipeline.new(ruact_manifest,
+      manifest = ruact_manifest
+      # Story 19-3 — in development, the page says loudly when its JavaScript
+      # was built by another ruact (`ruact_js_assets` reads this). The manifest
+      # this render resolved anyway: no other request to the Vite dev server.
+      @ruact_build_skew = __ruact_build_skew(manifest) if Rails.env.development?
+      pipeline = RenderPipeline.new(manifest,
                                     controller_path: controller_path, logger: logger,
                                     development: Flight::Renderer.development_default)
       # Story 19-1 — in an action that streams, the first load and a

data/lib/ruact/doctor.rb

@@ -145,14 +145,25 @@ module Ruact
 
     private
 
+    # Story 19-3 — the manifest also says which ruact built the JavaScript; a
+    # build by another one (or by one that recorded none, 0.0.21 and before)
+    # fails: the page then runs another release's runtime against this server.
     def check_manifest
       path = manifest_path
-      if Pathname(path).exist?
-        [:pass, "Manifest found at #{path}"]
-      else
-        [:fail, "Manifest not found — run vite build",
-         "Run vite build (or bin/dev) to generate the client manifest."]
+      unless Pathname(path).exist?
+        return [:fail, "Manifest not found — run vite build",
+                "Run vite build (or bin/dev) to generate the client manifest."]
       end
+
+      built = ClientManifest.from_hash(JSON.parse(File.read(path))).build_version
+      return [:pass, "Manifest found at #{path} (built by ruact #{built})"] unless BuildSkew.skewed?(built)
+
+      by = built ? "ruact #{built}" : "a ruact that did not record its version (0.0.21 or before)"
+      [:fail, "Manifest at #{path} was built by #{by}; this app runs ruact #{Ruact::VERSION}",
+       BuildSkew.remedy(Rails.root)]
+    rescue JSON::ParserError => e
+      [:fail, "Manifest at #{path} is not valid JSON (#{e.message.lines.first.strip})",
+       "Rebuild it: run vite build (or bin/dev)."]
     end
 
     def check_vite

data/lib/ruact/railtie.rb

@@ -80,6 +80,7 @@ module Ruact
 
       if manifest_path.exist?
         Ruact.manifest = Ruact::ClientManifest.load(manifest_path)
+        Ruact::Railtie.note_build_skew!(Ruact.manifest)
       else
         Ruact::Railtie.check_manifest!(manifest_path)
       end
@@ -209,6 +210,19 @@ module Ruact
       false
     end
 
+    # Story 19-3 — the built JavaScript is another ruact's: one error line in
+    # the log, in every environment, once per process for each version the
+    # build recorded (`to_prepare` runs again on every reload in development).
+    # It does not stop the boot: pages without a `<Suspense>` that streams may
+    # well work, and stopping was not decided.
+    #
+    # @param manifest [Ruact::ClientManifest]
+    # @return [void]
+    def self.note_build_skew!(manifest)
+      Ruact::BuildSkew.note(manifest.build_version, logger: Rails.logger, level: :error)
+      nil
+    end
+
     # Checks whether the manifest exists and either warns (dev) or raises (prod).
     # Extracted as a class method for direct testability without a full Rails app.
     def self.check_manifest!(manifest_path)

data/lib/ruact/version.rb

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

data/lib/ruact/view_helper.rb

@@ -265,35 +265,51 @@ module Ruact
     # never show. The bootstrap then reads the rows the document pushes while
     # it is still open.
     def ruact_vite_tags
-      if Rails.env.development? && vite_dev_running?
-        # @vitejs/plugin-react normally injects this preamble by processing index.html.
-        # Since our HTML is generated by Rails (not Vite), we inject it manually.
-        # Without it, every JSX file throws "can't detect preamble" at runtime.
-        # One async module, so the preamble still runs before any component
-        # module: it installs the preamble, then imports the client and the
-        # bootstrap, in that order.
-        dev_server = Ruact.config.vite_dev_server.chomp("/")
-        <<~HTML
-          <script type="module" async#{__ruact_nonce_attr}>
-            import RefreshRuntime from '#{dev_server}/@react-refresh';
-            RefreshRuntime.injectIntoGlobalHook(window);
-            window.$RefreshReg$ = () => {};
-            window.$RefreshSig$ = () => (type) => type;
-            window.__vite_plugin_react_preamble_installed__ = true;
-            await import('#{dev_server}/@vite/client');
-            await import('#{ruact_bootstrap_dev_url}');
-          </script>
-        HTML
-      else
-        # Production: read the hashed URL from the Vite manifest, keyed on the
-        # virtual entry id (the manifest key Vite emits for the virtual input).
-        entry = vite_manifest_entry(Ruact.bootstrap_virtual_id)
-        src   = entry ? "/assets/#{entry['file']}" : "/assets/application.js"
-        tag   = %(<script type="module" async src="#{src}"#{__ruact_nonce_attr}></script>)
-        # Story 17-0k — in development with neither the Vite dev server nor a
-        # build, that script 404s and the page stays empty with no error.
-        Rails.env.development? && entry.nil? ? "#{ruact_vite_down_warning}\n#{tag}" : tag
-      end
+      return ruact_build_skew_warning + ruact_vite_dev_tags if Rails.env.development? && vite_dev_running?
+
+      # Production: read the hashed URL from the Vite manifest, keyed on the
+      # virtual entry id (the manifest key Vite emits for the virtual input).
+      entry = vite_manifest_entry(Ruact.bootstrap_virtual_id)
+      src   = entry ? "/assets/#{entry['file']}" : "/assets/application.js"
+      tag   = %(<script type="module" async src="#{src}"#{__ruact_nonce_attr}></script>)
+      return tag unless Rails.env.development?
+
+      # Story 17-0k — in development with neither the Vite dev server nor a
+      # build, that script 404s and the page stays empty with no error. The
+      # component manifest on disk then describes no JavaScript the page runs:
+      # no word of its version (Story 19-3).
+      entry.nil? ? "#{ruact_vite_down_warning}\n#{tag}" : ruact_build_skew_warning + tag
+    end
+
+    # The development entry: the react-refresh preamble, `@vite/client`, then
+    # the bootstrap, from the Vite dev server.
+    def ruact_vite_dev_tags
+      # @vitejs/plugin-react normally injects this preamble by processing index.html.
+      # Since our HTML is generated by Rails (not Vite), we inject it manually.
+      # Without it, every JSX file throws "can't detect preamble" at runtime.
+      # One async module, so the preamble still runs before any component
+      # module: it installs the preamble, then imports the client and the
+      # bootstrap, in that order.
+      dev_server = Ruact.config.vite_dev_server.chomp("/")
+      <<~HTML
+        <script type="module" async#{__ruact_nonce_attr}>
+          import RefreshRuntime from '#{dev_server}/@react-refresh';
+          RefreshRuntime.injectIntoGlobalHook(window);
+          window.$RefreshReg$ = () => {};
+          window.$RefreshSig$ = () => (type) => type;
+          window.__vite_plugin_react_preamble_installed__ = true;
+          await import('#{dev_server}/@vite/client');
+          await import('#{ruact_bootstrap_dev_url}');
+        </script>
+      HTML
+    end
+
+    # Story 19-3 — the page's JavaScript was built by another ruact: the
+    # message the controller kept for this render, on the page
+    # ({Ruact::BuildSkew.banner}). Empty on a page no ruact render produced.
+    def ruact_build_skew_warning
+      message = instance_variable_defined?(:@ruact_build_skew) ? @ruact_build_skew : nil
+      message ? BuildSkew.banner(message) : ""
     end
 
     # Story 17-0k — `bin/rails server` on its own, once Vite has run before:

data/lib/ruact.rb

@@ -18,6 +18,7 @@ require_relative "ruact/render_context"
 require_relative "ruact/html_converter"
 require_relative "ruact/client_manifest"
 require_relative "ruact/manifest_resolver"
+require_relative "ruact/build_skew"
 require_relative "ruact/render_pipeline"
 require_relative "ruact/deferred_render"
 require_relative "ruact/cached_blocks"
@@ -61,8 +62,10 @@ module Ruact
     end
 
     # Returns the absolute path to the Vite plugin bundled inside this gem.
-    # Use this in vite.config.js: import ruact from '<%= Ruact.vite_plugin_path %>'
-    # Re-run `rails generate ruact:install` after gem upgrades to refresh the path.
+    # The vite.config.js `rails generate ruact:install` writes asks for it
+    # through Bundler each time Vite starts (Story 19.4) —
+    # `bundle exec ruby -e "require 'ruact'; print Ruact.vite_plugin_path"` —
+    # so after `bundle update ruact` the next build uses the new gem's plugin.
     #
     # @return [String] absolute path to vendor/javascript/vite-plugin-ruact/index.js
     def vite_plugin_path

data/vendor/javascript/vite-plugin-ruact/build-version.test.mjs

@@ -0,0 +1,101 @@
+// Story 19-3 — the manifest says which ruact built it. Every manifest the
+// plugin writes or serves (the build, the dev server's file, its
+// GET /__ruact/manifest) carries `__ruact__: { version }`, the gem's version read
+// from `lib/ruact/version.rb` beside the plugin; the in-memory manifest the
+// registry is generated from never does.
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import ruact, { BUILD_KEY, readRuactVersion, withBuild, buildManifest, generateRegistrySource } from "./index.js";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const GEM_VERSION = fs
+  .readFileSync(path.resolve(here, "../../../lib/ruact/version.rb"), "utf8")
+  .match(/VERSION = "([^"]+)"/)[1];
+
+let dir;
+beforeEach(() => {
+  dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "ruact-build-version-")));
+  const file = path.join(dir, "app/javascript/components/LikeButton.jsx");
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `"use client";\nexport function LikeButton() { return null; }\n`);
+});
+afterEach(() => fs.rmSync(dir, { recursive: true, force: true }));
+
+function server() {
+  const middlewares = new Map();
+  const handlers = {};
+  return {
+    middlewares: { use: (route, fn) => middlewares.set(route, fn) },
+    moduleGraph: { getModuleById: () => null, invalidateModule: () => {} },
+    ws: { send: () => {} },
+    watcher: { add: () => {}, on: (event, fn) => (handlers[event] ||= []).push(fn) },
+    get(route) {
+      let body = "";
+      middlewares.get(route)({ url: route, method: "GET" }, { setHeader: () => {}, end: (b) => (body = b) }, () => {});
+      return JSON.parse(body);
+    },
+    change(file) {
+      for (const fn of handlers.change) fn(file);
+    },
+  };
+}
+
+async function boot() {
+  const warnings = [];
+  const plugin = ruact();
+  await plugin.configResolved({ root: dir, logger: { info: () => {}, warn: (m) => warnings.push(m) } });
+  await plugin.buildStart({});
+  const dev = server();
+  await plugin.configureServer(dev);
+  return { dev, warnings };
+}
+
+const written = () => JSON.parse(fs.readFileSync(path.join(dir, "public/react-client-manifest.json"), "utf8"));
+
+describe("the build's version in the manifest (Story 19-3)", () => {
+  it("reads the gem's version from lib/ruact/version.rb", () => {
+    expect(readRuactVersion()).toBe(GEM_VERSION);
+  });
+
+  it("is null for a plugin that is not inside a gem", () => {
+    expect(readRuactVersion(path.join(dir, "lib/ruact/version.rb"))).toBeNull();
+    fs.mkdirSync(path.join(dir, "lib/ruact"), { recursive: true });
+    fs.writeFileSync(path.join(dir, "lib/ruact/version.rb"), "module Ruact; end\n");
+    expect(readRuactVersion(path.join(dir, "lib/ruact/version.rb"))).toBeNull();
+  });
+
+  it("the file buildStart writes carries it first", async () => {
+    const { warnings } = await boot();
+    const manifest = written();
+    expect(Object.keys(manifest)).toEqual([BUILD_KEY, "LikeButton"]);
+    expect(manifest[BUILD_KEY]).toEqual({ version: GEM_VERSION });
+    expect(warnings).toEqual([]);
+  });
+
+  it("GET /__ruact/manifest carries it, and the file the watcher rewrites does too", async () => {
+    const { dev } = await boot();
+    expect(dev.get("/__ruact/manifest")[BUILD_KEY]).toEqual({ version: GEM_VERSION });
+
+    const added = path.join(dir, "app/javascript/components/CommentBox.jsx");
+    fs.writeFileSync(added, `"use client";\nexport function CommentBox() { return null; }\n`);
+    dev.change(added);
+    expect(Object.keys(written())).toEqual([BUILD_KEY, "CommentBox", "LikeButton"]);
+    expect(Object.keys(dev.get("/__ruact/manifest"))).toEqual([BUILD_KEY, "CommentBox", "LikeButton"]);
+  });
+
+  it("never reaches the registry", () => {
+    const manifest = buildManifest(path.join(dir, "app/javascript/components"));
+    expect(manifest).not.toHaveProperty(BUILD_KEY);
+    expect(generateRegistrySource(manifest)).not.toContain(BUILD_KEY);
+  });
+
+  it("without a version, the manifest is the components only", () => {
+    const manifest = { LikeButton: { id: "/LikeButton.jsx", name: "LikeButton", chunks: [] } };
+    expect(withBuild(manifest, null)).toBe(manifest);
+    expect(Object.keys(withBuild(manifest, "1.2.3"))).toEqual([BUILD_KEY, "LikeButton"]);
+  });
+});

data/vendor/javascript/vite-plugin-ruact/index.js

@@ -69,6 +69,33 @@ const RESOLVED_BOOTSTRAP_ID = "\0" + BOOTSTRAP_VIRTUAL_ID;
 // point at the gem copy, regardless of the app's cwd.
 const RUNTIME_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "runtime");
 
+// Story 19-3 — the build says which ruact built it. The plugin ships inside the
+// gem (`<gem>/vendor/javascript/vite-plugin-ruact/`), so the gem's version is
+// `<gem>/lib/ruact/version.rb`, the one file `bin/release` writes. The manifest
+// carries it under a key no component can have (a component's is PascalCase or
+// `folder/_snake`); the server compares it with its own and says so loudly when
+// the page's JavaScript is another release's.
+export const BUILD_KEY = "__ruact__";
+const GEM_VERSION_FILE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../lib/ruact/version.rb");
+
+// The gem version beside this plugin, or null when the plugin is not inside a
+// gem (a copy elsewhere): the manifest then records none, and the server takes
+// the build for an older release's, which is what it is told to warn about.
+export function readRuactVersion(file = GEM_VERSION_FILE) {
+  try {
+    return fs.readFileSync(file, "utf8").match(/VERSION = "([^"]+)"/)?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// The manifest as written and served: the build's record first, then the
+// components. The in-memory manifest never holds it — the registry and the
+// build's chunk matching iterate the components only.
+export function withBuild(manifest, version) {
+  return version ? { [BUILD_KEY]: { version }, ...manifest } : manifest;
+}
+
 export default function ruact(options = {}) {
   const {
     componentsDir = "app/javascript/components",
@@ -78,6 +105,7 @@ export default function ruact(options = {}) {
   let root;
   let manifest = {};
   let flightClient; // { source: "app" | "vendored", version, mode }
+  let ruactVersion = null;
 
   return installServerFunctionsHooks({
     name: "vite-plugin-ruact",
@@ -94,6 +122,13 @@ export default function ruact(options = {}) {
       flightClient = resolveFlightClient(root, config.isProduction ? "production" : "development");
       // Dev server and build alike, so a build log shows it too.
       config.logger?.info?.(`[ruact] Flight client: ${describeFlightClient(flightClient)}`);
+      ruactVersion = readRuactVersion();
+      if (!ruactVersion) {
+        config.logger?.warn?.(
+          `[ruact] could not read the ruact version from ${GEM_VERSION_FILE}: the manifest will not say which ` +
+            "ruact built it, and the server will warn that this build is another release's.",
+        );
+      }
     },
 
     // Story 10.1b / 14.2 — resolve ruact's virtual module ids.
@@ -121,7 +156,7 @@ export default function ruact(options = {}) {
     // During dev: build the manifest from source files
     buildStart() {
       manifest = buildManifest(path.resolve(root, componentsDir));
-      writeManifest(path.resolve(root, manifestOutput), manifest);
+      writeManifest(path.resolve(root, manifestOutput), withBuild(manifest, ruactVersion));
     },
 
     // During build: update with hashed chunk URLs from the bundle
@@ -180,7 +215,7 @@ export default function ruact(options = {}) {
         delete entry._sourceFile;
       }
 
-      writeManifest(path.resolve(root, manifestOutput), final);
+      writeManifest(path.resolve(root, manifestOutput), withBuild(final, ruactVersion));
     },
 
     // Dev server: watch components dir and rebuild manifest on change. Story
@@ -207,13 +242,13 @@ export default function ruact(options = {}) {
           out[name] = rest;
         }
         res.setHeader("Content-Type", "application/json");
-        res.end(JSON.stringify(out));
+        res.end(JSON.stringify(withBuild(out, ruactVersion)));
       });
 
       const rebuild = (file) => {
         if (!file.startsWith(dir)) return;
         manifest = buildManifest(dir);
-        writeManifest(path.resolve(root, manifestOutput), manifest);
+        writeManifest(path.resolve(root, manifestOutput), withBuild(manifest, ruactVersion));
         const mod = server.moduleGraph.getModuleById(RESOLVED_REGISTRY_ID);
         if (mod) {
           server.moduleGraph.invalidateModule(mod);

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

@@ -20,6 +20,8 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { build } from "vite";
 import {
+  BUILD_KEY,
+  readRuactVersion,
   buildManifest,
   generateRegistrySource,
   REGISTRY_VIRTUAL_ID,
@@ -143,9 +145,13 @@ describe("prod id-match invariant — real vite build (Story 10.1b AC2, LOAD-BEA
     });
 
     // The manifest the gem will read (ids === Flight moduleIds).
-    const manifest = JSON.parse(
+    const written = JSON.parse(
       fs.readFileSync(path.join(dir, "public/react-client-manifest.json"), "utf8")
     );
+    // Story 19-3 — the build's record comes first, and is not a component.
+    const { [BUILD_KEY]: build19_3, ...manifest } = written;
+    expect(Object.keys(written)[0]).toBe(BUILD_KEY);
+    expect(build19_3).toEqual({ version: readRuactVersion() });
     const manifestIds = new Set(Object.values(manifest).map((e) => e.id));
 
     // Prod ids stay source-relative (eager-inlined components → no facade chunk

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruact
 version: !ruby/object:Gem::Version
-  version: 0.0.21
+  version: 0.0.22
 platform: ruby
 authors:
 - Luiz Garcia
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-15 00:00:00.000000000 Z
+date: 2026-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -43,6 +43,7 @@ files:
 - RELEASING.md
 - SECURITY.md
 - lib/generators/ruact/install/install_generator.rb
+- lib/generators/ruact/install/legacy/vite.config.pinned.js
 - lib/generators/ruact/install/templates/AGENTS.md.tt
 - lib/generators/ruact/install/templates/Procfile.dev.tt
 - lib/generators/ruact/install/templates/dev.tt
@@ -71,6 +72,7 @@ files:
 - lib/generators/ruact/scaffold/templates/views/new.html.erb.tt
 - lib/generators/ruact/scaffold/templates/views/show.html.erb.tt
 - lib/ruact.rb
+- lib/ruact/build_skew.rb
 - lib/ruact/cached_blocks.rb
 - lib/ruact/client_manifest.rb
 - lib/ruact/component_attributes.rb
@@ -159,6 +161,7 @@ files:
 - vendor/javascript/ruact-server-functions-runtime/package.json
 - vendor/javascript/ruact-server-functions-runtime/usequery.test.mjs
 - vendor/javascript/vite-plugin-ruact/bootstrap.test.mjs
+- vendor/javascript/vite-plugin-ruact/build-version.test.mjs
 - vendor/javascript/vite-plugin-ruact/flight-conformance.test.mjs
 - vendor/javascript/vite-plugin-ruact/index.js
 - vendor/javascript/vite-plugin-ruact/manifest-contract.test.mjs