@rangojs/router 0.0.0-experimental.122 → 0.0.0-experimental.125

package/src/rsc/handler.ts

@@ -453,6 +453,8 @@ export function createRSCHandler<
       cacheProfiles: router.cacheProfiles,
       executionContext: executionCtx,
       themeConfig: router.themeConfig,
+      stateCookieName: router.resolvedStateCookieName,
+      version,
     });
     if (earlyMetricsStore) {
       requestContext._debugPerformance = true;
@@ -1015,10 +1017,19 @@ export function createRSCHandler<
       } catch (error) {
         // Check if middleware/handler returned Response
         if (error instanceof Response) {
+          // An action revalidation render is delivered to the client over the
+          // same Flight-parsing path as a partial navigation, so a Response
+          // thrown during it must be converted exactly like a partial one
+          // (raw 200 -> hard-nav hint, 3xx -> Flight redirect). Without this,
+          // the no-middleware path returns the raw Response (the with-middleware
+          // path is already covered by the isPartial || actionContinuation
+          // guard below).
+          const treatAsPartial = isPartial || actionContinuation != null;
+
           // During partial (client-side navigation), a 200 Response from a handler
           // means the route serves raw content (JSON, text, etc.), not JSX.
           // Signal the browser to hard-navigate so it renders the raw response.
-          if (isPartial && error.status === 200) {
+          if (treatAsPartial && error.status === 200) {
             console.warn(
               `[RSC] Route handler at ${url.pathname} returned a Response during client-side navigation. ` +
                 `Falling back to hard navigation. Use data-external on the <Link> to avoid the extra round-trip.`,
@@ -1032,7 +1043,7 @@ export function createRSCHandler<
             });
           }
 
-          if (isPartial) {
+          if (treatAsPartial) {
             const intercepted = interceptRedirectForPartial(
               error,
               createRedirectFlightResponse,
@@ -1079,6 +1090,7 @@ export function createRSCHandler<
               rootLayout: router.rootLayout,
               handles: handleStore.stream(),
               version,
+              stateCookieName: router.resolvedStateCookieName,
               themeConfig: router.themeConfig,
               warmupEnabled: router.warmupEnabled,
               initialTheme: requireRequestContext().theme,

package/src/rsc/helpers.ts

@@ -12,6 +12,25 @@ import type { RequestContext } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
 import { isRedirectResponse } from "../response-utils.js";
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
+import { formatCacheSignalHeader } from "../router/telemetry.js";
+import type { RscPayload } from "./types.js";
+
+/**
+ * DEVELOPMENT/TEST ONLY. When the debug cache signal gate is on,
+ * match/matchPartial populate ctx._cacheSignal. Emit it as the X-Rango-Cache
+ * header. When the gate is off, ctx._cacheSignal is undefined and NOTHING is
+ * attached — output is byte-identical to the default. Header mutation failures
+ * are swallowed so immutable Response headers (e.g. protocol-switch) are safe.
+ */
+function applyCacheSignalHeader(target: Headers, ctx: RequestContext): void {
+  const signal = ctx._cacheSignal;
+  if (!signal || signal.length === 0) return;
+  try {
+    target.set("X-Rango-Cache", formatCacheSignalHeader(signal));
+  } catch {
+    // Headers immutable — skip.
+  }
+}
 
 /**
  * Copy stub headers from the request context onto a target Headers instance:
@@ -85,6 +104,7 @@ export function createResponseWithMergedHeaders(
   const mergedHeaders = new Headers(init.headers);
   applyStubHeaders(mergedHeaders, ctx.res.headers);
   ctx.res.headers.delete("set-cookie");
+  applyCacheSignalHeader(mergedHeaders, ctx);
 
   // ctx.res.status overrides init.status when explicitly set (e.g. 404 for
   // notFound, 500 for error). Default ctx.res.status is 200.
@@ -166,6 +186,20 @@ export function interceptRedirectForPartial(
   return intercepted;
 }
 
+/**
+ * Attach location state set during a request to a payload's metadata.
+ * No-op if no location state was set. Callers must ensure payload.metadata
+ * is populated (the non-null assertion holds for the partial/action payloads
+ * that reach this helper).
+ */
+export function attachLocationStateIfPresent(payload: RscPayload): void {
+  const locationState = getLocationState();
+  if (locationState) {
+    payload.metadata!.locationState =
+      resolveLocationStateEntries(locationState);
+  }
+}
+
 /**
  * Only cache successful responses. Non-200 statuses (errors, redirects) are
  * not cached -- notFound() produces 500 in response routes, and explicit

package/src/rsc/origin-guard.ts

@@ -69,11 +69,8 @@ export type OriginCheckConfig<TEnv = any> =
  * Returns true to allow, false to reject.
  */
 export function defaultOriginCheck(request: Request, url: URL): boolean {
-  // 1. Read Origin header (present on all cross-origin requests and
-  //    same-origin POST/PUT/PATCH/DELETE in modern browsers)
   let requestOrigin = request.headers.get("origin");
 
-  // 2. Fallback to Referer if Origin is absent (some proxies strip it)
   if (!requestOrigin) {
     const referer = request.headers.get("referer");
     if (referer) {
@@ -85,22 +82,13 @@ export function defaultOriginCheck(request: Request, url: URL): boolean {
     }
   }
 
-  // 3. No Origin or Referer — allow (can't be browser-initiated CSRF)
   if (!requestOrigin) return true;
 
-  // "null" origin comes from privacy-sensitive contexts (data: URLs,
-  // sandboxed iframes, cross-origin redirects). Reject it.
   if (requestOrigin === "null") return false;
 
-  // 4. Determine expected host from Host header or URL.
-  // X-Forwarded-Host/Proto are NOT used — they are client-controllable
-  // unless a trusted proxy strips them. On standard deployments (Cloudflare
-  // Workers, Node behind nginx/caddy) the Host header is already correct.
-  // For non-standard setups, use the custom function escape hatch.
   const expectedHost = request.headers.get("host") || url.host;
   const expectedProtocol = url.protocol;
 
-  // 5. Build expected origin and compare (case-insensitive)
   const expectedOrigin = `${expectedProtocol}//${expectedHost}`;
 
   return requestOrigin.toLowerCase() === expectedOrigin.toLowerCase();

package/src/rsc/progressive-enhancement.ts

@@ -254,11 +254,11 @@ export async function handleProgressiveEnhancement<TEnv>(
         rootLayout: ctx.router.rootLayout,
         handles: handleStore.stream(),
         version: ctx.version,
+        stateCookieName: ctx.router.resolvedStateCookieName,
         themeConfig: ctx.router.themeConfig,
         warmupEnabled: ctx.router.warmupEnabled,
         initialTheme: requireRequestContext().theme,
       },
-      formState: actionResult,
     };
 
     const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
@@ -276,6 +276,8 @@ export async function handleProgressiveEnhancement<TEnv>(
       url,
       undefined,
     );
+    // reactFormState carries the useActionState payload via the SSR-option path
+    // (renderToReadableStream({ formState })); it does NOT travel on RscPayload.
     const htmlStream = await ssrModule.renderHTML(rscStream, {
       formState: reactFormState,
       nonce,
@@ -362,6 +364,7 @@ async function renderPeErrorBoundary<TEnv>(
       rootLayout: ctx.router.rootLayout,
       handles: handleStore.stream(),
       version: ctx.version,
+      stateCookieName: ctx.router.resolvedStateCookieName,
       themeConfig: ctx.router.themeConfig,
       warmupEnabled: ctx.router.warmupEnabled,
       initialTheme: requireRequestContext().theme,

package/src/rsc/rsc-rendering.ts

@@ -9,9 +9,7 @@
 import {
   requireRequestContext,
   setRequestContextParams,
-  getLocationState,
 } from "../server/request-context.js";
-import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
 import { appendMetric } from "../router/metrics.js";
 import { getSSRSetup, isRscRequest } from "./ssr-setup.js";
 import type { RscPayload } from "./types.js";
@@ -19,6 +17,7 @@ import type { MatchResult } from "../types.js";
 import {
   createResponseWithMergedHeaders,
   createSimpleRedirectResponse,
+  attachLocationStateIfPresent,
 } from "./helpers.js";
 import type { HandlerContext } from "./handler-context.js";
 
@@ -53,6 +52,7 @@ export async function handleRscRendering<TEnv>(
       handles: handleStore.stream(),
       version: ctx.version,
       prefetchCacheTTL: ctx.router.prefetchCacheTTL,
+      stateCookieName: ctx.router.resolvedStateCookieName,
       themeConfig: ctx.router.themeConfig,
       initialTheme: reqCtx.theme,
     },
@@ -99,6 +99,7 @@ export async function handleRscRendering<TEnv>(
           handles: handleStore.stream(),
           version: ctx.version,
           prefetchCacheTTL: ctx.router.prefetchCacheTTL,
+          stateCookieName: ctx.router.resolvedStateCookieName,
         },
       };
     }
@@ -153,11 +154,7 @@ export async function handleRscRendering<TEnv>(
   // SSR (full page) requests ignore location state since there's no history.state
   // to write to on a fresh page load.
   if (isPartial && payload.metadata) {
-    const locationState = getLocationState();
-    if (locationState) {
-      payload.metadata.locationState =
-        resolveLocationStateEntries(locationState);
-    }
+    attachLocationStateIfPresent(payload);
   }
 
   const metricsStore = reqCtx._metricsStore;

package/src/rsc/runtime-warnings.ts

@@ -39,3 +39,17 @@ export function warnNonRedirectPeResponse(): void {
       `ignored — the page will re-render at the current URL instead.`,
   );
 }
+
+/**
+ * Warn when a non-redirect Response is returned (not thrown) from an action
+ * on the JS (fetch) path. A raw Response cannot be serialized into Flight, so
+ * it is discarded — mirroring the PE path. Use `throw redirect('/path')` for
+ * redirects.
+ */
+export function warnNonRedirectActionResponse(actionId: string): void {
+  console.warn(
+    `[@rangojs/router] Server action "${actionId}" returned a Response ` +
+      `that is not a redirect. Non-redirect Responses cannot be serialized ` +
+      `and are ignored. Use \`throw redirect('/path')\` for redirects.`,
+  );
+}

package/src/rsc/server-action.ts

@@ -18,9 +18,7 @@
 import {
   requireRequestContext,
   setRequestContextParams,
-  getLocationState,
 } from "../server/request-context.js";
-import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
 import { appendMetric } from "../router/metrics.js";
 import type { RscPayload } from "./types.js";
 import {
@@ -28,21 +26,11 @@ import {
   createResponseWithMergedHeaders,
   createSimpleRedirectResponse,
   interceptRedirectForPartial,
+  attachLocationStateIfPresent,
 } from "./helpers.js";
+import { warnNonRedirectActionResponse } from "./runtime-warnings.js";
 import type { HandlerContext } from "./handler-context.js";
 
-/**
- * Attach location state set during the action to a payload's metadata.
- * No-op if no location state was set.
- */
-function attachLocationState(payload: RscPayload): void {
-  const locationState = getLocationState();
-  if (locationState) {
-    payload.metadata!.locationState =
-      resolveLocationStateEntries(locationState);
-  }
-}
-
 /**
  * Data flowing from action execution to the revalidation phase.
  * When the action completes without redirect/error-boundary, the handler
@@ -109,7 +97,7 @@ export async function executeServerAction<TEnv>(
 
   try {
     loadedAction = await ctx.loadServerAction(actionId);
-    const data = await loadedAction!.apply(null, args);
+    let data = await loadedAction!.apply(null, args);
 
     // Intercept redirect Responses: serializing one as the action returnValue
     // would fail, and revalidation would run needlessly.
@@ -119,6 +107,14 @@ export async function executeServerAction<TEnv>(
         ctx.createRedirectFlightResponse,
       );
       if (intercepted) return intercepted;
+
+      // Non-redirect Response returned (not thrown): a raw Response cannot be
+      // serialized into Flight. Discard it and re-render — mirroring the PE
+      // path (progressive-enhancement.ts) so JS and no-JS behave identically.
+      if (process.env.NODE_ENV !== "production") {
+        warnNonRedirectActionResponse(actionId);
+      }
+      data = undefined;
     }
 
     returnValue = { ok: true, data };
@@ -224,18 +220,21 @@ export async function executeServerAction<TEnv>(
   }
 
   // Build continuation for the revalidation phase
-  const resolvedActionId =
-    (loadedAction as { $id?: string; $$id?: string } | undefined)?.$id ??
-    (loadedAction as { $$id?: string } | undefined)?.$$id ??
-    actionId;
+  const actionMeta = loadedAction as
+    | { $id?: string; $$id?: string }
+    | undefined;
+  const resolvedActionId = actionMeta?.$id ?? actionMeta?.$$id ?? actionId;
 
   return {
     returnValue,
     actionStatus,
     temporaryReferences,
     actionContext: {
+      // Defensive copy of the already-parsed url (avoids re-parsing
+      // request.url). actionUrl is persisted into the continuation and later
+      // flows into matchPartial, so it must not alias the handler's live url.
       actionId: resolvedActionId,
-      actionUrl: new URL(request.url),
+      actionUrl: new URL(url),
       actionResult: returnValue.data,
       formData: actionFormData,
     },
@@ -274,8 +273,8 @@ export async function revalidateAfterAction<TEnv>(
   );
 
   if (!matchResult) {
-    // matchPartial returns null when the route is a redirect or the request
-    // is missing required headers (previousUrl). Check for redirect first.
+    // matchPartial returns null when the route is a redirect or no previous-URL
+    // context could be resolved. Check for redirect first.
     const fullMatch = await ctx.router.match(request, { env });
     setRequestContextParams(fullMatch.params, fullMatch.routeName);
 
@@ -286,14 +285,17 @@ export async function revalidateAfterAction<TEnv>(
       return createSimpleRedirectResponse(fullMatch.redirect);
     }
 
-    // Non-redirect: this branch is only reachable when the action request
-    // is missing the X-RSC-Router-Client-Path header (defensive). The
-    // client requires isPartial for action responses, so producing a full
-    // payload here would be rejected. Return 500 instead.
+    // Non-redirect: this branch is only reachable when no previous URL could
+    // be resolved (neither X-RSC-Router-Client-Path nor a usable Referer), or
+    // the previous URL was unparseable (defensive). The client requires
+    // isPartial for action responses, so producing a full payload here would
+    // be rejected. Return 500 instead.
     throw new Error(
       `[RSC] matchPartial returned null for a non-redirect route ` +
         `during action revalidation (${url.pathname}). This indicates ` +
-        `a malformed action request (missing X-RSC-Router-Client-Path header).`,
+        `a malformed action request: no previous-URL context could be ` +
+        `resolved (neither X-RSC-Router-Client-Path nor a usable Referer), ` +
+        `or the previous URL was unparseable.`,
     );
   }
 
@@ -319,7 +321,7 @@ export async function revalidateAfterAction<TEnv>(
     returnValue,
   };
 
-  attachLocationState(payload);
+  attachLocationStateIfPresent(payload);
 
   const renderStart = performance.now();
   const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {

package/src/rsc/types.ts

@@ -43,6 +43,8 @@ export interface RscPayload {
     version?: string;
     /** TTL in milliseconds for the client-side in-memory prefetch cache */
     prefetchCacheTTL?: number;
+    /** Server-resolved rango state cookie name; the client reads it verbatim. */
+    stateCookieName?: string;
     /** Theme configuration for FOUC prevention */
     themeConfig?: ResolvedThemeConfig | null;
     /** Initial theme from cookie (for SSR hydration) */
@@ -57,7 +59,6 @@ export interface RscPayload {
     locationState?: Record<string, unknown>;
   };
   returnValue?: { ok: boolean; data: unknown };
-  formState?: unknown;
 }
 
 /**

package/src/runtime-env.ts

@@ -0,0 +1,18 @@
+// Runtime-safe detection of a test runner (Vitest), used to decide whether a
+// create*() call with no plugin-injected $$id may fall back to a synthetic id (a
+// bare test) or must fail loud (dev / a real build).
+//
+// `process` is absent in some target runtimes (the browser, certain edge/worker
+// RSC environments), so probe it through `globalThis` with optional chaining —
+// NEVER a bare `process.env.VITEST`, which would ReferenceError before the
+// intended error is thrown. Unlike `process.env.NODE_ENV` (folded by the app's
+// build `define`), `VITEST` is not folded, so this stays a small runtime check;
+// it lives only on the create*() error path (id missing), which never runs in a
+// correct production build.
+//
+// Vitest sets `VITEST` in every test process — the node project and the
+// react-server forks alike (the RSC project forces NODE_ENV=production, so NODE_ENV
+// cannot distinguish it from a real build; `VITEST` can). A real build never sets it.
+export function isUnderTestRunner(): boolean {
+  return !!globalThis.process?.env?.VITEST;
+}

package/src/search-params.ts

@@ -7,10 +7,6 @@
  * URLSearchParams instance.
  */
 
-// ============================================================================
-// Schema Types
-// ============================================================================
-
 /** Supported scalar types for search params (append ? for optional). */
 export type SearchSchemaValue =
   | "string"
@@ -23,10 +19,6 @@ export type SearchSchemaValue =
 /** A search schema maps param names to their type descriptors. */
 export type SearchSchema = Record<string, SearchSchemaValue>;
 
-// ============================================================================
-// Type-Level Schema Resolution
-// ============================================================================
-
 /** Strip trailing `?` from a schema value to get the base type. */
 type BaseType<T extends string> = T extends `${infer B}?` ? B : T;
 
@@ -163,10 +155,6 @@ type ExtractParamsFromPattern<T extends string> =
             : { [K in Param]: string }
       : {};
 
-// ============================================================================
-// Runtime Parser
-// ============================================================================
-
 /**
  * Parse URLSearchParams into a typed object using the given schema.
  *
@@ -210,10 +198,6 @@ export function parseSearchParams<T extends SearchSchema>(
   return result as ResolveSearchSchema<T>;
 }
 
-// ============================================================================
-// Runtime Serializer
-// ============================================================================
-
 /**
  * Serialize a typed search params object to a query string (without leading `?`).
  * Skips `undefined` and `null` values.

package/src/segment-loader-promise.ts

@@ -26,7 +26,10 @@ const IS_BROWSER = typeof window !== "undefined";
 
 interface LoaderCacheEntry {
   sources: any[];
-  promise: Promise<any[]> | any[];
+  // buildLoaderPromise always returns a Promise, so the cached value is never a
+  // bare array. The public getMemoizedLoaderPromise return type stays broader
+  // (Promise<any[]> | any[]) to mirror its siblings.
+  promise: Promise<any[]>;
 }
 
 const objectLoaderCache = IS_BROWSER
@@ -56,7 +59,16 @@ function hasSameReferences(a: any[], b: any[]): boolean {
   return true;
 }
 
-function buildLoaderPromise(loaders: ResolvedSegment[]): Promise<any[]> {
+/**
+ * Build a fresh aggregate Promise.all over the loaders' resolved data refs.
+ * Unlike getMemoizedLoaderPromise this never caches, so each call yields a new
+ * Promise — correct for sites that await the result immediately (a shared,
+ * already-resolved promise would leak React's `.status` across server requests
+ * and skip the Suspense fallback).
+ *
+ * @internal
+ */
+export function buildLoaderPromise(loaders: ResolvedSegment[]): Promise<any[]> {
   if (loaders.length === 0) {
     return Promise.resolve([]);
   }