@rangojs/router 0.0.0-experimental.a769fbe7 → 0.0.0-experimental.ac99d918

package/src/rsc/runtime-warnings.ts

@@ -8,6 +8,7 @@ import {
   createResponseWithMergedHeaders,
   carryOverRedirectHeaders,
 } from "./helpers.js";
+import { isRedirectResponse } from "../response-utils.js";
 
 // W3 -----------------------------------------------------------------------
 
@@ -18,16 +19,14 @@ import {
  */
 export function extractRedirectResponse(value: unknown): Response | null {
   if (!(value instanceof Response)) return null;
-  const location = value.headers.get("Location");
-  if (value.status >= 300 && value.status < 400 && location) {
-    const redirect = createResponseWithMergedHeaders(null, {
-      status: value.status,
-      headers: { Location: location },
-    });
-    carryOverRedirectHeaders(value, redirect);
-    return redirect;
-  }
-  return null;
+  if (!isRedirectResponse(value)) return null;
+  const location = value.headers.get("Location")!;
+  const redirect = createResponseWithMergedHeaders(null, {
+    status: value.status,
+    headers: { Location: location },
+  });
+  carryOverRedirectHeaders(value, redirect);
+  return redirect;
 }
 
 /**
@@ -40,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,31 +18,19 @@
 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 {
   hasBodyContent,
   createResponseWithMergedHeaders,
   createSimpleRedirectResponse,
-  carryOverRedirectHeaders,
+  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
@@ -97,7 +85,10 @@ export async function executeServerAction<TEnv>(
       args = await ctx.decodeReply(body, { temporaryReferences });
     }
   } catch (error) {
-    throw new Error(`Failed to decode action arguments: ${error}`, {
+    // Keep the original error as `cause` for server-side logging, but do not
+    // interpolate it into the message: that string can surface to the client
+    // and may leak decode internals.
+    throw new Error("Failed to decode action arguments", {
       cause: error,
     });
   }
@@ -109,51 +100,35 @@ 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 from actions. Without this, the redirect
-    // Response would be serialized as the action returnValue (which fails)
-    // and the revalidation step would run unnecessarily.
+    // Intercept redirect Responses: serializing one as the action returnValue
+    // would fail, and revalidation would run needlessly.
     if (data instanceof Response) {
-      const redirectUrl = data.headers.get("Location");
-      const isRedirect = data.status >= 300 && data.status < 400 && redirectUrl;
-      if (isRedirect) {
-        const locationState = getLocationState();
-        let redirect: Response;
-        if (locationState) {
-          redirect = ctx.createRedirectFlightResponse(
-            redirectUrl,
-            resolveLocationStateEntries(locationState),
-          );
-        } else {
-          redirect = createSimpleRedirectResponse(redirectUrl);
-        }
-        carryOverRedirectHeaders(data, redirect);
-        return redirect;
+      const intercepted = interceptRedirectForPartial(
+        data,
+        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 };
   } catch (error) {
     // Handle thrown redirect (e.g., throw redirect('/path'))
     if (error instanceof Response) {
-      const redirectUrl = error.headers.get("Location");
-      const isRedirect =
-        error.status >= 300 && error.status < 400 && redirectUrl;
-      if (isRedirect) {
-        const locationState = getLocationState();
-        let redirect: Response;
-        if (locationState) {
-          redirect = ctx.createRedirectFlightResponse(
-            redirectUrl,
-            resolveLocationStateEntries(locationState),
-          );
-        } else {
-          redirect = createSimpleRedirectResponse(redirectUrl);
-        }
-        carryOverRedirectHeaders(error, redirect);
-        return redirect;
-      }
+      const intercepted = interceptRedirectForPartial(
+        error,
+        ctx.createRedirectFlightResponse,
+      );
+      if (intercepted) return intercepted;
 
       // Non-redirect Response thrown from action — this will be treated
       // as a regular error and routed to the error boundary. Warn in dev
@@ -208,10 +183,15 @@ export async function executeServerAction<TEnv>(
       const payload: RscPayload = {
         metadata: {
           pathname: url.pathname,
+          // routerId exposed for the frontend (current app identity); see
+          // rsc-rendering.ts partial branch.
+          routerId: ctx.router.id,
           segments: errorResult.segments,
           isPartial: true,
           matched: errorResult.matched,
           diff: errorResult.diff,
+          resolvedIds: errorResult.resolvedIds,
+          params: errorResult.params,
           isError: true,
           handles: handleStore.stream(),
           version: ctx.version,
@@ -223,32 +203,41 @@ export async function executeServerAction<TEnv>(
       // location state is a success-only semantic. Error boundary responses
       // update the error UI but should not mutate browser history state.
 
-      const debugChannel = requireRequestContext()._debugChannel;
       const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
         temporaryReferences,
-        ...(debugChannel && { debugChannel }),
+        onError: (error: unknown) => {
+          ctx.callOnError(error, "rendering", { request, url, env });
+        },
       });
 
       return createResponseWithMergedHeaders(rscStream, {
         status: actionStatus,
-        headers: { "content-type": "text/x-component;charset=utf-8" },
+        headers: {
+          "content-type": "text/x-component;charset=utf-8",
+          // Router identity for the client's pre-decode integrity check (the
+          // action apply path has no post-decode guard). See response-adapter.
+          "X-RSC-Router-Id": ctx.router.id,
+        },
       });
     }
   }
 
   // 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,
     },
@@ -287,8 +276,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);
 
@@ -299,14 +288,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.`,
     );
   }
 
@@ -316,10 +308,15 @@ export async function revalidateAfterAction<TEnv>(
   const payload: RscPayload = {
     metadata: {
       pathname: url.pathname,
+      // routerId exposed for the frontend (current app identity); see
+      // rsc-rendering.ts partial branch.
+      routerId: ctx.router.id,
       segments: matchResult.segments,
       isPartial: true,
       matched: matchResult.matched,
       diff: matchResult.diff,
+      resolvedIds: matchResult.resolvedIds,
+      params: matchResult.params,
       slots: matchResult.slots,
       handles: handleStore.stream(),
       version: ctx.version,
@@ -327,11 +324,14 @@ export async function revalidateAfterAction<TEnv>(
     returnValue,
   };
 
-  attachLocationState(payload);
+  attachLocationStateIfPresent(payload);
 
   const renderStart = performance.now();
   const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
     temporaryReferences,
+    onError: (error: unknown) => {
+      ctx.callOnError(error, "rendering", { request, url, env });
+    },
   });
   const rscSerializeDur = performance.now() - renderStart;
   // This measures synchronous stream creation, not end-to-end stream consumption.
@@ -345,6 +345,11 @@ export async function revalidateAfterAction<TEnv>(
 
   return createResponseWithMergedHeaders(rscStream, {
     status: actionStatus,
-    headers: { "content-type": "text/x-component;charset=utf-8" },
+    headers: {
+      "content-type": "text/x-component;charset=utf-8",
+      // Router identity for the client's pre-decode integrity check (the action
+      // apply path has no post-decode guard). See response-adapter.
+      "X-RSC-Router-Id": ctx.router.id,
+    },
   });
 }

package/src/rsc/ssr-setup.ts

@@ -77,7 +77,7 @@ export function getSSRSetup<TEnv>(
   url: URL,
   metricsStore: MetricsStore | undefined,
 ): Promise<SSRSetup> {
-  const early = _getRequestContext()?.var?.[SSR_SETUP_VAR] as
+  const early = _getRequestContext()?._variables?.[SSR_SETUP_VAR] as
     | Promise<SSRSetup>
     | undefined;
   if (early) return early;
@@ -98,7 +98,7 @@ export function getSSRSetup<TEnv>(
  * the isRscRequest decision in rsc-rendering.ts.
  *
  * Note: response/mime routes are excluded by the caller — this function
- * runs after previewMatch() classifies the route type.
+ * runs after classifyRequest() determines the request mode.
  */
 export function mayNeedSSR(request: Request, url: URL): boolean {
   if (
@@ -126,3 +126,19 @@ export function mayNeedSSR(request: Request, url: URL): boolean {
 
   return true;
 }
+
+// Final render-time decision: is the response an RSC stream (vs HTML)? Distinct
+// from mayNeedSSR, which is a conservative pre-classifier (it treats a missing
+// Accept header as needing SSR; this treats it as RSC).
+export function isRscRequest(
+  request: Request,
+  url: URL,
+  isPartial: boolean,
+): boolean {
+  return (
+    isPartial ||
+    (!request.headers.get("accept")?.includes("text/html") &&
+      !url.searchParams.has("__html")) ||
+    url.searchParams.has("__rsc")
+  );
+}

package/src/rsc/types.ts

@@ -7,7 +7,7 @@
 
 import type { ResolvedSegment, SlotState } from "../types.js";
 import type { HandleData } from "../server/handle-store.js";
-import type { RSCRouterInternal } from "../router/router-interfaces.js";
+import type { RangoInternal } from "../router/router-interfaces.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 
 /**
@@ -19,10 +19,19 @@ export interface RscPayload {
   metadata?: {
     pathname: string;
     segments: ResolvedSegment[];
+    /** Router instance ID. When this changes between navigations, the client
+     *  discards cached segments and does a full tree replacement (app switch). */
+    routerId?: string;
     isPartial?: boolean;
     isError?: boolean;
     matched?: string[];
     diff?: string[];
+    /**
+     * All segment ids re-resolved on the server, including null-component
+     * ones excluded from `segments`/`diff`. Drives client-side handle-bucket
+     * cleanup. Superset of `diff`. See MatchResult.resolvedIds.
+     */
+    resolvedIds?: string[];
     /** Merged route params from the matched route */
     params?: Record<string, string>;
     slots?: Record<string, SlotState>;
@@ -34,19 +43,26 @@ 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) */
     initialTheme?: Theme;
+    /** URL prefix for all routes (from createRouter({ basename })). */
+    basename?: string;
     /** Whether connection warmup is enabled */
     warmupEnabled?: boolean;
-    /** Server-side redirect with optional state (for partial requests) */
-    redirect?: { url: string };
+    /**
+     * Server-side redirect with optional state (for partial requests).
+     * `external: true` (from redirect(url, { external: true })) tells the client
+     * to hard-navigate to an off-host target instead of validating same-origin.
+     */
+    redirect?: { url: string; external?: boolean };
     /** Server-set location state to include in history.pushState */
     locationState?: Record<string, unknown>;
   };
   returnValue?: { ok: boolean; data: unknown };
-  formState?: unknown;
 }
 
 /**
@@ -65,10 +81,7 @@ export interface RSCDependencies {
     payload: T,
     options?: {
       temporaryReferences?: unknown;
-      debugChannel?: {
-        readable?: ReadableStream;
-        writable?: WritableStream;
-      };
+      onError?: (error: unknown) => string | void;
     },
   ) => ReadableStream<Uint8Array>;
 
@@ -177,7 +190,7 @@ export interface CreateRSCHandlerOptions<
   /**
    * The RSC router instance
    */
