ruact 0.0.5 → 0.0.6

data/spec/ruact/validation_errors_spec.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# Story 13.3 (FR98) — unit specs for the pure validation-error normalizer
+# Ruact::ServerFunctions::ValidationErrors.normalize. The normalizer turns an
+# ActiveModel-ish record, a raw ActiveModel::Errors, or a pre-shaped Hash into
+# the canonical wire shape `{ [attribute: String] => Array<String> }` (full
+# messages, `base` key, `{}` on a valid/empty/nil source, idempotent on
+# already-canonical input). Pure — no Rails/request/Ruact.config reads.
+
+require "spec_helper"
+require "active_model"
+
+require "ruact/server_functions/validation_errors"
+
+module Ruact
+  module ServerFunctions
+    RSpec.describe ValidationErrors, :story_13_3 do
+      # A minimal ActiveModel record so the normalizer can exercise the real
+      # `errors.group_by_attribute` / `ActiveModel::Error#full_message` API
+      # (present since Rails 6.1; gem pins `rails ~> 8.0`).
+      let(:record_class) do
+        Class.new do
+          include ActiveModel::Model
+          include ActiveModel::Attributes
+
+          attribute :title, :string
+          attribute :body, :string
+
+          def self.name = "ValidationErrorsSpecPost"
+        end
+      end
+
+      describe ".normalize" do
+        context "with a record responding to #errors" do
+          it "returns the canonical { attr => [full_message] } shape" do
+            record = record_class.new
+            record.errors.add(:title, :blank) # "Title can't be blank"
+
+            expect(described_class.normalize(record)).to eq("title" => ["Title can't be blank"])
+          end
+
+          it "keys base-level errors under the string 'base' with the bare message" do
+            record = record_class.new
+            record.errors.add(:base, "is invalid overall")
+
+            expect(described_class.normalize(record)).to eq("base" => ["is invalid overall"])
+          end
+
+          it "groups multiple attributes and multiple messages per attribute" do
+            record = record_class.new
+            record.errors.add(:title, :blank)              # "Title can't be blank"
+            record.errors.add(:title, "is too short")      # "Title is too short"
+            record.errors.add(:body, "is invalid")         # "Body is invalid"
+
+            expect(described_class.normalize(record)).to eq(
+              "title" => ["Title can't be blank", "Title is too short"],
+              "body" => ["Body is invalid"]
+            )
+          end
+
+          it "returns {} for a record with no errors (success symmetry)" do
+            expect(described_class.normalize(record_class.new)).to eq({})
+          end
+        end
+
+        context "with a raw ActiveModel::Errors" do
+          it "normalizes the Errors object directly" do
+            record = record_class.new
+            record.errors.add(:title, :blank)
+
+            expect(described_class.normalize(record.errors)).to eq("title" => ["Title can't be blank"])
+          end
+        end
+
+        context "with a pre-shaped Hash" do
+          it "stringifies keys and leaves canonical array values untouched (idempotent)" do
+            canonical = { "title" => ["Title can't be blank"] }
+
+            expect(described_class.normalize(canonical)).to eq(canonical)
+          end
+
+          it "stringifies symbol keys" do
+            expect(described_class.normalize(title: ["x"])).to eq("title" => ["x"])
+          end
+
+          it "coerces a scalar value into a one-element array" do
+            expect(described_class.normalize("title" => "can't be blank")).to eq("title" => ["can't be blank"])
+          end
+
+          it "coerces non-string message values to strings" do
+            expect(described_class.normalize("count" => [1, 2])).to eq("count" => %w[1 2])
+          end
+
+          it "returns {} for an empty Hash" do
+            expect(described_class.normalize({})).to eq({})
+          end
+        end
+
+        context "with nil / empty sources" do
+          it "returns {} for nil" do
+            expect(described_class.normalize(nil)).to eq({})
+          end
+        end
+
+        it "is idempotent — normalizing its own output yields the same Hash" do
+          record = record_class.new
+          record.errors.add(:title, :blank)
+          record.errors.add(:base, "is invalid overall")
+
+          once = described_class.normalize(record)
+          expect(described_class.normalize(once)).to eq(once)
+        end
+      end
+    end
+  end
+end

data/spec/ruact/view_helper_spec.rb

@@ -2,6 +2,7 @@
 
 require "spec_helper"
 require "active_support/core_ext/string/output_safety"
+require "active_support/string_inquirer"
 
 module Ruact
   RSpec.describe ViewHelper do
