ruact 0.0.6 → 0.0.8

data/spec/support/matchers/flight_fixture_matcher.rb

@@ -1,267 +1,16 @@
 # frozen_string_literal: true
 
 require_relative "../flight_wire_parser"
+require "ruact/testing/flight_structure_diff"
 
 module Ruact
   module Spec
-    # Internal helpers shared by the structural Flight matchers. Lives under
-    # `Ruact::Spec` (test-only namespace) — no top-level constants leak into
-    # the gem's public API surface.
-    # rubocop:disable Metrics/ClassLength -- single cohesive helper for matcher diffing/formatting; splitting would scatter related logic across files.
-    class FlightStructureDiff
-      # Keys the parser produces on every row. Predicates and expected rows
-      # may only reference these keys; unknown keys raise upfront so typos
-      # like `payloed:` don't silently match every row via `nil == nil`.
-      KNOWN_ROW_KEYS = %i[id class payload raw].freeze
-
-      # Keys that must be present in every expected-row hash passed to
-      # `match_flight_structure`. Excludes `:raw` because expected rows are
-      # authored as semantic descriptions, not byte-level snapshots.
-      REQUIRED_EXPECTED_KEYS = %i[id class payload].freeze
-
-      # Compute the set of differences between actual parsed rows and the
-      # expected structure. Import rows are matched as a multiset (their
-      # relative order among each other is not significant per AC1);
-      # everything else compares positionally.
-      def self.compute(actual_rows, expected_rows)
-        validate_expected_rows!(expected_rows)
-        return diffs_for_length_mismatch(actual_rows, expected_rows) if actual_rows.length != expected_rows.length
-
-        diffs = []
-        pending_actual_imports = []
-        pending_expected_imports = []
-
-        actual_rows.zip(expected_rows).each_with_index do |(actual, expected), i|
-          if actual[:class] == :import && expected[:class] == :import
-            pending_actual_imports << [i, actual]
-            pending_expected_imports << [i, expected]
-            next
-          end
-
-          next if rows_equal?(actual, expected)
-
-          diffs << build_field_diff(i, actual, expected)
-        end
-
-        diffs.concat(diff_imports_unordered(pending_actual_imports, pending_expected_imports))
-        diffs.sort_by { |d| d[:idx] }
-      end
-
-      # Imports are an unordered multiset within their class (AC1). Sort both
-      # sides by `:id` (always unique per render) and any leftover diffs come
-      # from semantic mismatch in the same-position-after-sort pair.
-      def self.diff_imports_unordered(actual_pairs, expected_pairs)
-        return [] if actual_pairs.empty? && expected_pairs.empty?
-
-        sort_key = ->(pair) { [pair[1][:id].to_i, pair[1][:payload].to_s] }
-        sorted_actual = actual_pairs.sort_by(&sort_key)
-        sorted_expected = expected_pairs.sort_by(&sort_key)
-
-        sorted_actual.zip(sorted_expected).filter_map do |(act_idx, act_row), (_exp_idx, exp_row)|
-          next if rows_equal?(act_row, exp_row)
-
-          build_field_diff(act_idx, act_row, exp_row)
-        end
-      end
-
-      def self.diffs_for_length_mismatch(actual_rows, expected_rows)
-        diffs = []
-        [actual_rows.length, expected_rows.length].max.times do |i|
-          actual = actual_rows[i]
-          expected = expected_rows[i]
-          if actual.nil?
-            diffs << { kind: :missing, idx: i, expected_row: expected }
-          elsif expected.nil?
-            diffs << { kind: :extra, idx: i, actual_row: actual }
-          elsif !rows_equal?(actual, expected)
-            diffs << build_field_diff(i, actual, expected)
-          end
-        end
-        diffs
-      end
-
-      def self.rows_equal?(actual, expected)
-        REQUIRED_EXPECTED_KEYS.all? { |k| actual[k] == expected[k] }
-      end
-
-      def self.build_field_diff(idx, actual, expected)
-        field_diff = nil
-        REQUIRED_EXPECTED_KEYS.each do |key|
-          next if actual[key] == expected[key]
-
-          path, sub_expected, sub_actual = first_difference(expected[key], actual[key], ".#{key}")
-          field_diff = { path: path, expected: sub_expected, got: sub_actual }
-          break
-        end
-
-        {
-          kind: :differs,
-          idx: idx,
-          row_class: actual[:class],
-          path: field_diff[:path],
-          expected: field_diff[:expected],
-          got: field_diff[:got],
-          expected_row: expected,
-          got_row: actual
-        }
-      end
-
-      # Walks parallel structures (Hash/Array/scalar) and returns the path,
-      # expected leaf, and actual leaf at the first differing position.
-      def self.first_difference(expected, actual, path)
-        return [path, expected, actual] if expected.class != actual.class
-        return [path, expected, actual] unless expected.is_a?(Array) || expected.is_a?(Hash)
-
-        return diff_in_array(expected, actual, path) if expected.is_a?(Array)
-
-        diff_in_hash(expected, actual, path)
-      end
-
-      def self.diff_in_array(expected, actual, path)
-        [expected.length, actual.length].max.times do |i|
-          return ["#{path}[#{i}]", expected[i], actual[i]] if i >= expected.length || i >= actual.length
-          next if expected[i] == actual[i]
-
-          return first_difference(expected[i], actual[i], "#{path}[#{i}]")
-        end
-        [path, expected, actual]
-      end
-
-      def self.diff_in_hash(expected, actual, path)
-        (expected.keys | actual.keys).each do |key|
-          return ["#{path}[#{key.inspect}]", expected[key], actual[key]] if !expected.key?(key) || !actual.key?(key)
-          next if expected[key] == actual[key]
-
-          return first_difference(expected[key], actual[key], "#{path}[#{key.inspect}]")
-        end
-        [path, expected, actual]
-      end
-
-      # Validates each expected row carries the required `:id`, `:class`,
-      # `:payload` keys. Without this, an expected row of `{ id: 0, class:
-      # :model }` would silently pass against any actual row whose payload
-      # was nil — because the `==` check reads `expected[:payload]` as nil.
-      def self.validate_expected_rows!(expected_rows)
-        expected_rows.each_with_index do |row, i|
-          unless row.is_a?(Hash)
-            raise ArgumentError,
-                  "match_flight_structure: expected row #{i} must be a Hash, got #{row.class}: #{row.inspect}"
-          end
-
-          missing = REQUIRED_EXPECTED_KEYS.reject { |k| row.key?(k) }
-          next if missing.empty?
-
-          raise ArgumentError,
-                "match_flight_structure: expected row #{i} is missing required keys: #{missing.inspect}. " \
-                "Each expected row must include :id, :class, and :payload."
-        end
-      end
-
-      # Validates a predicate hash for `include_flight_row`. Unknown keys
-      # (typos like `payloed:` or `clas:`) raise immediately so they don't
-      # silently match any row via `row[:payloed]` returning nil.
-      def self.validate_predicate!(predicate)
-        unless predicate.is_a?(Hash)
-          raise ArgumentError,
-                "include_flight_row: predicate must be a Hash, got #{predicate.class}: #{predicate.inspect}"
-        end
-        raise ArgumentError, "include_flight_row: predicate cannot be empty" if predicate.empty?
-
-        unknown = predicate.keys - KNOWN_ROW_KEYS
-        return if unknown.empty?
-
-        raise ArgumentError,
-              "include_flight_row: predicate has unknown keys: #{unknown.inspect}. " \
-              "Allowed keys: #{KNOWN_ROW_KEYS.inspect}."
-      end
-
-      def self.format_single(diff)
-        case diff[:kind]
-        when :missing
-          row = diff[:expected_row]
-          "Expected row #{diff[:idx]} (#{row[:class]}) was not produced.\n  expected: #{row.inspect}"
-        when :extra
-          row = diff[:actual_row]
-          "Got unexpected row #{diff[:idx]} (#{row[:class]}): #{row.inspect}"
-        else
-          format_field_diff(diff)
-        end
-      end
-
-      def self.format_field_diff(diff)
-        <<~MSG.strip
-          Expected Flight output to match structure.
-
-          Row #{diff[:idx]} (#{diff[:row_class]}) differs at #{diff[:path]}:
-            expected: #{diff[:expected].inspect}
-            got:      #{diff[:got].inspect}
-
-          Row #{diff[:idx]} (#{diff[:row_class]}) full diff:
-            expected: #{diff[:expected_row][:payload].inspect}
-            got:      #{diff[:got_row][:payload].inspect}
-        MSG
-      end
-
-      # Builds the multi-row failure message: header naming the diff count,
-      # AC3-specified wording for missing / extra / differing rows, and a
-      # `Row N (<class>): ✓` summary line for every matching row so the
-      # reader can see what passed.
-      def self.format_multi(diffs, actual_rows, expected_rows)
-        header = "Expected Flight output to match structure. #{diffs.length} rows differ:"
-        total = [actual_rows.length, expected_rows.length].max
-        diff_by_idx = diffs.to_h { |d| [d[:idx], d] }
-
-        body = (0...total).map do |i|
-          diff = diff_by_idx[i]
-          if diff
-            format_entry(diff)
-          else
-            row_class = (actual_rows[i] || expected_rows[i])[:class]
-            "Row #{i} (#{row_class}): ✓"
-          end
-        end
-
-        ([header, ""] + body).join("\n")
-      end
-
-      def self.format_entry(diff)
-        case diff[:kind]
-        when :missing
-          row = diff[:expected_row]
-          "Expected row #{diff[:idx]} (#{row[:class]}) was not produced.\n  expected: #{row.inspect}"
-        when :extra
-          row = diff[:actual_row]
-          "Got unexpected row #{diff[:idx]} (#{row[:class]}): #{row.inspect}"
-        else
-          <<~ENTRY.strip
-            Row #{diff[:idx]} (#{diff[:row_class]}) differs at #{diff[:path]}:
-              expected: #{diff[:expected].inspect}
-              got:      #{diff[:got].inspect}
-          ENTRY
-        end
-      end
-
-      # Subset / case-equality match used by `include_flight_row`. Plain
-      # values use `==`; richer matchers (`hash_including`, `array_including`,
-      # `kind_of`, regexes) use `===` which delegates to their custom logic.
-      # Predicate keys are validated upfront by `validate_predicate!`, so
-      # this method can assume every key is one of the known row keys.
-      def self.row_matches?(row, predicate)
-        predicate.all? do |key, expected_value|
-          actual_value = row[key]
-          case expected_value
-          when Symbol, Numeric, NilClass, TrueClass, FalseClass
-            expected_value == actual_value
-          else
-            # rubocop:disable Style/CaseEquality -- intentional: lets RSpec mock argument matchers
-            # (hash_including, array_including, kind_of, etc.) drive predicate semantics via #===.
-            expected_value === actual_value
-            # rubocop:enable Style/CaseEquality
-          end
-        end
-      end
-    end
-    # rubocop:enable Metrics/ClassLength
+    # Story 15.4 (FR108) — the structural diff engine was PROMOTED onto the
+    # gem's `lib/` load path as `Ruact::Testing::FlightStructureDiff` (shared,
+    # single implementation — wrap, not fork). This test-only `Ruact::Spec`
+    # alias keeps the internal matcher wrappers below and their self-tests
+    # working unchanged.
+    FlightStructureDiff = Ruact::Testing::FlightStructureDiff
   end
 end
 

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

