@rangojs/router 0.20.0 → 0.22.0

package/src/router/request-classification.ts

@@ -170,6 +170,21 @@ export async function classifyRequest<TEnv = any>(
   const willFullRender =
     !isAction && !isLoaderFetch && !isPartialReq && !isPeRender;
 
+  // Before the version check: each router has its own version, so a tab of
+  // another app always carries one this router does not have. That request is
+  // an app switch, not a stale client.
+  const clientRouterId = url.searchParams.get("_rsc_rid");
+  if (
+    clientRouterId &&
+    clientRouterId !== deps.routerId &&
+    url.searchParams.has("_rsc_partial")
+  ) {
+    return {
+      mode: "app-switch",
+      reloadUrl: stripInternalParams(url).toString(),
+    };
+  }
+
   const clientVersion = url.searchParams.get("_rsc_v");
   if (
     deps.routerVersion &&
@@ -195,18 +210,6 @@ export async function classifyRequest<TEnv = any>(
     };
   }
 
-  const clientRouterId = url.searchParams.get("_rsc_rid");
-  if (
-    clientRouterId &&
-    clientRouterId !== deps.routerId &&
-    url.searchParams.has("_rsc_partial")
-  ) {
-    return {
-      mode: "app-switch",
-      reloadUrl: stripInternalParams(url).toString(),
-    };
-  }
-
   const result = await resolveRoute<TEnv>(pathname, {
     findMatch: deps.findMatch,
     lite: true,

package/src/router/route-trie-builder.ts

@@ -37,6 +37,12 @@ export interface TrieLeaf {
   pr?: true;
   /** Passthrough: handler kept in bundle for live fallback on unknown params */
   pt?: true;
+  /**
+   * On-demand prerender eligible: the route opted into router.prerender()
+   * refresh. Distinct from `pr` — an od route may have no build-baked entry yet
+   * still needs a writable-overlay lookup at serve time.
+   */
+  od?: true;
   /** Response type for non-RSC routes (json, text, image, any) */
   rt?: string;
   /** Negotiate variants: response-type routes sharing this path */
@@ -72,6 +78,7 @@ export interface TrieNode {
  * @param prerenderRouteNames - Optional set of prerendered route names (sets leaf.pr)
  * @param passthroughRouteNames - Optional set of passthrough route names (sets leaf.pt)
  * @param responseTypeRoutes - Optional map of route name to response type (sets leaf.rt)
+ * @param onDemandRouteNames - Optional set of on-demand-eligible route names (sets leaf.od)
  */
 export function buildRouteTrie(
   routeManifest: Record<string, string>,
@@ -80,6 +87,7 @@ export function buildRouteTrie(
   prerenderRouteNames?: Set<string>,
   passthroughRouteNames?: Set<string>,
   responseTypeRoutes?: Record<string, string>,
+  onDemandRouteNames?: Set<string>,
 ): TrieNode {
   const root: TrieNode = {};
 
@@ -99,6 +107,7 @@ export function buildRouteTrie(
       ...(trailingSlash ? { ts: trailingSlash } : {}),
       ...(prerenderRouteNames?.has(routeName) ? { pr: true } : {}),
       ...(passthroughRouteNames?.has(routeName) ? { pt: true } : {}),
+      ...(onDemandRouteNames?.has(routeName) ? { od: true } : {}),
       ...(responseType ? { rt: responseType } : {}),
     });
   }

package/src/router/router-context.ts

@@ -100,6 +100,7 @@ export interface RouterContext<TEnv = any> {
       parent: any,
       fn: () => T,
     ) => T;
+    runIsolated: <T>(forRoute: string, fn: () => T) => T;
   };
 
   getMetricsStore: () => MetricsStore | undefined;

package/src/router/router-interfaces.ts

@@ -225,6 +225,29 @@ export interface Rango<
    * ```
    */
   fetch(request: Request, input?: RouterRequestInput<TEnv>): Promise<Response>;
+
+  /**
+   * Bind `{ env, ctx }` and get the on-demand (ISR-style) prerender runner, to refresh from a running app —
+   * fetch handler, cron, queue, workflow, webhook, or server action.
+   *
+   * Requestless: the producer renders with route params and env only, never the
+   * caller's cookies/headers/session. Only routes that opted in via
+   * `Prerender(..., { onDemand })` are persistable; others return a skipped
+   * result. Configure the store via the `prerender` router option.
+   *
+   * @example
+   * ```ts
+   * const prerender = router.prerender({ env, ctx });
+   * await prerender("/products/42");
+   * await prerender(
+   *   { route: "products.detail", params: { id: "42" } },
+   *   { throwOnError: true },
+   * );
+   * await prerender.many(targets, { concurrency: 4 });
+   * await prerender.markStale(["product:42"]);
+   * ```
+   */
+  prerender: import("../prerender/on-demand.js").PrerenderFn<TEnv, TRoutes>;
 }
 
 /**
@@ -332,6 +355,13 @@ export interface RangoInternal<
    */
   readonly cache?: RangoOptions<TEnv>["cache"];
 
+  /**
+   * Prerender store configuration (the writable durable overlay for on-demand
+   * prerender). Stored separately from the `prerender` trigger method so the RSC
+   * handler can resolve it per request. @internal
+   */
+  readonly _prerenderConfig?: RangoOptions<TEnv>["prerender"];
+
   /**
    * Not found component to render when no route matches
    */
@@ -457,7 +487,8 @@ export interface RangoInternal<
   readonly nonce?: NonceProvider<TEnv>;
 
   /**
-   * RSC version string
+   * The consumer-set version (createRouter({ version })), used for both of the
+   * router's versions. Undefined when the router uses its build versions.
    */
   readonly version?: string;
 
@@ -619,6 +650,9 @@ export interface RangoInternal<
    * Handle an RSC request.
    */
   fetch(request: Request, input?: RouterRequestInput<TEnv>): Promise<Response>;
+
+  /** On-demand prerender binder: router.prerender({ env, ctx }) returns the runner. */
+  prerender: import("../prerender/on-demand.js").PrerenderFn<TEnv, TRoutes>;
 }
 
 /**

package/src/router/router-options.ts

@@ -341,6 +341,36 @@ export interface RangoOptions<TEnv = any> {
         searchParams?: CacheSearchParams;
       });
 
+  /**
+   * Writable prerender store for on-demand (ISR-style) prerender refresh.
+   *
+   * A durable overlay in front of the bundled build manifest. When provided,
+   * `router.prerender(target, { env, ctx })` renders a route requestlessly and
+   * writes a versioned payload here; the serve path reads the overlay before the
+   * bundled manifest. Same union shape as `cache`: a plain config object or a
+   * factory resolved per request/per call (never at `createRouter()` time), so
+   * multi-tenant apps never memoize one request's binding for another.
+   *
+   * @example Cloudflare KV overlay with SWR revalidation
+   * ```typescript
+   * import { createKVPrerenderStore } from "@rangojs/router/prerender/cloudflare";
+   *
+   * const router = createRouter<AppEnv>({
+   *   prerender: (env) => ({
+   *     store: createKVPrerenderStore(env.PRERENDER_KV),
+   *     ttl: 3600,
+   *     onRevalidate: (target, e) => e.PRERENDER_QUEUE.send({ target }),
+   *   }),
+   * });
+   * ```
+   */
+  prerender?:
+    | import("../prerender/on-demand.js").PrerenderConfig<TEnv>
+    | ((
+        env: TEnv,
+        ctx?: ExecutionContext,
+      ) => import("../prerender/on-demand.js").PrerenderConfig<TEnv>);
+
   /**
    * Named cache profiles for "use cache" directive.
    * Profile names map to TTL/SWR configuration.
@@ -502,13 +532,23 @@ export interface RangoOptions<TEnv = any> {
   nonce?: NonceProvider<TEnv>;
 
   /**
-   * RSC version string included in metadata.
-   * The browser sends this back on partial requests to detect version mismatches.
+   * Version override. When set, this exact value is used for both of the
+   * router's versions: it keys the router's cached data (segments, `"use
+   * cache"` values, loader data) and its stored HTML (PPR shells,
+   * document-cache responses), is sent in payload metadata, and is what the
+   * browser's `_rsc_v` is compared with (a mismatch reloads the tab).
+   *
+   * Leave it unset for the default: rango computes two versions per router at
+   * build time, a data version from the router's server code and a document
+   * version that also covers the client assets. The same code builds to the
+   * same versions, so a deploy that does not change this router keeps its
+   * cache. In dev both are a stamp bumped on every RSC module edit.
    *
-   * Defaults to the auto-generated VERSION from `@rangojs/router:version` virtual module.
-   * Only set this if you need a custom versioning strategy.
+   * Set it to clear this router's cache on demand (change the value), or to
+   * tie the cache to your own release id (a per-deploy value clears the cache
+   * on every deploy).
    *
-   * @default VERSION from @rangojs/router:version
+   * @default the router's build versions
    */
   version?: string;
 

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

@@ -36,7 +36,7 @@ import {
 import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { _getRequestContext } from "../../server/request-context.js";
 import { getRouterContext } from "../router-context.js";
-import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
+import { trackStreamedHandler } from "./streamed-handler-boundary.js";
 import { observeSegmentHandler } from "../instrument.js";
 import {
   track,
@@ -280,6 +280,13 @@ export interface ResolveSegmentOptions {
    * #918: resolved twice on a MISS, once and discarded on a HIT).
    */
   chain?: readonly EntryData[];
+  /**
+   * The matched chain entry being resolved: where the sync path catches a
+   * handler error, so a streamed handler (or slot owned by a routeless layout)
+   * recovers into the same boundary. resolveSegment sets it for the entry it
+   * resolves; nested resolutions keep the outer value.
+   */
+  boundaryEntry?: EntryData;
 }
 
 /**
@@ -298,6 +305,8 @@ export async function resolveSegment<TEnv>(
   options?: ResolveSegmentOptions,
 ): Promise<ResolvedSegment[]> {
   const segments: ResolvedSegment[] = [];
+  const boundaryEntry = options?.boundaryEntry ?? entry;
+  if (!options?.boundaryEntry) options = { ...options, boundaryEntry };
 
   if (entry.type === "layout" || entry.type === "cache") {
     if (!options?.skipLoaders) {
@@ -398,19 +407,15 @@ export async function resolveSegment<TEnv>(
         if (result instanceof Promise) {
           warnOnStreamedResponse(result, entry.id);
           result.finally(doneRouteHandler).catch(() => {});
-          const tracked = deps.trackHandler(result, {
+          component = trackStreamedHandler(deps, result, {
+            boundaryEntry,
             segmentId: entry.shortCode,
             segmentType: entry.type,
-          });
-          observeStreamedHandler(
-            tracked,
-            entry.shortCode,
-            entry.type,
-            context.pathname,
+            context,
             routeKey,
             params,
-          );
-          component = tracked;
+            recover: !options?.throwOnError,
+          });
         } else {
           doneRouteHandler();
           component = result;
@@ -679,19 +684,15 @@ export async function resolveParallelEntry<TEnv>(
             : handler;
         if (result instanceof Promise) {
           result.finally(doneParallelHandler).catch(() => {});
-          const tracked = deps.trackHandler(result, {
+          component = trackStreamedHandler(deps, result, {
+            boundaryEntry: options?.boundaryEntry ?? parallelEntry,
             segmentId: `${parentShortCode}.${slot}`,
             segmentType: "parallel",
-          });
-          observeStreamedHandler(
-            tracked,
-            `${parentShortCode}.${slot}`,
-            "parallel",
-            context.pathname,
+            context,
             routeKey,
             params,
-          );
-          component = tracked as ReactNode;
+            recover: !options?.throwOnError,
+          });
         } else {
           doneParallelHandler();
           component = result as ReactNode;

package/src/router/segment-resolution/loader-cache.ts

@@ -9,7 +9,8 @@
  *   1. options.key(requestCtx) — full override, stored namespaced as
  *      loader:{loaderId}:key:{encodeURIComponent(result)} (#1009)
  *   2. store.keyGenerator(requestCtx, defaultKey) — store-level modification
- *   3. loader:{loaderId}:{host}{pathname}:{sortedParams} — default
+ *   3. loader:{loaderId}:{routerId}@{host}{pathname}:{sortedParams} — default
+ *      (a loader's ctx is one router's: cache-key-utils.ts, the router rule)
  *
  * Values are serialized via RSC Flight (serializeResult/deserializeResult),
  * supporting ReactNode, Promises, null, and all RSC-serializable types.
@@ -50,24 +51,34 @@ import {
   type LoaderIdentityRead,
 } from "../../server/context.js";
 import type { HandlerContext, InternalHandlerContext } from "../../types.js";
-import type { HandleStore } from "../../server/handle-store.js";
+import type {
+  HandleStore,
+  RecordAuthority,
+} from "../../server/handle-store.js";
 import type { CacheItemResult } from "../../cache/types.js";
 import {
   startHandleCapture,
   type HandleCapture,
 } from "../../cache/handle-capture.js";
-import { encodeHandles, decodeHandles } from "../../cache/handle-snapshot.js";
+import {
+  appendHandles,
+  encodeHandles,
+  decodeHandles,
+  type OwnedPushDelivery,
+} from "../../cache/handle-snapshot.js";
+import type { ShellLoaderSeedEntry } from "../../cache/shell-snapshot.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 import { runIdentityExempt } from "../../cache/cache-exec-scope.js";
 import {
   getRequestContext,
   _getRequestContext,
   runWithRequestContext,
+  type RequestContext,
 } from "../../server/request-context.js";
 import { observePhase, PHASES } from "../instrument.js";
 import {
   KEY_PART_PREFIX,
-  sortedRouteParams,
+  requestKeyBase,
 } from "../../cache/cache-key-utils.js";
 import {
   resolveTtl,
@@ -78,6 +89,7 @@ import {
   DEFAULT_ROUTE_TTL,
 } from "../../cache/cache-policy.js";
 import { readThroughItem } from "../../cache/read-through-swr.js";
+import { isWarmReplace, noteWarmWrite } from "../../prerender/warm-request.js";
 import {
   executionStart,
   predatesInvalidation,
@@ -128,17 +140,6 @@ function debugLoaderCacheLog(message: string): void {
   }
 }
 
-function getDefaultLoaderCacheKey(
-  loaderId: string,
-  host: string,
-  pathname: string,
-  params: Record<string, string>,
-): string {
-  const paramStr = sortedRouteParams(params);
-  const base = paramStr ? `${pathname}:${paramStr}` : pathname;
-  return `loader:${loaderId}:${host}${base}`;
-}
-
 /**
  * A loader's own `key()` result as its entry key (#1009). The result is
  * often request input, and the item family (`getItem`/`setItem`) has no
@@ -149,7 +150,7 @@ function getDefaultLoaderCacheKey(
  * - an encoded result holds no `:`, so the key reads unambiguously from
  *   the right (result, `key:`, loader id), and two namespaced keys are
  *   equal only for the same loader and result;
- * - a default key `loader:<id>:<host><pathname>...` holds a `/` past its
+ * - a default key `loader:<id>:[<router>@]<host><pathname>...` holds a `/` past its
  *   id, and an encoded result holds none, so the two are equal only if one
  *   loader's id is literally `<other id>:<host>/<path>...`. Loader ids can
  *   hold `:` (a dev id is a root-relative path, absolute `D:/...` on
@@ -178,8 +179,9 @@ async function resolveLoaderKey(
   // (cache-runtime pushes ctx.url.host). Without it, a multi-tenant host router
   // serving the same pathname for different hosts would leak one host's cached
   // loader data to another.
-  const host = getRequestContext()?.url?.host ?? "localhost";
-  const defaultKey = getDefaultLoaderCacheKey(loaderId, host, pathname, params);
+  const requestCtx = getRequestContext();
+  const host = requestCtx?.url?.host ?? "localhost";
+  const defaultKey = `loader:${loaderId}:${requestKeyBase(requestCtx, host, pathname, undefined, params)}`;
   if (options === false) return { key: defaultKey, declared: false };
   const keyFn = options.key;
   return {
@@ -256,26 +258,6 @@ function chainLoaderEntries(entry: EntryData): readonly LoaderEntry[] {
   return loaders;
 }
 
-/**
- * The ids of the loaders a request over the matched chain `entries` runs on
- * the live lane (no `ssr: false`), on a chain entry, its orphan layouts or
- * its parallel slots. A document HIT tail restores the record's pushes of
- * every other owner as authoritative (withCacheLookup, HandleStore
- * pushRestored); a live-lane loader is a hole, so its live run replaces its
- * recorded pushes instead. Memoized per entry.
- */
-export function liveLaneLoaderIds(
-  entries: readonly EntryData[],
-): ReadonlySet<string> {
-  const ids = new Set<string>();
-  for (const entry of entries) {
-    for (const l of chainLoaderEntries(entry)) {
-      if (!l.bake) ids.add(l.loader.$$id);
-    }
-  }
-  return ids;
-}
-
 /**
  * The lane of each loader the matched chain `entries` registers: "live" (no
  * `ssr: false`) or "bake". A loader registered on both is "live". A PPR
@@ -295,6 +277,75 @@ export function routeLoaderLanes(
   return lanes;
 }
 
+/**
+ * The pins this request serves loaders from, by loader id: the seed a
+ * document HIT tail (serveShellHit) or a navigation replay whose doc record
+ * hit (matchPartialWithPprReplay) armed from the shell entry's loader
+ * records. A capture serves none: its bake-lane loaders execute.
+ *
+ * The one answer to "is this loader served from the shell record on this
+ * request", for its value (resolveLoaderData) and for the record's copies of
+ * its handle pushes (loaderPins): both look the loader up here and nowhere
+ * else. A condition that makes pins, or one loader's pin, not apply belongs
+ * here or in the seed's decode (shell-snapshot.ts buildShellLoaderSeed),
+ * never after a lookup, or the two disagree: issues #1001 and #1003 were the
+ * pushes decided from the request's type while the value was decided from
+ * the pin.
+ */
+function servedPins(
+  reqCtx: RequestContext<any> | undefined,
+): ReadonlyMap<string, ShellLoaderSeedEntry> | undefined {
+  return isShellCaptureActive(reqCtx) ? undefined : reqCtx?._shellLoaderSeed;
+}
+
+/**
+ * What a record restored on a request over the matched chain `entries` is to
+ * each loader's handle pushes (HandleStore RecordAuthority), from the pins
+ * the request serves (servedPins). Call it when the record hits: the pins are
+ * read here, once, because a navigation replay arms its seed for the match
+ * only and the store asks while loader bodies run.
+ *
+ * Each side applies its own lane to the pin. The value is per registration
+ * (resolveLoaderData: an `ssr: false` registration is served its pin). The
+ * pushes are per loader: one the route also registers without `ssr: false`
+ * is a hole whatever its other registration's pin says, because the capture
+ * credited its pushes to the live registration's run (routeLoaderLanes).
+ *
+ * A dependency the route does not register has no pin of its own, and the
+ * record does not name the loader that ran it at capture: its copies stand
+ * only while every `ssr: false` loader is pinned (exact when the pins are
+ * all there or all gone).
+ */
+export function loaderPins(
+  entries: readonly EntryData[],
+  reqCtx: RequestContext<any> | undefined,
+): OwnedPushDelivery {
+  const pins = servedPins(reqCtx);
+  let lanes: ReadonlyMap<string, "live" | "bake"> | undefined;
+  let dependency: RecordAuthority | undefined;
+  return (loaderId) => {
+    lanes ??= routeLoaderLanes(entries);
+    const lane = lanes.get(loaderId);
+    if (lane === "live") return "hole";
+    if (lane === "bake") {
+      const pin = pins?.get(loaderId);
+      return pin ? (pin.complete ? "pin" : "copies") : "hole";
+    }
+    if (dependency === undefined) {
+      let bakeLane = 0;
+      let pinned = 0;
+      for (const [id, registered] of lanes) {
+        if (registered !== "bake") continue;
+        bakeLane++;
+        if (pins?.has(id)) pinned++;
+      }
+      dependency =
+        bakeLane > 0 && pinned === bakeLane ? "copies" : "placeholders";
+    }
+    return dependency;
+  };
+}
+
 function getLoaderStore(
   loaderEntry: LoaderEntry,
 ): import("../../cache/types.js").SegmentCacheStore | null {
@@ -323,11 +374,12 @@ function getLoaderStore(
  * replay; and the store reads the body scope to tell a live push from a
  * replayed one.
  * A PPR shell capture records the replayed pushes under this loader (its
- * push funnel reads the pushReplayed owner, shell-capture.ts), so a shell
- * HIT restores them owned (HandleStore.pushRestored). This replay still
- * runs on that HIT: the store drops its settled values, which the record
- * already restored, and keeps the thenable ones the record could not keep
- * (a deferred push, the reason the loader's record carries `runs`).
+ * push funnel reads the pushReplayed owner, shell-capture.ts), so a replay
+ * of that shell that serves this loader from its pin restores them owned
+ * (HandleStore.pushRestored), on a document HIT and on a navigation alike.
+ * This replay still runs there: the store drops its settled values, which
+ * the record already restored, and keeps the thenable ones the record could
+ * not keep (a deferred push, the reason the loader's pin carries `runs`).
  */
 async function replayLoaderHandles(
   encoded: string | undefined,
@@ -338,34 +390,7 @@ async function replayLoaderHandles(
 ): Promise<void> {
   const recorded = encoded ? await decodeHandles(encoded) : {};
   if (!recorded) return;
-  const delivers = new Map<string, boolean>();
-  const claims = (owner: string): boolean => {
-    let deliver = delivers.get(owner);
-    if (deliver === undefined) {
-      deliver = claim ? claim(owner) : true;
-      delivers.set(owner, deliver);
-    }
-    return deliver;
-  };
-  const replay = (): void => {
-    for (const key in recorded) {
-      const owner = key.slice(key.indexOf(":") + 1);
-      if (!claims(owner)) continue;
-      for (const [handleName, values] of Object.entries(recorded[key])) {
-        for (const value of values) {
-          handleStore.pushReplayed(handleName, segmentId, value, owner);
-        }
-      }
-    }
-  };
-  // A hole's entry, pushes or none, takes the place of the shell copies of
-  // its pushes (HandleStore.redeliverReplays). Not once the hole delivered
-  // in this request: a run a reader started first replaces them itself.
-  if (claims(cachedLoaderId)) {
-    handleStore.redeliverReplays(cachedLoaderId, replay);
-  } else {
-    replay();
-  }
+  appendHandles(recorded, handleStore, segmentId, claim, cachedLoaderId);
 }
 
 /**
@@ -492,10 +517,11 @@ export function resolveLoaderData<TEnv>(
     return createMaskedLoaderPromise();
   }
 
-  if (bakeSegmentKey) {
-    const seed = reqCtx?._shellLoaderSeed;
-    if (seed && seed.has(bakeSegmentKey)) {
-      const recorded = seed.get(bakeSegmentKey)!;
+  // `bake`: the pin is the `ssr: false` registration's. The caller's key is
+  // passed for an unflagged loader of an entry without loading() too.
+  if (bakeSegmentKey && loaderEntry.bake) {
+    const recorded = servedPins(reqCtx)?.get(loaderEntry.loader.$$id);
+    if (recorded) {
       if (!recorded.holes) {
         // Pin-first (hole-free record): the pinned container is what the
         // payload serves (recorded paths win wholesale), resolved
@@ -734,7 +760,11 @@ function executeLoaderData<TEnv>(
     };
 
     const data = await readThroughItem({
-      getItem: (k) => store.getItem!(k),
+      // A router.prerender() warm takes the miss path: the body runs and
+      // setItem replaces the entry.
+      getItem: isWarmReplace(requestCtxForExecute)
+        ? async () => null
+        : (k) => store.getItem!(k),
       // Handles ride the entry like "use cache" (encodeHandles: Flight, pending
       // pushes awaited up to its timeout, the whole blob dropped on a timeout
       // or a thrown encode). Encoded here, inside the deferred write, so a
@@ -761,7 +791,9 @@ function executeLoaderData<TEnv>(
             ...o,
             tags: entryTags.length > 0 ? entryTags : undefined,
             ...(handles ? { handles } : {}),
+            startedAt: start?.at,
           });
+          noteWarmWrite(requestCtxForExecute, "item");
         }),
       key,
       execute: async () => {
@@ -800,7 +832,8 @@ function executeLoaderData<TEnv>(
     });
 
     // An entry without handles (none recorded, or dropped by an encode
-    // timeout) replays none, and still stands for a hole's shell copies.
+    // timeout) replays none, and still takes the place of the loader's
+    // placeholders (appendHandles): a claimed entry is the loader's source.
     if (cachedRead && handleStore && owningSegmentId) {
       await replayLoaderHandles(
         hitHandles,