@rangojs/router 0.0.0-experimental.19 → 0.0.0-experimental.1db96a9e

package/src/rsc/index.ts

@@ -29,28 +29,8 @@ export type {
   NonceProvider,
 } from "./types.js";
 
-// Re-export HandleStore types for consumers who need custom handling
-export {
-  createHandleStore,
-  type HandleStore,
-  type HandleData,
-} from "../server/handle-store.js";
-
 // Re-export request context utilities for server-side access to env/request/params
 export {
   getRequestContext,
   requireRequestContext,
-  setRequestContextParams,
 } from "../server/request-context.js";
-
-// Re-export cache store types and implementations
-export type {
-  SegmentCacheStore,
-  CachedEntryData,
-  CachedEntryResult,
-  SegmentCacheProvider,
-  SegmentHandleData,
-} from "../cache/types.js";
-
-export { MemorySegmentCacheStore } from "../cache/memory-segment-store.js";
-export { CFCacheStore, type CFCacheStoreOptions } from "../cache/cf/index.js";

package/src/rsc/loader-fetch.ts

@@ -168,8 +168,19 @@ export async function handleLoaderFetch<TEnv>(
             loaderResult: unknown;
           }
           const loaderPayload: LoaderPayload = { loaderResult: result };
-          const rscStream =
-            ctx.renderToReadableStream<LoaderPayload>(loaderPayload);
+          const rscStream = ctx.renderToReadableStream<LoaderPayload>(
+            loaderPayload,
+            {
+              onError: (error: unknown) => {
+                ctx.callOnError(error, "rendering", {
+                  request,
+                  url,
+                  env,
+                  loaderName: loaderId,
+                });
+              },
+            },
+          );
 
           return createResponseWithMergedHeaders(rscStream, {
             headers: { "content-type": "text/x-component;charset=utf-8" },
@@ -199,7 +210,16 @@ export async function handleLoaderFetch<TEnv>(
         name: err.name,
       },
     };
-    const rscStream = ctx.renderToReadableStream(errorPayload);
+    const rscStream = ctx.renderToReadableStream(errorPayload, {
+      onError: (error: unknown) => {
+        ctx.callOnError(error, "rendering", {
+          request,
+          url,
+          env,
+          loaderName: loaderId,
+        });
+      },
+    });
 
     return createResponseWithMergedHeaders(rscStream, {
       status: 500,

package/src/rsc/manifest-init.ts

@@ -31,7 +31,11 @@ export async function buildRouterTrieFromUrlpatterns(
 ): Promise<void> {
   const { generateManifestFull } =
     await import("../build/generate-manifest.js");
-  const generated = generateManifestFull(router.urlpatterns);
+  const generated = generateManifestFull(
+    router.urlpatterns,
+    undefined,
+    router.basename ? { urlPrefix: router.basename } : undefined,
+  );
   if (
     generated._routeAncestry &&
     Object.keys(generated._routeAncestry).length > 0

package/src/rsc/progressive-enhancement.ts

@@ -10,6 +10,7 @@ import {
   requireRequestContext,
   setRequestContextParams,
 } from "../server/request-context.js";
+import { getSSRSetup } from "./ssr-setup.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 import { executeMiddleware } from "../router/middleware.js";
 import type { RscPayload, ReactFormState } from "./types.js";
@@ -242,6 +243,8 @@ export async function handleProgressiveEnhancement<TEnv>(
     const payload: RscPayload = {
       metadata: {
         pathname: url.pathname,
+        routerId: ctx.router.id,
+        basename: ctx.router.basename,
         segments: match.segments,
         matched: match.matched,
         diff: match.diff,
@@ -256,11 +259,21 @@ export async function handleProgressiveEnhancement<TEnv>(
       formState: actionResult,
     };
 
-    const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
-    const [ssrModule, streamMode] = await Promise.all([
-      ctx.loadSSRModule(),
-      ctx.resolveStreamMode(request, env, url),
-    ]);
+    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+      onError: (error: unknown) => {
+        ctx.callOnError(error, "rendering", { request, url, env });
+      },
+    });
+    // metricsStore=undefined is safe: the handler already stashed the early
+    // SSR setup promise on request variables, so getSSRSetup returns it
+    // without falling back to a fresh startSSRSetup.
+    const [ssrModule, streamMode] = await getSSRSetup(
+      ctx,
+      request,
+      env,
+      url,
+      undefined,
+    );
     const htmlStream = await ssrModule.renderHTML(rscStream, {
       formState: reactFormState,
       nonce,
@@ -335,6 +348,8 @@ async function renderPeErrorBoundary<TEnv>(
   const payload: RscPayload = {
     metadata: {
       pathname: url.pathname,
+      routerId: ctx.router.id,
+      basename: ctx.router.basename,
       segments: errorResult.segments,
       matched: errorResult.matched,
       diff: errorResult.diff,
@@ -349,11 +364,21 @@ async function renderPeErrorBoundary<TEnv>(
     },
   };
 
-  const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
-  const [ssrModule, streamMode] = await Promise.all([
-    ctx.loadSSRModule(),
-    ctx.resolveStreamMode(request, env, url),
-  ]);
+  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+    onError: (error: unknown) => {
+      ctx.callOnError(error, "rendering", { request, url, env });
+    },
+  });
+  // metricsStore=undefined is safe: the handler already stashed the early
+  // SSR setup promise on request variables, so getSSRSetup returns it
+  // without falling back to a fresh startSSRSetup.
+  const [ssrModule, streamMode] = await getSSRSetup(
+    ctx,
+    request,
+    env,
+    url,
+    undefined,
+  );
   const htmlStream = await ssrModule.renderHTML(rscStream, {
     nonce,
     streamMode,

package/src/rsc/rsc-rendering.ts

@@ -12,6 +12,8 @@ import {
   getLocationState,
 } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
+import { appendMetric } from "../router/metrics.js";
+import { getSSRSetup } from "./ssr-setup.js";
 import type { RscPayload } from "./types.js";
 import {
   createResponseWithMergedHeaders,
@@ -28,13 +30,9 @@ export async function handleRscRendering<TEnv>(
   handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
   nonce: string | undefined,
 ): Promise<Response> {
-  // Retrieve handler-level timing from variables
   const reqCtx = requireRequestContext();
-  const handlerTimingArr: string[] = reqCtx.var.__handlerTiming || [];
-  const handlerStart: number = reqCtx.var.__handlerStart || 0;
 
   let payload: RscPayload;
-  let serverTiming: string | undefined;
   let hasInterceptSlots = false;
 
   if (isPartial) {
@@ -53,11 +51,11 @@ export async function handleRscRendering<TEnv>(
         return createSimpleRedirectResponse(match.redirect);
       }
 
-      serverTiming = match.serverTiming;
-
       payload = {
         metadata: {
           pathname: url.pathname,
+          routerId: ctx.router.id,
+          basename: ctx.router.basename,
           segments: match.segments,
           matched: match.matched,
           diff: match.diff,
@@ -66,18 +64,20 @@ export async function handleRscRendering<TEnv>(
           rootLayout: ctx.router.rootLayout,
           handles: handleStore.stream(),
           version: ctx.version,
+          prefetchCacheTTL: ctx.router.prefetchCacheTTL,
           themeConfig: ctx.router.themeConfig,
           initialTheme: reqCtx.theme,
         },
       };
     } else {
       setRequestContextParams(result.params, result.routeName);
-      serverTiming = result.serverTiming;
+
       hasInterceptSlots = !!result.slots;
 
       payload = {
         metadata: {
           pathname: url.pathname,
+          routerId: ctx.router.id,
           segments: result.segments,
           matched: result.matched,
           diff: result.diff,
@@ -86,6 +86,7 @@ export async function handleRscRendering<TEnv>(
           slots: result.slots,
           handles: handleStore.stream(),
           version: ctx.version,
+          prefetchCacheTTL: ctx.router.prefetchCacheTTL,
         },
       };
     }
@@ -132,14 +133,14 @@ export async function handleRscRendering<TEnv>(
         { headers: { "Content-Type": "application/json" } },
       );
     } else {
-      serverTiming = match.serverTiming;
-
       payload = {
         // Initial SSR can reconstruct the tree from segments + rootLayout,
         // so we omit root to avoid sending the same structure twice.
 
         metadata: {
           pathname: url.pathname,
+          routerId: ctx.router.id,
+          basename: ctx.router.basename,
           segments: match.segments,
           matched: match.matched,
           diff: match.diff,
@@ -148,6 +149,7 @@ export async function handleRscRendering<TEnv>(
           rootLayout: ctx.router.rootLayout,
           handles: handleStore.stream(),
           version: ctx.version,
+          prefetchCacheTTL: ctx.router.prefetchCacheTTL,
           themeConfig: ctx.router.themeConfig,
           initialTheme: reqCtx.theme,
         },
@@ -166,10 +168,24 @@ export async function handleRscRendering<TEnv>(
     }
   }
 
+  const metricsStore = reqCtx._metricsStore;
+  const renderStart = performance.now();
+
   // Serialize to RSC stream
   const rscSerializeStart = performance.now();
-  const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
+  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+    onError: (error: unknown) => {
+      ctx.callOnError(error, "rendering", { request, url, env });
+    },
+  });
   const rscSerializeDur = performance.now() - rscSerializeStart;
+  // This measures synchronous stream creation, not end-to-end stream consumption.
+  appendMetric(
+    metricsStore,
+    "rsc-serialize",
+    rscSerializeStart,
+    rscSerializeDur,
+  );
 
   // Determine if this is an RSC request or HTML request.
   // Partial requests (_rsc_partial) are always RSC -- they come from client-side
@@ -181,15 +197,9 @@ export async function handleRscRendering<TEnv>(
       !url.searchParams.has("__html")) ||
     url.searchParams.has("__rsc");
 
-  // Build complete Server-Timing: handler phases + match/manifest + RSC serialize
-  const timingParts: string[] = [...handlerTimingArr];
-  if (serverTiming) {
-    timingParts.push(serverTiming);
-  }
-  timingParts.push(`rsc-serialize;dur=${rscSerializeDur.toFixed(2)}`);
-
   if (isRscRequest) {
-    const fullTiming = timingParts.join(", ");
+    const renderDur = performance.now() - renderStart;
+    appendMetric(metricsStore, "render:total", renderStart, renderDur);
     const rscHeaders: Record<string, string> = {
       "content-type": "text/x-component;charset=utf-8",
       vary: "accept, X-Rango-State, X-RSC-Router-Client-Path",
@@ -205,22 +215,19 @@ export async function handleRscRendering<TEnv>(
         rscHeaders["cache-control"] = cc;
       }
     }
-    if (fullTiming) {
-      rscHeaders["Server-Timing"] = fullTiming;
-    }
     return createResponseWithMergedHeaders(rscStream, {
       headers: rscHeaders,
     });
   }
 
-  // Delegate to SSR for HTML response
-  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)}`);
+  // Delegate to SSR for HTML response (reuse early setup if available)
+  const [ssrModule, streamMode] = await getSSRSetup(
+    ctx,
+    request,
+    env,
+    url,
+    metricsStore,
+  );
 
   const ssrRenderStart = performance.now();
   const htmlStream = await ssrModule.renderHTML(rscStream, {
@@ -228,23 +235,12 @@ export async function handleRscRendering<TEnv>(
     streamMode,
   });
   const ssrRenderDur = performance.now() - ssrRenderStart;
-  timingParts.push(`ssr-render-html;dur=${ssrRenderDur.toFixed(2)}`);
+  appendMetric(metricsStore, "ssr-render-html", ssrRenderStart, ssrRenderDur);
 
-  // Add total handler duration
-  if (handlerStart) {
-    const totalHandler = performance.now() - handlerStart;
-    timingParts.push(`handler-total;dur=${totalHandler.toFixed(2)}`);
-  }
-
-  const fullTiming = timingParts.join(", ");
-  const htmlHeaders: Record<string, string> = {
-    "content-type": "text/html;charset=utf-8",
-  };
-  if (fullTiming) {
-    htmlHeaders["Server-Timing"] = fullTiming;
-  }
+  const renderDur = performance.now() - renderStart;
+  appendMetric(metricsStore, "render:total", renderStart, renderDur);
 
   return createResponseWithMergedHeaders(htmlStream, {
-    headers: htmlHeaders,
+    headers: { "content-type": "text/html;charset=utf-8" },
   });
 }

package/src/rsc/server-action.ts

@@ -21,6 +21,7 @@ import {
   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,
@@ -207,6 +208,7 @@ export async function executeServerAction<TEnv>(
       const payload: RscPayload = {
         metadata: {
           pathname: url.pathname,
+          routerId: ctx.router.id,
           segments: errorResult.segments,
           isPartial: true,
           matched: errorResult.matched,
@@ -224,6 +226,9 @@ export async function executeServerAction<TEnv>(
 
       const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
         temporaryReferences,
+        onError: (error: unknown) => {
+          ctx.callOnError(error, "rendering", { request, url, env });
+        },
       });
 
       return createResponseWithMergedHeaders(rscStream, {
@@ -274,6 +279,8 @@ export async function revalidateAfterAction<TEnv>(
 ): Promise<Response> {
   const { returnValue, actionStatus, temporaryReferences, actionContext } =
     continuation;
+  const reqCtx = requireRequestContext();
+  const metricsStore = reqCtx._metricsStore;
 
   const matchResult = await ctx.router.matchPartial(
     request,
@@ -308,11 +315,10 @@ export async function revalidateAfterAction<TEnv>(
   // Return updated segments
   setRequestContextParams(matchResult.params, matchResult.routeName);
 
-  const serverTiming = matchResult.serverTiming;
-
   const payload: RscPayload = {
     metadata: {
       pathname: url.pathname,
+      routerId: ctx.router.id,
       segments: matchResult.segments,
       isPartial: true,
       matched: matchResult.matched,
@@ -326,19 +332,25 @@ export async function revalidateAfterAction<TEnv>(
 
   attachLocationState(payload);
 
+  const renderStart = performance.now();
   const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
     temporaryReferences,
+    onError: (error: unknown) => {
+      ctx.callOnError(error, "rendering", { request, url, env });
+    },
   });
-
-  const actionHeaders: Record<string, string> = {
-    "content-type": "text/x-component;charset=utf-8",
-  };
-  if (serverTiming) {
-    actionHeaders["Server-Timing"] = serverTiming;
-  }
+  const rscSerializeDur = performance.now() - renderStart;
+  // This measures synchronous stream creation, not end-to-end stream consumption.
+  appendMetric(metricsStore, "rsc-serialize", renderStart, rscSerializeDur);
+  appendMetric(
+    metricsStore,
+    "render:total",
+    renderStart,
+    performance.now() - renderStart,
+  );
 
   return createResponseWithMergedHeaders(rscStream, {
     status: actionStatus,
-    headers: actionHeaders,
+    headers: { "content-type": "text/x-component;charset=utf-8" },
   });
 }

package/src/rsc/ssr-setup.ts

@@ -0,0 +1,128 @@
+/**
+ * SSR Setup Utilities
+ *
+ * Manages early kickoff and retrieval of SSR module loading and stream mode
+ * resolution. Both operations are request-scoped but independent of route
+ * matching, so they can run in parallel with segment resolution.
+ */
+
+import type { HandlerContext } from "./handler-context.js";
+import type { SSRModule } from "./types.js";
+import type { SSRStreamMode } from "../router/router-options.js";
+import type { MetricsStore } from "../server/context.js";
+import { appendMetric } from "../router/metrics.js";
+import { _getRequestContext } from "../server/request-context.js";
+
+export type SSRSetup = readonly [SSRModule, SSRStreamMode];
+
+/**
+ * Key used to stash the early SSR setup promise on request variables.
+ * Read back via `getSSRSetup`.
+ */
+export const SSR_SETUP_VAR = "__ssrSetup";
+
+/**
+ * Start loading the SSR module and resolving the stream mode in parallel.
+ * When a `getMetricsStore` getter is provided, records individual
+ * `ssr:module-load` and `ssr:stream-mode` metrics (the getter is called
+ * lazily so stores created after kickoff are still captured). Without a
+ * getter the promises run bare — no `.then()` microtasks, no
+ * `performance.now()` calls — keeping the non-debug hot path lean.
+ */
+export function startSSRSetup<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  getMetricsStore?: () => MetricsStore | undefined,
+): Promise<SSRSetup> {
+  if (!getMetricsStore) {
+    return Promise.all([
+      ctx.loadSSRModule(),
+      ctx.resolveStreamMode(request, env, url),
+    ]);
+  }
+  const start = performance.now();
+  return Promise.all([
+    ctx.loadSSRModule().then((mod) => {
+      appendMetric(
+        getMetricsStore(),
+        "ssr:module-load",
+        start,
+        performance.now() - start,
+      );
+      return mod;
+    }),
+    ctx.resolveStreamMode(request, env, url).then((mode) => {
+      appendMetric(
+        getMetricsStore(),
+        "ssr:stream-mode",
+        start,
+        performance.now() - start,
+      );
+      return mode;
+    }),
+  ]);
+}
+
+/**
+ * Retrieve the SSR setup result. Returns the early-kicked-off promise
+ * when available (stashed on request variables), otherwise starts a
+ * fresh setup.
+ */
+export function getSSRSetup<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  metricsStore: MetricsStore | undefined,
+): Promise<SSRSetup> {
+  const early = _getRequestContext()?._variables?.[SSR_SETUP_VAR] as
+    | Promise<SSRSetup>
+    | undefined;
+  if (early) return early;
+  return startSSRSetup(
+    ctx,
+    request,
+    env,
+    url,
+    metricsStore ? () => metricsStore : undefined,
+  );
+}
+
+/**
+ * Classify whether a request may require SSR (HTML rendering).
+ *
+ * Returns false for requests that are definitively RSC-only, loader fetches,
+ * prerender collection, or Accept-based RSC (no text/html). This mirrors
+ * the isRscRequest decision in rsc-rendering.ts.
+ *
+ * Note: response/mime routes are excluded by the caller — this function
+ * runs after classifyRequest() determines the request mode.
+ */
+export function mayNeedSSR(request: Request, url: URL): boolean {
+  if (
+    url.searchParams.has("_rsc_partial") ||
+    url.searchParams.has("_rsc_action") ||
+    request.headers.has("rsc-action") ||
+    url.searchParams.has("_rsc_loader") ||
+    url.searchParams.has("__rsc") ||
+    url.searchParams.has("__prerender_collect")
+  ) {
+    return false;
+  }
+
+  // Mirror the Accept-based RSC decision from rsc-rendering.ts:
+  // if Accept is present and does not include text/html (and no __html override),
+  // the response will be RSC, not HTML.
+  const accept = request.headers.get("accept");
+  if (
+    accept &&
+    !accept.includes("text/html") &&
+    !url.searchParams.has("__html")
+  ) {
+    return false;
+  }
+
+  return true;
+}

package/src/rsc/types.ts

@@ -19,6 +19,9 @@ 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[];
@@ -32,10 +35,14 @@ export interface RscPayload {
     handles?: AsyncGenerator<HandleData, void, unknown>;
     /** RSC version string for cache invalidation */
     version?: string;
+    /** TTL in milliseconds for the client-side in-memory prefetch cache */
+    prefetchCacheTTL?: number;
     /** 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) */
@@ -61,7 +68,10 @@ export interface RSCDependencies {
    */
   renderToReadableStream: <T>(
     payload: T,
-    options?: { temporaryReferences?: unknown },
+    options?: {
+      temporaryReferences?: unknown;
+      onError?: (error: unknown) => string | void;
+    },
   ) => ReadableStream<Uint8Array>;
 
   /**

package/src/search-params.ts

@@ -55,14 +55,22 @@ type Simplify<T> = { [K in keyof T]: T[K] };
 /**
  * Resolve a SearchSchema to its typed object.
  *
+ * Both required and optional params resolve to `T | undefined` at the handler
+ * level. The required/optional distinction is a consumer-facing contract
+ * (e.g., for href() and reverse() autocomplete) — it tells callers which
+ * params the route expects, but the handler must still check for undefined
+ * since the framework cannot trust the client to send all required params.
+ *
  * @example
  * type S = { q: "string"; page: "number?"; sort: "string?" };
  * type R = ResolveSearchSchema<S>;
- * // { q: string; page?: number; sort?: string }
+ * // { q: string | undefined; page?: number; sort?: string }
  */
 export type ResolveSearchSchema<T extends SearchSchema> = Simplify<
   {
-    [K in RequiredKeys<T> & string]: ResolveBaseType<BaseType<T[K]>>;
+    [K in RequiredKeys<T> & string]:
+      | ResolveBaseType<BaseType<T[K]>>
+      | undefined;
   } & {
     [K in OptionalKeys<T> & string]?: ResolveBaseType<BaseType<T[K]>>;
   }
@@ -166,7 +174,9 @@ type ExtractParamsFromPattern<T extends string> =
  * - `"number"` / `"number?"` - coerced via `Number()`; NaN treated as missing
  * - `"boolean"` / `"boolean?"` - `"true"` / `"1"` -> true, `"false"` / `"0"` / `""` -> false
  *
- * Missing required params are set to their zero value (empty string / 0 / false).
+ * Missing params (both required and optional) are omitted from the result
+ * (undefined). The required/optional distinction is a consumer-facing contract
+ * only — the handler must check for undefined.
  */
 export function parseSearchParams<T extends SearchSchema>(
   searchParams: URLSearchParams,
@@ -180,13 +190,7 @@ export function parseSearchParams<T extends SearchSchema>(
     const raw = searchParams.get(key);
 
     if (raw === null) {
-      if (!isOptional) {
-        // Required param missing: use zero value
-        if (baseType === "string") result[key] = "";
-        else if (baseType === "number") result[key] = 0;
-        else if (baseType === "boolean") result[key] = false;
-      }
-      // Optional params are omitted (undefined)
+      // Missing params are omitted (undefined) regardless of required/optional
       continue;
     }
 
@@ -194,11 +198,10 @@ export function parseSearchParams<T extends SearchSchema>(
       result[key] = raw;
     } else if (baseType === "number") {
       const num = Number(raw);
-      if (Number.isNaN(num)) {
-        if (!isOptional) result[key] = 0;
-      } else {
+      if (!Number.isNaN(num)) {
         result[key] = num;
       }
+      // NaN treated as missing (undefined)
     } else if (baseType === "boolean") {
       result[key] = raw === "true" || raw === "1";
     }