ruact 0.0.5 → 0.0.6

data/lib/ruact/signed_references.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Story 13.2 (FR96) — the canonical record-reference primitive: a **signed,
+  # scoped, expiring** SignedGlobalID token instead of a raw id or attribute
+  # dump.
+  #
+  # A controller that puts `@post.id` (or an attribute hash) into props hands
+  # the client a *forgeable, unscoped, non-expiring* reference: swap `id: 7`
+  # for `id: 8` and, if the action trusts `params[:id]` raw, it reaches a record
+  # it should not. `Ruact.signed_global_id` mints a `SignedGlobalID` instead —
+  # HMAC-signed by the app secret (tamper-proof), bound to a `for:` purpose
+  # (scoped to one use-site), and `expires_in:`-bounded — and
+  # `Ruact.locate_signed` resolves it back, raising
+  # {Ruact::InvalidSignedGlobalIDError} (→ a clean 4xx) on a tampered, expired,
+  # or wrong-purpose token. This is the structural antidote to forged-reference
+  # attacks, the inbound-safety counterpart to the serialize-only invariant
+  # (Story 13.1).
+  #
+  # This is **opt-in and explicit** — it follows the same grain as
+  # `ruact_props` (an explicit allowlist, not auto-detection). The developer
+  # reaches for the helper; ruact never silently rewrites every
+  # `ActiveRecord::Base` in props, and never auto-coerces inbound params into
+  # records.
+  #
+  # @example Outbound — sign a reference in props, resolve it in an action
+  #   # controller producing props
+  #   def edit
+  #     @post_ref = Ruact.signed_global_id(@post, for: :post_edit, expires_in: 1.hour)
+  #   end
+  #
+  #   # server function receiving the reference back from the client
+  #   def update
+  #     post = Ruact.locate_signed(params[:post_ref], for: :post_edit)
+  #     post.update!(post_params)
+  #   end
+  module SignedReferences
+    # Sentinel marking "the caller omitted this keyword", kept distinct from an
+    # explicit `nil`. Omission falls back to the configured default and, failing
+    # that, raises loudly (AC1: "omitting both is a loud error, not a silent
+    # insecure default"). An explicit `expires_in: nil` is honored as a
+    # deliberate, reviewed non-expiring token.
+    UNSET = Object.new
+    def UNSET.inspect = "Ruact::SignedReferences::UNSET"
+    UNSET.freeze
+    private_constant :UNSET
+
+    # Mint a `SignedGlobalID` token string for a record, scoped to a `for:`
+    # purpose and bounded by `expires_in:`.
+    #
+    # @param record [GlobalID::Identification] an ActiveRecord (or any
+    #   GlobalID-locatable) record — anything responding to `#to_sgid`.
+    # @param for [Symbol, String] the purpose binding the token to one
+    #   use-site. Omitted → {Ruact::Configuration#signed_global_id_default_purpose};
+    #   if neither is set (or it resolves to `nil`), raises {Ruact::Error} —
+    #   ruact refuses to sign an unscoped reference.
+    # @param expires_in [ActiveSupport::Duration, nil] token lifetime. Omitted
+    #   → {Ruact::Configuration#signed_global_id_default_expires_in}; if neither
+    #   is set, raises {Ruact::Error}. Pass an explicit `nil` to deliberately
+    #   mint a non-expiring token (a reviewed per-call choice).
+    # @return [String] the signed token, safe to serialize as a prop (it is a
+    #   plain `String`, so the Flight serializer carries it unchanged).
+    # @raise [Ruact::Error] when the record is not GlobalID-locatable, or when a
+    #   purpose/expiry cannot be resolved.
+    def signed_global_id(record, for: UNSET, expires_in: UNSET)
+      __ruact_require_global_id!
+      purpose = __ruact_resolve_purpose(binding.local_variable_get(:for))
+      expiry  = __ruact_resolve_expiry(expires_in)
+
+      unless record.respond_to?(:to_sgid)
+        raise Ruact::Error,
+              "Ruact.signed_global_id expects a GlobalID-locatable record (one responding to " \
+              "#to_sgid, e.g. an ActiveRecord model); got #{record.class}."
+      end
+
+      record.to_sgid(for: purpose, expires_in: expiry).to_s
+    end
+
+    # Resolve a signed token back to its record, verifying signature, expiry,
+    # and purpose. The inverse of {#signed_global_id}.
+    #
+    # @param token [String, nil] the signed token received from the client.
+    # @param for [Symbol, String] the purpose the token must match — resolved
+    #   the same way as {#signed_global_id} (omitted → config → raise).
+    # @return [GlobalID::Identification] the located record.
+    # @raise [Ruact::InvalidSignedGlobalIDError] when the token is tampered,
+    #   expired, or scoped to a different purpose (`locate_signed` returns
+    #   `nil`). The structured-error chain maps this to a clean 4xx — no
+    #   `ActiveRecord::RecordNotFound` leak, no raw-id trust.
+    # @raise [Ruact::Error] when a purpose cannot be resolved.
+    def locate_signed(token, for: UNSET)
+      __ruact_require_global_id!
+      purpose = __ruact_resolve_purpose(binding.local_variable_get(:for))
+      record  = GlobalID::Locator.locate_signed(token, for: purpose)
+      return record unless record.nil?
+
+      raise Ruact::InvalidSignedGlobalIDError,
+            "Signed reference could not be verified for purpose #{purpose.inspect} " \
+            "(it may be tampered, expired, or scoped to a different purpose)."
+    end
+
+    private
+
+    # Lazy-require globalid only when a signed-reference helper is actually
+    # called — the gem keeps a single hard runtime dependency (nokogiri) and
+    # stays loadable in pure-Ruby contexts (mirrors the class-name-string
+    # matching in ErrorRendering that avoids requiring ActiveRecord at load).
+    # globalid ships with every Rails app, so a host never hits the rescue.
+    def __ruact_require_global_id!
+      require "global_id"
+    rescue LoadError
+      raise Ruact::Error,
+            "Ruact signed references require the `globalid` gem, which ships with Rails. " \
+            "Add `gem \"globalid\"` to your Gemfile if you are running ruact outside a Rails app."
+    end
+
+    # Purpose must ALWAYS be present — an unscoped token is never acceptable, so
+    # both omission-without-default AND an explicit `for: nil` raise.
+    def __ruact_resolve_purpose(arg)
+      resolved = arg.equal?(UNSET) ? Ruact.config.signed_global_id_default_purpose : arg
+      return resolved unless resolved.nil?
+
+      raise Ruact::Error,
+            "Ruact signed references require a purpose: pass `for:` (a Symbol/String scoping the " \
+            "token to one use-site) or set `Ruact.config.signed_global_id_default_purpose`. " \
+            "Refusing to sign or resolve an unscoped reference."
+    end
+
+    # Expiry distinguishes omission from a deliberate `nil`. An explicit value
+    # (including `nil` → non-expiring) is honored; pure omission falls to the
+    # configured default and, if that too is unset, raises — never a silent
+    # non-expiring token. The resolved value is then type-checked: only `nil`
+    # (the one reviewed non-expiring escape hatch) or an `ActiveSupport::Duration`
+    # (anything responding to `#from_now`, which is what globalid calls) is
+    # allowed — so a stray `false` (which globalid would silently treat as
+    # non-expiring) or a bare Integer (which globalid would crash on) is rejected
+    # loudly, closing the second silent non-expiring path.
+    def __ruact_resolve_expiry(arg)
+      omitted = arg.equal?(UNSET)
+      expiry  = omitted ? Ruact.config.signed_global_id_default_expires_in : arg
+
+      if omitted && expiry.nil?
+        raise Ruact::Error,
+              "Ruact.signed_global_id requires an expiry: pass `expires_in:` (an " \
+              "ActiveSupport::Duration like `15.minutes`, or an explicit `nil` to deliberately mint a " \
+              "non-expiring token) or set `Ruact.config.signed_global_id_default_expires_in`. " \
+              "Refusing to silently mint a non-expiring reference."
+      end
+
+      unless expiry.nil? || expiry.respond_to?(:from_now)
+        raise Ruact::Error,
+              "Ruact signed-reference expiry must be an ActiveSupport::Duration (e.g. `15.minutes`) " \
+              "or an explicit `nil` (a deliberate non-expiring token); got #{expiry.inspect}. " \
+              "A bare Integer or `false` is rejected to avoid an accidental non-expiring token."
+      end
+
+      expiry
+    end
+  end
+
+  extend SignedReferences
+end