@@ -48,5 +49,83 @@ module Ruact
           .to raise_error(Ruact::Error, /__ruact_component__ called outside a ruact_render flow/)
       end
     end
+
+    # Story 14.2 (FR104) — the public JS-asset helper. Emits the dev/prod
+    # bootstrap entry `<script>` tags (re-targeting `virtual:ruact/bootstrap`)
+    # plus the `__FLIGHT_DATA` inline script. The controller delegates to this
+    # one implementation (parity asserted in controller_spec).
+    describe "#ruact_js_assets", :story_14_2 do
+      let(:asset_helper) do
+        obj = Object.new
+        obj.extend(described_class)
+        obj
+      end
+      let(:payload) { "0:[\"$\",\"div\",null,{}]\n" }
+
+      context "when in dev with the Vite dev server running" do
+        before do
+          allow(Rails).to receive(:env).and_return(ActiveSupport::StringInquirer.new("development"))
+          allow(asset_helper).to receive(:vite_dev_running?).and_return(true)
+        end
+
+        it "emits the react-refresh preamble, @vite/client, and the bootstrap module", :aggregate_failures do
+          html = asset_helper.ruact_js_assets(payload)
+          expect(html).to include("__vite_plugin_react_preamble_installed__")
+          expect(html).to include("http://localhost:5173/@vite/client")
+          # Targets the virtual entry at the dev server's /@id/__x00__ URL — NOT
+          # a stale application.jsx path.
+          expect(html).to include("/@id/__x00__#{Ruact.bootstrap_virtual_id}")
+          expect(html).not_to include("application.jsx")
+        end
+
+        it "includes the __FLIGHT_DATA inline bootstrap script", :aggregate_failures do
+          html = asset_helper.ruact_js_assets(payload)
+          expect(html).to include("__FLIGHT_DATA")
+          expect(html).to include("d.push(")
+        end
+
+        it "returns an html_safe buffer" do
+          expect(asset_helper.ruact_js_assets(payload)).to be_html_safe
+        end
+      end
+
+      context "when in prod (Vite manifest lookup)" do
+        before do
+          allow(Rails).to receive(:env).and_return(ActiveSupport::StringInquirer.new("production"))
+        end
+
+        it "looks up the manifest with the SAME id the generated vite.config input uses (AC3 — no drift)" do
+          allow(asset_helper).to receive(:vite_manifest_entry).and_return(nil)
+          asset_helper.ruact_js_assets(payload)
+          expect(asset_helper).to have_received(:vite_manifest_entry).with(Ruact.bootstrap_virtual_id)
+        end
+
+        it "emits the hashed bootstrap URL from the manifest entry", :aggregate_failures do
+          allow(asset_helper).to receive(:vite_manifest_entry)
+            .with(Ruact.bootstrap_virtual_id).and_return({ "file" => "bootstrap-abc123.js" })
+          html = asset_helper.ruact_js_assets(payload)
+          expect(html).to include(%(src="/assets/bootstrap-abc123.js"))
+          expect(html).to include("__FLIGHT_DATA")
+        end
+
+        it "falls back to /assets/application.js when the manifest entry is missing" do
+          allow(asset_helper).to receive(:vite_manifest_entry).and_return(nil)
+          expect(asset_helper.ruact_js_assets(payload)).to include("/assets/application.js")
+        end
+      end
+
+      context "without a Flight payload (entry tags only)" do
+        before do
+          allow(Rails).to receive(:env).and_return(ActiveSupport::StringInquirer.new("production"))
+          allow(asset_helper).to receive(:vite_manifest_entry).and_return(nil)
+        end
+
+        it "emits only the entry tag (no __FLIGHT_DATA)", :aggregate_failures do
+          html = asset_helper.ruact_js_assets
+          expect(html).not_to include("__FLIGHT_DATA")
+          expect(html).to include("<script type=\"module\"")
+        end
+      end
+    end
   end
 end

data/spec/spec_helper.rb

@@ -50,11 +50,6 @@ RSpec.configure do |config|
   config.before do
     Ruact.instance_variable_set(:@config, nil)
     Ruact.instance_variable_set(:@configured_at_least_once, false)
-    # Story 8.0a: both server-function registries are lazy-initialized module
-    # singletons. Wipe them between examples so register/clear specs in one file
-    # cannot bleed entries into another under random order.
-    Ruact.instance_variable_set(:@action_registry, nil)
-    Ruact.instance_variable_set(:@query_registry, nil)
     # Story 9.3: specs that set `Rails.logger = instance_double(Logger)` (e.g.
     # railtie_spec, configuration_spec) leave a per-example double on the global
     # after they finish; rspec then refuses to call it from the NEXT example.