@@ -151,11 +151,36 @@ export const __RUNTIME_VERSION__: number;
  *
  * The gem's own headers (`Accept`, `Content-Type`, `X-CSRF-Token`)
  * win over `defaultHeaders` — CSRF cannot be silently overridden.
+ *
+ * Story 15.6 (FR110) — `autoRevalidate` (default `false`) is the app-wide
+ * auto-revalidate default: when `true`, every successful, non-redirecting
+ * mutation `await`s an in-place Flight refresh of the current path (via
+ * `revalidate()`) before resolving with the action's JSON result. A per-call
+ * `withRefresh(accessor)` wins over this global default.
  */
 export function configureRuactRuntime(options: {
   defaultHeaders?: Record<string, string> | (() => Record<string, string>) | null;
+  autoRevalidate?: boolean;
 }): void;
 
+/**
+ * Story 15.6 (FR110) — per-call auto-revalidate wrapper. Wraps a generated
+ * server-function accessor and returns a new accessor that forces an in-place
+ * Flight refresh of the current path after a successful, non-redirecting call —
+ * regardless of the app-wide `autoRevalidate` default (per-call explicit wins).
+ * Runtime-only: it does not change the codegen or the wire.
+ *
+ * A `$redirect` response still wins (the refresh is skipped); a failed mutation
+ * still throws before any refresh; and if no router is installed the descriptive
+ * `revalidate()` error surfaces (a successful mutation whose refresh rejects
+ * rejects the returned promise).
+ *
+ * The wrapped accessor keeps its own call signature (the same
+ * `(arg1?, arg2?) => Promise<unknown>` / `(formData) => Promise<void>`
+ * intersection the codegen emits).
+ */
+export function withRefresh<F extends (...args: never[]) => Promise<unknown>>(accessor: F): F;
+
 /**
  * Re-run-4 (2026-05-15) — structured error thrown for 4xx/5xx responses.
  * Callers can branch on `status` and inspect `body` (already

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

@@ -14,9 +14,11 @@
 // enforces). Reads are CSRF-free (GET semantics).
 //
 // 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.
+// `revalidate`, `withRefresh`, `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 15.6
+// added `withRefresh` — a runtime-only wrapper; it is NOT re-exported through the
+// generated `.ruact/server-functions.ts` barrel, so codegen output is unchanged.)
 
 // 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
@@ -33,8 +35,16 @@ const RUNTIME_VERSION = 1;
 // 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.
+// Story 15.6 (FR110) — `autoRevalidate` is the app-wide default for the
+// auto-revalidate opt-in: when `true`, every successful, NON-redirecting mutation
+// (`_makeServerFunction` accessor) `await`s an in-place Flight refresh of the
+// current path (via the existing `revalidate()`) BEFORE resolving with the
+// action's JSON result. Default `false` → today's behavior, byte-identical. A
+// per-call `withRefresh(accessor)` wrapper forces the refresh for a single call
+// and WINS over this global (D5: per-call explicit beats the global default).
 const runtimeOptions = {
   defaultHeaders: null,
+  autoRevalidate: false,
 };
 export function configureRuactRuntime(options) {
   if (options && Object.prototype.hasOwnProperty.call(options, "defaultHeaders")) {
@@ -47,6 +57,15 @@ export function configureRuactRuntime(options) {
       );
     }
   }
+  if (options && Object.prototype.hasOwnProperty.call(options, "autoRevalidate")) {
+    const value = options.autoRevalidate;
+    if (typeof value !== "boolean") {
+      throw new TypeError(
+        "configureRuactRuntime: autoRevalidate must be a boolean",
+      );
+    }
+    runtimeOptions.autoRevalidate = value;
+  }
 }
 
 /**
@@ -101,12 +120,28 @@ export class RuactActionError extends Error {
  *     (`globalThis.__ruact_navigate`, `window.location.assign` fallback) and
  *     resolves `null`.
  *
+ * Story 15.6 (FR110) — auto-revalidate opt-in. When the call opts in — via the
+ * app-wide `configureRuactRuntime({ autoRevalidate: true })` default OR the
+ * per-call `withRefresh(accessor)` wrapper — a SUCCESSFUL, NON-redirecting
+ * mutation `await`s an in-place Flight refresh of the current path (the existing
+ * `revalidate()`) BEFORE the promise resolves, then resolves with the action's
+ * JSON result. This is pure client-side COMPOSITION of the two requests that
+ * already exist (POST-JSON mutation + GET-Flight refresh) — no new wire shape, no
+ * inbound Flight deserialization (serialize-only invariant intact). A `$redirect`
+ * WINS: the redirect is followed and the refresh is SKIPPED (refreshing the old
+ * path would be wrong). A failed mutation throws before the refresh runs, so no
+ * refresh happens. If the refresh is requested with no router installed, the
+ * descriptive `revalidate()` error surfaces (it is not swallowed).
+ *
  * @param {{ method: string, path: string, segments?: string[] }} descriptor
  * @returns {(arg1?: Record<string, unknown> | FormData, arg2?: FormData | Record<string, unknown>) => Promise<unknown>}
  */
 export function _makeServerFunction(descriptor) {
   const { method, path, segments = [] } = descriptor || {};
-  return async function ruactServerFunctionCall(...callArgs) {
+  // The core invoker takes the raw call-args plus a `refreshOverride`:
+  //   undefined → fall back to the app-wide `runtimeOptions.autoRevalidate`;
+  //   true/false → an explicit per-call decision that WINS over the global (D5).
+  const invoke = async function (callArgs, refreshOverride) {
     if (callArgs.length > 2) {
       throw new TypeError(
         `ruact server function ${method} ${path} called with ${callArgs.length} arguments — ` +
@@ -115,8 +150,61 @@ export function _makeServerFunction(descriptor) {
     }
     const args = pickWirePayload(callArgs);
     const url = interpolatePath(path, segments, args);
+    // AC4 — a failed mutation throws HERE, before any refresh is sequenced.
     const parsed = await ruactInvoke({ method, url, args, label: path });
-    return followRedirectIfPresent(parsed);
+    const { value, redirected } = followRedirect(parsed);
+    // AC2 — redirect wins: the destination already re-renders; skip the refresh.
+    if (redirected) return value;
+    const refresh =
+      refreshOverride === undefined ? runtimeOptions.autoRevalidate === true : refreshOverride === true;
+    if (refresh) {
+      // AC1 — refresh the current path in place BEFORE resolving. AC5 — if no
+      // router is installed, `revalidate()`'s descriptive error surfaces here
+      // (D3: a mutation that succeeded but whose refresh rejects rejects the
+      // promise — consistent with `revalidate()`'s loud-by-default stance).
+      await revalidate();
+    }
+    return value;
+  };
+  const accessor = function ruactServerFunctionCall(...callArgs) {
+    return invoke(callArgs, undefined);
+  };
+  // Stash the core invoker on the accessor (non-enumerable) so `withRefresh` can
+  // force a refresh for a single call WITHOUT the codegen emitting a different
+  // accessor shape — the generated `.ruact/server-functions.ts` stays byte-
+  // identical (AC6). Keyed by a module-private Symbol so host code can't collide.
+  Object.defineProperty(accessor, REFRESH_INVOKER, { value: invoke, enumerable: false });
+  return accessor;
+}
+
+// Story 15.6 (FR110) — module-private handle used by `withRefresh` to reach a
+// server-function accessor's core invoker (see `_makeServerFunction`).
+const REFRESH_INVOKER = Symbol("ruactRefreshInvoker");
+
+/**
+ * Story 15.6 (FR110) — per-call auto-revalidate wrapper. Wraps a generated
+ * server-function accessor and returns a NEW accessor that forces the in-place
+ * Flight refresh after a successful, non-redirecting call — regardless of the
+ * app-wide `autoRevalidate` default (D5: per-call explicit wins). Runtime-only:
+ * it does not change the codegen or the wire.
+ *
+ *   import { createPost } from "@/.ruact/server-functions";
+ *   import { withRefresh } from "ruact/server-functions-runtime";
+ *   await withRefresh(createPost)(formData); // mutation + refresh in one await
+ *
+ * @param {Function} accessor A `_makeServerFunction`-produced accessor.
+ * @returns {(...args: unknown[]) => Promise<unknown>} A refreshing accessor.
+ */
+export function withRefresh(accessor) {
+  const invoke = typeof accessor === "function" ? accessor[REFRESH_INVOKER] : undefined;
+  if (typeof invoke !== "function") {
+    throw new TypeError(
+      "ruact withRefresh() expects a server-function accessor produced by the ruact codegen " +
+        "(imported from @/.ruact/server-functions)",
+    );
+  }
+  return function ruactRefreshingCall(...callArgs) {
+    return invoke(callArgs, true);
   };
 }
 
@@ -519,6 +607,15 @@ function readSegment(args, seg) {
 // `{ "$redirect": "<path>" }`; follow it via the router handoff and resolve
 // `null` (consistent with the 204→null contract).
 function followRedirectIfPresent(parsed) {
+  return followRedirect(parsed).value;
+}
+
+// Story 15.6 — the same follow logic, but reporting WHETHER a redirect was
+// followed as an explicit boolean. Auto-revalidate needs to distinguish "a
+// redirect was followed → skip the refresh" from "the action genuinely resolved
+// `null`/204 → still refresh" — inferring redirect from `value === null` would
+// wrongly skip the refresh after an ordinary empty-body mutation.
+function followRedirect(parsed) {
   if (
     parsed &&
     typeof parsed === "object" &&
@@ -526,9 +623,9 @@ function followRedirectIfPresent(parsed) {
     typeof parsed.$redirect === "string"
   ) {
     navigateTo(parsed.$redirect);
-    return null;
+    return { value: null, redirected: true };
   }
-  return parsed;
+  return { value: parsed, redirected: false };
 }
 
 function navigateTo(target) {

data/vendor/javascript/ruact-server-functions-runtime/index.test.mjs

@@ -15,6 +15,7 @@ import {
   RuactActionError,
   configureRuactRuntime,
   revalidate,
+  withRefresh,
 } from "./index.js";
 
 // Helper — a route-driven accessor targeting `POST /posts` (the canonical
@@ -822,3 +823,175 @@ describe("Story 9.3 — _makeServerFunction (route-driven, real path+verb)", ()
     expect(result).toEqual({ post: { id: 1 }, $redirect: 42 });
   });
 });
+
+// =============================================================================
+// Story 15.6 (FR110) — auto-revalidate opt-in: one await = mutation + refresh
+// =============================================================================
+
+describe("Story 15.6 — auto-revalidate opt-in", () => {
+  let originalRevalidate;
+  let originalNavigate;
+  let originalLocation;
+  let originalWindow;
+
+  beforeEach(() => {
+    originalRevalidate = globalThis.__ruact_revalidate;
+    originalNavigate = globalThis.__ruact_navigate;
+    originalLocation = globalThis.location;
+    originalWindow = globalThis.window;
+    globalThis.location = { pathname: "/posts", search: "?page=2" };
+  });
+
+  afterEach(() => {
+    // Reset the app-wide default so a leaked `autoRevalidate: true` can't bleed
+    // into the un-opted-in byte-parity tests elsewhere in the suite.
+    configureRuactRuntime({ autoRevalidate: false });
+    if (originalRevalidate === undefined) delete globalThis.__ruact_revalidate;
+    else globalThis.__ruact_revalidate = originalRevalidate;
+    globalThis.__ruact_navigate = originalNavigate;
+    if (originalLocation === undefined) {
+      // jsdom / browser env — leave the real `location` alone
+    } else {
+      globalThis.location = originalLocation;
+    }
+    globalThis.window = originalWindow;
+  });
+
+  // (a) request-composition order — POST then Flight refresh, in that order,
+  // resolves with the action's JSON result.
+  it("global default: refreshes the current path AFTER the mutation and resolves the JSON result", async () => {
+    const order = [];
+    mockFetchOk({ id: 7 });
+    const fetchSpy = globalThis.fetch;
+    fetchSpy.mockImplementation(async () => {
+      order.push("fetch");
+      return {
+        ok: true,
+        status: 200,
+        headers: { get: (n) => (n.toLowerCase() === "content-type" ? "application/json" : null) },
+        text: vi.fn().mockResolvedValue(JSON.stringify({ id: 7 })),
+        json: vi.fn().mockResolvedValue({ id: 7 }),
+      };
+    });
+    const revalidateSpy = vi.fn(async () => {
+      order.push("revalidate");
+    });
+    globalThis.__ruact_revalidate = revalidateSpy;
+    configureRuactRuntime({ autoRevalidate: true });
+
+    const createPost = _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+    const result = await createPost({ title: "x" });
+
+    expect(order).toEqual(["fetch", "revalidate"]);
+    expect(revalidateSpy).toHaveBeenCalledWith("/posts?page=2");
+    expect(result).toEqual({ id: 7 });
+  });
+
+  it("per-call withRefresh: forces the refresh even when the global default is OFF", async () => {
+    mockFetchOk({ id: 1 });
+    const revalidateSpy = vi.fn().mockResolvedValue(undefined);
+    globalThis.__ruact_revalidate = revalidateSpy;
+    configureRuactRuntime({ autoRevalidate: false });
+
+    const createPost = _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+    const result = await withRefresh(createPost)({ title: "x" });
+
+    expect(revalidateSpy).toHaveBeenCalledWith("/posts?page=2");
+    expect(result).toEqual({ id: 1 });
+  });
+
+  it("refreshes after a genuine null/204 result (not misread as a redirect)", async () => {
+    mockFetchOk("", { status: 204, contentType: "text/plain" });
+    const revalidateSpy = vi.fn().mockResolvedValue(undefined);
+    globalThis.__ruact_revalidate = revalidateSpy;
+
+    const createPost = _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+    const result = await withRefresh(createPost)({});
+
+    expect(revalidateSpy).toHaveBeenCalledTimes(1);
+    expect(result).toBeNull();
+  });
+
+  // (b) error propagation — a failed mutation rejects and issues NO refresh.
+  it("mutation failure propagates and does NOT refresh (refresh sequenced after success)", async () => {
+    mockFetchError(422, JSON.stringify({ error: "invalid" }));
+    const revalidateSpy = vi.fn().mockResolvedValue(undefined);
+    globalThis.__ruact_revalidate = revalidateSpy;
+    configureRuactRuntime({ autoRevalidate: true });
+
+    const createPost = _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+
+    await expect(createPost({ title: "" })).rejects.toMatchObject({
+      name: "RuactActionError",
+      status: 422,
+    });
+    expect(revalidateSpy).not.toHaveBeenCalled();
+  });
+
+  // (c) redirect-wins — a $redirect follows the redirect and issues NO refresh.
+  it("redirect wins: follows the $redirect, resolves null, and SKIPS the refresh", async () => {
+    mockFetchOk({ $redirect: "/posts/1" });
+    const navSpy = vi.fn();
+    globalThis.__ruact_navigate = navSpy;
+    const revalidateSpy = vi.fn().mockResolvedValue(undefined);
+    globalThis.__ruact_revalidate = revalidateSpy;
+    configureRuactRuntime({ autoRevalidate: true });
+
+    const createPost = _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+    const result = await createPost({ title: "x" });
+
+    expect(navSpy).toHaveBeenCalledWith("/posts/1");
+    expect(result).toBeNull();
+    expect(revalidateSpy).not.toHaveBeenCalled();
+  });
+
+  // (d) no-router — the descriptive revalidate() error surfaces (not swallowed).
+  it("no router installed: surfaces the descriptive revalidate() error", async () => {
+    mockFetchOk({ id: 1 });
+    if ("__ruact_revalidate" in globalThis) delete globalThis.__ruact_revalidate;
+    configureRuactRuntime({ autoRevalidate: true });
+
+    const createPost = _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+
+    await expect(createPost({ title: "x" })).rejects.toThrow(
+      /ruact: revalidate\(\) called but no router is installed/,
+    );
+  });
+
+  it("D3: a successful mutation whose refresh REJECTS rejects the returned promise", async () => {
+    mockFetchOk({ id: 9 });
+    const revalidateSpy = vi.fn().mockRejectedValue(new Error("Flight refresh failed"));
+    globalThis.__ruact_revalidate = revalidateSpy;
+
+    const createPost = _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+
+    await expect(withRefresh(createPost)({ title: "x" })).rejects.toThrow("Flight refresh failed");
+    expect(revalidateSpy).toHaveBeenCalledTimes(1);
+  });
+
+  // (e) un-opted-in is byte-identical to today: exactly one fetch, no refresh.
+  it("un-opted-in call is byte-identical: one fetch, no refresh", async () => {
+    mockFetchOk({ id: 1 });
+    const revalidateSpy = vi.fn().mockResolvedValue(undefined);
+    globalThis.__ruact_revalidate = revalidateSpy;
+    // global default stays OFF (reset in afterEach), no withRefresh wrapper.
+
+    const createPost = _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+    const result = await createPost({ title: "x" });
+
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    expect(revalidateSpy).not.toHaveBeenCalled();
+    expect(result).toEqual({ id: 1 });
+  });
+
+  it("withRefresh throws a descriptive TypeError for a non-accessor argument", () => {
+    expect(() => withRefresh(() => {})).toThrow(/server-function accessor produced by the ruact codegen/);
+    expect(() => withRefresh(null)).toThrow(TypeError);
+  });
+
+  it("configureRuactRuntime rejects a non-boolean autoRevalidate", () => {
+    expect(() => configureRuactRuntime({ autoRevalidate: "yes" })).toThrow(
+      /autoRevalidate must be a boolean/,
+    );
+  });
+});