data/lib/ruact/string_distance.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Damerau-Levenshtein string distance + a "did you mean?" closest-match
+  # helper, factored out of {Ruact::ClientManifest} (Story 7.4) so the
+  # Story 13.5 component-contract validator can reuse the SAME closest-match
+  # grain for typo'd prop/slot names ("did you mean `postId`?") without
+  # duplicating the algorithm.
+  #
+  # Names are short (≤ 30 chars in practice) so the full O(m·n) DP table is
+  # fine — the readability win over the two-row trick is worth ~30 cells.
+  module StringDistance
+    # Damerau-Levenshtein distance — like classic Levenshtein but treats an
+    # adjacent transposition (e.g. "ke"↔"ek") as a single edit.
+    #
+    # @param left [String]
+    # @param right [String]
+    # @return [Integer] the edit distance
+    # rubocop:disable Metrics/AbcSize
+    def self.damerau_levenshtein(left, right)
+      return right.length if left.empty?
+      return left.length if right.empty?
+
+      m = left.length
+      n = right.length
+      d = Array.new(m + 1) { Array.new(n + 1, 0) }
+      (0..m).each { |i| d[i][0] = i }
+      (0..n).each { |j| d[0][j] = j }
+
+      (1..m).each do |i|
+        (1..n).each do |j|
+          cost = left[i - 1] == right[j - 1] ? 0 : 1
+          d[i][j] = [
+            d[i - 1][j] + 1,        # deletion
+            d[i][j - 1] + 1,        # insertion
+            d[i - 1][j - 1] + cost  # substitution
+          ].min
+          if i > 1 && j > 1 && left[i - 1] == right[j - 2] && left[i - 2] == right[j - 1]
+            d[i][j] = [d[i][j], d[i - 2][j - 2] + cost].min
+          end
+        end
+      end
+
+      d[m][n]
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # Returns the entry in +pool+ within Damerau-Levenshtein distance +max+ of
+    # +name+ (case-insensitive), preferring the smallest distance. Returns +nil+
+    # when nothing qualifies.
+    #
+    # @param name [String] the typo'd name to match
+    # @param pool [Array<String>] candidate names
+    # @param max [Integer] inclusive distance threshold (default 2)
+    # @return [String, nil]
+    def self.closest_match(name, pool, max: 2)
+      target = name.downcase
+      best = nil
+      best_distance = max + 1
+
+      pool.each do |candidate|
+        distance = damerau_levenshtein(target, candidate.downcase)
+        next if distance > max || distance >= best_distance
+
+        best_distance = distance
+        best = candidate
+      end
+
+      best
+    end
+  end
+end

