@rangojs/router 0.20.0 → 0.22.0

package/dist/types/cache/tag-invalidation.d.ts

@@ -37,16 +37,17 @@
  */
 import type { SegmentCacheStore } from "./types.js";
 import { type ExecutionStart } from "./invalidation-order.js";
-export { executionStart, invalidatedSince, type ExecutionStart, } from "./invalidation-order.js";
+export { executionStart, invalidatedSince, markResponseStart, type ExecutionStart, } from "./invalidation-order.js";
 /**
  * The write gate of every cache execution (#977): whether one of `tags` was
  * invalidated after the execution that produced the value started.
  *
- * Every built-in store stamps an entry when it is written (CFCacheStore's
- * `taggedAt`, VercelCacheStore's `ta`) or checks nothing on write
- * (MemorySegmentCacheStore), so a value read before an invalidation and
- * written after it would be served as newer than the invalidation until it
- * expires. Two answers, either one skips the write:
+ * A store stamps an entry with the execution's start (CFCacheStore's
+ * `taggedAt`, VercelCacheStore's `ta`, #1068), but only CFCacheStore with KV
+ * markers rejects it on a later request's read, and MemorySegmentCacheStore
+ * refuses the write. The gate saves the write everywhere and is the only
+ * guard where a read compares nothing. Two answers, either one skips the
+ * write:
  *
  * - this isolate's order (invalidatedSince), which sees every request's
  *   updateTag()/revalidateTag() here, the calling one included;

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

@@ -36,6 +36,17 @@ export interface CacheGetResult {
      */
     shouldRevalidate: boolean;
 }
+/**
+ * Where an entry a store writes during one request can be read by a later
+ * request. `router.prerender()` warms a route only when the app store answers
+ * `"global"` or `"regional"`: a warm fills the store where it runs, which
+ * serves other traffic only when the store is shared beyond that place.
+ * - `"global"`: every location reads the same entries.
+ * - `"regional"`: each region has its own copy; a warm fills the region it
+ *   runs in.
+ * - `"local"`: only the process, isolate or edge location that wrote it.
+ */
+export type CacheStoreScope = "global" | "regional" | "local";
 /**
  * Low-level segment cache store interface.
  *
@@ -43,9 +54,21 @@ 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> {
+    /**
+     * Where an entry this store writes can be read ({@link CacheStoreScope}).
+     * Absent: unknown to the router, treated as `"local"`.
+     */
+    readonly scope?: CacheStoreScope;
     /**
      * The store honors getShell(..., { claimRevalidation: false }) without
      * claiming an SWR lock. Navigation replay requires this opt-in because it
@@ -140,6 +163,11 @@ export interface SegmentCacheStore<TEnv = unknown> {
      * @param ttl - Time-to-live in seconds
      * @param swr - Optional stale-while-revalidate window in seconds
      * @param tags - Optional cache tags for invalidation
+     *
+     * The built-in stores read the start of the render from the `Response`
+     * object itself (#1068). A custom store, or a wrapper that rebuilds the
+     * `Response` before delegating, stamps write time. The write gate
+     * (`predatesInvalidation`) runs before this call either way.
      */
     putResponse?(key: string, response: Response, ttl: number, swr?: number, tags?: string[]): Promise<void>;
     /**
@@ -361,13 +389,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;
     /**
@@ -389,9 +418,10 @@ export interface ShellCacheEntry {
      * bake-lane loader pins (pruned to what a HIT reads, issue #941). Replaying
      * them on a HIT keeps the freshly rendered hydration payload equal to the
      * frozen prelude after the underlying cache entries have drifted; every
-     * other read on a HIT, a hole's included, reads the store. Empty when the capture
-     * recorded nothing (a prerender-served capture without bake-lane loaders,
-     * a tombstone). A custom store returns it as putShell received it. See
+     * other read on a HIT, a hole's included, reads the store. A
+     * prerender-served capture holds a `handles` record instead of a doc record
+     * (ShellSnapshotHandlesValue). Empty for a tombstone. A custom store
+     * returns it as putShell received it. See
      * docs/design/ppr-shell-resume.md ("the capture data snapshot").
      */
     snapshot: ShellSnapshotRecord[];