data/vendor/javascript/ruact-server-functions-runtime/index.d.ts

@@ -1,15 +1,11 @@
-// Story 8.1 — TypeScript declarations for the real server-functions runtime.
+// TypeScript declarations for the route-driven server-functions runtime.
 // Mirrors the JS exports in `index.js` so the generated module's
-// `import { _makeRef } from "ruact/server-functions-runtime"` resolves under
-// `tsc --noEmit` (AC10's import guarantee).
+// `import { _makeServerFunction } from "ruact/server-functions-runtime"`
+// resolves under `tsc --noEmit`. Story 9.9 demolished the v1 `_makeRef` accessor.
 //
-// The generated module's per-export signature is
-// `(args?: Record<string, unknown>) => Promise<unknown>` per the 8.0a
-// codegen contract; the runtime accepts a wider `FormData` argument too
-// (Story 8.2 owns the codegen signature widening if it picks the FormData
-// path). Devs writing call sites against the 8.0a-emitted module continue
-// to see the conservative Record<string, unknown> signature; the FormData
-// branch only fires through Story 8.2's `<form action={fn}>` wiring.
+// The runtime accepts a wider `FormData` argument as well as the conservative
+// `Record<string, unknown>` shape; the FormData branch fires through the
+// `<form action={fn}>` wiring.
 
 /**
  * Re-run-3 (2026-05-15), refined Re-run-4 (2026-05-15) — local alias
@@ -36,46 +32,25 @@ type RuactResponse = typeof globalThis extends { Response: new (...args: never[]
   : unknown;
 
 /**
- * Returns a callable accessor for a server function registered with the
- * given Ruby symbol name. The accessor, when invoked, POSTs the args to
- * `/__ruact/fn/${name}`.
- *
- * Story 8.2 (refined 2026-05-17 per review patch R1) — the return type
- * is an intersection of FOUR call signatures so the same exported
- * reference is usable from every call site:
- *
- *   1. `()` / `(args)` / `(prevState, formData)` — direct callers and
- *      `useActionState`'s two-arg invocation; returns `Promise<unknown>`.
- *   2. `(formData: FormData)` — assignable to React 19's `<form action>`
- *      prop, which is typed as `(formData: FormData) => void | Promise<void>`.
- *      Promise generics are invariant in TS, so `Promise<unknown>` is
- *      NOT assignable to `Promise<void>` even via the void-discard rule;
- *      the intersection lets `<form action={createPost}>` typecheck
- *      DIRECTLY against the emitted module without a call-site cast.
- *
- * Runtime behavior is unchanged — `_makeRef` always resolves with the
- * JSON-decoded value. The `Promise<void>` overload is a TYPE-ONLY
- * surface: when React invokes the function from a `<form action>` prop,
- * the return value is discarded by React anyway.
- */
-export function _makeRef(
-  name: string,
-): ((
-  arg1?: Record<string, unknown> | RuactFormData,
-  arg2?: RuactFormData | Record<string, unknown>,
-) => Promise<unknown>) &
-  ((formData: RuactFormData) => Promise<void>);
-
-/**
- * Story 9.3 — the route-driven (v2) accessor. The codegen emits
+ * Story 9.3 — the route-driven accessor. The codegen emits
  * `_makeServerFunction({ method, path, segments })` for every non-GET routed
  * action on a `Ruact::Server` controller. The returned callable targets the
  * REAL Rails route + verb (e.g. `POST /posts`, `PUT /posts/:id`), interpolating
  * dynamic path segments by name from the single call argument, and follows a
  * Bucket-2 `{ "$redirect": "<path>" }` response client-side.
  *
- * Shares the same intersection call-signature contract as {@link _makeRef} so
- * `<form action={createPost}>` and `useActionState` keep type-checking.
+ * Story 8.2 (refined 2026-05-17 per review patch R1) — the return type is an
+ * intersection of call signatures so the same exported reference is usable from
+ * every call site:
+ *
+ *   1. `()` / `(args)` / `(prevState, formData)` — direct callers and
+ *      `useActionState`'s two-arg invocation; returns `Promise<unknown>`.
+ *   2. `(formData: FormData)` — assignable to React 19's `<form action>`
+ *      prop, which is typed as `(formData: FormData) => void | Promise<void>`.
+ *      Promise generics are invariant in TS, so `Promise<unknown>` is NOT
+ *      assignable to `Promise<void>` even via the void-discard rule; the
+ *      intersection lets `<form action={createPost}>` typecheck DIRECTLY
+ *      against the emitted module without a call-site cast.
  */
 export function _makeServerFunction(descriptor: {
   method: string;
@@ -117,9 +92,29 @@ export function _makeQuery(descriptor: {
  * order-independent) share ONE in-flight request. Dedup is in-flight only:
  * once a request settles the shared entry is dropped, so a fresh mount
  * refetches (no TTL cache, no stale-while-revalidate).
+ *
+ * Story 13.4 — the `reference` parameter accepts ANY codegen-emitted accessor
+ * shape: the pre-13.4 declaration typed it `(params?: Record<string, unknown>)
+ * => Promise<unknown>`, which a now-TYPED query accessor (e.g. `(params: { term:
+ * string | number | boolean | null }) => Promise<unknown>`) is NOT assignable to
+ * under `strict` (contravariant param mismatch). Widening to `(...args: never[])
+ * => Promise<unknown>` accepts every typed/untyped/no-kwargs accessor without a
+ * cast and without a regression. `T` (the return type) stays the explicitly-
+ * specifiable return-typing generic — `useQuery<User[]>(searchUsers, { term })`.
+ *
+ * SCOPE BOUNDARY (intentional): the second `params` argument stays
+ * `Record<string, unknown>` — `useQuery` does NOT re-check the params SHAPE
+ * against the accessor. Per-param compile-time checking (missing-required,
+ * unknown-key, wrong-typed) is delivered at the ACCESSOR's own call site
+ * (`searchUsers({ term })`), which is where FR99 narrows the type. Inferring the
+ * params type here would require a second generic `P` that is impossible to make
+ * both inferred-from-the-accessor AND compatible with the explicit
+ * `useQuery<User[]>(…)` return-typing form (TS short-circuits inference of a
+ * defaulted trailing type parameter, and rejects a partial type-argument list
+ * for a non-defaulted one). This matches the pre-13.4 `params` contract exactly.
  */
 export function useQuery<T = unknown>(
-  reference: (params?: Record<string, unknown>) => Promise<unknown>,
+  reference: (...args: never[]) => Promise<unknown>,
   params?: Record<string, unknown>,
 ): { data: T | undefined; loading: boolean; error: unknown };
 

data/vendor/javascript/ruact-server-functions-runtime/index.js

@@ -1,26 +1,27 @@
-// Story 8.1 — real server-functions runtime.
+// Server-functions runtime (route-driven, v2).
 //
-// Replaces the Story 8.0a placeholder. Each export of the generated module
-// `app/javascript/.ruact/server-functions.ts` calls `_makeRef("<symbol>")`
-// and gets back a function that, when invoked, POSTs to
-// `/__ruact/fn/<symbol>` with the args serialized as JSON or FormData.
+// Each export of the generated module `app/javascript/.ruact/server-functions.ts`
+// is built by `_makeServerFunction({ method, path, segments })` (mutations) or
+// `_makeQuery({ path, kind: "query" })` (reads), targeting the REAL Rails route
+// + verb. Story 9.9 demolished the v1 `_makeRef` accessor + the synthetic
+// endpoint it POSTed to.
 //
-// Wire contract (locked by Story 8.0 ADR Decision-log clarification of
-// 2026-05-13, items 2–3): POST for everything (actions AND queries),
-// request body carries the args, response is JSON. CSRF symmetric — the
-// runtime forwards the `<meta name="csrf-token">` value as `X-CSRF-Token`
-// if the meta tag is present in the document (the gem does not impose its
-// own CSRF; the host's `protect_from_forgery` is what enforces).
+// Wire contract: mutations send the args as JSON or FormData over the route's
+// real verb; reads issue a GET with params serialized into the query string;
+// responses are JSON. CSRF (mutations only) — the runtime forwards the
+// `<meta name="csrf-token">` value as `X-CSRF-Token` if the meta tag is present
+// (the gem does not impose its own CSRF; the host's `protect_from_forgery`
+// enforces). Reads are CSRF-free (GET semantics).
 //
-// The `_makeRef` export surface and the `"ruact/server-functions-runtime"`
-// import path are part of the locked API — do NOT change without coordinated
-// codegen + Vite-plugin updates.
+// The export surface (`_makeServerFunction`, `_makeQuery`, `useQuery`,
+// `revalidate`, `configureRuactRuntime`, `RuactActionError`) and the
+// `"ruact/server-functions-runtime"` import path are part of the locked API —
+// do NOT change without coordinated codegen + Vite-plugin updates.
 
 // Story 9.5 — `useQuery` is a React hook, so the runtime now depends on React.
 // React is declared as a `peerDependency` (every host already has it; the
-// runtime never bundles its own copy). This is the runtime's first React
-// import — the mutation path (`_makeRef` / `_makeServerFunction`) stays
-// React-free.
+// runtime never bundles its own copy). The mutation path
+// (`_makeServerFunction`) stays React-free.
 import { useState, useEffect } from "react";
 
 const RUNTIME_VERSION = 1;
@@ -28,8 +29,8 @@ const RUNTIME_VERSION = 1;
 // Re-run-5 (2026-05-15) — module-level runtime configuration. Hosts
 // in API mode (no session cookie / no CSRF meta tag) need a way to
 // inject auth headers (`Authorization: Bearer …`) on every call.
-// `_makeRef`'s signature is locked by the codegen so we don't widen
-// it; instead, hosts call `configureRuactRuntime` once at app boot
+// the accessor signatures are locked by the codegen so we don't widen
+// them; instead, hosts call `configureRuactRuntime` once at app boot
 // to register a headers-producing function. The function runs on
 // every fetch so dynamic tokens (refreshed at runtime) are picked up.
 const runtimeOptions = {
@@ -73,59 +74,22 @@ export class RuactActionError extends Error {
 }
 
 /**
- * Returns a callable accessor for a server function registered with the
- * given Ruby symbol name. The accessor, when invoked, POSTs the args to
- * `/__ruact/fn/${name}` and resolves with the response (JSON-decoded for
- * application/json responses, text for everything else).
- *
- * Story 8.2 — the returned function accepts up to TWO positional
- * arguments to support React 19's `useActionState` shape:
- *
- *   useActionState(action, initialState)
+ * Story 9.3 — the route-driven (v2) accessor. The codegen emits
+ * `_makeServerFunction({ method, path, segments })` for every non-GET routed
+ * action on a `Ruact::Server` controller. The returned callable targets the
+ * REAL Rails route + verb (e.g. `POST /posts`, `PUT /posts/:id`).
  *
- * calls `action(prevState, formData)` on every submit. `_makeRef` picks
- * the FormData-typed candidate from the call and discards the prevState
- * argument silently — prev-state is a client-only concern, never
+ * Story 8.2 — the returned function accepts up to TWO positional arguments to
+ * support React 19's `useActionState` shape: `useActionState(action,
+ * initialState)` calls `action(prevState, formData)` on every submit. The
+ * accessor picks the FormData-typed candidate from the call and discards the
+ * prevState argument silently — prev-state is a client-only concern, never
  * transmitted to the server. The single-arg shape (`fn(args)` from event
  * handlers; `<form action={fn}>` passing FormData directly) is preserved.
  *
- * Argument shape selection rules (first match wins):
- *   - 0 args                                     → JSON body, `{}`
- *   - 1 arg, FormData                            → multipart
- *   - 1 arg, plain object / null / undefined     → JSON body
- *   - 2 args, FormData in either slot            → multipart (FormData wins;
- *                                                  the other arg is discarded)
- *   - 2 args, neither FormData                   → JSON body of the SECOND arg
- *                                                  (the `useActionState` payload
- *                                                  slot); first arg discarded
- *                                                  as prev-state
- *   - 3+ args                                    → TypeError
- *
- * @param {string} name
- * @returns {(arg1?: Record<string, unknown> | FormData, arg2?: FormData | Record<string, unknown>) => Promise<unknown>}
- */
-export function _makeRef(name) {
-  return function ruactServerFunctionCall(...callArgs) {
-    if (callArgs.length > 2) {
-      throw new TypeError(
-        `ruact action :${name} called with ${callArgs.length} arguments — ` +
-          "expected 0, 1, or 2 (the useActionState shape)",
-      );
-    }
-    return ruactPost(name, pickWirePayload(callArgs));
-  };
-}
-
-/**
- * Story 9.3 — the route-driven (v2) accessor. The codegen emits
- * `_makeServerFunction({ method, path, segments })` for every non-GET routed
- * action on a `Ruact::Server` controller (instead of v1's `_makeRef("<sym>")`).
- * The returned callable targets the REAL Rails route + verb (e.g. `POST /posts`,
- * `PUT /posts/:id`) rather than the v1 synthetic `POST /__ruact/fn/:name`.
- *
- * It shares the exact fetch core (`ruactInvoke`) with `_makeRef` — FormData
- * branching, CSRF meta injection, text-first parsing, `RuactActionError`,
- * `redirect: "error"` — so all the salvaged 8.1/8.2 behaviors are preserved.
+ * It uses the shared fetch core (`ruactInvoke`) — FormData branching, CSRF
+ * meta injection, text-first parsing, `RuactActionError`, `redirect: "error"`
+ * — so all the salvaged 8.1/8.2 behaviors are preserved.
  * Two additions over v1:
  *   - **Path-param interpolation (D7):** dynamic `:id`-style segments are read
  *     BY NAME from the single call argument (FormData.get / object property) and
@@ -163,9 +127,9 @@ export function _makeServerFunction(descriptor) {
  * named query route (`GET /q/<jsId>`), serializing `params` into the query
  * string.
  *
- * Reads are CSRF-free (NFR27 / the 2026-06-02 ADR addendum voids the old
- * `POST /__ruact/fn/:id` query mechanism and restores HTTP GET semantics):
- * no request body, no `X-CSRF-Token`. It shares `parseResponse` /
+ * Reads are CSRF-free (NFR27 / the 2026-06-02 ADR addendum restored HTTP GET
+ * semantics for queries): no request body, no `X-CSRF-Token`. It shares
+ * `parseResponse` /
  * `RuactActionError` / `redirect: "error"` with the mutation path so the
  * success + failure shapes are identical.
  *
@@ -333,8 +297,8 @@ export function useQuery(reference, params) {
 }
 
 // Story 8.2 — picks the argument the wire request should serialize from
-// `_makeRef`'s call-args, following the rules documented in the JSDoc
-// above. Exported through `__internals` for the vitest suite (AC10) — it
+// `_makeServerFunction`'s call-args, following the useActionState rules
+// documented above. Exported through `__internals` for the vitest suite (AC10) — it
 // is intentionally NOT part of the public runtime surface.
 function pickWirePayload(callArgs) {
   const isFD = (v) => typeof FormData !== "undefined" && v instanceof FormData;
@@ -414,29 +378,10 @@ export const __internals = {
   },
 };
 
-// v1 (Story 8.1) — POST to the synthetic endpoint. A thin wrapper over the
-// shared `ruactInvoke` core; the URL, verb, and error label are exactly what
-// 8.1 used so the v1 path stays byte-behavior-identical (Story 9.3 AC6).
-//
-// Re-run-3 (2026-05-15) — `encodeURIComponent(name)` so a stray `/`, `?`, or
-// `#` in a name (only reachable through direct/buggy `_makeRef` calls — the
-// gem-side route constraint and the codegen validator both refuse
-// non-identifier characters) cannot rewrite the path or hijack the
-// query/fragment of the request URL.
-function ruactPost(name, args) {
-  return ruactInvoke({
-    method: "POST",
-    url: `/__ruact/fn/${encodeURIComponent(name)}`,
-    args,
-    label: name,
-  });
-}
-
-// Story 9.3 — the shared fetch core for BOTH v1 (`_makeRef`) and v2
-// (`_makeServerFunction`). Extracted verbatim from the original `ruactPost` so
-// neither path drifts: same FormData branching, CSRF injection, `redirect:
-// "error"`, text-first parsing, and structured `RuactActionError`. The only
-// parameters are the verb + URL + the wire payload + a human label for errors.
+// Story 9.3 — the shared fetch core for the route-driven (`_makeServerFunction`)
+// mutation path: FormData branching, CSRF injection, `redirect: "error"`,
+// text-first parsing, and structured `RuactActionError`. The only parameters
+// are the verb + URL + the wire payload + a human label for errors.
 async function ruactInvoke({ method, url, args, label }) {
   const init = buildFetchInit(args, method);
   let response;
@@ -572,8 +517,7 @@ function readSegment(args, seg) {
 // Story 9.3 (AC8 / D2) — the client half of the `$redirect` contract 9.2
 // deferred. A Bucket-2 mutation that `redirect_to`s returns
 // `{ "$redirect": "<path>" }`; follow it via the router handoff and resolve
-// `null` (consistent with the 204→null contract). Only applied on the v2 path
-// — the v1 endpoint never emits `$redirect`, so `_makeRef` is unaffected (AC6).
+// `null` (consistent with the 204→null contract).
 function followRedirectIfPresent(parsed) {
   if (
     parsed &&