data/lib/ruact/validation_errors_collector.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require_relative "server_functions/validation_errors"
+
+module Ruact
+  # Story 13.3 (FR98) — the per-request validation-error collector, shared by
+  # {Ruact::Server} (Bucket-2 JSON-body injection + redirect flash stash) and
+  # {Ruact::Controller} (page-render `errors` prop + redirect-back flash read).
+  #
+  # This is the **opt-in** half of the Inertia-style `errors` round-trip
+  # (design (B), the explicit-allowlist grain that 13.1/13.2 reinforced — NO
+  # auto-injection, NO globally reserved prop on every response). A host action
+  # opts in with a single call after its save attempt:
+  #
+  #   def create
+  #     @post = Post.new(post_params)
+  #     if @post.save
+  #       redirect_to @post
+  #     else
+  #       ruact_errors(@post)            # registers {attr => [full messages]}
+  #       render :new                    # (Bucket 1) or fall through (Bucket 2)
+  #     end
+  #   end
+  #
+  # Because the canonical shape derives from `record.errors` (empty on a valid
+  # record), the SAME `ruact_errors(@post)` call yields `{}` on success and the
+  # populated map on failure — the "always present, same code path" invariant of
+  # AC1, delivered per-action without reserving a global prop name or disturbing
+  # the Story 9.2 Bucket-2 `204 No Content` contract for an untouched collector.
+  #
+  # The reader form (no argument) returns the always-present hash for binding to
+  # a form component on the page render:
+  #
+  #   <PostForm post={@post} errors={ruact_errors} />
+  module ValidationErrorsCollector
+    extend ActiveSupport::Concern
+
+    # Flash key the Bucket-1 redirect-back round-trip stashes the canonical
+    # errors under (single-use, session-backed — the exact Inertia semantics).
+    RUACT_ERRORS_FLASH_KEY = :ruact_errors
+
+    # `view_assigns` keys (ivar names without the leading `@`) that must NEVER
+    # serialize into a Bucket-2 body: the two collector internals (Rails only
+    # filters a fixed set of `@_`-named ivars, not every `@__`-prefixed one), and
+    # the reserved `errors` output key itself (a stray dev ivar literally named
+    # `@errors` is dropped so it can neither clobber the round-trip key nor trip
+    # strict serialization — the collector is the source of truth).
+    RESERVED_ASSIGN_KEYS = %w[__ruact_errors __ruact_errors_touched errors].freeze
+
+    # Sentinel distinguishing the COLLECT call (`ruact_errors(record)`, argument
+    # given) from the READ call (`ruact_errors`, no argument). `nil` is a valid
+    # collect argument (it normalizes to `{}`), so it cannot be the sentinel.
+    NOT_GIVEN = Object.new
+    private_constant :NOT_GIVEN
+
+    included do
+      # Expose the reader to the view so a template can bind
+      # `errors={ruact_errors}` on a component. Guarded for non-controller hosts
+      # (which never reach the page-render path).
+      helper_method :ruact_errors if respond_to?(:helper_method)
+    end
+
+    # Dual-purpose helper.
+    #
+    #   ruact_errors(@post)  → COLLECT: normalize the record's errors into the
+    #     canonical `{attr => [full messages]}` shape, merge it into the
+    #     per-request collector, mark the collector touched, and return the
+    #     normalized hash (so it can also be used inline).
+    #   ruact_errors         → READ: return the always-present collector (`{}` by
+    #     default), for binding to a form component on the page render.
+    #
+    # Merging across multiple records is additive per attribute (later calls
+    # union their messages onto earlier ones), so an action validating several
+    # records surfaces them under one `errors` object.
+    #
+    # @overload ruact_errors(record)
+    #   @param record [#errors, ActiveModel::Errors, Hash, nil] the failed record
+    #   @return [Hash{String=>Array<String>}] the normalized errors for +record+
+    # @overload ruact_errors
+    #   @return [Hash{String=>Array<String>}] the always-present collector
+    def ruact_errors(record = NOT_GIVEN)
+      return __ruact_errors if record.equal?(NOT_GIVEN)
+
+      normalized = ServerFunctions::ValidationErrors.normalize(record)
+      @__ruact_errors_touched = true
+      __ruact_errors.merge!(normalized) do |_attribute, existing, incoming|
+        existing | incoming
+      end
+      normalized
+    end
+
+    private
+
+    # The per-request collector. A private ivar (NOT a `view_assigns` ivar) so it
+    # never collides with the dev's own assigns during Bucket-2 serialization.
+    def __ruact_errors
+      @__ruact_errors ||= {}
+    end
+
+    # Whether `ruact_errors` was called in a writing form this request (or the
+    # collector was seeded from a redirect-back flash). Gates the Bucket-2
+    # injection so an UNTOUCHED collector preserves the 9.2 `204 No Content`
+    # contract — a populated `{}` (opted-in success) is still "touched".
+    def __ruact_errors_touched?
+      @__ruact_errors_touched == true
+    end
+
+    # Stash the canonical errors in `flash` so they survive a Bucket-1
+    # redirect-back (the re-render is a fresh GET). No-op when the collector was
+    # never touched, or when the host has no usable session/flash (an API-only
+    # host without sessions degrades to the Bucket-2 body path rather than
+    # crashing — AC4 constraint).
+    def __ruact_stash_errors_in_flash
+      return unless __ruact_errors_touched?
+      return unless respond_to?(:flash)
+
+      flash[RUACT_ERRORS_FLASH_KEY] = __ruact_errors
+    rescue StandardError
+      nil
+    end
+
+    # Seed the collector from a redirect-back flash on the re-rendered GET so the
+    # reader exposes the surviving errors as a page-render prop. `flash` is
+    # single-use (Rails sweeps it after this request), so the prop does not
+    # persist beyond the re-render.
+    def __ruact_read_errors_from_flash
+      return unless respond_to?(:flash)
+
+      stashed = flash[RUACT_ERRORS_FLASH_KEY]
+      return if stashed.nil?
+
+      @__ruact_errors_touched = true
+      __ruact_errors.merge!(ServerFunctions::ValidationErrors.normalize(stashed))
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/ruact/version.rb

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

