@rangojs/router 0.31.0 → 0.33.0

package/src/cache/cache-scope.ts

@@ -235,6 +235,22 @@ function positionalParts(parts: readonly (string | null)[]): string[] {
     : parts.map((part) => part ?? "");
 }
 
+/**
+ * A route record key's own parts (CacheScope.resolveKeyFrom): `own`, the
+ * scope's default key or its store's keyGenerator result (undefined under a
+ * `key()` of its own), then the request `kind` unless `own` starts with
+ * `{kind}:`. A default key does, and so does a keyGenerator result built on
+ * `defaultKey` (`${defaultKey}|x`), which stays byte for byte. One that
+ * ignores `defaultKey` (a constant, the pathname) gave a document, a
+ * navigation and each intercept navigation one record, so a document GET
+ * rendered an intercept's. The kind is a part, never a `{kind}:` prefix: a
+ * prefix would give the results `x` and `doc:x` one record.
+ */
+function ownParts(own: string | undefined, kind: string | undefined): string[] {
+  if (own === undefined) return kind === undefined ? [] : [kind];
+  return kind === undefined || own.startsWith(`${kind}:`) ? [own] : [own, kind];
+}
+
 /**
  * One key resolution per request, resolver (`by`: a `key()` or a store's
  * keyGenerator) and `slot`, held on the request context (`_resolvedCacheKeys`,
@@ -530,8 +546,10 @@ export class CacheScope {
    * replaces the URL part, and its store's keyGenerator does not run. It
    * appends `kind` instead (routeRecordKind): the `key()` decides which
    * requests of one kind share a record, never that a document, a
-   * navigation and an intercept navigation do. With no partition part it is
-   * resolveDefaultKey alone. With a `key()` on the chain but no request
+   * navigation and an intercept navigation do. A keyGenerator result that
+   * does not start with its kind gets `kind` after it too (ownParts). With
+   * no partition part it is resolveDefaultKey alone, or that result and
+   * `kind` composed. With a `key()` on the chain but no request
    * context it rejects (keyWithoutContextError). `partitionedPrefix`
    * prefixes a key built from partition parts only (the response family's
    * `response:`, which passes no `kind`: a response route answers every
@@ -556,7 +574,9 @@ export class CacheScope {
     if (!requestCtx || !this.mayPartition) {
       return this.keyFns.length > 0
         ? Promise.reject(keyWithoutContextError())
-        : this.resolveDefaultKey(requestCtx, defaultKey);
+        : this.resolveDefaultKey(requestCtx, defaultKey).then((own) =>
+            composeCacheKeys([], ownParts(own, kind)),
+          );
     }
     return Promise.all([
       this.resolvePartitionParts(requestCtx, defaultKey),
@@ -565,10 +585,11 @@ export class CacheScope {
         : this.resolveDefaultKey(requestCtx, defaultKey),
     ]).then(([[keys, storeParts], ownDefault]) => {
       const generated = positionalParts(storeParts);
-      if (keys.length === 0 && generated.length === 0) return ownDefault!;
-      const last = ownDefault ?? kind;
-      if (last !== undefined) generated.push(last);
-      return partitionedPrefix + composeCacheKeys(keys, generated);
+      const own = ownParts(ownDefault, kind);
+      if (keys.length === 0 && generated.length === 0) {
+        return composeCacheKeys([], own);
+      }
+      return partitionedPrefix + composeCacheKeys(keys, [...generated, ...own]);
     });
   }
 

package/src/cache/cf/cf-cache-types.ts

@@ -419,19 +419,23 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
   /**
    * Custom key generator applied to all cache operations.
    * Receives the full RequestContext (including env) and the default-generated key.
-   * Return value becomes the final cache key (unless route overrides with `key` option).
+   * The return value is the cache key (unless route overrides with `key`
+   * option), except that a route record keeps its request kind: a result that
+   * does not start with `defaultKey`'s prefix (`doc:`, `partial:`,
+   * `intercept:<intercept>:`) gets the kind appended (see
+   * SegmentCacheStore.keyGenerator).
    *
    * Reserved prefixes: tag-invalidation markers live in the SAME KV namespace as
    * data, keyed `__tag__/<tag>` (and `__tagmarker__/<tag>` for the L1 cache). A
    * returned key must NOT begin with `__tag__/` or `__tagmarker__/`, or it can
    * collide with a tag marker and corrupt invalidation. The documented
-   * prepend-style generators below are safe.
+   * generators below start with `defaultKey` and are safe.
    *
    * @example Using headers for user segmentation
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
    *   const segment = ctx.request.headers.get('x-user-segment') || 'default';
-   *   return `${segment}:${defaultKey}`;
+   *   return `${defaultKey}|${segment}`;
    * }
    * ```
    *
@@ -439,7 +443,7 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
    *   const region = ctx.env.REGION || 'us';
-   *   return `${region}:${defaultKey}`;
+   *   return `${defaultKey}|${region}`;
    * }
    * ```
    *
@@ -447,7 +451,7 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
    *   const locale = cookies().get('locale')?.value || 'en';
-   *   return `${locale}:${defaultKey}`;
+   *   return `${defaultKey}|${locale}`;
    * }
    * ```
    */

