ruact 0.0.7 → 0.0.9

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

@@ -0,0 +1,159 @@
+<!-- ruact:begin -->
+<!-- Managed by `rails generate ruact:install`. Re-run it with --force after a
+     gem upgrade to refresh ONLY this marked section; everything you write
+     outside the markers is preserved. Kept in sync manually with the online
+     copy at https://ruact.dev/llms.txt -->
+
+# ruact — conventions for coding agents
+
+ruact renders React Server Components from Rails. ERB templates ARE the server
+components (serialized to the React Flight wire format), Rails routes are the
+single source of truth, and there is no Node server — Vite only bundles the
+client components. ruact is NOT Inertia, react-rails, or Next.js: do not
+transplant their patterns. When unsure, read the generated code (see "Ground
+truth" below) instead of guessing.
+
+## Mental model
+
+- A page is a normal Rails controller action rendering a normal `.html.erb`.
+- Interactive components live in `app/javascript/components/` as `"use client"`
+  files, mounted from ERB with a PascalCase self-closing tag:
+  `<LikeButton postId={@post.id} />`.
+- Mutations are ordinary non-GET controller actions on a controller that does
+  `include Ruact::Server`. Reads are `Ruact::Query` classes in `app/queries/`.
+- ruact generates a typed TypeScript module from the route table; React imports
+  server functions from `@/.ruact/server-functions`.
+
+## Server functions — the verb rule
+
+`include Ruact::Server` makes a controller's routed non-GET actions
+(`POST`/`PATCH`/`PUT`/`DELETE`) callable from React. GET page actions are
+untouched. There is no per-action DSL and no synthetic endpoint: the action IS
+the function, reached at its real route, visible in `bin/rails routes`. The JS
+runtime forwards the CSRF token automatically; keep `include Ruact::Server`
+AFTER `protect_from_forgery` in the ancestor chain.
+
+```ruby
+class PostsController < ApplicationController
+  include Ruact::Server
+
+  def create
+    @post = Post.create!(post_params) # ivars become the JSON result
+  end
+end
+```
+
+```tsx
+import { createPost } from "@/.ruact/server-functions";
+const { post } = await createPost({ post: { title: "Hi" } });
+```
+
+## Reads — queries and useQuery
+
+Reads are public methods on `Ruact::Query` subclasses in `app/queries/`,
+mounted in `config/routes.rb` with `ruact_queries CatalogQuery` (one named GET
+route per public method, default prefix `/q`). Call them with `useQuery`:
+
+```tsx
+import { categories, useQuery } from "@/.ruact/server-functions";
+const { data, loading, error } = useQuery(categories);
+```
+
+Query params come from the method's keyword arguments and accept ONLY
+`string | number | boolean | null` (arrays/objects are rejected). Queries run
+the host controller's callback chain (authentication etc.) before the query
+object is instantiated.
+
+## Ground truth — read the generated file
+
+`app/javascript/.ruact/server-functions.ts` is regenerated from the route
+table (it is gitignored). It is the authoritative list of every accessor and
+its typed params — READ THAT FILE instead of simulating the name generation.
+Regenerate it after changing routes or queries:
+
+    bin/rails ruact:server_functions:generate
+
+## Five traps
+
+1. **Component tags take no children.** Client component tags are self-closing
+   ONLY: `<Card content={@body} />`, never `<Card>...</Card>`. Children (a
+   matching closing tag) fail LOUDLY with a `PreprocessorError` at preprocess
+   time — pass content as a prop instead. Sole exception: the built-in
+   `<Suspense fallback="...">...</Suspense>` pair.
+2. **`{}` props are Ruby, not JavaScript.** `<Badge label={@post.title} />`
+   evaluates `@post.title` as a Ruby expression in the ERB. No JS ternaries,
+   no `{...spread}`, no JSX children. Plain unbraced string props are not
+   supported either — always use braces.
+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
+   what every generated-accessor call sends (including
+   `<form action={createPost}>`). Any other request shape renders normally
+   (a Flight stream for client-side navigation, an HTML page otherwise). You
+   cannot infer the response shape from the controller body alone — the
+   caller picks it.
+4. **`ruact_errors` requires fall-through.** On the `if @post.save ... else`
+   path, call `ruact_errors(@post)` and let the action END there — ruact's
+   implicit render injects `errors: { attribute: [messages] }` into the JSON.
+   An explicit `render` on that branch opts out of the injection. In the
+   redirect-back flow, `ruact_errors(@post)` then `redirect_to` carries the
+   errors through flash to the next render.
+5. **Accessor names are derived, not declared.** `posts#create` → `createPost`,
+   `posts#publish_all` → `publishAllPosts`; query methods camelCase the same
+   way (`search_users` → `searchUsers`). Collisions fail loudly at boot;
+   break an action tie with `ruact_function_name :action, as: "otherName"` —
+   a query tie by renaming the query method. Never guess a name — read
+   `app/javascript/.ruact/server-functions.ts`.
+
+## Serialization is an allowlist
+
+Only the fields you name cross to the client. `include Ruact::Serializable` +
+`ruact_props :id, :title` is that allowlist — on a PORO OR an ActiveRecord model
+(lazy AR readers checked on first serialize, not class-load; a typo still raises):
+
+```ruby
+class Post < ApplicationRecord
+  include Ruact::Serializable
+  ruact_props :id, :title # other columns never cross
+end
+```
+
+The manual row hash `{ id: p.id, title: p.title }` is the equivalent for a
+no-model shape. An object with no allowlist warns + falls back to `as_json` in
+dev; production (`strict_serialization`) raises, as does `as_json` returning `self`.
+
+## Record references — signed and explicit
+
+Do not put raw record ids in props and trust them later. Mint a scoped signed
+token and resolve it back:
+
+```ruby
+token = Ruact.signed_global_id(@post, for: :editing, expires_in: 1.hour)
+post  = Ruact.locate_signed(params[:token], for: :editing) # tampered → 400
+```
+
+The purpose (`for:`) is always required; the expiry must be explicit — a
+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: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.
+- `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 are required: Vite serves the client
+  components and writes the client manifest).
+- If your app has TypeScript tooling configured, `npx tsc --noEmit`
+  type-checks call sites against the generated accessor types (a fresh
+  install does not ship a tsconfig).
+- In request specs, `require "ruact/testing"` then assert a page rendered a
+  component — `expect(response).to have_ruact_component("PostList").with_props(including("posts"))`
+  — no browser. Function-call/query responses are JSON: `JSON.parse(response.body)`.
+
+Docs: https://ruact.dev — compact agent reference at https://ruact.dev/llms.txt
+<!-- ruact:end -->

data/lib/generators/ruact/install/templates/Procfile.dev.tt

@@ -1,2 +1,5 @@
 web: bin/rails server -p 3000
 vite: npm run dev
+<% if shadcn? -%>
+css: npx @tailwindcss/cli -i app/javascript/styles/globals.css -o app/assets/builds/tailwind.css --watch
+<% end -%>

data/lib/generators/ruact/install/templates/globals.css.tt

@@ -0,0 +1,20 @@
+/* Tailwind entry — the SOURCE, not the asset the browser gets.
+ *
+ * Built into app/assets/builds/tailwind.css by the `css` process in
+ * Procfile.dev, which Propshaft then serves and the layout links:
+ *
+ *   this file ──build──> app/assets/builds/tailwind.css
+ *             ──Propshaft──> /assets/tailwind-<digest>.css
+ *             ──stylesheet_link_tag in app/views/layouts──> the page
+ *
+ * `npx shadcn init` appends its design tokens (the CSS variables the
+ * components reference by name) below this import — that is why
+ * components.json points its `tailwind.css` at this file.
+ */
+@import "tailwindcss";
+
+/* Tailwind v4 declares its class scan here instead of in a config file.
+   Components carry most of the classes; the ERB views carry the page-level
+   ones, so both paths are needed. */
+@source "../components";
+@source "../../views";

data/lib/generators/ruact/install/templates/initializer.rb.tt

@@ -1,6 +1,15 @@
 # frozen_string_literal: true
 
 Ruact.configure do |config|
+  # Render ruact pages through your app's own layout, so the document `<head>`
+  # is yours: `stylesheet_link_tag`, favicons, fonts, analytics and any gem that
+  # writes into `<head>` all reach a ruact page. Requires the layout to call
+  # `<%%= ruact_js_assets %>` (this generator adds it next to the React root).
+  #
+  # Set to false to use ruact's built-in minimal shell instead — it has no
+  # stylesheet slot, so your app's CSS will NOT reach a ruact-rendered page.
+  config.layout = true
+
   # Path to the react-client-manifest.json generated by the Vite plugin.
   # Defaults to Rails.root.join("public/react-client-manifest.json").
   # config.manifest_path = Rails.root.join("public", "react-client-manifest.json")

data/lib/generators/ruact/install/templates/package.json.tt

@@ -4,7 +4,8 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "vite build"
+    "build": "vite build"<% if shadcn? %>,
+    "build:css": "@tailwindcss/cli -i app/javascript/styles/globals.css -o app/assets/builds/tailwind.css --minify"<% end %>
   },
   "dependencies": {
     "react": "^19.0.0",
@@ -12,6 +13,11 @@
   },
   "devDependencies": {
     "@vitejs/plugin-react": "^4.3.4",
+<% if shadcn? -%>
+    "@tailwindcss/cli": "^4.0.0",
+    "tailwindcss": "^4.0.0",
+    "tw-animate-css": "^1.0.0",
+<% end -%>
     "vite": "^6.0.7"
   }
 }

data/lib/generators/ruact/install/templates/tsconfig.json.tt

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["app/javascript/*"]
+    }
+  },
+  "include": ["app/javascript/**/*.ts", "app/javascript/**/*.tsx"]
+}

data/lib/generators/ruact/scaffold/scaffold_shadcn_preflight.rb

@@ -47,6 +47,16 @@ module Ruact
         # List/DeleteDialog primitives. EVERY entry is a plain `npx shadcn add`
         # primitive — there is NO `data-table` recipe and NO `@tanstack/react-table`
         # dependency (Story 10.2b removed the engine; the List is a plain `table`).
+        # The COMPLETE primitive set — the union of everything any generated
+        # resource can import. `#required_shadcn_components` NARROWS this per
+        # resource (the input-family entries depend on the attribute types),
+        # but `ruact:install --shadcn` runs before any resource exists, so it
+        # prints this superset. A spec pins the narrowed list as a subset of
+        # this one, so the two cannot drift apart.
+        ALL_SHADCN_COMPONENTS = %w[
+          button input textarea switch select label badge table alert-dialog dropdown-menu
+        ].freeze
+
         def required_shadcn_components
           components = ["button"]
           components << "input"    if form_uses_input?

data/lib/ruact/configuration.rb

@@ -24,6 +24,7 @@ module Ruact
       signed_global_id_default_purpose
       signed_global_id_default_expires_in
       shadcn_compatible_versions
+      layout
     ].freeze
 
     # @!attribute [r] manifest_path