data/lib/ruact/view_helper.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "json"
+require "socket"
+
 module Ruact
   # ActionView helper module included in ActionView::Base via Railtie.
   # Provides the +__ruact_component__+ method that ERB templates call after the
@@ -27,5 +30,104 @@ module Ruact
       token = ctx.register(name, props)
       "<!-- #{token} -->".html_safe
     end
+
+    # Story 14.2 (FR104) — emits ruact's full JavaScript asset block: the
+    # dev/prod bootstrap entry `<script>` tags (re-targeting the virtual entry
+    # `virtual:ruact/bootstrap` — in dev the react-refresh preamble + `@vite/client`
+    # + the bootstrap module; in prod the hashed URL read from the Vite manifest)
+    # AND, when a Flight payload is given, the `__FLIGHT_DATA` inline bootstrap
+    # `<script>` the entry reads on boot.
+    #
+    # This is the SINGLE implementation of the JS asset markup —
+    # `Ruact::Controller#ruact_html_shell` delegates to it so the controller's
+    # generated shell and any view that calls the helper emit byte-identical tags
+    # (no drift). Available in every view via the railtie's
+    # `ActionView::Base.include(Ruact::ViewHelper)`.
+    #
+    # @param flight_payload [String, nil] the per-render Flight wire payload to
+    #   inline as `__FLIGHT_DATA`; omit (or pass nil) to emit only the entry tags.
+    # @return [ActiveSupport::SafeBuffer] the asset markup, html_safe
+    # @example In a layout
+    #   <%= ruact_js_assets %>
+    def ruact_js_assets(flight_payload = nil)
+      parts = []
+      parts << ruact_flight_data_script(flight_payload) unless flight_payload.nil?
+      parts << ruact_vite_tags
+      parts.join("\n").html_safe
+    end
+
+    private
+
+    # The `__FLIGHT_DATA` inline bootstrap `<script>` — pushes the per-render
+    # Flight payload onto the global queue the bootstrap entry drains on boot.
+    # `</script>` in the payload is escaped to prevent an HTML/XSS breakout
+    # (mandatory whenever Flight data is inlined into a `<script>` tag).
+    def ruact_flight_data_script(flight_payload)
+      escaped_payload = flight_payload.gsub("</script>", '<\/script>')
+      <<~HTML.strip
+        <script>
+          (function() {
+            var d = (self.__FLIGHT_DATA = self.__FLIGHT_DATA || []);
+            d.push(#{escaped_payload.inspect});
+          })();
+        </script>
+      HTML
+    end
+
+    # The bootstrap entry `<script>` tags — dev serves the virtual module from
+    # the Vite dev server (with the react-refresh preamble + `@vite/client`);
+    # prod reads the hashed URL from the Vite manifest. Both target the SAME
+    # virtual entry id (`Ruact.bootstrap_virtual_id`) so dev/prod stay in lockstep.
+    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.
+        react_preamble = <<~JS
+          <script type="module">
+            import RefreshRuntime from 'http://localhost:5173/@react-refresh';
+            RefreshRuntime.injectIntoGlobalHook(window);
+            window.$RefreshReg$ = () => {};
+            window.$RefreshSig$ = () => (type) => type;
+            window.__vite_plugin_react_preamble_installed__ = true;
+          </script>
+        JS
+
+        react_preamble + <<~HTML
+          <script type="module" src="http://localhost:5173/@vite/client"></script>
+          <script type="module" src="#{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"
+        %(<script type="module" src="#{src}"></script>)
+      end
+    end
+
+    # The Vite dev-server URL for the virtual bootstrap. Vite serves virtual
+    # modules under `/@id/`, encoding the resolved id's leading NUL (`\0`) as
+    # `__x00__` — so `\0virtual:ruact/bootstrap` is served at
+    # `/@id/__x00__virtual:ruact/bootstrap`. A plain `/virtual:...` URL falls
+    # through to the dev server's HTML fallback, so this encoding is required.
+    def ruact_bootstrap_dev_url
+      "http://localhost:5173/@id/__x00__#{Ruact.bootstrap_virtual_id}"
+    end
+
+    def vite_dev_running?
+      require "socket"
+      Socket.tcp("localhost", 5173, connect_timeout: 1).close
+      true
+    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ETIMEDOUT, SocketError
+      false
+    end
+
+    def vite_manifest_entry(src_path)
+      manifest_path = Rails.root.join("public", "assets", ".vite", "manifest.json")
+      return nil unless File.exist?(manifest_path)
+
+      JSON.parse(File.read(manifest_path))[src_path]
+    end
   end
 end

data/lib/ruact.rb

@@ -4,7 +4,10 @@ require_relative "ruact/version"
 require_relative "ruact/errors"
 require_relative "ruact/configuration"
 require_relative "ruact/serializable"
+require_relative "ruact/signed_references"
 require_relative "ruact/flight"
+require_relative "ruact/string_distance"
+require_relative "ruact/component_contract"
 require_relative "ruact/erb_preprocessor"
 require_relative "ruact/render_context"
 require_relative "ruact/html_converter"
@@ -13,7 +16,6 @@ require_relative "ruact/render_pipeline"
 require_relative "ruact/view_helper"
 require_relative "ruact/erb_preprocessor_hook"
 require_relative "ruact/server_functions"
-require_relative "ruact/server_action"
 require_relative "ruact/query"
 # Railtie loads ruact/controller when inside a Rails app
 require_relative "ruact/railtie" if defined?(Rails)
@@ -22,24 +24,6 @@ module Ruact
   class << self
     attr_accessor :manifest, :streaming_mode
 
-    # Registry of `ruact_action` declarations. Populated by Story 8.1's
-    # controller macro; consumed by {Ruact::ServerFunctions::Snapshot} when
-    # writing the Rails↔Vite bridge JSON.
-    #
-    # @return [Ruact::ServerFunctions::Registry] lazy-initialized singleton.
-    def action_registry
-      @action_registry ||= ServerFunctions::Registry.new
-    end
-
-    # Registry of `ruact_query` declarations. Populated by Story 9.1's
-    # controller macro; consumed by {Ruact::ServerFunctions::Snapshot} when
-    # writing the Rails↔Vite bridge JSON.
-    #
-    # @return [Ruact::ServerFunctions::Registry] lazy-initialized singleton.
-    def query_registry
-      @query_registry ||= ServerFunctions::Registry.new
-    end
-
     # Story 8.4 — Absolute path to the gem's `lib/` root. Used by
     # {Ruact::ServerFunctions::BacktraceCleaner} to classify backtrace frames as
     # APP or GEM. Memoised at first call so the per-frame `start_with?` check
@@ -60,6 +44,22 @@ module Ruact
       File.expand_path("../vendor/javascript/vite-plugin-ruact/index.js", __dir__)
     end
 
+    # Story 14.2 (FR104) — the SINGLE source of truth for the bootstrap entry id.
+    # ruact's React entry is served as the virtual module `virtual:ruact/bootstrap`
+    # (by the bundled Vite plugin) instead of a `app/javascript/application.jsx`
+    # file in the user's tree. Every reference point must agree on this id:
+    #   - the generated `vite.config` `rollupOptions.input`
+    #   - the dev `<script src>` (`/@id/__x00__virtual:ruact/bootstrap`)
+    #   - the production Vite-manifest lookup key
+    #   - the plugin's `resolveId`/`load` (`BOOTSTRAP_VIRTUAL_ID` in index.js)
+    # `Ruact::ViewHelper#ruact_js_assets` and `templates/vite.config.js.tt` both
+    # read this constant so they can never drift (the regression AC3 guards).
+    #
+    # @return [String] the bootstrap virtual-module id ("virtual:ruact/bootstrap")
+    def bootstrap_virtual_id
+      "virtual:ruact/bootstrap"
+    end
+
     # Yields a mutable Configuration draft for block-style setup. The draft is
     # frozen and atomically swapped into `Ruact.config` when the block returns.
     # Mutating `Ruact.config` outside this block raises

data/lib/tasks/ruact.rake

@@ -8,67 +8,24 @@ namespace :ruact do
   end
 
   namespace :server_functions do
-    # Story 8.0a — manual / CI / production codegen entry point. Mirrors the
-    # Railtie hook (config.to_prepare) for environments where the dev server
+    # Story 8.0a / 9.9 — manual / CI / production codegen entry point. Mirrors
+    # the Railtie hook (config.to_prepare) for environments where the dev server
     # is not running (CI, deploy pipelines, container build steps).
     #
-    # Pipeline:
-    #   1. `Snapshot.generate!` writes the JSON bridge IF its registry
-    #      payload differs from the on-disk version (write-if-changed by
-    #      payload, not by timestamp).
-    #   2. `Snapshot.read_for_codegen` re-loads the persisted JSON — this is
-    #      the on-disk source of truth that the Vite plugin consumes, and
-    #      reusing it (instead of freshly dumping with a new timestamp)
-    #      keeps the TS module byte-stable on unchanged registries.
-    #   3. `Codegen.generate_ts!` writes the TS module via the same write-
-    #      if-changed guard.
+    # Story 9.9 — the route-driven (v2) codegen is the sole writer. The task
+    # forces the route table to load, then writes the v2 snapshot to the REAL
+    # bridge (`tmp/cache/ruact/server-functions.json`) and renders the TS module
+    # (`app/javascript/.ruact/server-functions.ts`), both write-if-changed.
     #
     # Exit codes: 0 on success or no-op rewrites; 1 on
-    # `Ruact::ConfigurationError` (invalid symbol shape per AC7, cross-
-    # registry collision, invalid kind, or a corrupted snapshot rejected by
-    # the codegen's identifier guard).
-    desc "Regenerate app/javascript/.ruact/server-functions.ts from the gem registries (Story 8.0a)"
+    # `Ruact::ConfigurationError` (a server-function naming collision, an
+    # invalid name, or a corrupted snapshot rejected by the codegen guards).
+    desc "Regenerate app/javascript/.ruact/server-functions.ts from the Rails route table (Story 9.9)"
     task generate: :environment do
       require "ruact/server_functions"
-      require "json"
-
-      json_path = Rails.root.join("tmp/cache/ruact/server-functions.json")
-      ts_path   = Rails.root.join("app/javascript/.ruact/server-functions.ts")
 
       begin
-        Ruact::ServerFunctions::Snapshot.generate!(
-          action_registry: Ruact.action_registry,
-          query_registry: Ruact.query_registry,
-          path: json_path
-        )
-        # Pass-2 patch 2026-05-14 — the JSON can disappear OR be partially
-        # written between `generate!` and `File.read` (a concurrent rake
-        # invocation flushing mid-write, a tmpdir wipe by Spring, an
-        # externally-managed `tmp/cache` cleaner). Both `Errno::ENOENT` AND
-        # `JSON::ParserError` indicate the same TOCTOU window — re-invoke
-        # `generate!` once with the same registries; if the second read
-        # still fails we surface the error with a clear "[ruact] error"
-        # envelope so the caller sees a real failure rather than an
-        # unwrapped Errno / parser backtrace.
-        snapshot = begin
-          JSON.parse(File.read(json_path)).transform_keys(&:to_sym)
-        rescue Errno::ENOENT, JSON::ParserError
-          Ruact::ServerFunctions::Snapshot.generate!(
-            action_registry: Ruact.action_registry,
-            query_registry: Ruact.query_registry,
-            path: json_path
-          )
-          JSON.parse(File.read(json_path)).transform_keys(&:to_sym)
-        end
-        Ruact::ServerFunctions::Codegen.generate_ts!(
-          snapshot: snapshot,
-          output_path: ts_path
-        )
-
-        # Story 9.3 — also emit the route-driven (v2) parallel target
-        # (`server-functions.next.{json,ts}`). Vite does not render the `.next`
-        # bridge, so the rake is the production/CI path that materializes it for
-        # parity + inspection. The real `server-functions.ts` above stays v1.
+        Rails.application.routes_reloader.execute_unless_loaded
         Ruact::ServerFunctions.write_v2_snapshot!(
           route_set: Rails.application.routes, root: Rails.root, logger: Rails.logger
         )

data/spec/fixtures/story_7_9_views/controller_request_spec_support/errors_demo/new.html.erb

@@ -0,0 +1,3 @@
+<div>
+  <DemoButton label={"new-post"} errors={ruact_errors} />
+</div>