@@ -552,12 +582,22 @@ export interface ShellReadStats {
 }
 /**
  * The families a shell snapshot pins: the doc segment record (recorded by
- * RecordingShellStore) and the settled CONTAINER of each bake-lane loader
- * (lane rule: see resolveLoaderData, loader-cache.ts). No cache read is
- * pinned: a HIT's holes, and a bake-lane loader body that runs on the HIT,
- * read the store.
+ * RecordingShellStore), the settled CONTAINER of each bake-lane loader
+ * (lane rule: see resolveLoaderData, loader-cache.ts), and a prerender-served
+ * entry's `handles` record. No cache read is pinned: a HIT's holes, and a bake-lane
+ * loader body that runs on the HIT, read the store.
  */
-export type ShellSnapshotFamily = "segment" | "loader";
+export type ShellSnapshotFamily = "segment" | "loader" | "handles";
+/**
+ * The stored form of the `handles` family: the handle arrays of a
+ * prerender-served capture that hold a loader-owned push, in the doc record's
+ * format (CachedEntryData `handles` + `handleOwners`). A Prerender + ppr
+ * route's handler layer comes from the prerender store, whose build-time
+ * entry has no loader push, so the entry keeps these for the HIT to restore
+ * as a doc record's (issue #1057, yieldFromStore in cache-lookup.ts). An
+ * entry written before it (v0.21) has none and serves as it did.
+ */
+export type ShellSnapshotHandlesValue = Pick<CachedEntryData, "handles" | "handleOwners">;
 /**
  * The stored form of a loader-family snapshot value: the bake-lane loader's
  * settled container, Flight-serialized AFTER eliding every still-pending nested
@@ -590,17 +630,18 @@ export interface ShellSnapshotLoaderValue {
     runs: 0 | 1;
 }
 /**
- * One snapshot record: the doc segment record or a bake-lane loader pin.
- * `value` carries it in its stored/serialized shape so it round-trips
- * through a JSON-serializing store (KV, CF, Vercel) with the rest of the
- * ShellCacheEntry:
+ * One snapshot record: the doc segment record, a bake-lane loader pin, or a
+ * prerender-served entry's handle record. `value` carries it in its
+ * stored/serialized shape so it round-trips through a JSON-serializing store
+ * (KV, CF, Vercel) with the rest of the ShellCacheEntry:
  * - `segment` -> {@link CachedEntryData} (already JSON-able)
  * - `loader`  -> {@link ShellSnapshotLoaderValue}
+ * - `handles` -> {@link ShellSnapshotHandlesValue}
  */
 export interface ShellSnapshotRecord {
     family: ShellSnapshotFamily;
     key: string;
-    value: CachedEntryData | ShellSnapshotLoaderValue;
+    value: CachedEntryData | ShellSnapshotLoaderValue | ShellSnapshotHandlesValue;
 }
 /**
  * Options for setItem() for function-level caching ("use cache").
@@ -614,6 +655,17 @@ export interface CacheItemOptions {
     swr?: number;
     /** Cache tags for invalidation */
     tags?: string[];
+    /**
+     * Ms since epoch when the execution that produced the value started (#1068).
+     * A store stamps a tagged entry with it instead of its write time. Later
+     * requests then reject an entry an invalidation landed under in
+     * CFCacheStore with KV markers; MemorySegmentCacheStore refuses the write.
+     * Not rejected: VercelCacheStore (a read compares the stamp with the
+     * invalidating request's mask only) and CFCacheStore L1 hits in purge mode
+     * or without KV. Absent or not positive: write time. A custom store may
+     * ignore it.
+     */
+    startedAt?: number;
 }
 /**
  * Serialized segment data stored in cache
@@ -656,7 +708,12 @@ export interface CachedEntryData {
     expiresAt: number;
     /** Cache tags for invalidation */
     tags?: string[];