@@ -135,6 +136,47 @@ module Ruact
     #     suppress the warning — the documented "override" path.
     #   @example Allow shadcn v3 once you have verified it
     #     Ruact.configure { |c| c.shadcn_compatible_versions = [1, 2, 3] }
+    #
+    # @!attribute [r] layout
+    #   @return [Boolean, String] Which document wrapper a ruact page's HTML
+    #     response is rendered into. The Flight response shape
+    #     (`text/x-component`) is never affected — this is only about the
+    #     full-document render a browser gets on a normal navigation.
+    #
+    #     - `false` (default) — render the gem's built-in minimal shell.
+    #     - `true` — render through the controller's normal Rails layout.
+    #     - a String — render through that named layout (e.g. `"ruact"`).
+    #
+    #     The layout path exists because the document `<head>` belongs to the
+    #     host app: `stylesheet_link_tag`, favicons, fonts, analytics and any
+    #     `<head>`-writing gem only reach the page when Rails' own layout owns
+    #     the document. The built-in shell carries no stylesheet slot, so under
+    #     the `false` default a ruact page renders with no app CSS at all —
+    #     which is why `rails generate ruact:install` writes `config.layout =
+    #     true` into the generated initializer and adds `<%= ruact_js_assets %>`
+    #     to your layout in the same run.
+    #
+    #     **This setting is deliberately explicit — there is no auto-detection.**
+    #     ruact used to try to infer whether your layout was ready by inspecting
+    #     it. Deciding that reliably means answering "does this template call
+    #     this method?", which cannot be done by pattern-matching a template
+    #     language: three review rounds each found another shape that fooled it
+    #     (a mention in a comment, a commented-out call, a trim-mode comment),
+    #     and each wrong answer governed how every page in the app rendered.
+    #     One explicit line is worth more than a clever guess here.
+    #
+    #     A layout is ready when it calls `<%= ruact_js_assets %>` (which emits
+    #     the React root's bootstrap entry tags and the per-render Flight
+    #     payload) next to a `<div id="root"></div>`. If it does not, ruact says
+    #     so loudly in development rather than serving a blank page, and
+    #     `rails ruact:doctor` reports it.
+    #   @note A ruact view is rendered in its own pass (it produces the component
+    #     tree), so `content_for` declared inside the view does NOT reach the
+    #     layout. Set document metadata from the controller instead.
+    #   @example Let your layout own the document (what ruact:install writes)
+    #     Ruact.configure { |c| c.layout = true }
+    #   @example Use a dedicated layout for ruact pages only
+    #     Ruact.configure { |c| c.layout = "ruact" }
     ATTRIBUTES.each do |attr|
       attr_reader attr
 
