@rangojs/router 0.20.0 → 0.22.0

package/src/router/segment-resolution/revalidation.ts

@@ -47,7 +47,7 @@ import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
 import { observeEvent, observeSegmentHandler } from "../instrument.js";
 import { runInSegmentTagScope } from "../../cache/cache-tag.js";
-import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
+import { trackStreamedHandler } from "./streamed-handler-boundary.js";
 import {
   track,
   RangoContext,
@@ -441,6 +441,8 @@ async function resolveParallelSlotComponent<TEnv>(args: {
   deps: SegmentResolutionDeps<TEnv>;
   routeKey: string;
   params: Record<string, string>;
+  /** Matched chain entry (where the sync path catches), else the slot's owner. */
+  boundaryEntry: EntryData;
 }): Promise<{ component: ReactNode | undefined; handlerRan: boolean }> {
   const {
     shouldResolve,
@@ -452,6 +454,7 @@ async function resolveParallelSlotComponent<TEnv>(args: {
     deps,
     routeKey,
     params,
+    boundaryEntry,
   } = args;
 
   let component: ReactNode | undefined;
@@ -484,19 +487,15 @@ async function resolveParallelSlotComponent<TEnv>(args: {
             : handler;
         if (result instanceof Promise) {
           warnOnStreamedResponse(result, parallelId);
-          const tracked = deps.trackHandler(result, {
+          component = trackStreamedHandler(deps, result, {
+            boundaryEntry,
             segmentId: parallelId,
             segmentType: "parallel",
-          });
-          observeStreamedHandler(
-            tracked,
-            parallelId,
-            "parallel",
-            context.pathname,
+            context,
             routeKey,
             params,
-          );
-          component = tracked as ReactNode;
+            recover: true,
+          });
         } else {
           component = result as ReactNode;
         }
@@ -547,6 +546,8 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
      * to it: loader sub-ids are filtered out and slots are re-grouped by parent).
      */
     loaderOrder?: "after" | "before";
+    /** Matched chain entry being resolved; see ResolveSegmentOptions.boundaryEntry. */
+    boundaryEntry?: EntryData;
   },
 ): Promise<SegmentRevalidationResult> {
   const segments: ResolvedSegment[] = [];
@@ -696,6 +697,7 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       deps,
       routeKey,
       params,
+      boundaryEntry: options?.boundaryEntry ?? entry,
     });
 
     segments.push({
@@ -865,19 +867,17 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         if (result instanceof Promise) {
           warnOnStreamedResponse(result, routeEntry.id);
           result.finally(doneHandler).catch(() => {});
-          const tracked = deps.trackHandler(result, {
-            segmentId: entry.shortCode,
-            segmentType: entry.type,
-          });
-          observeStreamedHandler(
-            tracked,
-            entry.shortCode,
-            entry.type,
-            context.pathname,
-            routeKey,
-            params,
-          );
-          return { content: tracked };
+          return {
+            content: trackStreamedHandler(deps, result, {
+              boundaryEntry: entry,
+              segmentId: entry.shortCode,
+              segmentType: entry.type,
+              context,
+              routeKey,
+              params,
+              recover: true,
+            }),
+          };
         }
         doneHandler();
         return { content: result };
@@ -1098,6 +1098,8 @@ export async function resolveSegmentWithRevalidation<TEnv>(
         deps,
         actionContext,
         stale,
+        undefined,
+        entry,
       );
       segments.push(...orphanResult.segments);
       matchedIds.push(...orphanResult.matchedIds);
@@ -1126,6 +1128,8 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   stale?: boolean,
   /** Parent route entry — its loaders are inherited so parallel slots can access them. */
   parentRouteEntry?: EntryData,
+  /** Matched chain entry being resolved (see ResolveSegmentOptions.boundaryEntry); defaults to parentRouteEntry. */
+  boundaryEntry: EntryData | undefined = parentRouteEntry,
 ): Promise<SegmentRevalidationResult> {
   invariant(
     orphan.type === "layout" || orphan.type === "cache",
@@ -1286,7 +1290,11 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     deps,
     actionContext,
     stale,
-    { parentChainDefault: "force-render", loaderOrder: "before" },
+    {
+      parentChainDefault: "force-render",
+      loaderOrder: "before",
+      boundaryEntry,
+    },
   );
   segments.push(...parallelResult.segments);
   matchedIds.push(...parallelResult.matchedIds);
@@ -1307,6 +1315,8 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
       deps,
       actionContext,
       stale,
+      undefined,
+      boundaryEntry,
     );
     segments.push(...nestedResult.segments);
     matchedIds.push(...nestedResult.matchedIds);

package/src/router/segment-resolution/streamed-handler-boundary.ts

@@ -0,0 +1,133 @@
+/**
+ * Streamed handlers (loading()): track, observe, and recover a rejection into
+ * the declared errorBoundary() / notFoundBoundary() fallback.
+ *
+ * Invariants:
+ * - No status write and no onError call: the status is committed at first
+ *   flush, and trackHandler already reports each rejection once.
+ * - The recovered promise resolves, so Flight reports no error. The writers
+ *   that refuse a failed render through Flight errors need the failure
+ *   recorded here: `_renderErrors` for the document cache and a prerender
+ *   warm, `_recoveredHandlerErrors` for cacheRoute (cache(), and the doc record
+ *   a PPR capture needs). The shell capture and the SWR re-render own both,
+ *   so a derived render never writes into (or reads) the foreground's.
+ * - Nothing to render to rethrows the original rejection: no boundary found, a
+ *   thrown Response (redirect), a Skip, a throwing fallback.
+ * - No recovery when `recover` is false (prerender throwOnError, the intercept
+ *   background re-render): those lanes must reject so nothing is baked/cached.
+ */
+
+import type { ReactNode } from "react";
+import { isDataNotFoundError } from "../../errors.js";
+import {
+  createErrorInfo,
+  createNotFoundInfo,
+  renderErrorFallback,
+  renderNotFoundFallback,
+  resolveNotFoundFallback,
+} from "../error-handling.js";
+import { _getRequestContext } from "../../server/request-context.js";
+import type { EntryData } from "../../server/context.js";
+import type { ErrorInfo, HandlerContext } from "../../types/index.js";
+import type { SegmentResolutionDeps } from "../types.js";
+import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
+
+export interface StreamedHandlerOptions<TEnv> {
+  /**
+   * Entry to look boundaries up from: the matched chain entry being resolved
+   * (where the sync path catches, whatever routeless layout owns a slot), or
+   * the intercept's declaring entry.
+   */
+  boundaryEntry: EntryData;
+  segmentId: string;
+  segmentType: ErrorInfo["segmentType"];
+  context: HandlerContext<any, TEnv>;
+  routeKey?: string;
+  params: Record<string, string>;
+  /** False where the rejection must reach the caller (prerender, intercept background re-render). */
+  recover: boolean;
+}
+
+const NOOP = (): void => {};
+
+/**
+ * Track a streamed handler promise and return the segment component: the
+ * tracked promise itself when there is nothing to recover to, else a promise
+ * that resolves to the declared fallback on rejection.
+ */
+export function trackStreamedHandler<TEnv>(
+  deps: SegmentResolutionDeps<TEnv>,
+  result: Promise<unknown>,
+  options: StreamedHandlerOptions<TEnv>,
+): ReactNode {
+  const { segmentId, segmentType, context } = options;
+  const tracked = deps.trackHandler(result as Promise<ReactNode>, {
+    segmentId,
+    segmentType,
+  });
+  observeStreamedHandler(
+    tracked,
+    segmentId,
+    segmentType,
+    context.pathname,
+    options.routeKey,
+    options.params,
+  );
+
+  if (!options.recover) return tracked as ReactNode;
+  const { boundaryEntry } = options;
+  const hasBoundary =
+    deps.findNearestErrorBoundary(boundaryEntry) != null ||
+    deps.findNearestNotFoundBoundary(boundaryEntry) != null ||
+    deps.notFoundComponent !== undefined;
+  if (!hasBoundary) return tracked as ReactNode;
+
+  // Captured now: the rejection can settle outside the request's ALS frame.
+  const reqCtx = _getRequestContext();
+  const recovered = tracked.catch((error: unknown): ReactNode => {
+    const node = renderBoundary(error, deps, options, boundaryEntry);
+    if (node === undefined) throw error;
+    if (reqCtx)
+      (reqCtx._recoveredHandlerErrors ??= new Map()).set(segmentId, error);
+    reqCtx?._renderErrors?.push(error);
+    return node;
+  });
+  // A dropped segment (never rendered) must not become an unhandledRejection.
+  recovered.catch(NOOP);
+  return recovered as ReactNode;
+}
+
+function renderBoundary<TEnv>(
+  error: unknown,
+  deps: SegmentResolutionDeps<TEnv>,
+  options: StreamedHandlerOptions<TEnv>,
+  boundaryEntry: EntryData,
+): ReactNode | undefined {
+  if (error instanceof Response) return undefined;
+  if ((error as { name?: string } | null)?.name === "Skip") return undefined;
+  const { segmentId, segmentType, context } = options;
+  try {
+    if (isDataNotFoundError(error)) {
+      const boundary = deps.findNearestNotFoundBoundary(boundaryEntry);
+      if (boundary == null && deps.notFoundComponent === undefined) {
+        return undefined;
+      }
+      return renderNotFoundFallback(
+        resolveNotFoundFallback(
+          boundary,
+          deps.notFoundComponent,
+          context.pathname,
+        ),
+        createNotFoundInfo(error, segmentId, segmentType, context.pathname),
+      );
+    }
+    const fallback = deps.findNearestErrorBoundary(boundaryEntry);
+    if (fallback == null) return undefined;
+    return renderErrorFallback(
+      fallback,
+      createErrorInfo(error, segmentId, segmentType),
+    );
+  } catch {
+    return undefined;
+  }
+}

package/src/router/trie-matching.ts

@@ -25,6 +25,8 @@ export interface TrieMatchResult {
   pr?: true;
   /** Passthrough: handler kept for live fallback on unknown params */
   pt?: true;
+  /** On-demand prerender eligible (router.prerender() refreshable) */
+  od?: true;
   /** Response type for non-RSC routes (json, text, image, any) */
   responseType?: string;
   /** Negotiate variants: response-type routes sharing this path */
@@ -343,6 +345,7 @@ function validateAndBuild(
   if (redirectTo) result.redirectTo = redirectTo;
   if (leaf.pr) result.pr = true;
   if (leaf.pt) result.pt = true;
+  if (leaf.od) result.od = true;
   if (leaf.rt) result.responseType = leaf.rt;
   if (leaf.nv) result.negotiateVariants = leaf.nv;
   if (leaf.rf) result.rscFirst = true;

package/src/router-versions.ts

@@ -0,0 +1,60 @@
+/**
+ * Per-router cache versions: the shapes shared by the build (which computes
+ * them, vite/discovery/build-versions.ts) and the runtime (which reads them,
+ * server/build-version-table.ts). No imports, so the Vite plugin bundle can
+ * use it without resolving the `@rangojs/router:version` virtual module.
+ *
+ * Design: docs/design/per-app-cache-version.md.
+ */
+
+/**
+ * The two versions one `createRouter()` serves with.
+ *
+ * - `data` keys cached RSC data: segment entries, `"use cache"` values and
+ *   loader data. It follows the router's server code only.
+ * - `document` keys stored HTML (PPR shells, document-cache responses), is the
+ *   value the browser echoes as `_rsc_v`, and stamps `ShellCacheEntry.buildVersion`.
+ *   It follows the server code and the client asset URLs.
+ */
+export interface RouterVersions {
+  readonly data: string;
+  readonly document: string;
+}
+
+/**
+ * The build's table as the `@rangojs/router:version` module exports it:
+ * router id to `[data, document]`. {@link DEFAULT_ROUTER_VERSIONS_KEY} holds
+ * the whole-build pair, used for a router the build could not attribute.
+ */
+export type RouterVersionsTable = Readonly<
+  Record<string, readonly [data: string, document: string]>
+>;
+
+/** Table key of the whole-build versions. Not a legal `$$id` (8 hex chars). */
+export const DEFAULT_ROUTER_VERSIONS_KEY = "*";
+
+/** One value for both versions: a consumer-set `version`, or the dev stamp. */
+export function uniformVersions(version: string): RouterVersions {
+  return { data: version, document: version };
+}
+
+/**
+ * The versions a router serves with under `table`: a consumer-set `version`
+ * for both; else the router's own entry; else the whole-build pair, for a
+ * router the table does not list. `undefined` when there is no table (dev,
+ * tests) or it has neither entry. One function for the request handler and
+ * the build's shell capture, which must stamp what the handler will check.
+ */
+export function resolveVersionsFrom(
+  table: RouterVersionsTable | undefined,
+  routerId: string | undefined,
+  override: string | undefined,
+): RouterVersions | undefined {
+  if (override !== undefined) return uniformVersions(override);
+  if (!table) return undefined;
+  const pair =
+    (routerId !== undefined && Object.hasOwn(table, routerId)
+      ? table[routerId]
+      : undefined) ?? table[DEFAULT_ROUTER_VERSIONS_KEY];
+  return pair ? { data: pair[0], document: pair[1] } : undefined;
+}

package/src/router.ts

@@ -14,6 +14,14 @@ import {
   isValidDevDiscoveryEpoch,
 } from "./dev-discovery-protocol.js";
 import { createReverse, type ReverseFunction } from "./reverse.js";
+import {
+  resolvePrerenderVersion,
+  resolveRouterVersions,
+} from "./server/build-version-table.js";
+import { isDevEnvironment } from "./errors.js";
+import { isViteDevServer } from "./cache/store-scope.js";
+import { createPrerenderTrigger } from "./prerender/create-prerender-trigger.js";
+import { createMemoryPrerenderStore } from "./prerender/memory-prerender-store.js";
 import {
   registerRouteMap,
   getRouterManifest,
@@ -155,6 +163,7 @@ export function createRouter<TEnv = any>(
     notFound,
     onError,
     cache,
+    prerender: prerenderConfigOption,
     cacheProfiles: cacheProfilesOption,
     theme: themeOption,
     urls: urlsOption,
@@ -181,6 +190,16 @@ export function createRouter<TEnv = any>(
     strictMode: strictModeOption = true,
   } = options;
 
+  const defaultDevPrerenderStore = prerenderConfigOption
+    ? undefined
+    : createMemoryPrerenderStore();
+  const effectivePrerenderConfigOption =
+    prerenderConfigOption ??
+    ((() =>
+      isViteDevServer() && defaultDevPrerenderStore
+        ? { store: defaultDevPrerenderStore }
+        : undefined) as RangoOptions<TEnv>["prerender"]);
+
   // Debug cache signal gate (DEVELOPMENT/TEST ONLY). Enabled by the
   // debugCacheSignal option OR the RANGO_TEST_SIGNALS=1 env flag. When off,
   // no X-Rango-Cache header is emitted and output is byte-identical.
@@ -744,6 +763,77 @@ export function createRouter<TEnv = any>(
     );
   }
 
+  // Shared reverse function (also the value behind router.reverse).
+  const reverseFn = createReverse(mergedRouteMap);
+  const reverseLoose = reverseFn as unknown as (
+    name: string,
+    params?: Record<string, string>,
+  ) => string;
+
+  // On-demand prerender binder (router.prerender({ env, ctx }) -> runner with .many / .markStale).
+  // Requestless: runProducer runs matchForPrerender with onDemand=true (arming
+  // the personalization guard); the store/config resolve per call from {env,ctx}.
+  // The key version is the router's data version, resolved by the same call the
+  // handler's overlay read makes (resolvePrerenderVersion), so the keys agree.
+  const prerenderTrigger = createPrerenderTrigger<TEnv, {}>({
+    routerId,
+    resolveVersion: () => resolvePrerenderVersion(routerId, version),
+    isDev: isDevEnvironment,
+    isViteDevServer,
+    ensureManifest: () => ensureRouterManifest(routerId),
+    resolveConfig: (env, ctx) => {
+      const opt = effectivePrerenderConfigOption;
+      if (!opt) return undefined;
+      return typeof opt === "function" ? opt(env, ctx) : opt;
+    },
+    reverse: (route, params) => {
+      try {
+        return reverseLoose(route, params);
+      } catch {
+        return undefined;
+      }
+    },
+    matchRoute: async (pathname) => {
+      const m = await findMatch(pathname);
+      if (!m) return null;
+      return {
+        routeName: m.routeKey,
+        params: m.params,
+        isOnDemand: m.od === true,
+        isPassthrough: m.pt === true,
+      };
+    },
+    runProducer: ({ pathname, isPassthrough, env, dev }) =>
+      _matchForPrerender<TEnv>(
+        pathname,
+        {},
+        {
+          ...prerenderDeps,
+          versions: resolveRouterVersions(routerId, version),
+        },
+        undefined,
+        isPassthrough,
+        env,
+        dev,
+        true,
+      ),
+    // A warm goes through router.fetch's handler: the one createRouter's own
+    // cache, nonce and version configure. An entry that passes them to
+    // createRSCHandler itself is not what a warm runs.
+    resolveCacheConfig: (env, ctx) =>
+      typeof cache === "function" ? cache(env, ctx) : cache,
+    // Called from inside a request, the warm leaves that request's scopes:
+    // it runs in the context the request entered the handler with
+    // (RequestContext._runAtRequestEntry).
+    fetch: (request, input) => {
+      const atRequestEntry = _getRequestContext()?._runAtRequestEntry;
+      return atRequestEntry
+        ? atRequestEntry(() => router.fetch(request, input))
+        : router.fetch(request, input);
+    },
+    ambientOrigin: () => _getRequestContext()?.url.origin,
+  });
+
   // Create match handler functions bound to router state
   const matchHandlers = createMatchHandlers<TEnv>({
     buildRouterContext,
@@ -866,6 +956,7 @@ export function createRouter<TEnv = any>(
       // Collect route keys that have prerender handlers (for non-trie match path)
       let prerenderRouteKeys: Set<string> | undefined;
       let passthroughRouteKeys: Set<string> | undefined;
+      let onDemandRouteKeys: Set<string> | undefined;
       for (const [name, entry] of manifest.entries()) {
         if (entry.type === "route" && entry.isPrerender) {
           if (!prerenderRouteKeys) prerenderRouteKeys = new Set();
@@ -874,6 +965,10 @@ export function createRouter<TEnv = any>(
             if (!passthroughRouteKeys) passthroughRouteKeys = new Set();
             passthroughRouteKeys.add(name);
           }
+          if (entry.isOnDemand === true) {
+            if (!onDemandRouteKeys) onDemandRouteKeys = new Set();
+            onDemandRouteKeys.add(name);
+          }
         }
       }
 
@@ -900,6 +995,7 @@ export function createRouter<TEnv = any>(
             cacheProfiles: resolvedCacheProfiles,
             ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
             ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
+            ...(onDemandRouteKeys ? { onDemandRouteKeys } : {}),
           });
         }
       } else {
@@ -920,6 +1016,7 @@ export function createRouter<TEnv = any>(
           cacheProfiles: resolvedCacheProfiles,
           ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
           ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
+          ...(onDemandRouteKeys ? { onDemandRouteKeys } : {}),
         });
       }
 
@@ -1020,7 +1117,7 @@ export function createRouter<TEnv = any>(
     // Type-safe URL builder using merged route map
     // Types are tracked through the builder chain via TRoutes parameter
     // Seeded with static route names from the generated file (injected by Vite)
-    reverse: createReverse(mergedRouteMap),
+    reverse: reverseFn,
 
     // Expose accumulated route map for typeof extraction
     // Returns {} initially, but builder chain accumulates specific route types
@@ -1037,6 +1134,15 @@ export function createRouter<TEnv = any>(
     // Expose cache configuration for RSC handler
     cache,
 
+    // Expose the prerender store config (durable overlay) for the RSC handler to
+    // resolve per request. Stored under _prerenderConfig because `prerender` on
+    // the instance is the trigger method (router.prerender()).
+    _prerenderConfig: effectivePrerenderConfigOption,
+
+    // On-demand prerender trigger: router.prerender({ env, ctx })(target),
+    // plus .many() and .markStale() on the runner.
+    prerender: prerenderTrigger,
+
     // Expose notFound component for RSC handler
     notFound,
 

package/src/rsc/full-payload.ts

@@ -52,8 +52,12 @@ export function buildFullPayload(
       rootLayout: ctx.router.rootLayout,
       // Full render: resolve deferred handle values server-side so SSR markup and
       // the first sync useHandle read see resolved values. Partial payloads
-      // (rsc-rendering.ts) keep streaming (handleStore.stream()).
-      handles: resolvedHandleStream(handleStore),
+      // (rsc-rendering.ts) keep streaming (handleStore.stream()). A shell
+      // capture renders from what its record keeps (resolvedHandleStream).
+      handles: resolvedHandleStream(
+        handleStore,
+        reqCtx._shellCaptureRun === true,
+      ),
       // Post-handler-barrier pushes (streaming loader ctx.handle() writes)
       // stream here; the client applies them after hydration. Instantly
       // complete when the loader lane is idle — including PPR shell capture,

package/src/rsc/handler-context.ts

@@ -14,6 +14,11 @@ import type { SSRStreamMode } from "../router/router-options.js";
 
 export interface HandlerContext<TEnv = unknown> {
   router: RangoInternal<TEnv, any>;
+  /**
+   * The router's DOCUMENT version (router-versions.ts): payload metadata, the
+   * `_rsc_v` reload check, and PPR shell stamping and gating. The data version
+   * is not here; cache stores read it from the request context.
+   */
   version: string;
   devDiscoveryEpoch?: number;
   renderToReadableStream: RSCDependencies["renderToReadableStream"];