@rangojs/router 0.0.0-experimental.20 → 0.0.0-experimental.20dbba0c

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";
     }

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;
+}

package/src/segment-loader-promise.ts

@@ -0,0 +1,122 @@
+import type { ResolvedSegment } from "./types.js";
+
+/**
+ * Cache of aggregate Promise.all results keyed on the first loader's
+ * `loaderData` reference. Each entry holds the source refs it was built from
+ * plus the resulting Promise/array; lookup scans entries for the matching
+ * source array (typically a single entry, since distinct loader groups rarely
+ * share a first source). Object first-refs live in a WeakMap (auto-GC);
+ * primitive first-refs (strings/numbers/booleans/null) live in a Map so
+ * loaders that resolve to primitive data are memoized too — bounded in
+ * practice by the application's loader set.
+ *
+ * Keying externally means reconciliation's fresh segment objects no longer
+ * drop memoization — the cache survives as long as the underlying loader
+ * segments do, and GC collects entries when those loaders are released
+ * (object keys only).
+ *
+ * Browser-only. On the server each SSR render needs a fresh Promise so
+ * Suspense can actually suspend and emit the loading fallback HTML before
+ * content streams. A shared already-resolved promise has `.status` attached
+ * by React on first `use()`; subsequent observations return synchronously
+ * and skip the fallback. The zero-loader case is especially prone because
+ * every empty-loader site would otherwise share one promise across requests.
+ */
+const IS_BROWSER = typeof window !== "undefined";
+
+interface LoaderCacheEntry {
+  sources: any[];
+  promise: Promise<any[]> | any[];
+}
+
+const objectLoaderCache = IS_BROWSER
+  ? new WeakMap<object, LoaderCacheEntry[]>()
+  : null;
+const primitiveLoaderCache = IS_BROWSER
+  ? new Map<unknown, LoaderCacheEntry[]>()
+  : null;
+
+// In the browser, a single shared empty aggregate is safe (and desirable) —
+// reusing the same resolved promise keeps React's `use()` in a known-fulfilled
+// state across renders. On the server it would leak `.status = "fulfilled"`
+// across requests and skip the Suspense fallback, so we rebuild on each call.
+const SHARED_EMPTY_LOADER_PROMISE: Promise<any[]> | null = IS_BROWSER
+  ? Promise.resolve([])
+  : null;
+
+function hasSameReferences(a: any[], b: any[]): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function buildLoaderPromise(loaders: ResolvedSegment[]): Promise<any[]> {
+  if (loaders.length === 0) {
+    return Promise.resolve([]);
+  }
+  return Promise.all(
+    loaders.map((loader) =>
+      loader.loaderData instanceof Promise
+        ? loader.loaderData
+        : Promise.resolve(loader.loaderData),
+    ),
+  );
+}
+
+function isObjectLike(value: unknown): value is object {
+  return (
+    value !== null && (typeof value === "object" || typeof value === "function")
+  );
+}
+
+/**
+ * Memoize an aggregate Promise.all for a set of loader segments. Reusing the
+ * same aggregate across renders — invalidated only when any underlying
+ * loader.loaderData ref changes — keeps React's `use()` in "known fulfilled"
+ * state and prevents a fresh Promise.all from suspending (and briefly
+ * committing the Suspense fallback) on every partial update that doesn't
+ * actually change loader data.
+ *
+ * @internal
+ */
+export function getMemoizedLoaderPromise(
+  loaders: ResolvedSegment[],
+): Promise<any[]> | any[] {
+  if (loaders.length === 0) {
+    return SHARED_EMPTY_LOADER_PROMISE ?? buildLoaderPromise(loaders);
+  }
+  if (!objectLoaderCache || !primitiveLoaderCache) {
+    return buildLoaderPromise(loaders);
+  }
+
+  const sources = loaders.map((loader) => loader.loaderData);
+  const first = sources[0];
+  const entries = isObjectLike(first)
+    ? objectLoaderCache.get(first)
+    : primitiveLoaderCache.get(first);
+
+  if (entries) {
+    for (const entry of entries) {
+      if (hasSameReferences(entry.sources, sources)) {
+        return entry.promise;
+      }
+    }
+  }
+
+  const promise = buildLoaderPromise(loaders);
+  const newEntry: LoaderCacheEntry = { sources, promise };
+  if (entries) {
+    entries.push(newEntry);
+  } else if (isObjectLike(first)) {
+    objectLoaderCache.set(first, [newEntry]);
+  } else {
+    primitiveLoaderCache.set(first, [newEntry]);
+  }
+  return promise;
+}

package/src/segment-system.tsx

@@ -2,11 +2,7 @@ import * as React from "react";
 import { createElement, type ReactNode, type ComponentType } from "react";
 import { OutletProvider } from "./client.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