package/src/cache/document-cache-policy.ts

@@ -69,7 +69,11 @@ export function shouldCacheResponse(
   response: Response,
   requestCtx?: Pick<
     RequestContext,
-    "_payloadVisitorTheme" | "_payloadDeferred" | "_payloadVisitorLocation"
+    | "_payloadVisitorTheme"
+    | "_payloadDeferred"
+    | "_payloadSourceScoped"
+    | "_payloadVisitorLocation"
+    | "_documentLocationState"
   >,
 ): CacheDirectives | null {
   // Only cache successful responses
@@ -100,6 +104,12 @@ export function shouldCacheResponse(
     return null;
   }
 
+  // The payload carries the visitor's location state (#1330,
+  // server/document-location-state.ts).
+  if (requestCtx?._documentLocationState) {
+    return null;
+  }
+
   // prefetch: false. The payload carries deferred units: it answers one
   // page's prefetch and nothing else. parseCacheControl refuses the
   // Cache-Control it is sent with (rsc-rendering.ts NOT_REUSED), but a
@@ -109,10 +119,36 @@ export function shouldCacheResponse(
     return null;
   }
 
+  // A partial scoped to its source page: this cache keys it by
+  // URL and the ids the client holds, so it would answer another page with
+  // the same ids. rsc-rendering.ts sends it NOT_REUSED; a middleware can
+  // replace that after next().
+  if (requestCtx?._payloadSourceScoped) {
+    return null;
+  }
+
   const cacheControl = response.headers.get("Cache-Control");
   return parseCacheControl(cacheControl);
 }
 
+/**
+ * Whether a response carries one client's state, which a stored copy would
+ * replay to that client's later requests: a per-client signal header (a state
+ * cookie rotation, `x-rango-keep-cache`) or location state. The stored
+ * prefetch Cache-Control (rsc/request-stages.ts) is not sent on
+ * one.
+ */
+export function carriesClientState(
+  response: Response,
+  requestCtx: Pick<RequestContext, "_locationState" | "_documentLocationState">,
+): boolean {
+  return (
+    hasPerClientSignal(response.headers) ||
+    (requestCtx._locationState?.length ?? 0) > 0 ||
+    requestCtx._documentLocationState === true
+  );
+}
+
 /**
  * Whether this cache will store the response the current render produces, as
  * far as the render can tell: the middleware runs it (a MISS or a stale

package/src/cache/document-cache.ts

@@ -276,6 +276,13 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       return next();
     }
 
+    // Location state is already set for this request (a document redirect's
+    // cookie, an earlier middleware): the response is the visitor's, so a
+    // stored body must not answer it, and it is not stored.
+    if ((requestCtx._locationState?.length ?? 0) > 0) {
+      return next();
+    }
+
     // The write gate's start (#977) and the entry's stamp (#1068): the
     // request's, not this middleware's, also for a stale refresh. A
     // middleware ahead of this one can read tagged data the document bakes,
@@ -350,6 +357,11 @@ export function createDocumentCacheMiddleware<TEnv = any>(
         if (!cached.shouldRevalidate) {
           // Fresh hit - return immediately
           log(`[DocumentCache] HIT ${typeLabel}: ${url.pathname}`);
+          // Nothing in it runs: its loaders' output is replayed, and no
+          // failed render is ever stored (throwIfRenderErrored). A prefetch
+          // answered with it leaves with the router's prefetch Cache-Control
+          // (rsc/request-stages.ts).
+          requestCtx._servedFromStorage = true;
           return drainOnResponseCallbacks(
             addCacheStatusHeader(cached.response, "HIT"),
             requestCtx,

package/src/cache/memory-segment-store.ts

@@ -120,13 +120,14 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
 
   /**
    * Custom key generator applied to all cache operations.
-   * Receives the full RequestContext and the default-generated key.
+   * Receives the full RequestContext and the default-generated key. A route
+   * record keeps its request kind (see SegmentCacheStore.keyGenerator).
    *
    * @example
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
    *   const locale = cookies().get('locale')?.value || 'en';
-   *   return `${locale}:${defaultKey}`;
+   *   return `${defaultKey}|${locale}`;
    * }
    * ```
    */