-  router: RSCRouterInternal<TEnv, TRoutes>;
+  router: RangoInternal<TEnv, TRoutes>;
 
   /**
    * RSC dependencies from @vitejs/plugin-rsc/rsc.

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;
 
@@ -81,11 +73,11 @@ export type ResolveSearchSchema<T extends SearchSchema> = Simplify<
 // ============================================================================
 
 /** Resolve the global route map from RegisteredRoutes or GeneratedRouteMap. */
-type GlobalRouteMap = keyof RSCRouter.RegisteredRoutes extends never
-  ? keyof RSCRouter.GeneratedRouteMap extends never
+type GlobalRouteMap = keyof Rango.RegisteredRoutes extends never
+  ? keyof Rango.GeneratedRouteMap extends never
     ? Record<string, string>
-    : RSCRouter.GeneratedRouteMap
-  : RSCRouter.RegisteredRoutes;
+    : Rango.GeneratedRouteMap
+  : Rango.RegisteredRoutes;
 
 /**
  * Extract the resolved search params type for a named route.
@@ -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-content-promise.ts

@@ -0,0 +1,67 @@
+import type { ReactNode } from "react";
+
+/**
+ * Stable Promise wrappers keyed on the component itself. Objects (React
+ * elements, functions, lazy payloads) land in a WeakMap so entries GC when
+ * the underlying component is released; primitives (string, number, boolean,
+ * null) land in a Map so memoization still applies to text-/null-backed
+ * segments like those in partial-update flows. Keeping this cache outside
+ * the segment eliminates preservation fields on ResolvedSegment — it survives
+ * reconciliation naturally because the component ref is what's stable.
+ *
+ * Browser-only. On the server each SSR render needs a fresh pending promise
+ * so Suspense can emit the loading fallback HTML before content streams. A
+ * shared already-resolved promise has `.status === "fulfilled"` attached by
+ * React on its first observation — subsequent `use()` calls return
+ * synchronously without suspending, so the Suspense fallback never makes it
+ * into the initial HTML. Route-definition components share refs across
+ * requests, so a global cache would leak tracked state between renders.
+ */
+const IS_BROWSER = typeof window !== "undefined";
+const objectContentCache = IS_BROWSER
+  ? new WeakMap<object, Promise<ReactNode>>()
+  : null;
+const primitiveContentCache = IS_BROWSER
+  ? new Map<unknown, Promise<ReactNode>>()
+  : null;
+
+/**
+ * Return a stable Promise wrapping `component`, memoized on the component ref.
+ *
+ * A fresh `Promise.resolve(component)` each render would suspend for one
+ * microtask and briefly commit the loading fallback inside Suspender — the
+ * intercept / parallel-slot flicker this indirection prevents. Reusing the
+ * same Promise ref keeps React's `use()` in "known fulfilled" state after
+ * the first observation.
+ *
+ * @internal
+ */
+export function getMemoizedContentPromise(
+  component: ReactNode,
+): Promise<ReactNode> {
+  if (component instanceof Promise) {
+    return component as Promise<ReactNode>;
+  }
+
+  if (!objectContentCache || !primitiveContentCache) {
+    return Promise.resolve(component);
+  }
+
+  if (component !== null && typeof component === "object") {
+    const cached = objectContentCache.get(component);
+    if (cached) {
+      return cached;
+    }
+    const promise = Promise.resolve(component);
+    objectContentCache.set(component, promise);
+    return promise;
+  }
+
+  const cached = primitiveContentCache.get(component);
+  if (cached) {
+    return cached;
+  }
+  const promise = Promise.resolve(component);
+  primitiveContentCache.set(component, promise);
+  return promise;
+}