-import type {
-  ResolvedSegment,
-  LoaderDataResult,
-  RootLayoutProps,
-} from "./types.js";
+import type { ResolvedSegment, RootLayoutProps } from "./types.js";
 import { isLoaderDataResult } from "./types.js";
 import { invariant } from "./errors.js";
 import {
@@ -14,12 +10,55 @@ import {
   LoaderBoundary,
 } from "./route-content-wrapper.js";
 import { RootErrorBoundary } from "./root-error-boundary.js";
+import { getMemoizedContentPromise } from "./segment-content-promise.js";
+import { getMemoizedLoaderPromise } from "./segment-loader-promise.js";
 
 // ViewTransition is only available in React experimental.
 // Access via namespace import to avoid compile-time errors on stable React.
 const ReactViewTransition: any =
   "ViewTransition" in React ? (React as any).ViewTransition : null;
 
+function restoreParallelLoaderMarkers(
+  segments: ResolvedSegment[],
+): ResolvedSegment[] {
+  const parallelLoadingByNamespace = new Map<string, ReactNode>();
+  let nextSegments: ResolvedSegment[] | null = null;
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+
+    if (segment.type === "parallel") {
+      if (
+        segment.namespace &&
+        segment.loading !== undefined &&
+        segment.loading !== null &&
+        segment.loading !== false
+      ) {
+        parallelLoadingByNamespace.set(segment.namespace, segment.loading);
+      }
+      continue;
+    }
+
+    if (segment.type !== "loader" || segment.parallelLoading !== undefined) {
+      continue;
+    }
+
+    const parallelLoading = segment.namespace
+      ? parallelLoadingByNamespace.get(segment.namespace)
+      : undefined;
+    if (parallelLoading === undefined) {
+      continue;
+    }
+
+    if (!nextSegments) {
+      nextSegments = segments.slice();
+    }
+    nextSegments[i] = { ...segment, parallelLoading };
+  }
+
+  return nextSegments ?? segments;
+}
+
 /**
  * Resolve loader data from raw results, unwrapping LoaderDataResult wrappers
  */
@@ -143,6 +182,10 @@ export async function renderSegments(
   } = options || {};
 
   const temporalLazyRefs: Promise<any>[] = [];
+  const normalizedSegments = restoreParallelLoaderMarkers(segments);
+  const normalizedInterceptSegments = interceptSegments
+    ? restoreParallelLoaderMarkers(interceptSegments)
+    : undefined;
 
   /**
    * Registers promises from lazy/async components for awaiting.
@@ -167,7 +210,7 @@ export async function renderSegments(
     );
   }
   // Separate segments by type, passing intercept segments for explicit injection
-  const tree = segmentTreeWalk(segments, interceptSegments);
+  const tree = segmentTreeWalk(normalizedSegments, normalizedInterceptSegments);
   // Render content segments as siblings
   let content: ReactNode = null;
   for (const node of tree) {
@@ -219,10 +262,7 @@ export async function renderSegments(
       loading !== null && loading !== undefined && loading !== false
         ? createElement(RouteContentWrapper, {
             key: `suspense-loading-${id}`,
-            content:
-              resolvedComponent instanceof Promise
-                ? resolvedComponent
-                : Promise.resolve(resolvedComponent),
+            content: getMemoizedContentPromise(resolvedComponent),
             fallback: loading,
             segmentId: id,
           })
@@ -246,16 +286,7 @@ export async function renderSegments(
 
     // Prepare loader data if there are loaders
     const loaderIds = loaderEntries.map((loader) => loader.loaderId!);
-    const loaderDataPromise =
-      loaderEntries.length > 0
-        ? Promise.all(
-            loaderEntries.map((loader) =>
-              loader.loaderData instanceof Promise
-                ? loader.loaderData
-                : Promise.resolve(loader.loaderData),
-            ),
-          )
-        : Promise.resolve([]);
+    const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
 
     // Use LoaderBoundary when loading is defined to maintain consistent tree structure
     // This ensures cached segments (which may not have loader segments) have the same
@@ -284,13 +315,68 @@ export async function renderSegments(
         children: nodeContent,
       });
     } else {
-      // Has loaders but no loading skeleton - await loaders and render directly
-      const resolvedData = await loaderDataPromise;
+      // Has loaders but no loading skeleton.
+      // Split: parallel-owned loaders stream (their parallel has loading()),
+      // layout-owned loaders are awaited (they gate the layout content).
+      const layoutLoaders = loaderEntries.filter((l) => !l.parallelLoading);
+      const parallelOwnedLoaders = loaderEntries.filter(
+        (l) => !!l.parallelLoading,
+      );
+
+      // Await only layout-owned loaders
+      const layoutLoaderIds = layoutLoaders.map((l) => l.loaderId!);
+      const layoutLoaderDataPromise =
+        layoutLoaders.length > 0
+          ? Promise.all(
+              layoutLoaders.map((l) =>
+                l.loaderData instanceof Promise
+                  ? l.loaderData
+                  : Promise.resolve(l.loaderData),
+              ),
+            )
+          : Promise.resolve([]);
+      const resolvedData = await layoutLoaderDataPromise;
       const { loaderData, errorFallback } = resolveLoaderData(
         resolvedData,
-        loaderIds,
+        layoutLoaderIds,
       );
 
+      // Parallel-owned loaders: attach to their owning parallel segment
+      // as loaderDataPromise so ParallelOutlet wraps in LoaderBoundary
+      if (parallelOwnedLoaders.length > 0) {
+        const loadersByParallelNamespace = new Map<string, ResolvedSegment[]>();
+
+        for (const loader of parallelOwnedLoaders) {
+          if (!loader.namespace) {
+            continue;
+          }
+          const existing = loadersByParallelNamespace.get(loader.namespace);
+          if (existing) {
+            existing.push(loader);
+          } else {
+            loadersByParallelNamespace.set(loader.namespace, [loader]);
+          }
+        }
+
+        for (const p of node.parallel) {
+          if (!p.loading || !p.namespace) {
+            continue;
+          }
+
+          const ownedLoaders = loadersByParallelNamespace.get(p.namespace);
+          if (!ownedLoaders || ownedLoaders.length === 0) {
+            continue;
+          }
+
+          p.loaderIds = ownedLoaders.map((l) => l.loaderId!);
+          const aggregated = getMemoizedLoaderPromise(ownedLoaders);
+          p.loaderDataPromise =
+            (forceAwait || isAction) && aggregated instanceof Promise
+              ? await aggregated
+              : aggregated;
+        }
+      }
+
       content = createElement(OutletProvider, {
         key,
         content: outletContent,