@rangojs/router 0.24.4 → 0.26.0

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

@@ -422,6 +422,7 @@ function shellHeadToEntry(head: ShellFrameHead): ShellEntryHead {
     reactVersion: head.rv,
     buildVersion: head.bv,
     initialTheme: head.i,
+    pathname: head.lp,
     docKey: head.dk,
     prunedRecords: head.pr,
     navigationOnly: head.no,
@@ -499,8 +500,6 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private readonly namespace?: string;
   private readonly explicitBaseUrl?: string;
   private readonly waitUntil?: (fn: () => Promise<void>) => void;
-  /** The `version` option: used for every versioned family when set. */
-  private readonly explicitVersion?: string;
   private readonly edgeLookupTimeoutMs: number;
   private readonly edgeReadTimeoutMs: number;
   private readonly kvReadTimeoutMs: number;
@@ -553,7 +552,6 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // the internal host. Only the explicit override can be captured eagerly.
     this.explicitBaseUrl = options.baseUrl;
     this.defaults = options.defaults;
-    this.explicitVersion = options.version;
     // Coalesce only finite numbers to the override; a non-finite value (NaN from
     // `Number(env.UNSET)`, or Infinity) would otherwise sail past `?? DEFAULT`
     // (which only replaces null/undefined) into setTimeout, where NaN/Infinity
@@ -1627,8 +1625,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // stamp). Carried on doc L1 entries for the herd guard; never serve them.
     headers.delete(CACHE_EXPIRES_AT_HEADER);
     headers.delete(CACHE_REVALIDATING_AT_HEADER);
-    // Finding #3 (read side): strip per-client signals a pre-fix or
-    // pinned-version L1 entry may carry. See the read-side note in the design doc.
+    // Finding #3 (read side): strip per-client signals a pre-fix L1 entry
+    // may carry. See the read-side note in the design doc.
     stripPerClientSignals(headers);
     return new Response(response.body, {
       status: response.status,
@@ -2695,6 +2693,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           t: tags,
           ta: taggedAt,
           i: entry.initialTheme,
+          lp: entry.pathname,
           dk: entry.docKey,
           pr: entry.prunedRecords,
           no: entry.navigationOnly,
@@ -2950,7 +2949,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private keyToRequest(key: string, family: KeyVersion): Request {
     const encodedKey = encodeURIComponent(key);
     return new Request(
-      `${this.resolveBaseUrl()}${versionKeyPrefix(this.explicitVersion, family)}${encodedKey}`,
+      `${this.resolveBaseUrl()}${versionKeyPrefix(family)}${encodedKey}`,
       { method: "GET" },
     );
   }
@@ -2974,7 +2973,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * @internal
    */
   private async toKVKey(key: string, family: KeyVersion): Promise<string> {
-    const composed = `${versionKeyPrefix(this.explicitVersion, family)}${key}`;
+    const composed = `${versionKeyPrefix(family)}${key}`;
     if (kvKeyByteLength(composed) <= KV_MAX_KEY_BYTES) return composed;
     const prefix = truncateToBytes(composed, KV_KEY_PRESERVED_PREFIX_BYTES);
     return `${prefix}~${await kvKeyDigest(composed)}`;

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

@@ -322,23 +322,6 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    */
   tagCacheTtl?: number;
 
-  /**
-   * Cache version string override. When set, this exact value prefixes every
-   * versioned key the store writes (`v/{version}/...`), for cached data and
-   * stored HTML alike; changing it makes every earlier entry unreachable.
-   *
-   * Leave it unset for the default: the store keys with the versions of the
-   * router serving the request. Segment entries and `"use cache"` items use
-   * the router's data version; document responses and PPR shells use its
-   * document version (see `createRouter({ version })`). Those are computed
-   * from the router's built code, so a deploy that does not change the router
-   * keeps its entries.
-   *
-   * Tag invalidation markers are never versioned: an invalidation applies to
-   * the entries of every version, including one that comes back in a rollback.
-   */
-  version?: string;
-
   /**
    * Latency budget (ms) for an L1 edge cache (CF Cache API) read. A `match`
    * slower than this is abandoned and treated as a miss, so a degraded colo

package/src/cache/cf/cf-shell-frame.ts

@@ -47,6 +47,8 @@ export interface ShellFrameHead {
   ta?: number;
   /** ShellCacheEntry.initialTheme */
   i?: string;
+  /** ShellCacheEntry.pathname (a visitor-keyed shell's rendered location). */
+  lp?: string;
   /** ShellCacheEntry.docKey; navigation replay needs it after any round trip. */
   dk?: string;
   /** ShellCacheEntry.prunedRecords (diagnostic). */
@@ -79,6 +81,7 @@ function isShellFrameHead(value: unknown): value is ShellFrameHead {
         head.t.every((tag) => typeof tag === "string"))) &&
     (head.ta === undefined || isFiniteNumber(head.ta)) &&
     (head.i === undefined || typeof head.i === "string") &&
+    (head.lp === undefined || typeof head.lp === "string") &&
     (head.dk === undefined || typeof head.dk === "string") &&
     (head.pr === undefined || typeof head.pr === "string") &&
     (head.no === undefined || head.no === true) &&

package/src/cache/handle-snapshot.ts

@@ -177,8 +177,8 @@ export type OwnedPushDelivery = (loaderId: string) => RecordAuthority;
  * says the record supplies that loader's value too ("pin", "copies"), and is
  * a placeholder (pushPlaceholder) everywhere else: without `owned`, every
  * owner. Neither claims its loader, so the loader's own cache() HIT still
- * delivers (the thenable pushes a restored copy lets through, or its entry's
- * pushes in a placeholder's place).
+ * delivers (the pushes holding a promise a restored copy lets through, or its
+ * entry's pushes in a placeholder's place).
  */
 export function restoreHandles(
   handles: Record<string, SegmentHandleData>,

package/src/cache/types.ts

@@ -445,7 +445,7 @@ export interface ShellCacheEntry {
   /** React.version captured at prerender time; the read-time invalidation gate. */
   reactVersion: string;
   /**
-   * Build version captured at prerender time: the RSC handler's `version`,
+   * Build version captured at prerender time: the RSC handler's version,
    * which is the router's DOCUMENT version (router-versions.ts) — a hash of
    * its server code and the client asset names by default, a stamp bumped on
    * dev RSC-module edits. The second read-time gate: a persistent shared
@@ -468,6 +468,14 @@ export interface ShellCacheEntry {
    * ThemeProvider.
    */
   initialTheme?: string;
+  /**
+   * The payload pathname of a shell keyed by the visitor's URL
+   * (`rewrite(...).shell("visitor")`, visitorShellKey); absent when the
+   * capture rendered its key's own URL. The serve tail replays it as it does
+   * `initialTheme`, and the serve gate serves the entry only to a request
+   * that renders this location.
+   */
+  pathname?: string;
   /**
    * The CAPTURE DATA SNAPSHOT, in stored/serialized form: the doc segment
    * record every HIT replays the handler layer from (`docKey`) and the
@@ -678,11 +686,13 @@ export interface ShellSnapshotLoaderValue {
    */
   holes: 0 | 1;
   /**
-   * 1 when the capture saw a loader push it could not record (a deferred
-   * push, one with masked nested promises, or one made outside any loader
-   * body): a HIT then still runs the loader body in the background
-   * (pin-first) so those pushes reach the page. 0: a hole-free record is
-   * served from the pin alone and its body does not run on a HIT.
+   * 1 when the capture saw a loader push it could not record (one whose
+   * settled value holds masked nested promises, one a live-lane loader made,
+   * or one made outside any loader body): a HIT then still runs the loader
+   * body in the background (pin-first) so those pushes reach the page. A
+   * pushed promise that settles thenable-free is recorded (#1182).
+   * 0: a hole-free record is served from the pin alone and its body does not
+   * run on a HIT.
    *
    * Both bits are always written. A record stored before they existed (v0.17)
    * reads each missing bit as 1 (buildShellLoaderSeed): its snapshot lacks

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

@@ -271,6 +271,8 @@ interface VercelShellEnvelope {
   t?: string[];
   /** initialTheme the capture render was built with (resume theme fidelity). */
   i?: string;
+  /** ShellCacheEntry.pathname (a visitor-keyed shell's rendered location). */
+  lp?: string;
   /** Capture data snapshot (ShellCacheEntry.snapshot). */
   sn: ShellSnapshotRecord[];
   /**
@@ -328,7 +330,7 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
    *
    * Vercel does not reconcile entries between deployments; the store does it
    * through its keys, which carry the serving router's cache versions (see
-   * `version`). So a deploy that changes a router's code stops reading that
+   * `getCacheVersions`). So a deploy that changes a router's code stops reading that
    * router's old entries, and a deploy that does not keeps them. A namespace
    * that changes per deployment (`getCache({ namespace: VERCEL_DEPLOYMENT_ID })`)
    * still works and clears the cache on every deploy, which is what you want
@@ -361,19 +363,6 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
     defaultKey: string,
   ) => string | Promise<string>;
 
-  /**
-   * Version override, folded into every versioned key as `v/{version}/...`.
-   * When set, this exact value is used for cached data and stored HTML alike;
-   * changing it makes everything this store wrote before unreachable.
-   *
-   * Leave it unset for the default: the store keys with the versions of the
-   * router serving the request, as CFCacheStore does. Segments and `"use
-   * cache"` items use the router's data version; responses and PPR shells use
-   * its document version (see `createRouter({ version })`). Tag markers are
-   * never versioned, so an invalidation applies to every version.
-   */
-  version?: string;
-
   /**
    * Max serialized entry size in bytes before a write is skipped. Defaults to
    * VERCEL_MAX_ITEM_BYTES (2 MB - the platform's hard cap).
@@ -535,8 +524,6 @@ export class VercelCacheStore<
 
   private readonly cache: VercelRuntimeCache;
   private readonly waitUntil?: (promise: Promise<unknown>) => void;
-  /** The `version` option: used for every versioned family when set. */
-  private readonly explicitVersion?: string;
   private readonly maxItemBytes: number;
   private readonly memo: ResolvedShellMemoOptions;
   private readonly handleMemos: VercelHandleMemos;
@@ -561,7 +548,6 @@ export class VercelCacheStore<
     this.waitUntil = options.waitUntil;
     this.defaults = options.defaults;
     this.keyGenerator = options.keyGenerator;
-    this.explicitVersion = options.version;
     this.maxItemBytes = options.maxItemBytes ?? VERCEL_MAX_ITEM_BYTES;
     this.maxShellEntryBytes = Math.floor((this.maxItemBytes * 3) / 4);
     this.memo = resolveShellMemoOptions(options.memo, {
@@ -1158,6 +1144,7 @@ export class VercelCacheStore<
       reactVersion: env.rv,
       buildVersion: env.bv,
       initialTheme: env.i,
+      pathname: env.lp,
       snapshot: env.sn,
       docKey: env.dk,
       prunedRecords: env.pr,
@@ -1326,6 +1313,7 @@ export class VercelCacheStore<
         e: Math.min(expiresAt, now + retentionTtl * 1000),
         t: safeTags.length > 0 ? safeTags : undefined,
         i: entry.initialTheme,
+        lp: entry.pathname,
         sn: entry.snapshot,
         dk: entry.docKey,
         pr: entry.prunedRecords,
@@ -1512,7 +1500,7 @@ export class VercelCacheStore<
   // cross-family one reads as corrupt. See the class doc for passing a wider
   // hash (sha256) when many keys are live.
   private toStoreKey(key: string, family: CacheFamily): string {
-    return `${versionKeyPrefix(this.explicitVersion, FAMILY_VERSION[family])}rg:${family}:${key}`;
+    return `${versionKeyPrefix(FAMILY_VERSION[family])}rg:${family}:${key}`;
   }
 
   private async write(
@@ -1743,7 +1731,7 @@ export class VercelCacheStore<
 
   private asShellEnvelope(raw: unknown): VercelShellEnvelope | null {
     if (!isRecord(raw)) return null;
-    const { p, po, rv, bv, c, s, e, t, i, sn, dk, pr, no } = raw;
+    const { p, po, rv, bv, c, s, e, t, i, lp, sn, dk, pr, no } = raw;
     if (typeof rv !== "string" || typeof bv !== "string") return null;
     // Document half: required unless navigationOnly (`no`), which stores
     // neither field. Tolerate a legacy navigationOnly envelope that still
@@ -1766,6 +1754,7 @@ export class VercelCacheStore<
       e,
       t: Array.isArray(t) ? (t as string[]) : undefined,
       i: typeof i === "string" ? i : undefined,
+      lp: typeof lp === "string" ? lp : undefined,
       // A non-array field reads as no records.
       sn: Array.isArray(sn) ? (sn as ShellSnapshotRecord[]) : [],
       dk: typeof dk === "string" ? dk : undefined,