@@ -188,6 +230,7 @@ module Ruact
         @signed_global_id_default_purpose = nil
         @signed_global_id_default_expires_in = nil
         @shadcn_compatible_versions = [1, 2]
+        @layout = false
       end
     end
 
@@ -249,7 +292,37 @@ module Ruact
       when :query_route_prefix      then validate_query_route_prefix!(value)
       when :query_parent_controller then validate_query_parent_controller!(value)
       when :shadcn_compatible_versions then validate_shadcn_compatible_versions!(value)
+      when :layout                     then validate_layout!(value)
+      end
+    end
+
+    # The value selects a render strategy by identity (`true` / `false`) or
+    # names a layout (String). Anything else would otherwise be treated as "not
+    # false" and reach `render_to_string(layout: <value>)`, where a Symbol
+    # layout name or a stray nil surfaces as a confusing first-request 500
+    # instead of a boot-time error. `nil` is rejected on purpose: "no layout" is
+    # spelled `false`, so a nil left over from a conditional in the initializer
+    # is a mistake, not a silent shell fallback.
+    def validate_layout!(value)
+      return if [true, false].include?(value)
+      return if value.is_a?(String) && !value.empty?
+
+      # `:auto` is rejected BY NAME because it used to be the default. An app
+      # carrying it forward from an older initializer must be told it is gone,
+      # not have it silently reinterpreted as "some truthy value".
+      if value == :auto
+        raise Ruact::ConfigurationError,
+              "Ruact::Configuration#layout no longer supports :auto — it inferred whether your " \
+              "layout was ready by inspecting it, which could not be done reliably. " \
+              "Set `true` to render through your app's layout (make sure it calls " \
+              "`<%= ruact_js_assets %>`), or `false` for ruact's built-in shell."
       end