package/src/cache/segment-codec.ts

@@ -309,8 +309,8 @@ export async function serializeSegments(
  * cached with the route record).
  *
  * The loading "null" sentinel decodes here (not on the consumer): loading:null
- * must survive as null, and shipping the raw sentinel would change the
- * deduplicateLoaderSegments loading-presence check.
+ * must survive as null, and shipping the raw sentinel would hand renderSegments
+ * a truthy `loading`, the fallback tree shape (docs/tree-structure.md).
  */
 export async function fragmentSegments(
   data: SerializedSegmentData[],

package/src/cache/shell-snapshot.ts

@@ -407,7 +407,7 @@ const PIN_KEY_PREFIX = /^[^D.]*D\d+\./;
  * Deserializations run in parallel; a record that fails to decode is skipped
  * and reported to `onUndecodable`: its loader runs instead, which a document
  * HIT has already committed a prelude against, so serveShellHit retires the
- * entry (dc-t89). Returns undefined when the snapshot carries no loader
+ * entry. Returns undefined when the snapshot carries no loader
  * records, without touching the Flight codec (kept lazy for cold paths and
  * non-RSC configs).
  */

package/src/cache/types.ts

@@ -93,16 +93,21 @@ export interface SegmentCacheStore<TEnv = unknown> {
   /**
    * Custom key generator applied to all cache operations using this store.
    * Receives the full RequestContext and the default-generated key.
-   * Return value becomes the final cache key (unless route overrides with `key` option).
+   * The return value is the cache key (unless route overrides with `key`
+   * option), with a route record's request kind appended when it does not
+   * start with that kind (below).
    *
    * Resolution priority:
    * 1. Route-level `key` function (replaces the URL part; the request kind stays)
    * 2. Store-level `keyGenerator` (modifies default key)
    * 3. Default key generation (prefix:pathname:params)
    *
-   * Keep `defaultKey` in the result: its prefix names the request kind (a
-   * document, a navigation or an intercept navigation), whose records hold
-   * different segments. A result without it gives every kind one record.
+   * A route record keeps its request kind (a document, a navigation or an
+   * intercept navigation), whose records hold different segments: the kind
+   * is `defaultKey`'s prefix (`doc:`, `partial:`, `intercept:<intercept>:`),
+   * and a result that does not start with it gets the kind appended as a
+   * key part of its own. Build on `defaultKey` (`${defaultKey}|${segment}`)
+   * and the result is the record key byte for byte.
    *
    * Return `defaultKey` unchanged to leave a request unpartitioned. An empty
    * string is not a key: where the result partitions a nested cache() on
@@ -114,7 +119,7 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
    *   const segment = ctx.request.headers.get('x-user-segment') || 'default';
-   *   return `${segment}:${defaultKey}`;
+   *   return `${defaultKey}|${segment}`;
    * }
    * ```
    *
@@ -122,7 +127,7 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
    *   const region = ctx.env.REGION || 'us';
-   *   return `${region}:${defaultKey}`;
+   *   return `${defaultKey}|${region}`;
    * }
    * ```
    *
@@ -130,7 +135,7 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
    *   const locale = cookies().get('locale')?.value || 'en';
-   *   return `${locale}:${defaultKey}`;
+   *   return `${defaultKey}|${locale}`;
    * }
    * ```
    */

package/src/cache/vercel/vercel-cache-store.ts

@@ -356,7 +356,8 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
 
   /**
    * Custom key generator applied to all cache operations (region/locale/user
-   * segmentation). Receives the request context and the default key.
+   * segmentation). Receives the request context and the default key. A route
+   * record keeps its request kind (see SegmentCacheStore.keyGenerator).
    */
   keyGenerator?: (
     ctx: RequestContext<TEnv>,

package/src/client-urls/types.ts

@@ -85,8 +85,9 @@ export interface ClientUrlLoaderRecord {
    */
   readonly ssr?: false;
   /**
-   * loader(Def, { prefetch: false }): a prefetch of the route, or of an
-   * intercept's target from its source, defers this loader and the click
+   * loader(Def, { prefetch: false }): a viewport or render prefetch of the
+   * route, or of an intercept's target from its source, defers this loader
+   * (a hover prefetch runs it) and the click
    * that adopts it runs it in its fill request (see {@link LoaderOptions}).
    * Projected onto the materialized stub.
    */
@@ -169,12 +170,13 @@ export interface ClientUrlHelpers {
    * holes).
    *
    * Pass `{ prefetch: false }` to keep this loader out of the route's
-   * prefetches (see {@link LoaderOptions}): an in-group click still shows
+   * viewport and render prefetches; a hover prefetch runs it (see
+   * {@link LoaderOptions}). An in-group click still shows
    * the destination at once, commits the adopted prefetch with the other
    * loaders' data, and runs only the flagged loaders in its one fill
    * request. A `layout()` loader with the flag is flagged on every route
-   * below it. Inside intercept() it defers the loader in a prefetch of the
-   * intercept from its source, as in urls().
+   * below it. Inside intercept() it defers the loader in a viewport or
+   * render prefetch of the intercept from its source, as in urls().
    */
   readonly loader: <TData>(
     definition: LoaderDefinition<TData>,

package/src/prefetch-markers.ts

@@ -9,6 +9,16 @@
 /** Request header of a `<Link>` prefetch (browser/prefetch/fetch.ts). */
 export const PREFETCH_HEADER = "X-Rango-Prefetch";
 
+/**
+ * PREFETCH_HEADER's value on an intent prefetch: a hover or an explicit
+ * `prefetch()` call (browser/prefetch/fetch.ts prefetchDirect). The server
+ * defers nothing in it: `prefetch: false` loaders and the work behind a
+ * flagged `loading()` run, as in the navigation it starts early. A
+ * speculative prefetch (viewport, render) sends `1`, and any value other than
+ * this one reads as speculative.
+ */
+export const PREFETCH_INTENT = "intent";
+
 /**
  * The last row of a prefetch whose render reported an error
  * (rsc/prefetch-render-error.ts): a Flight hint with a code React does not

package/src/prefetch-source-scope.ts

@@ -0,0 +1,137 @@
+/**
+ * The source group of a prefetch answer a revalidate() rule kept from the
+ * page being left (#1331). Shared by the server, which reports
+ * the group in `x-rsc-prefetch-scope: params; <label>` (rsc/rsc-rendering.ts),
+ * and the browser, which stores the answer under that label and rebuilds it
+ * from the page on screen to look it up (browser/prefetch/cache.ts).
+ * Dependency free, like prefetch-markers.ts: the browser must not import the
+ * server modules that record the reads (router/source-reads.ts).
+ *
+ * Why a label is enough: a rule's decision depends on the source page only
+ * through what it read. Two pages with equal values of everything the kept
+ * rules read run every rule the same way, so one answer serves both.
+ */
+
+/** What the revalidate() rules that kept a segment read of the source page. */
+export interface SourceReads {
+  /**
+   * `currentParams` was read. Its key set is then part of the group: a rule
+   * can test a key's presence (`in`, `Object.keys`) without reading a value.
+   */
+  keys: boolean;
+  /**
+   * Each `currentParams` value read; a spread or JSON.stringify reads all.
+   * Non-empty only with `keys`: a value is read through `currentParams`.
+   */
+  params: Set<string>;
+  /** `fromRouteName` was read. */
+  route: boolean;
+  /** `currentUrl` was read: the answer is the exact page's. */
+  url: boolean;
+}
+
+/** The page a label describes: the source on the server, the screen in the browser. */
+export interface SourcePage {
+  params: Readonly<Record<string, string | undefined>>;
+  /** The public route name (route-name.ts publicRouteName). */
+  routeName: string | undefined;
+}
+
+/** What a label reads, without the values: one per kind of rule set. */
+export interface SourceShape {
+  keys: boolean;
+  route: boolean;
+  /** Sorted. */
+  names: readonly string[];
+}
+
+/** `x-rsc-prefetch-scope` value prefix of a params-grouped answer. */
+export const PARAMS_SCOPE_PREFIX = "params; ";
+
+export function createSourceReads(): SourceReads {
+  return { keys: false, params: new Set(), route: false, url: false };
+}
+
+export function hasSourceReads(reads: SourceReads): boolean {
+  return reads.keys || reads.route || reads.url || reads.params.size > 0;
+}
+
+/** Union `from` into `into`. */
+export function mergeSourceReads(into: SourceReads, from: SourceReads): void {
+  into.keys ||= from.keys;
+  into.route ||= from.route;
+  into.url ||= from.url;
+  for (const name of from.params) into.params.add(name);
+}
+
+export function shapeOfReads(reads: SourceReads): SourceShape {
+  return {
+    keys: reads.keys,
+    route: reads.route,
+    names: [...reads.params].sort(),
+  };
+}
+
+/**
+ * The label of `page` under `shape`: `&`-joined, `$k=<keys>` first, then
+ * `$r[=<route>]`, then `<name>[=<value>]` per read param, sorted. A missing
+ * value has no `=`. Names and values are URI-encoded, so a `$` entry never
+ * collides with a param (encodeURIComponent encodes `$`).
+ */
+export function formatSourceLabel(
+  shape: SourceShape,
+  page: SourcePage,
+): string {
+  const parts: string[] = [];
+  if (shape.keys) {
+    parts.push(
+      "$k=" + Object.keys(page.params).sort().map(encodeURIComponent).join(","),
+    );
+  }
+  if (shape.route) parts.push(entry("$r", page.routeName));
+  for (const name of shape.names) {
+    parts.push(entry(encodeURIComponent(name), page.params[name]));
+  }
+  return parts.join("&");
+}
+
+function entry(name: string, value: string | undefined): string {
+  return value === undefined ? name : name + "=" + encodeURIComponent(value);
+}
+
+/**
+ * The label of an `x-rsc-prefetch-scope` value, or undefined when the value
+ * is not a params scope.
+ */
+export function paramsScopeLabel(
+  header: string | null | undefined,
+): string | undefined {
+  if (!header?.startsWith(PARAMS_SCOPE_PREFIX)) return undefined;
+  return header.slice(PARAMS_SCOPE_PREFIX.length);
+}
+
+/** The shape of a label formatSourceLabel wrote. */
+export function parseSourceShape(label: string): SourceShape {
+  let keys = false;
+  let route = false;
+  const names: string[] = [];
+  for (const part of label.split("&")) {
+    if (part === "") continue;
+    const eq = part.indexOf("=");
+    const name = eq === -1 ? part : part.slice(0, eq);
+    if (name === "$k") keys = true;
+    else if (name === "$r") route = true;
+    else names.push(decodeURIComponent(name));
+  }
+  return { keys, route, names: names.sort() };
+}
+
+/** A stable id of a shape, for indexing. */
+export function sourceShapeId(shape: SourceShape): string {
+  return (
+    (shape.keys ? "k" : "") +
+    (shape.route ? "r" : "") +
+    ":" +
+    shape.names.map(encodeURIComponent).join(",")
+  );
+}

package/src/route-definition/helpers-types.ts

@@ -333,9 +333,10 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * loader(RecommendationsLoader),  // still streams behind loading()
    * ```
    *
-   * Pass `{ prefetch: false }` to keep the loader out of prefetches: a
-   * prefetch skips it and the click that adopts the prefetch fetches it in
-   * one follow-up request (see {@link LoaderOptions}). Only on a segment the
+   * Pass `{ prefetch: false }` to keep the loader out of speculative
+   * prefetches (viewport, render): such a prefetch skips it and the click
+   * that adopts it fetches it in one follow-up request; a hover prefetch runs
+   * it (see {@link LoaderOptions}). Only on a segment the
    * client does not have yet: a loader the client already holds runs in the
    * prefetch when it revalidates.
    *
@@ -361,14 +362,16 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * // Skip loading on SSR, only show on client navigation
    * loading(<Skeleton />, { ssr: false })
    *
-   * // Keep everything behind this fallback out of prefetches
+   * // Keep everything behind this fallback out of viewport and render
+   * // prefetches (a hover prefetch runs it)
    * loading(<Skeleton />, { prefetch: false })
    * ```
    * @param component - The loading UI to show during navigation
    * @param options - Configuration options
    * @param options.ssr - If false, skip showing loading on document requests (SSR)
    * @param options.prefetch - If false, the flag applies when this entry's
-   *   segment is new to the client. A prefetch then skips the whole unit: the
+   *   segment is new to the client. A viewport or render prefetch then skips
+   *   the whole unit (a hover prefetch runs it): the
    *   handler, its loaders, its orphan layouts and parallel slots and, for a
    *   layout, every deeper entry; the click that adopts the prefetch shows
    *   this fallback and fetches them in one follow-up request, which reads

package/src/route-definition/redirect.ts

@@ -20,6 +20,11 @@ import { prefixBasename } from "../router/basename.js";
  * Supports an optional state parameter to carry location state through the
  * redirect. On the target page, state can be read via useLocationState()
  * (use { flash: true } in createLocationState for read-once flash messages).
+ * On a client navigation or action the state travels in the redirect's
+ * payload. On a document request (a page load, a no-JS form post) it travels
+ * in a one-shot cookie the target's document request reads and clears, as
+ * JSON: give it plain JSON data there. `{ external: true }` carries none.
+ * Two entries of the same definition keep only the last.
  *
  * @param url - The URL to redirect to
  * @param statusOrOptions - HTTP status code (default: 302) or options object