-    /** Timestamp (ms since epoch) when tags were attached, for distributed invalidation */
+    /**
+     * Timestamp (ms since epoch) the entry's tags are valid as of, for
+     * distributed invalidation. The writer sets it to the start of the render
+     * that produced the record; a store stamps write time when it is absent
+     * (#1068). Which reads reject on it: see `CacheItemOptions.startedAt`.
+     */
     taggedAt?: number;
 }
 /**
@@ -696,10 +753,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
@@ -32,7 +33,7 @@
  * `getCache(...)` result, which satisfies the shape structurally. That keeps the
  * router free of a hard Vercel dependency.
  */
-import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, ShellDocumentRead, ShellDocumentReadOptions, CacheReadError } from "../types.js";
+import type { CacheStoreScope, SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, ShellDocumentRead, ShellDocumentReadOptions, CacheReadError } from "../types.js";
 import { type RequestContext } from "../../server/request-context.js";
 import { type StoreMemoOptions } from "../shell-memo.js";
 /**
@@ -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: () => ({
@@ -216,12 +227,19 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
  * ```
  */
 export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+    /**
+     * SegmentCacheStore.scope: the Runtime Cache is per region. A
+     * router.prerender() warm fills the region it runs in, which is all traffic
+     * only when the project's functions run in one region.
+     */
+    readonly scope: CacheStoreScope;
     readonly supportsPassiveShellReads: true;
     readonly defaults?: CacheDefaults;
     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/errors.d.ts

@@ -223,5 +223,11 @@ export declare function invariant(condition: any, message: string): asserts cond
  * @param error - Error to sanitize
  * @returns Response suitable for sending to client
  */
+/**
+ * Vite replaces import.meta.env.DEV at compile time. The fallback covers
+ * non-Vite environments (plain Node, test runners without Vite transforms).
+ * SECURITY: fail closed — default to production when the environment is ambiguous.
+ */
+export declare function isDevEnvironment(): boolean;
 export declare function sanitizeError(error: unknown): Response;
 export {};

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

@@ -39,8 +39,25 @@ 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, recordedOnly?: boolean): AsyncGenerator<HandleData, void, unknown>;
+/**
+ * `snapshot` without the pushes a record leaves out. A shell capture renders
+ * (resolvedHandleStream) and waits (settleCaptureRecord) on this cut only: a
+ * promise the record drops has no slot in the prelude, and waiting for it
+ * could refuse a capture for a value the shell does not hold.
  */
