@rangojs/router 0.19.1 → 0.21.0

package/dist/types/cache/shell-snapshot.d.ts

@@ -18,7 +18,9 @@
  * the capture's copy of a value: it is dynamic or has its own cache. A
  * bake-lane loader body that runs on a HIT reads the store too; its pinned
  * container paths stay the pin's (overlayLoaderContainer), and its settled
- * pushes stay the record's (HandleStore.pushRestored).
+ * pushes stay the record's (HandleStore.pushRestored). The two go together:
+ * a loader whose pin the entry lost runs fresh, and the record's copies of
+ * its pushes give way to that run's (restoreHandles).
  */
 import type { SegmentCacheStore, CacheGetResult, CacheItemResult, CacheItemOptions, CachedEntryData, ShellCacheEntry, ShellSnapshotRecord, CacheReadError } from "./types.js";
 /**
@@ -172,16 +174,30 @@ export interface ShellLoaderSeedEntry {
      * hole-free record: a hole-carrying one always runs.
      */
     runs: boolean;
+    /**
+     * The capture that wrote the pin recorded every settled push of the
+     * loader's run in the doc record (CachedEntryData.handleOwners): the pin
+     * carries the `runs` bit, which captures write since they record those
+     * pushes (v0.18). A replay then drops any other settled push of the loader
+     * (HandleStore RecordAuthority "pin"). False for an older pin, whose record
+     * may hold none and leaves them to the run.
+     */
+    complete: boolean;
 }
 /**
  * Materialize the loader-family seed from a shell snapshot for a HIT's tail
  * render: Flight-deserialize each recorded (promise-elided) bake-lane
- * container into a segment-key -> container Map, which serveShellHit assigns
- * to the tail context's `_shellLoaderSeed` for the resolveLoaderData overlay.
+ * container into a loader-id -> pin Map, which serveShellHit assigns to the
+ * tail context's `_shellLoaderSeed` (loader-cache.ts servedPins).
  * Lives here so every snapshot family is decoded in this module (the segment
  * family via {@link SeededShellStore}); the loader family is not a store
  * read, so it seeds the context instead of a store.
  *
+ * Keyed by loader, not by the segment a pin was stored under: a loader runs
+ * once per capture, so every segment that registers it pinned the same
+ * container, and the loader's value and its handle pushes are both looked up
+ * by loader. A key that does not parse pins nothing.
+ *
  * Deserializations run in parallel; a record that fails to decode is skipped
  * (that loader drifts — the pre-snapshot behavior — instead of failing the
  * HIT). Returns undefined when the snapshot carries no loader records, without

package/dist/types/cache/types.d.ts

@@ -43,6 +43,13 @@ export interface CacheGetResult {
  * The store deals with serialized data - RSC serialization is handled
  * by the cache provider layer.
  *
+ * A store that outlives the process has to keep one build from reading what
+ * other code wrote. The built-in stores prefix their keys with the serving
+ * router's cache versions; a custom store reads the same pair with
+ * `getCacheVersions()` (`@rangojs/router/cache`): `data` for segment entries
+ * and items, `document` for responses and shells, and no version on its
+ * tag-invalidation records, so an invalidation reaches every version.
+ *
  * @typeParam TEnv - Platform bindings type (e.g., Cloudflare env)
  */
 export interface SegmentCacheStore<TEnv = unknown> {
@@ -361,13 +368,14 @@ 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` —
-     * the `@rangojs/router:version` build stamp by default, bumped per build and
-     * on dev RSC-module edits). The second read-time gate: a persistent shared
+     * 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
      * store (KV/runtime-cache) survives deploys, and an app-code change that
      * keeps the same React version would otherwise leave a stale-build
-     * prelude+postponed live under the same key. A custom store returns it as
-     * putShell received it.
+     * prelude+postponed live under the same key. A deploy that changes neither
+     * keeps the entry. A custom store returns it as putShell received it.
      */
     buildVersion: string;
     /**
@@ -696,10 +704,13 @@ export type SegmentHandleData = Record<string, unknown[]>;
  * index (null: not owned). Only a PPR shell capture writes owners: the
  * settled pushes of the loader bodies it ran (an `ssr: false` loader's own,
  * the loaders it awaits, and its own cache() replays), which the record keeps
- * because the prelude rendered them. A document HIT restores a bake-lane
- * owner's value through HandleStore.pushRestored, and it stands against a run
- * of its loader there; a live-lane owner's (a hole), and every owner's on
- * any other replay of the record (a client navigation), go through
- * pushReplayed, so a run of the loader replaces it with its live push.
+ * because the prelude rendered them. A restore of the record
+ * (handle-snapshot.ts restoreHandles) keeps an owner's value where the
+ * request serves that loader from the pin stored with the record
+ * (HandleStore.pushRestored: it stands against a run of the loader), on a
+ * document HIT and on a navigation replay alike. Every other owner's value
+ * is a placeholder (pushPlaceholder): a live-lane loader's, and every
+ * owner's where the record has no pin for it. The loader's run, or its own
+ * cache() entry, replaces it.
  */
 export type HandleOwners = Record<string, Record<string, (string | null)[]>>;

package/dist/types/cache/vercel/vercel-cache-store.d.ts

@@ -23,7 +23,8 @@
  *   3. The platform guardrails: the 2 MB per-item ceiling (oversized writes
  *      silently no-op on Vercel, so we skip + report), the per-item tag cap, and
  *      cross-deploy non-reconciliation (TTL/tag updates are not reconciled across
- *      deployments - bake a build id into `version` or the getCache namespace).
+ *      deployments - every key carries the serving router's cache version, see
+ *      toStoreKey).
  *
  * Dependency stance: this module imports NOTHING from `@vercel/functions`. The
  * runtime cache handle (and `waitUntil`) are injected through the constructor and
@@ -92,14 +93,20 @@ export type VercelCacheDebug = boolean | ((event: VercelCacheReadDebugEvent) =>
 export interface VercelCacheStoreOptions<TEnv = unknown> {
     /**
      * The Vercel Runtime Cache handle - `getCache()` from `@vercel/functions`.
-     * Required. Construct it with a build-hash namespace to bust stale-shaped
-     * entries across deployments, since Vercel does not reconcile TTL/tags between
-     * deploys:
+     * Required.
      *
      * ```ts
      * import { getCache } from "@vercel/functions";
-     * new VercelCacheStore({ cache: getCache({ namespace: BUILD_ID }) });
+     * new VercelCacheStore({ cache: getCache() });
      * ```
+     *
+     * 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
+     * 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
+     * only if you need that.
      */
     cache: VercelRuntimeCache;
     /**
@@ -122,9 +129,15 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
      */
     keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
     /**
-     * Build/version id folded into every stored key as `v/{version}/...`. A second
-     * cross-deploy busting layer in addition to (or instead of) the getCache
-     * namespace. Changing it invalidates everything this store wrote previously.
+     * 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;
     /**
@@ -181,8 +194,8 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
  * that propagates expireTag rejections does get the strict guarantee, which is
  * what the unit suite exercises.)
  *
- * Key hashing / family isolation. The store namespaces its three value tiers as
- * `rg:{s|i|r}:{key}` so segment, `"use cache"`, and response entries occupy
+ * Key hashing / family isolation. The store namespaces its value tiers as
+ * `rg:{s|i|r|h}:{key}` so segment, `"use cache"`, response and shell entries occupy
  * disjoint keyspaces. That separation is only as strong as the cache's
  * `keyHashFunction`: `getCache`'s default is djb2, which folds every key to 32
  * bits (8 hex chars), so at a large live-key count a collision can let one
@@ -198,11 +211,9 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
  *
  * // One handle per process: getCache() resolves the platform cache on every
  * // call, and the PPR shell and tag-marker memos are kept per handle.
- * // `process.env` (not `import.meta.env`, which needs a VITE_ prefix and
- * // would be undefined here) so cross-deploy busting via `version` works.
- * const runtimeCache = getCache({
- *   namespace: process.env.VERCEL_DEPLOYMENT_ID,
- * });
+ * // No deployment id in the namespace: the store's keys carry the serving
+ * // router's cache versions, so a deploy keeps what its code did not change.
+ * const runtimeCache = getCache();
  *
  * export const router = createRouter({
  *   cache: () => ({
@@ -221,7 +232,8 @@ export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheSto
     readonly keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
     private readonly cache;
     private readonly waitUntil?;
-    private readonly version?;
+    /** The `version` option: used for every versioned family when set. */
+    private readonly explicitVersion?;
     private readonly maxItemBytes;
     private readonly memo;
     private readonly handleMemos;

package/dist/types/client-urls/navigation.d.ts

@@ -7,6 +7,8 @@ export interface ClientUrlNavigationIntent {
     /** Absolute destination pathname (mount included) and search ("?..." or ""). */
     readonly pathname: string;
     readonly search: string;
+    /** `history.state` the navigation will push (OptimisticLocation.state). */
+    readonly state: unknown;
     /**
      * transition({ when }) gated this navigation off at the swap: the
      * destination presents urgently instead of in a transition lane.
@@ -26,6 +28,8 @@ export interface ClientUrlDestination {
      * params minus these are the mount's (include prefix) params.
      */
     readonly originLocalParamNames: readonly string[];
+    /** `history.state` the navigation will push (ClientUrlNavigationIntent.state). */
+    readonly state: unknown;
 }
 export declare function setActiveInterceptTargets(targets: readonly string[] | undefined): void;
 export interface ClientUrlNavigationPresentation {
@@ -39,7 +43,9 @@ export interface ClientUrlNavigationPresentation {
     clear(): void;
 }
 export declare function registerClientUrlGroup(definition: ClientUrlPatterns, mount: string, namePrefix: string, setIntent: (intent: ClientUrlNavigationIntent | null) => void, routeId?: string): () => void;
-export declare function beginClientUrlNavigation(targetUrl: URL, signal: AbortSignal, decideTransition?: (destination: ClientUrlDestination) => boolean): ClientUrlNavigationPresentation | null;
+export declare function beginClientUrlNavigation(targetUrl: URL, signal: AbortSignal, 
+/** Builds the entry state; called only when the group presents the target. */
+buildState?: () => unknown, decideTransition?: (destination: ClientUrlDestination) => boolean): ClientUrlNavigationPresentation | null;
 /**
  * Run the held clientUrls route's per-loader revalidate() predicates and
  * encode their decisions for the request header. Predicates are CLIENT code

package/dist/types/client-urls/optimistic-location.d.ts

@@ -3,15 +3,21 @@ import { type Context } from "react";
  * Route identity of an optimistically rendered clientUrls() destination:
  * the values the local trie match produced for the URL the user navigated
  * to. Provided by ClientUrlsRoot around the optimistic branch ONLY, so
- * useParams / usePathname / useSearchParams inside that branch describe the
- * route being rendered while the same hooks in chrome outside it keep the
- * committed location until the canonical response commits (or redirects, in
- * which case the branch — and these values — are discarded).
+ * useParams / usePathname / useSearchParams / useLocationState inside that
+ * branch describe the route being rendered while the same hooks in chrome
+ * outside it keep the committed location until the canonical response commits
+ * (or redirects, in which case the branch — and these values — are discarded).
  */
 export interface OptimisticLocation {
     readonly params: Readonly<Record<string, string>>;
     readonly pathname: string;
     /** Search string including the leading "?" (or ""). */
     readonly search: string;
+    /**
+     * `history.state` the navigation will push: its `state` option, without
+     * what the server adds (that arrives with the canonical commit). History
+     * still holds the entry being left, so useLocationState reads this instead.
+     */
+    readonly state: unknown;
 }
 export declare const OptimisticLocationContext: Context<OptimisticLocation | null>;

package/dist/types/handles/deferred-resolution.d.ts

@@ -39,8 +39,18 @@ export declare function resolveDeferredHandleValues(data: HandleData): Promise<H
  * A hung handle promise blocks the full render like any unresolved await (no
  * handle-specific timeout). Partial / action payloads keep streaming via
  * `handleStore.stream()`.
+ *
+ * `recordedOnly` is a PPR shell capture's render (full-payload.ts): the
+ * snapshot is cut down to the pushes the capture's record keeps
+ * (getDataForSegment's `excludeLoaderPushes`, the filter captureHandles
+ * writes the record with). A HIT restores that record and hydrates with it,
+ * so a push the record leaves out must not be in the prelude either: it
+ * rendered an element no HIT's hydration data matched (issue #1035). Which
+ * pushes a record keeps is the capture funnel's decision (shell-capture.ts
+ * deriveShellCaptureContext: today it leaves out a deferred loader push and
+ * one holding a masked promise), not this function's.
  */
-export declare function resolvedHandleStream(handleStore: HandleStore): AsyncGenerator<HandleData, void, unknown>;
+export declare function resolvedHandleStream(handleStore: HandleStore, recordedOnly?: boolean): AsyncGenerator<HandleData, void, unknown>;
 /**
  * Resolve the deferred (Promise) values in ONE segment's handle bucket
  * (`handleName -> entries[]`). Same shallow + drop-rejections rule as

package/dist/types/prerender/build-shell-capture.d.ts

@@ -20,6 +20,7 @@
  * identity, the same eligibility rules as at runtime.
  */
 import type { ShellCacheEntry } from "../cache/types.js";
+import type { RouterVersions } from "../router-versions.js";
 import type { SSRModule } from "../rsc/types.js";
 import { type ResolvedPprConfig } from "../rsc/shell-serve.js";
 /**
@@ -67,13 +68,14 @@ export interface BuildShellCaptureOptions {
     /** Build-time env bindings (rango plugin buildEnv), if configured. */
     buildEnv?: unknown;
     /**
-     * The MAIN build's version (the version plugin's value folded into the
-     * shipped worker) — NOT the temp server's own version-plugin value. The
-     * serve-side isValidShellHit gate compares entry.buildVersion against the
-     * running worker's ctx.version; stamping the temp server's would make every
-     * build entry an eternal MISS.
+     * The versions the SHIPPED build serves this router with (the build table,
+     * or the router's consumer-set version) — NOT the temp server's own
+     * version-plugin stamp. The serve-side isValidShellHit gate compares
+     * entry.buildVersion against the running worker's ctx.version, which is the
+     * document version; stamping the temp server's would make every build entry
+     * an eternal MISS.
      */
-    buildVersion: string;
+    versions: RouterVersions;
     /**
      * The SSR half, composed by the plugin from the temp server's SSR
      * environment runner (react-dom/static prerender + Flight client), with the

package/dist/types/router/match-middleware/cache-lookup.d.ts

@@ -92,7 +92,7 @@
  *   - Action context (if POST)
  */
 import type { ResolvedSegment } from "../../types.js";
-import type { EntryData } from "../../server/context.js";
+import { type EntryData } from "../../server/context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 /**
  * Whether the prerender store holds a baked entry for this route + params.

package/dist/types/router/navigation-snapshot.d.ts

@@ -25,8 +25,15 @@ export interface ResolveNavigationDeps {
  * never produce a partial match, so the replay path must decide
  * `no-navigation-context` BEFORE spending shell-store reads — the two
  * predicates drifting apart would misattribute the bypass again.
+ *
+ * `requestOrigin` is the origin pathname matching uses (`url.origin`), which
+ * may not be `request.url`'s. `X-RSC-Router-Client-Path` is returned as sent.
+ * A Referer counts only when it resolves against that origin and stays there.
+ * A cross-origin Referer is dropped: resolveNavigation matches only the
+ * pathname, so a foreign URL would be treated as a route on this app. A value
+ * that does not parse is no context either.
  */
-export declare function getNavigationContextHeader(request: Request): string | null;
+export declare function getNavigationContextHeader(request: Request, requestOrigin: string): string | null;
 /**
  * Whether withCacheLookup's prerender short-circuit will serve this partial
  * from the build-time prerender store: a Prerender() match (`matched.pr`)

package/dist/types/router/router-interfaces.d.ts

@@ -357,7 +357,8 @@ export interface RangoInternal<TEnv = any, TRoutes extends Record<string, unknow
      */
     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;
     /**

package/dist/types/router/router-options.d.ts

@@ -466,13 +466,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.
-     *
-     * Defaults to the auto-generated VERSION from `@rangojs/router:version` virtual module.
-     * Only set this if you need a custom versioning strategy.
-     *
-     * @default VERSION from @rangojs/router:version
+     * 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.
+     *
+     * 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 the router's build versions
      */
     version?: string;
     /**

package/dist/types/router/segment-resolution/loader-cache.d.ts

@@ -42,6 +42,8 @@
  */
 import { type EntryData, type LoaderEntry } from "../../server/context.js";
 import type { HandlerContext } from "../../types.js";
+import { type OwnedPushDelivery } from "../../cache/handle-snapshot.js";
+import { type RequestContext } from "../../server/request-context.js";
 /**
  * Whether a request over the matched chain `entries` resolves a loader bound
  * with its own cache(): on a chain entry, or on its parallel slots, orphan
@@ -51,15 +53,6 @@ import type { HandlerContext } from "../../types.js";
  * Memoized per entry.
  */
 export declare function bindsLoaderCache(entries: readonly EntryData[]): boolean;
-/**
- * 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 declare function liveLaneLoaderIds(entries: readonly EntryData[]): ReadonlySet<string>;
 /**
  * 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
@@ -67,6 +60,25 @@ export declare function liveLaneLoaderIds(entries: readonly EntryData[]): Readon
  * one is live (shell-capture.ts deriveShellCaptureContext).
  */
 export declare function routeLoaderLanes(entries: readonly EntryData[]): ReadonlyMap<string, "live" | "bake">;
+/**
+ * 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 declare function loaderPins(entries: readonly EntryData[], reqCtx: RequestContext<any> | undefined): OwnedPushDelivery;
 /**
  * Resolve loader data with optional caching.
  *

package/dist/types/router-versions.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 declare const DEFAULT_ROUTER_VERSIONS_KEY = "*";
+/** One value for both versions: a consumer-set `version`, or the dev stamp. */
+export declare function uniformVersions(version: string): RouterVersions;
+/**
+ * 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 declare function resolveVersionsFrom(table: RouterVersionsTable | undefined, routerId: string | undefined, override: string | undefined): RouterVersions | undefined;

package/dist/types/rsc/handler-context.d.ts

@@ -12,6 +12,11 @@ import type { RSCDependencies, LoadSSRModule } from "./types.js";
 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"];

package/dist/types/rsc/shell-build-manifest.d.ts

@@ -11,8 +11,9 @@
  * served through the same serveShellHit as a captured one.
  *
  * Lifecycle:
- * - No expiry until the next deploy — the buildVersion gate retires entries
- *   the moment a new build ships (a new manifest replaces them anyway).
+ * - No expiry until the next deploy: every build ships its own manifest, and
+ *   its entries carry that build's document version for the router, which is
+ *   what the buildVersion gate compares.
  * - `ppr.ttl` drives STALENESS ONLY: past createdAt + ttl the entry still
  *   serves, but a runtime recapture is scheduled — SWR is the UPGRADE path
  *   from build entry to fresher runtime entry, not the bootstrap path. The

package/dist/types/rsc/types.d.ts

@@ -321,13 +321,11 @@ export interface CreateRSCHandlerOptions<TEnv = unknown, TRoutes extends Record<
      */
     cache?: HandlerCacheConfig | ((env: TEnv) => HandlerCacheConfig);
     /**
-     * RSC version string included in metadata.
-     * The browser sends this back on partial requests to detect version mismatches.
+     * Version override for this handler. Same meaning as
+     * `createRouter({ version })`, which it takes precedence over: this exact
+     * value is used for both of the router's versions.
      *
-     * Defaults to the auto-generated VERSION from `rsc-router:version` virtual module.
-     * Only set this if you need a custom versioning strategy.
-     *
-     * @default VERSION from rsc-router:version
+     * @default createRouter({ version }), else the router's build versions
      */
     version?: string;
     /**

package/dist/types/server/build-version-table.d.ts

@@ -0,0 +1,44 @@
+import { type RouterVersions, type RouterVersionsTable } from "../router-versions.js";
+/**
+ * The versions a router serves with, in order:
+ *
+ * 1. `override`, a consumer-set `version` (createRouter or createRSCHandler):
+ *    that exact value for both.
+ * 2. The router's entry in the build table, else the whole-build entry.
+ * 3. `VERSION` for both: the dev stamp, bumped on every RSC module edit.
+ */
+export declare function resolveRouterVersions(routerId: string | undefined, override?: string): RouterVersions;
+/**
+ * The versions of the router serving the current request, for a cache store
+ * building a key. A store operation with no request context (a detached task
+ * that lost the ALS) gets the whole-build versions: it misses the request's
+ * entries instead of reading another version's. When routers have versions of
+ * their own that is a write no router reads back, so it is logged, once per
+ * process: `ctx.waitUntil()` re-enters the request context for every task it
+ * runs (server/request-context.ts), and this line in a production log means
+ * some other path lost it.
+ *
+ * Public from `@rangojs/router/cache`, for a custom persistent store to key
+ * the way the built-in ones do. Prefix cached RSC data (segment entries, items) with
+ * `data` and stored HTML or responses (shells, document responses) with
+ * `document`, and leave tag-invalidation records unversioned; an empty string
+ * means "no version" (tests). Call it per operation, inside the request, not
+ * in the store's constructor: the cache factory runs before the request
+ * context exists.
+ */
+export declare function getCacheVersions(): RouterVersions;
+/** Which of the serving router's versions a store key carries; `null`: none. */
+export type KeyVersion = keyof RouterVersions | null;
+/**
+ * The `v/{version}/` prefix of a persistent store key, or "" for an
+ * unversioned one. A store-level `version` is used for every versioned kind;
+ * otherwise the version is the serving router's, read per operation because
+ * the cache factory builds the store before the request context exists.
+ */
+export declare function versionKeyPrefix(storeVersion: string | undefined, kind: KeyVersion): string;
+/**
+ * @internal Install a table, or restore the build's with `undefined`. A
+ * request handler resolves its router's versions once, when it is created, so
+ * a test that swaps the table (a "deploy") needs new handlers.
+ */
+export declare function installRouterVersionsTable(next: RouterVersionsTable | undefined): void;