@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.19

package/src/rsc/response-route-handler.ts

@@ -23,6 +23,7 @@ import type { HandlerContext } from "./handler-context.js";
 import { createResponseErrorPayload } from "./response-error.js";
 import {
   createResponseWithMergedHeaders,
+  finalizeResponse,
   isCacheableStatus,
   buildRouteMiddlewareEntries,
 } from "./helpers.js";
@@ -70,25 +71,15 @@ export async function handleResponseRoute<TEnv>(
 
   // Build lightweight context for response handler
   const reqCtx = requireRequestContext();
+  const cleanUrl = stripInternalParams(url);
   const responseHandlerCtx = {
     request,
     params: preview.params || {},
     env,
-    searchParams: url.searchParams,
-    url,
+    searchParams: cleanUrl.searchParams,
+    url: cleanUrl,
     pathname: url.pathname,
-    href: (name: string, hrefParams?: Record<string, string>) => {
-      if (name.startsWith("/")) {
-        if (!hrefParams) return name;
-        return name.replace(/:([^/]+)/g, (_, key) => {
-          const value = hrefParams[key];
-          if (value === undefined)
-            throw new Error(`Missing param "${key}" for path "${name}"`);
-          return encodeURIComponent(value);
-        });
-      }
-      return name;
-    },
+    reverse: createReverseFunction(handlerCtx.getRequiredRouteMap()),
     get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
     header: (name: string, value: string) => reqCtx.header(name, value),
     _responseType: preview.responseType,
@@ -103,10 +94,15 @@ export async function handleResponseRoute<TEnv>(
 
     // Re-wrap a handler-returned Response through createResponseWithMergedHeaders
     // so that stub headers (cookies, custom headers set via ctx.header()) are included.
+    // Use Headers (not Record<string, string>) to preserve duplicate entries like Set-Cookie.
     const rewrapResponse = (result: Response) => {
-      const headers: Record<string, string> = {};
+      const headers = new Headers();
       result.headers.forEach((value, key) => {
-        headers[key] = value;
+        if (key.toLowerCase() === "set-cookie") {
+          headers.append(key, value);
+        } else {
+          headers.set(key, value);
+        }
       });
       return createResponseWithMergedHeaders(result.body, {
         status: result.status,
@@ -231,12 +227,23 @@ export async function handleResponseRoute<TEnv>(
     }
 
     if (cacheScope?.enabled) {
+      // Evaluate condition — skip response cache when condition returns false
+      let conditionPassed = true;
+      if (cacheScope.config !== false && cacheScope.config.condition) {
+        try {
+          conditionPassed = !!cacheScope.config.condition(reqCtx);
+        } catch {
+          conditionPassed = false;
+        }
+      }
+
       const store = cacheScope.getStore() ?? reqCtx._cacheStore;
-      if (store?.getResponse && store?.putResponse) {
+      if (conditionPassed && store?.getResponse && store?.putResponse) {
         // Build cache key with response:{type}: prefix to avoid collision
         // with segment keys and differentiate between response types.
-        // Include url.search so query-driven responses cache separately.
-        let cacheKey = `response:${preview.responseType}:${url.pathname}${url.search}`;
+        // Include host and url.search so query-driven and multi-host
+        // responses cache separately.
+        let cacheKey = `response:${preview.responseType}:${url.host}${url.pathname}${url.search}`;
 
         // Priority 1: Route-level key function (full override)
         if (cacheScope.config !== false && cacheScope.config.key) {
@@ -286,11 +293,14 @@ export async function handleResponseRoute<TEnv>(
             // Stale hit (SWR) - return cached, revalidate in background
             reqCtx.waitUntil(async () => {
               try {
-                const fresh = await executeHandler();
+                // finalizeResponse drains any onResponse callbacks registered
+                // during middleware execution (e.g. middleware short-circuit)
+                // that createResponseWithMergedHeaders didn't reach.
+                const fresh = finalizeResponse(await executeHandler());
                 if (isCacheableStatus(fresh.status)) {
                   await store.putResponse!(
                     cacheKey,
-                    fresh,
+                    fresh.clone(),
                     cacheScope!.ttl,
                     cacheScope!.swr,
                   );
@@ -307,10 +317,11 @@ export async function handleResponseRoute<TEnv>(
         }
 
         // Cache miss - execute handler and cache the result.
-        // createResponseWithMergedHeaders inside the handler applies
-        // any callbacks registered during execution, so the response
-        // (and its clone) already include those transforms.
-        const response = await executeHandler();
+        // createResponseWithMergedHeaders inside the handler drains callbacks
+        // registered during handler execution. finalizeResponse catches any
+        // remaining callbacks (e.g. from middleware short-circuit where the
+        // handler never ran) so the cached artifact includes all transforms.
+        const response = finalizeResponse(await executeHandler());
 
         if (isCacheableStatus(response.status)) {
           reqCtx.waitUntil(async () => {
@@ -332,5 +343,5 @@ export async function handleResponseRoute<TEnv>(
     }
   }
 
-  return executeHandler();
+  return executeHandler().then(finalizeResponse);
 }

package/src/rsc/rsc-rendering.ts

@@ -111,6 +111,7 @@ export async function handleRscRendering<TEnv>(
       const nonLoaderSegments = match.segments.filter(
         (s) => s.type !== "loader",
       );
+      handleStore.seal();
       await handleStore.settled;
       const { serializeSegments } = await import("../cache/segment-codec.js");
       const serializedSegments = await serializeSegments(nonLoaderSegments);
@@ -213,13 +214,19 @@ export async function handleRscRendering<TEnv>(
   }
 
   // Delegate to SSR for HTML response
-  const ssrModuleStart = performance.now();
-  const ssrModule = await ctx.loadSSRModule();
-  const ssrModuleDur = performance.now() - ssrModuleStart;
-  timingParts.push(`ssr-module-load;dur=${ssrModuleDur.toFixed(2)}`);
+  const ssrSetupStart = performance.now();
+  const [ssrModule, streamMode] = await Promise.all([
+    ctx.loadSSRModule(),
+    ctx.resolveStreamMode(request, env, url),
+  ]);
+  const ssrSetupDur = performance.now() - ssrSetupStart;
+  timingParts.push(`ssr-setup;dur=${ssrSetupDur.toFixed(2)}`);
 
   const ssrRenderStart = performance.now();
-  const htmlStream = await ssrModule.renderHTML(rscStream, { nonce });
+  const htmlStream = await ssrModule.renderHTML(rscStream, {
+    nonce,
+    streamMode,
+  });
   const ssrRenderDur = performance.now() - ssrRenderStart;
   timingParts.push(`ssr-render-html;dur=${ssrRenderDur.toFixed(2)}`);
 

package/src/rsc/runtime-warnings.ts

@@ -0,0 +1,42 @@
+/**
+ * Runtime guardrail warnings (dev-only).
+ *
+ * W3: PE action redirect / Response handling.
+ */
+
+import {
+  createResponseWithMergedHeaders,
+  carryOverRedirectHeaders,
+} from "./helpers.js";
+
+// W3 -----------------------------------------------------------------------
+
+/**
+ * Extract a redirect Response from a thrown or returned value.
+ * Returns a redirect Response to send to the client, or null if the value
+ * is not a redirect Response.
+ */
+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;
+}
+
+/**
+ * Warn when a non-redirect Response is returned from an action during PE.
+ */
+export function warnNonRedirectPeResponse(): void {
+  console.warn(
+    `[rango] Server action returned a non-redirect Response during ` +
+      `progressive enhancement (no-JS) request. The Response will be ` +
+      `ignored — the page will re-render at the current URL instead.`,
+  );
+}

package/src/rsc/server-action.ts

@@ -1,9 +1,18 @@
 /**
  * Server Action Handler
  *
- * Handles server action execution and post-action revalidation.
- * Decodes action arguments, executes the action, handles redirects
- * and error boundaries, then revalidates affected segments.
+ * Handles server action execution and post-action revalidation as two
+ * separate phases:
+ *
+ * 1. executeServerAction — decodes args, runs the action, handles redirects
+ *    and error boundaries. Returns either a final Response (redirect/error)
+ *    or an ActionContinuation for the revalidation phase.
+ *
+ * 2. revalidateAfterAction — takes the continuation, matches affected
+ *    segments, builds the RSC payload, and returns the Flight response.
+ *
+ * The handler (handler.ts) runs the action BEFORE route middleware, then
+ * wraps revalidation inside route middleware — identical to a normal render.
  */
 
 import {
@@ -17,6 +26,7 @@ import {
   hasBodyContent,
   createResponseWithMergedHeaders,
   createSimpleRedirectResponse,
+  carryOverRedirectHeaders,
 } from "./helpers.js";
 import type { HandlerContext } from "./handler-context.js";
 
@@ -32,14 +42,40 @@ function attachLocationState(payload: RscPayload): void {
   }
 }
 
-export async function handleServerAction<TEnv>(
+/**
+ * Data flowing from action execution to the revalidation phase.
+ * When the action completes without redirect/error-boundary, the handler
+ * passes this to route middleware → revalidateAfterAction.
+ */
+export interface ActionContinuation {
+  returnValue: { ok: boolean; data: unknown };
+  actionStatus: number;
+  temporaryReferences: ReturnType<
+    HandlerContext["createTemporaryReferenceSet"]
+  >;
+  actionContext: {
+    actionId: string;
+    actionUrl: URL;
+    actionResult: unknown;
+    formData?: FormData;
+  };
+}
+
+/**
+ * Phase 1: Execute the server action.
+ *
+ * Decodes arguments, runs the action, handles redirects and error
+ * boundaries. Returns a final Response (redirect, error boundary render)
+ * or an ActionContinuation for the revalidation phase.
+ */
+export async function executeServerAction<TEnv>(
   ctx: HandlerContext<TEnv>,
   request: Request,
   env: TEnv,
   url: URL,
   actionId: string,
   handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
-): Promise<Response> {
+): Promise<Response | ActionContinuation> {
   const temporaryReferences = ctx.createTemporaryReferenceSet();
 
   // Decode action arguments from request body
@@ -82,15 +118,17 @@ export async function handleServerAction<TEnv>(
       const isRedirect = data.status >= 300 && data.status < 400 && redirectUrl;
       if (isRedirect) {
         const locationState = getLocationState();
+        let redirect: Response;
         if (locationState) {
-          // Redirect with state: needs Flight payload to carry state
-          return ctx.createRedirectFlightResponse(
+          redirect = ctx.createRedirectFlightResponse(
             redirectUrl,
             resolveLocationStateEntries(locationState),
           );
+        } else {
+          redirect = createSimpleRedirectResponse(redirectUrl);
         }
-        // Simple redirect: short-circuit with a header, no RSC serialization
-        return createSimpleRedirectResponse(redirectUrl);
+        carryOverRedirectHeaders(data, redirect);
+        return redirect;
       }
     }
 
@@ -103,28 +141,58 @@ export async function handleServerAction<TEnv>(
         error.status >= 300 && error.status < 400 && redirectUrl;
       if (isRedirect) {
         const locationState = getLocationState();
+        let redirect: Response;
         if (locationState) {
-          return ctx.createRedirectFlightResponse(
+          redirect = ctx.createRedirectFlightResponse(
             redirectUrl,
             resolveLocationStateEntries(locationState),
           );
+        } else {
+          redirect = createSimpleRedirectResponse(redirectUrl);
         }
-        return createSimpleRedirectResponse(redirectUrl);
+        carryOverRedirectHeaders(error, redirect);
+        return redirect;
+      }
+
+      // Non-redirect Response thrown from action — this will be treated
+      // as a regular error and routed to the error boundary. Warn in dev
+      // since the intent is likely a redirect with a missing Location header.
+      if (process.env.NODE_ENV !== "production") {
+        console.warn(
+          `[@rangojs/router] Server action "${actionId}" threw a Response ` +
+            `(status ${error.status}) that is not a redirect. ` +
+            `Non-redirect Responses are treated as errors. ` +
+            `Use \`throw redirect('/path')\` for redirects.`,
+        );
       }
     }
 
     returnValue = { ok: false, data: error };
     actionStatus = 500;
 
-    // Try to render error boundary
-    const errorResult = await ctx.router.matchError(
-      request,
-      { env },
-      error,
-      "route",
-    );
+    // Try to render error boundary.
+    // Report the action error first so it is not lost if matchError throws.
+    let errorResult;
+    try {
+      errorResult = await ctx.router.matchError(
+        request,
+        { env },
+        error,
+        "route",
+      );
+    } catch (matchErr) {
+      // matchError failed — report the original action error as unhandled,
+      // then let the matchError failure propagate.
+      ctx.callOnError(error, "action", {
+        request,
+        url,
+        env,
+        actionId,
+        handledByBoundary: false,
+      });
+      throw matchErr;
+    }
 
-    // Report the action error (handledByBoundary indicates if error boundary will render)
     ctx.callOnError(error, "action", {
       request,
       url,
@@ -165,17 +233,47 @@ export async function handleServerAction<TEnv>(
     }
   }
 
-  // Revalidate after action
+  // Build continuation for the revalidation phase
   const resolvedActionId =
     (loadedAction as { $id?: string; $$id?: string } | undefined)?.$id ??
     (loadedAction as { $$id?: string } | undefined)?.$$id ??
     actionId;
-  const actionContext = {
-    actionId: resolvedActionId,
-    actionUrl: new URL(request.url),
-    actionResult: returnValue.data,
-    formData: actionFormData,
+
+  return {
+    returnValue,
+    actionStatus,
+    temporaryReferences,
+    actionContext: {
+      actionId: resolvedActionId,
+      actionUrl: new URL(request.url),
+      actionResult: returnValue.data,
+      formData: actionFormData,
+    },
   };
+}
+
+/**
+ * Phase 2: Revalidate after action.
+ *
+ * Matches affected segments, builds the RSC payload, and returns the
+ * Flight response. Called inside route middleware (same as a normal render).
+ *
+ * Invariant: the response payload MUST have isPartial: true. The client
+ * (server-action-bridge) rejects non-partial payloads because partial
+ * reconciliation requires matched/diff semantics that full renders don't
+ * provide. Redirects are the only non-partial outcome and are handled via
+ * X-RSC-Redirect headers before Flight deserialization.
+ */
+export async function revalidateAfterAction<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  continuation: ActionContinuation,
+): Promise<Response> {
+  const { returnValue, actionStatus, temporaryReferences, actionContext } =
+    continuation;
 
   const matchResult = await ctx.router.matchPartial(
     request,
@@ -184,7 +282,8 @@ export async function handleServerAction<TEnv>(
   );
 
   if (!matchResult) {
-    // Fall back to full render
+    // matchPartial returns null when the route is a redirect or the request
+    // is missing required headers (previousUrl). Check for redirect first.
     const fullMatch = await ctx.router.match(request, { env });
     setRequestContextParams(fullMatch.params, fullMatch.routeName);
 
@@ -195,38 +294,15 @@ export async function handleServerAction<TEnv>(
       return createSimpleRedirectResponse(fullMatch.redirect);
     }
 
-    const serverTiming = fullMatch.serverTiming;
-
-    const payload: RscPayload = {
-      metadata: {
-        pathname: url.pathname,
-        segments: fullMatch.segments,
-        matched: fullMatch.matched,
-        diff: fullMatch.diff,
-        rootLayout: ctx.router.rootLayout,
-        handles: handleStore.stream(),
-        version: ctx.version,
-      },
-      returnValue,
-    };
-
-    attachLocationState(payload);
-
-    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
-      temporaryReferences,
-    });
-
-    const headers: Record<string, string> = {
-      "content-type": "text/x-component;charset=utf-8",
-    };
-    if (serverTiming) {
-      headers["Server-Timing"] = serverTiming;
-    }
-
-    return createResponseWithMergedHeaders(rscStream, {
-      status: actionStatus,
-      headers,
-    });
+    // 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.
+    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).`,
+    );
   }
 
   // Return updated segments

package/src/rsc/types.ts

@@ -114,6 +114,14 @@ export interface SSRRenderOptions {
    * Nonce for Content Security Policy (CSP)
    */
   nonce?: string;
+
+  /**
+   * SSR stream mode.
+   *
+   * - `"stream"` (default) — start flushing HTML immediately.
+   * - `"allReady"` — await `stream.allReady` before returning.
+   */
+  streamMode?: import("../router/router-options.js").SSRStreamMode;
 }
 
 /**

package/src/search-params.ts

@@ -127,20 +127,32 @@ type ExtractRouteParamsFromMap<TRouteMap, TName> = TName extends keyof TRouteMap
       : {}
   : {};
 
+/** Parse "a|b|c" into "a" | "b" | "c" */
+type ParseConstraint<T extends string> =
+  T extends `${infer First}|${infer Rest}` ? First | ParseConstraint<Rest> : T;
+
 /** Minimal inline param extraction (avoids importing from types.ts to prevent circular deps). */
 type ExtractParamsFromPattern<T extends string> =
   T extends `${string}:${infer Param}/${infer Rest}`
-    ? Param extends `${infer Name}?`
-      ? { [K in Name]?: string } & ExtractParamsFromPattern<`/${Rest}`>
-      : Param extends `${infer Name}(${string})`
-        ? { [K in Name]: string } & ExtractParamsFromPattern<`/${Rest}`>
-        : { [K in Param]: string } & ExtractParamsFromPattern<`/${Rest}`>
+    ? Param extends `${infer Name}(${infer C})?`
+      ? {
+          [K in Name]?: ParseConstraint<C>;
+        } & ExtractParamsFromPattern<`/${Rest}`>
+      : Param extends `${infer Name}(${infer C})`
+        ? {
+            [K in Name]: ParseConstraint<C>;
+          } & ExtractParamsFromPattern<`/${Rest}`>
+        : Param extends `${infer Name}?`
+          ? { [K in Name]?: string } & ExtractParamsFromPattern<`/${Rest}`>
+          : { [K in Param]: string } & ExtractParamsFromPattern<`/${Rest}`>
     : T extends `${string}:${infer Param}`
-      ? Param extends `${infer Name}?`
-        ? { [K in Name]?: string }
-        : Param extends `${infer Name}(${string})`
-          ? { [K in Name]: string }
-          : { [K in Param]: string }
+      ? Param extends `${infer Name}(${infer C})?`
+        ? { [K in Name]?: ParseConstraint<C> }
+        : Param extends `${infer Name}(${infer C})`
+          ? { [K in Name]: ParseConstraint<C> }
+          : Param extends `${infer Name}?`
+            ? { [K in Name]?: string }
+            : { [K in Param]: string }
       : {};
 
 // ============================================================================

package/src/server/context.ts

@@ -11,6 +11,7 @@ import type {
   TransitionConfig,
 } from "../types";
 import { invariant } from "../errors";
+import type { DefaultRouteName } from "../types/global-namespace.js";
 
 // ============================================================================
 //  Performance Metrics Types
@@ -120,6 +121,8 @@ export type InterceptSelectorContext<TEnv = any> = {
   request: Request; // The HTTP request object
   env: TEnv; // Platform bindings (Cloudflare env, etc.)
   segments: InterceptSegmentsState; // Client's current segments (where navigating FROM)
+  fromRouteName?: DefaultRouteName; // Named route being navigated away from (undefined for unnamed routes)
+  toRouteName?: DefaultRouteName; // Named route being navigated to (undefined for unnamed routes)
 };
 
 /**
@@ -254,10 +257,18 @@ interface HelperContext {
   urlPrefix?: string;
   /** Name prefix from include() - applied to all named routes */
   namePrefix?: string;
+  /** True when this scope is at root level (no named include boundary above).
+   *  Routes at root scope allow dot-local reverse to fall back to bare names. */
+  rootScoped?: boolean;
   /** Run helper for cleaner middleware code */
   run?: <T>(fn: () => T | Promise<T>) => T | Promise<T>;
   /** Tracked includes for build-time manifest generation */
   trackedIncludes?: TrackedInclude[];
+  /** Cache profiles for DSL-time cache("profileName") resolution */
+  cacheProfiles?: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
 }
 // Use a global symbol key so the AsyncLocalStorage instance survives HMR
 // module re-evaluation. Without this, Vite's RSC module runner may create
@@ -399,7 +410,9 @@ export const getContext = (): {
           searchSchemas: store.searchSchemas,
           urlPrefix: store.urlPrefix,
           namePrefix: store.namePrefix,
+          rootScoped: store.rootScoped,
           trackedIncludes: store.trackedIncludes,
+          cacheProfiles: store.cacheProfiles,
         },
         callback,
       );
@@ -436,7 +449,9 @@ export const getContext = (): {
           searchSchemas,
           urlPrefix: store?.urlPrefix,
           namePrefix: store?.namePrefix,
+          rootScoped: store?.rootScoped,
           trackedIncludes: store?.trackedIncludes,
+          cacheProfiles: store?.cacheProfiles,
         },
         callback,
       );
@@ -469,17 +484,41 @@ export function runWithPrefixes<T>(
   } else {
     combinedUrlPrefix = urlPrefix;
   }
-  const combinedNamePrefix = namePrefix
-    ? store.namePrefix
-      ? `${store.namePrefix}.${namePrefix}`
-      : namePrefix
-    : store.namePrefix;
+  const combinedNamePrefix =
+    namePrefix !== undefined
+      ? namePrefix === ""
+        ? store.namePrefix
+        : store.namePrefix
+          ? `${store.namePrefix}.${namePrefix}`
+          : namePrefix
+      : store.namePrefix;
+
+  // Track root scope for dot-local reverse resolution.
+  //
+  // The flag answers: "can this route reach bare names at root scope?"
+  // It propagates through the include chain:
+  //
+  //   { name: "" }    — transparent: inherit parent, default true
+  //   { name: "foo" } — inherit parent if already set, else create boundary (false)
+  //   no name          — inherit parent unchanged
+  //
+  // This means { name: "" } + nested { name: "sub" } keeps rootScoped=true
+  // (the outer transparent include establishes root access, and the inner
+  // named include inherits it). But a direct { name: "sub" } at root gets
+  // rootScoped=false (no prior root-access grant, so it creates a boundary).
+  const combinedRootScoped =
+    namePrefix === ""
+      ? (store.rootScoped ?? true)
+      : namePrefix !== undefined
+        ? (store.rootScoped ?? false)
+        : store.rootScoped;
 
   return RSCRouterContext.run(
     {
       ...store,
       urlPrefix: combinedUrlPrefix,
       namePrefix: combinedNamePrefix,
+      rootScoped: combinedRootScoped,
     },
     callback,
   );
@@ -501,6 +540,15 @@ export function getNamePrefix(): string | undefined {
   return store?.namePrefix;
 }
 
+/**
+ * Get whether the current scope is at root level (no named include boundary above).
+ * Returns true at root or inside { name: "" } includes, false inside named includes.
+ */
+export function getRootScoped(): boolean {
+  const store = RSCRouterContext.getStore();
+  return store?.rootScoped ?? true;
+}
+
 // Export HelperContext type for use in other modules
 export type { HelperContext };