-export declare function resolvedHandleStream(handleStore: HandleStore): AsyncGenerator<HandleData, void, unknown>;
+export declare function recordedHandleData(handleStore: HandleStore, snapshot: HandleData): HandleData;
 /**
  * Resolve the deferred (Promise) values in ONE segment's handle bucket
  * (`handleName -> entries[]`). Same shallow + drop-rejections rule as

package/dist/types/internal-suspense-audit.d.ts

@@ -0,0 +1 @@
+export declare const INTERNAL_RANGO_SUSPENSE_AUDIT: boolean;

package/dist/types/loader-store.d.ts

@@ -29,9 +29,10 @@
  *     reclaim a bucket that is about to be reused, and is held until any
  *     in-flight load settles.
  *
- * The store is intentionally module-level: each browser tab is its own JS
- * realm, so there is no cross-request pollution. Server renders never mutate
- * the store — the hook falls back to `OutletContext.loaderData`.
+ * Each router's NavigationStore owns one (navigation-store.ts), and hooks reach
+ * it through NavigationStoreContext: the router store is the single source of
+ * truth. Server renders have no store — the hook falls back to
+ * `OutletContext.loaderData`.
  */
 /** The loader-segment shape announcePendingStreams reads (ResolvedSegment). */
 export interface PendingStreamSource {
@@ -237,9 +238,4 @@ export declare class LoaderStore {
      */
     reset(): void;
 }
-/**
- * Module-level singleton. Each browser tab gets its own; SSR never mutates it.
- * The hook falls through to `OutletContext.loaderData` during the server render.
- */
-export declare const loaderStore: LoaderStore;
 export declare const EMPTY_LOADER_SNAPSHOT: LoaderEntry;

package/dist/types/outlet-provider.d.ts

@@ -1,4 +1,4 @@
-import { type ReactNode } from "react";
+import { type ComponentProps, type ReactNode } from "react";
 import type { ResolvedSegment } from "./types.js";
 /**
  * Outlet content provider — stores parent context for useLoader chain walking.
@@ -13,3 +13,4 @@ export declare function OutletProvider({ content, parallel, segment, loaderData,
     pending?: boolean;
     children: ReactNode;
 }): ReactNode;
+export declare function AuditedOutletProvider({ children, ...props }: ComponentProps<typeof OutletProvider>): ReactNode;

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/prerender/cloudflare.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Cloudflare KV writable prerender store (`@rangojs/router/prerender/cloudflare`).
+ *
+ * Backs the durable overlay for on-demand prerender on Cloudflare. Self-contained
+ * (no CFCacheStore construction constraints): entries are stored under the
+ * versioned key `prerender:{routerId}:{version}:{routeName}:{paramHash}`, and
+ * tag invalidation uses the same timestamp-marker technique as the runtime cache
+ * — a per-tag KV marker holding the ms epoch of the last invalidation; a read
+ * treats the entry as stale (never deleted) when any of its tags' markers is at
+ * or after the entry's storedAt.
+ *
+ * Key design constraints (see docs/design/ondemand-prerender.md, Store Model):
+ * - staleAt is SOFT metadata; entries are written with NO KV expirationTtl. Hard
+ *   expiry would delete the entry SWR needs and re-expose older bundled-manifest
+ *   content below the overlay.
+ * - Prerender keys are route + params + variant only — never host-namespaced, so
+ *   a refresh from a different host than the serve request still hits.
+ * - Invalidation is mark-stale, not delete (deleting would re-expose the manifest
+ *   entry as the result of an "invalidation").
+ * - Tag markers use a prerender-specific prefix, separate from the runtime cache's
+ *   `updateTag()`/`revalidateTag()` namespace, and are scoped by router id
+ *   (`{prefix}{encodeURIComponent(routerId)}/{tag}`): routers sharing one KV
+ *   namespace (an app behind a host router) must not mark each other's entries.
+ * - Markers carry no expiry: an entry without a `ttl` never goes stale by
+ *   itself, so an expired marker would silently drop an invalidation.
+ */
+import type { KVNamespace } from "../cache/cf/cf-cache-types.js";
+import { type WritablePrerenderStore } from "./writable-store.js";
+export interface KVPrerenderStoreOptions {
+    /** Injectable clock for `markStale` markers in deterministic tests. Defaults to Date.now. */
+    now?: () => number;
+}
+/**
+ * Create a {@link WritablePrerenderStore} backed by a Cloudflare KV namespace.
+ *
+ * @example
+ * ```ts
+ * import { createKVPrerenderStore } from "@rangojs/router/prerender/cloudflare";
+ *
+ * createRouter<Env>({
+ *   prerender: (env) => ({
+ *     store: createKVPrerenderStore(env.PRERENDER_KV),
+ *     ttl: 3600,
+ *     onRevalidate: (target, e) => e.PRERENDER_QUEUE.send({ target }),
+ *   }),
+ * });
+ * ```
+ */
+export declare function createKVPrerenderStore(kv: KVNamespace, options?: KVPrerenderStoreOptions): WritablePrerenderStore;