+
+      raise Ruact::ConfigurationError,
+            "Ruact::Configuration#layout must be true, false, or a non-empty String layout name; " \
+            "got #{value.inspect} (#{value.class.name}). " \
+            "true renders through your app's layout (which must call ruact_js_assets); " \
+            "false uses ruact's built-in shell."
     end
 
     def validate_max_upload_bytes!(value)

data/lib/ruact/controller/document_rendering.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module Ruact
+  module Controller
+    # How a ruact response becomes a full HTML DOCUMENT — the wrapper a browser
+    # gets on a normal navigation, as opposed to the raw `text/x-component`
+    # Flight body an in-app navigation gets.
+    #
+    # Split out of `Ruact::Controller` because it answers one self-contained
+    # question ("who owns the `<head>`?") whose answer is load-bearing: the host
+    # app's layout does, because `stylesheet_link_tag`, favicons, fonts,
+    # analytics and every `<head>`-writing gem live there. `#ruact_html_shell`
+    # is the fallback for an app whose layout has not been migrated — it is
+    # deliberately minimal and has NO stylesheet slot.
+    module DocumentRendering
+      extend ActiveSupport::Concern
+
+      # Proof that a host layout called `ruact_js_assets`: the helper always
+      # emits the `__FLIGHT_DATA` bootstrap script when a payload is present,
+      # and `render_ruact_document` always supplies one. Matching on the payload
+      # script (rather than on the entry `<script src>`) keeps the check true in
+      # BOTH dev and production, whose entry tags differ.
+      RUACT_ASSETS_MARKER = "__FLIGHT_DATA"
+
+      # What counts as a mount target and what counts as a real call both live in
+      # {Ruact::LayoutSource}, shared with `ruact:install` so the runtime and the
+      # generator can never disagree about whether a layout is migrated.
+
+      private
+
+      # Emit the full HTML document a browser gets on a normal navigation.
+      #
+      # `Ruact.config.layout` decides, and it is EXPLICIT — ruact does not try
+      # to infer whether your layout is ready. It used to: three review rounds
+      # each found another template shape that fooled the inference (a mention
+      # in a comment, a commented-out call, a trim-mode comment), and each wrong
+      # answer governed how every page in the app rendered. Answering "does this
+      # template call this method?" is not something pattern-matching can do
+      # reliably, so the question is no longer asked. See
+      # Ruact::Configuration#layout.
+      #
+      # - `false` (the default) → the built-in shell. Byte-identical to ruact's
+      #   behaviour before the layout path existed, with no detection in the
+      #   way, so an app that has not opted in cannot be affected by any of this.
+      # - `true` / a String → render through the app's layout. `ruact:install`
+      #   writes both halves of that opt-in together: `config.layout = true` in
+      #   the initializer AND `<%= ruact_js_assets %>` in the layout.
+      #
+      # An opted-in layout that does not actually emit the assets would produce
+      # a blank page, so the rendered document is checked before it is
+      # committed: that is a configuration error, raised in development/test and
+      # logged-and-degraded in production rather than served to real traffic.
+      def render_ruact_document(payload)
+        layout = Ruact.config.layout
+        return render html: ruact_html_shell(payload).html_safe, layout: false if layout == false
+
+        unless ruact_layout_resolvable?(layout)
+          __ruact_handle_unready_layout(layout, :missing)
+          return render html: ruact_html_shell(payload).html_safe, layout: false
+        end
+
+        # Copied to the view by Rails' `view_assigns` plumbing (the name does not
+        # match the `/\A@_/` protected-ivar filter) — that is how the layout's
+        # zero-argument `ruact_js_assets` reaches THIS render's Flight payload.
+        @ruact_flight_payload = payload
+        document = render_to_string(html: "".html_safe, layout: layout)
+
+        if ruact_document_mountable?(document)
+          render html: document.html_safe, layout: false
+        else
+          __ruact_handle_unready_layout(layout, :unwired)
+          render html: ruact_html_shell(payload).html_safe, layout: false
+        end
+      ensure
+        remove_instance_variable(:@ruact_flight_payload) if instance_variable_defined?(:@ruact_flight_payload)
+      end
+
+      # A document is only usable if BOTH halves are present: the payload/bootstrap
+      # block AND something to mount into. Checking the assets alone accepts a
+      # layout that calls `ruact_js_assets` in `<head>` but never got the root div
+      # — React then boots with no mount target and the page is silently blank.
+      def ruact_document_mountable?(document)
+        document.include?(RUACT_ASSETS_MARKER) && Ruact::LayoutSource.root?(document)
+      end
+
+      # Is there a layout to render into at all? Asking FIRST matters: passing
+      # `layout: true` to a controller with no resolvable layout raises
+      # `ArgumentError("There was no default layout for ...")`, which would turn
+      # every page of an API-shaped or `layout false` controller into a 500 in
+      # an app that opted in globally. `_default_layout`'s `require_layout`
+      # argument defaults to false precisely so it can be used as a probe — it
+      # returns nil instead of raising, and honours `action_has_layout?`.
+      #
+      # `NameError` is deliberately NOT swallowed: `_default_layout` re-raises it
+      # as "Could not render layout: ..." to surface a broken layout resolver
+      # (`layout -> { MissingConstant::LAYOUT }`). Turning that into "no layout"
+      # would hide the developer's bug behind a silently degraded page.
+      def ruact_layout_resolvable?(layout)
+        return ruact_layout_exists?(layout) if layout.is_a?(String)
+
+        resolved = _default_layout(lookup_context, [:html], [])
+        return false if resolved.nil? || resolved == false
+        # `_default_layout` returns a Template for the conventional lookup but a
+        # bare String path for a controller-declared `layout "name"` — and it
+        # returns that String WITHOUT checking the template exists. Treating
+        # "not nil" as resolvable therefore sent a declared-but-missing layout
+        # into `render_to_string`, where it raised `MissingTemplate` instead of
+        # taking the intended degrade-to-shell path.
+        return ruact_layout_exists?(resolved) if resolved.is_a?(String)
+
+        true
+      rescue NameError
+        raise
+      rescue StandardError
+        false
+      end
+
+      def ruact_layout_exists?(name)
+        lookup_context.exists?(name.to_s.delete_prefix("layouts/"), ["layouts"])
+      end
+
+      def __ruact_handle_unready_layout(_layout, reason)
+        detail =
+          if reason == :missing
+            "no layout could be resolved for it"
+          else
+            "the layout it rendered emitted no `ruact_js_assets` output (or no " \
+              "`<div id=\"root\"></div>` to mount into), which would have been a blank page"
+          end
+
+        message = <<~MSG.strip
+          ruact: #{controller_path}##{action_name} fell back to ruact's built-in HTML shell — #{detail}.
+            `Ruact.config.layout` is set, so this is a configuration error, not a default:
+            the built-in shell has no stylesheet slot, so your app's CSS does not reach this page.
+            Add `<%= ruact_js_assets %>` next to the `<div id="root"></div>` in your layout
+            (`rails generate ruact:install` writes both; `rails ruact:doctor` reports what is missing),
+            or set `Ruact.configure { |c| c.layout = false }` to use the built-in shell deliberately.
+        MSG
+
+        # A MISSING layout is a legitimate per-controller choice — an API-shaped
+        # controller, or one that declared `layout false`, inside an app that
+        # opted in globally. Raising there would break a normal Rails pattern,
+        # so it degrades to the shell and says so where a developer will see it.
+        #
+        # An UNWIRED layout is different: the developer pointed ruact at a
+        # layout that cannot mount the app, which is their bug to see — loudly
+        # in development, and degraded (never blank) in production.
+        if reason == :missing
+          logger&.info(message) if __ruact_local_env?
+          return
+        end
+
+        raise Ruact::Error, message if __ruact_local_env?
+
+        logger&.error(message)
+      end
+
+      def __ruact_local_env?
+        Rails.env.development? || Rails.env.test?
+      rescue StandardError
+        false
+      end
+
+      def ruact_html_shell(flight_payload)
+        # Story 14.2 — the JS asset block (entry `<script>` tags + `__FLIGHT_DATA`)
+        # is delegated to the single `Ruact::ViewHelper#ruact_js_assets`
+        # implementation. The bootstrap entry script is a deferred ES module, so it
+        # runs after the inline `__FLIGHT_DATA` classic script has populated the
+        # queue regardless of source order — emitting the whole block in `<body>`
+        # is correct.
+        <<~HTML
+          <!DOCTYPE html>
+          <html lang="en">
+            <head>
+              <meta charset="UTF-8" />
+              <meta name="viewport" content="width=device-width, initial-scale=1" />
+              #{ruact_csrf_meta_tag}
+              <title>Rails RSC</title>
+            </head>
+            <body>
+              <div id="root"></div>
+              #{ruact_js_assets(flight_payload)}
+            </body>
+          </html>
+        HTML
+      end
+
+      # Story 8.3 review R7 — emits `<meta name="csrf-token" content="...">`
+      # into the shell so the JS runtime's `<meta>` lookup can forward a
+      # valid `X-CSRF-Token` on every server-function (mutation) call. Without
+      # this, hosts that route `ruact_render` through the gem's HTML shell (the
+      # standard path) have no token in the document and the host's
+      # `protect_from_forgery` rejects every non-GET server function.
+      #
+      # Returns an empty string when CSRF protection isn't available
+      # (non-Rails specs, or hosts that have deliberately stripped
+      # `form_authenticity_token` from the controller surface).
+      def ruact_csrf_meta_tag
+        return "" unless respond_to?(:form_authenticity_token, true)
+
+        token = form_authenticity_token
+        return "" if token.nil? || token.empty?
+
+        %(<meta name="csrf-token" content="#{ERB::Util.html_escape(token)}" />)
+      rescue StandardError
+        ""
+      end
+    end
+  end
+end