@rangojs/router 0.20.0 → 0.22.0

package/dist/types/prerender/writable-store.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Writable prerender store contract for on-demand (ISR-style) prerender refresh.
+ *
+ * The bundled build manifest (store.ts) is immutable and read-only. On-demand
+ * prerender adds a writable durable overlay in front of it: `router.prerender()`
+ * renders a route and writes a versioned envelope here; the serve path reads the
+ * overlay before the bundled manifest.
+ *
+ * This module is types + pure helpers only — no React/RSC/plugin-rsc imports —
+ * so it can be imported by the testing barrel and platform adapters alike.
+ */
+import type { PrerenderEntry } from "./store.js";
+/**
+ * Structured durable-overlay key. Includes the router's cache version so a
+ * deploy that changed the router's server code never reads Flight payloads
+ * that reference its previous build, and so Cloudflare gradual deployments
+ * stay correct (old and new worker versions each read their own namespace).
+ */
+export interface PrerenderKey {
+    routerId: string;
+    /**
+     * The owning router's cache version (its data version, or
+     * `createRouter({ version })`). Opaque: never set or read by app code; a
+     * store keys off it as given.
+     */
+    version: string;
+    routeName: string;
+    /** DJB2 8-hex hash of the canonical params (see param-hash.ts). */
+    paramHash: string;
+}
+/**
+ * @internal What the trigger stamps on a write. TTL is soft staleness metadata
+ * (`staleAt`), never a hard store expiry: hard expiry would delete the entry
+ * a stale-while-revalidate serve needs, and an expired overlay would fall back
+ * to older bundled-manifest content.
+ */
+export interface StoredEntryOptions {
+    /** Seconds until the entry is considered stale. Absent = never stale. */
+    ttl?: number;
+    tags: string[];
+    /** Canonical params, stored for verify-on-read. */
+    params: Record<string, string>;
+}
+/** What a page and a "removed" marker both carry: a store reads either alike. */
+interface StoredEnvelope {
+    v: 1;
+    meta: {
+        /**
+         * When the render started, not when the entry was written: a `markStale()`
+         * at or after it (strictly after in an in-process store) covers the entry.
+         * A `remove()` marker renders nothing and carries its write time.
+         */
+        storedAt: number;
+        /**
+         * Absent = never stale. Soft metadata only; controls `onRevalidate`
+         * scheduling, not serving. Counts the ttl from the write. A store may
+         * lower it (tag markers do).
+         */
+        staleAt?: number;
+        /** The configured ttl in seconds, as a result reports it. Absent = none. */
+        ttl?: number;
+        tags: string[];
+        /** The key's `version` at write time; verified on read. */
+        version: string;
+        /** Verified against the request's params on read (DJB2 collision guard). */
+        params: Record<string, string>;
+    };
+}
+type StoredPage = StoredEnvelope & {
+    entry: PrerenderEntry;
+    removed?: never;
+};
+/**
+ * The "removed" marker (tombstone) stored in place of a page, by
+ * `prerender.remove()` or by a refresh whose render hit `notFound()` (or
+ * declined with `ctx.passthrough()`). A request that finds it is not served
+ * the build-time entry below the overlay. No `entry`: a router from before the
+ * marker rejects it as malformed (a miss) instead of serving an empty page.
+ * `meta` is stamped like a page's for a render outcome, so that marker goes
+ * stale and is rechecked; a `remove()` marker has no `staleAt` and no tags.
+ */
+type StoredTombstone = StoredEnvelope & {
+    removed: true;
+    entry?: never;
+};
+/**
+ * Versioned envelope the router composes on a refresh or a removal and
+ * verifies on every read: a page, or the marker that the page was removed. A
+ * store persists either as given and returns it as stored.
+ */
+export type PrerenderStoredEntry = StoredPage | StoredTombstone;
+/**
+ * The writable durable overlay: plain get/set. Backed in production by a
+ * platform adapter (Cloudflare KV, …) and in dev/tests by an in-memory store.
+ * The router composes the envelope before `set()` and verifies whatever `get()`
+ * returns (shape, `version`, params collision guard), so a store holds no
+ * policy of its own.
+ *
+ * Key everything off the `key` argument (`serializePrerenderKey(key)` carries
+ * `key.version`). Never call `getCacheVersions()` here: the trigger's `set()`
+ * runs outside the producer's request context, where it returns the
+ * whole-build fallback instead of the owning router's version.
+ */
+export interface WritablePrerenderStore {
+    /**
+     * The envelope stored under `key`, or null. Never memoize a miss: a refresh
+     * can write the key after a request missed it. May lower `meta.staleAt` (a
+     * tag marked stale after the entry was written).
+     */
+    get(key: PrerenderKey): Promise<PrerenderStoredEntry | null>;
+    /**
+     * Persist `stored` (a page, or the marker that the page was removed) under
+     * `key`, replacing any previous entry. No expiry.
+     */
+    set(key: PrerenderKey, stored: PrerenderStoredEntry): Promise<void>;
+    delete?(key: PrerenderKey): Promise<void>;
+    /**
+     * Mark the entries of router `routerId` (`PrerenderKey.routerId`) carrying
+     * any of `tags` stale (they keep serving). A mark covers an entry whose
+     * `meta.storedAt` it is at or after (strictly after for an in-process
+     * store), including one `set()` after the mark: a store that marks held
+     * entries in place has to remember its marks. Scope it to that router: routers
+     * behind a host router share one store, and a tag is only meaningful inside
+     * the router whose routes declared it. Optional: without it,
+     * `router.prerender().markStale()` is a no-op for this store.
+     */
+    markStale?(routerId: string, tags: string[]): Promise<void>;
+}
+/**
+ * Serialize a {@link PrerenderKey} to the design's string form:
+ *   `prerender:{routerId}:{version}:{routeName}:{paramHash}`
+ */
+export declare function serializePrerenderKey(key: PrerenderKey): string;
+/**
+ * @internal Compose the versioned envelope the trigger hands to `store.set()`.
+ * `now` is `meta.storedAt`; `staleFrom` (default `now`) is where the ttl
+ * starts counting. Both are passed explicitly so tests stay deterministic.
+ */
+export declare function composeStoredEntry(key: PrerenderKey, entry: PrerenderEntry, options: StoredEntryOptions, now: number, staleFrom?: number): StoredPage;
+/**
+ * @internal Compose the "removed" marker stored in place of a page. Its meta
+ * is a page's (composeStoredEntry), so `ttl` and `tags` mean the same: the
+ * marker of a render outcome is given the route's and is rechecked like a
+ * page; `prerender.remove()` gives neither, and its marker never goes stale.
+ */
+export declare function composeStoredTombstone(key: PrerenderKey, options: StoredEntryOptions, now: number, staleFrom?: number): StoredTombstone;
+/**
+ * @internal Verify a store's answer is safe to serve for this key: the
+ * envelope shape and version tag, the key version, and the stored params
+ * against the request's (the 8-hex DJB2 collision guard, param-hash.ts: a
+ * runtime write keyed off webhook-supplied params must not serve one page's
+ * content under another's URL, nor remove another's page). False means treat
+ * it as a miss. Run by the router on every read, so a third-party store
+ * cannot skip it.
+ */
+export declare function isStoredEntryValidFor(stored: unknown, key: PrerenderKey, params: Record<string, string>): stored is PrerenderStoredEntry;
+/** True once `now` has passed the entry's soft `staleAt`. Never-stale entries never go stale. */
+export declare function isStoredEntryStale(stored: PrerenderStoredEntry, now: number): boolean;
+/**
+ * @internal Lower `meta.staleAt` to `at` when it is unset or later. Shared by
+ * the stores' tag marking so the rule cannot drift between them.
+ */
+export declare function lowerStoredEntryStaleAt(stored: PrerenderStoredEntry, at: number): void;
+/**
+ * @internal `store.get(key)` verified for serving (isStoredEntryValidFor). A
+ * store error (e.g. a KV outage) reads as a miss: the serve path falls back to
+ * the bundled manifest or live handler, and the trigger's stale check renders.
+ */
+export declare function readVerifiedStoredEntry(store: WritablePrerenderStore, key: PrerenderKey, params: Record<string, string>): Promise<PrerenderStoredEntry | null>;
+export {};

package/dist/types/prerender.d.ts

@@ -81,6 +81,26 @@ export interface PrerenderOptions {
      * ```
      */
     concurrency?: number;
+    /**
+     * Opt this route into on-demand (ISR-style) prerender refresh via
+     * `router.prerender()`. `true` uses the router-level `prerender` defaults; an
+     * object overrides them per route.
+     *
+     * Any truthy value opts in — a literal, a spread, or an imported const:
+     * producer retention in the production bundle is driven by the evaluated
+     * route manifest (the same source that sets the runtime od flag), not a
+     * textual scan of the call.
+     *
+     * @example
+     * ```typescript
+     * export const ProductPage = Prerender(
+     *   async () => [{ id: "featured" }],
+     *   async (ctx) => <Product data={await ctx.env.PRODUCTS.get(ctx.params.id)} />,
+     *   { onDemand: { ttl: 3600, tags: ({ params }) => [`product:${params.id}`] } },
+     * );
+     * ```
+     */
+    onDemand?: import("./prerender/on-demand.js").OnDemandOption;
 }
 /**
  * Context passed to Prerender() handlers at build time.
@@ -98,6 +118,13 @@ export interface BuildContext<TParams> {
      * changing build semantics.
      */
     dev: boolean;
+    /**
+     * True when this render is a requestless on-demand refresh driven by
+     * `router.prerender()` (rather than a build-time or dev prerender). The
+     * producer is still requestless — cookies/headers are unavailable — but
+     * `ctx.env` is the live trigger binding, not the shared build env.
+     */
+    onDemand: boolean;
     /**
      * Build-time environment bindings (KV, D1, etc.) supplied by the Vite plugin.
      * Only available when `buildEnv` is configured in rango() options.

package/dist/types/reverse.d.ts

@@ -31,7 +31,7 @@ export type ParamsFor<TRoutes, TName extends keyof TRoutes> = ExtractParams<Rout
 /**
  * Check if an object type has any keys
  */
-type IsEmptyObject<T> = keyof T extends never ? true : false;
+export type IsEmptyObject<T> = keyof T extends never ? true : false;
 /**
  * Extract search schema from a route entry.
  * Returns {} if no search schema is defined.

package/dist/types/route-content-wrapper.d.ts

@@ -1,4 +1,4 @@
-import type { ReactNode } from "react";
+import type { ComponentProps, ReactNode } from "react";
 import { Component } from "react";
 import type { ResolvedSegment } from "./types.js";
 /**
@@ -70,6 +70,7 @@ export declare function RouteContentWrapper({ content, fallback, segmentId, }: {
     fallback?: ReactNode;
     segmentId?: string;
 }): ReactNode;
+export declare function AuditedRouteContent({ content, fallback, segmentId, }: ComponentProps<typeof RouteContentWrapper>): ReactNode;
 /**
  * LoaderBoundary - Client component that resolves loader promises and renders OutletProvider
  *
@@ -102,3 +103,4 @@ export interface LoaderBoundaryProps {
     children: ReactNode;
 }
 export declare function LoaderBoundary({ loaderDataPromise, loaderIds, loaderStreams, awaitedLoaderIds, fallback, outletKey, outletContent, segment, parallel, children, }: LoaderBoundaryProps): ReactNode;
+export declare function AuditedLoaderBoundary({ fallback, children, ...resolver }: LoaderBoundaryProps): ReactNode;

package/dist/types/router/error-handling.d.ts

@@ -78,6 +78,8 @@ export declare function findNearestNotFoundBoundary(entry: EntryData | null, def
  * Sanitizes error details in production
  */
 export declare function createErrorInfo(error: unknown, segmentId: string, segmentType: ErrorInfo["segmentType"]): ErrorInfo;
+/** Invoke an errorBoundary() fallback that may be a handler or a plain node. */
+export declare function renderErrorFallback(fallback: ReactNode | ErrorBoundaryHandler, errorInfo: ErrorInfo): ReactNode;
 /**
  * Create an error segment with the fallback component
  * Renders the fallback with error info and reset function

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

@@ -37,7 +37,7 @@ export declare function createHandlerContext<TEnv>(params: Record<string, string
  * search, reverse, and use(handle) work. Request-time properties
  * (request, env, headers, cookies, get, set, res) throw with a clear error.
  */
-export declare function createPrerenderContext<TEnv>(params: Record<string, string>, pathname: string, routeMap: Record<string, string>, routeName?: string, buildVars?: Record<string, any>, isPassthroughRoute?: boolean, buildEnv?: TEnv, devMode?: boolean): InternalHandlerContext<any, TEnv>;
+export declare function createPrerenderContext<TEnv>(params: Record<string, string>, pathname: string, routeMap: Record<string, string>, routeName?: string, buildVars?: Record<string, any>, isPassthroughRoute?: boolean, buildEnv?: TEnv, devMode?: boolean, onDemand?: boolean): InternalHandlerContext<any, TEnv>;
 /**
  * Create a StaticContext for Static() handlers at build time.
  *

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

@@ -92,8 +92,18 @@
  *   - 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";
+import type { PrerenderStore } from "../../prerender/store.js";
+import type { PrerenderTargetObject, ResolvedPrerender } from "../../prerender/on-demand.js";
+import { type RequestContext } from "../../server/request-context.js";
+/**
+ * @internal Replace the prerender store this module serves from, and return
+ * the one it replaced. For serveShellRequest (testing/serve-shell-request.ts),
+ * which installs the production store over the artifacts it bakes for a call
+ * and puts the previous one back after it.
+ */
+export declare function setPrerenderStoreForTests(store: PrerenderStore | null | undefined): PrerenderStore | null | undefined;
 /**
  * Whether the prerender store holds a baked entry for this route + params.
  * Consulted by the PPR replay gate (matchPartialWithPprReplay), which must
@@ -106,6 +116,10 @@ import type { MatchContext, MatchPipelineState } from "../match-context.js";
  * subsequent get() share one underlying load.
  */
 export declare function prerenderEntryExists(routeKey: string | undefined, params: Record<string, string>, pathname: string, entries: EntryData[]): Promise<boolean>;
+/** @internal Tests only (testing/serve-shell-request.ts resetShellTestState). */
+export declare function resetOverlayRevalidationsForTests(): void;
+/** @internal Exported for the eviction unit test. */
+export declare function scheduleOverlayRevalidation<TEnv>(serializedKey: string, onRevalidate: NonNullable<ResolvedPrerender["config"]["onRevalidate"]>, target: PrerenderTargetObject, reqCtx: RequestContext<TEnv>, now?: number): void;
 /**
  * Async generator middleware type
  */

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/pattern-matching.d.ts

@@ -134,6 +134,8 @@ export interface RouteMatchResult<TEnv = any> {
     pr?: true;
     /** Passthrough: handler kept for live fallback on unknown params (from trie) */
     pt?: true;
+    /** On-demand prerender eligible (router.prerender() refreshable) */
+    od?: true;
     /** Response type for non-RSC routes (json, text, image, any) */
     responseType?: string;
     /** Negotiate variants: response-type routes sharing this path */

package/dist/types/router/prefetch-default.d.ts

@@ -1,9 +1,9 @@
 /**
  * Resolve the router-wide default Link prefetch strategy once, at router init.
- * The resolved value ships to the client in payload metadata; the browser
- * entry applies it via `setDefaultPrefetchStrategy` (browser/prefetch/
- * default-strategy.ts) and every `<Link>` without an explicit `prefetch` prop
- * falls back to it.
+ * The resolved value ships to the client in payload metadata; the router
+ * store carries it (`NavigationStoreContext.defaultPrefetch`, see
+ * browser/prefetch/default-strategy.ts) and every `<Link>` without an explicit
+ * `prefetch` prop falls back to it.
  *
  * The type lives HERE (not in browser/react/Link.tsx) because both seats need
  * it: this server-side resolver and the client Link/default-strategy modules.

package/dist/types/router/prerender-match.d.ts

@@ -5,10 +5,19 @@ import type { PartialPrerenderProps } from "../urls/pattern-types.js";
 import type { HandlerContext, ResolvedSegment } from "../types";
 import type { SerializedSegmentData } from "../cache/types.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
+import type { RouterVersions } from "../router-versions.js";
+import type { OnDemandRouteConfig } from "../prerender/on-demand.js";
 export interface PrerenderMatchDeps<TEnv = any> {
     /** Owning router id; scopes bake-time root-scope/search-schema lookups the
      *  same way reqCtx._routerId does at runtime (issue #762). */
     routerId?: string;
+    /**
+     * The owning router's cache versions. Set on the requestless on-demand
+     * producer's context as `_versions`, so cache stores built inside the render
+     * key under the router's pair like a live request does instead of the
+     * whole-build fallback (server/build-version-table.ts getCacheVersions).
+     */
+    versions?: RouterVersions;
     findMatch: (pathname: string) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
     buildRouterContext: () => RouterContext<TEnv>;
     mergedRouteMap: Record<string, string>;
@@ -20,7 +29,15 @@ export interface PrerenderMatchDeps<TEnv = any> {
  */
 export declare function matchForPrerender<TEnv = any>(pathname: string, params: Record<string, string>, deps: PrerenderMatchDeps<TEnv>, buildVars?: Record<string, any>, isPassthroughRoute?: boolean, buildEnv?: TEnv, 
 /** Dev-only: check getParams() for passthrough routes to skip unknown params. */
-devMode?: boolean): Promise<{
+devMode?: boolean, 
+/**
+ * Requestless on-demand refresh (router.prerender()). Arms the personalization
+ * guard: cookies()/headers()/response mutations throw a
+ * PrerenderPersonalizationError so the caller maps a personalized render to
+ * skipped-personalized instead of baking a shared payload. `buildEnv` here is
+ * the live trigger env, not the shared build env.
+ */
+onDemand?: boolean): Promise<{
     segments: SerializedSegmentData[];
     /** RSC-encoded handle map ("" when none) — see handle-snapshot.ts. Encoded in
      *  the producer (where the Flight codec resolves) so the node-side build/dev
@@ -33,6 +50,11 @@ devMode?: boolean): Promise<{
      *  the sinks store it as-is (no longer merge raw records). */
     interceptHandles?: string;
     passthrough?: true;
+    /** On-demand only: the render hit `notFound()` and nothing else failed. */
+    notFound?: true;
+    /** Route-level onDemand config (ttl/tags) read off the route entry; only set
+     *  when `onDemand` and the route declared an onDemand object literal. */
+    onDemandConfig?: OnDemandRouteConfig;
     /**
      * The matched route entry's `ppr` path option, surfaced so the build
      * collection can flag Prerender+ppr routes as build-time shell candidates

package/dist/types/router/route-trie-builder.d.ts

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

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

@@ -45,6 +45,7 @@ export interface RouterContext<TEnv = any> {
     getContext: () => {
         getOrCreateStore: (key: string) => any;
         runWithStore: <T>(store: any, namespace: string, parent: any, fn: () => T) => T;
+        runIsolated: <T>(forRoute: string, fn: () => T) => T;
     };
     getMetricsStore: () => MetricsStore | undefined;
     createCacheScope: (cacheConfig: any, parent: CacheScope | null) => CacheScope | null;

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

@@ -184,6 +184,28 @@ export interface Rango<TEnv = any, TRoutes extends Record<string, unknown> = Rec
      * ```
      */
     fetch(request: Request, input?: RouterRequestInput<TEnv>): Promise<Response>;
+    /**
+     * Bind `{ env, ctx }` and get the on-demand (ISR-style) prerender runner, to refresh from a running app —
+     * fetch handler, cron, queue, workflow, webhook, or server action.
+     *
+     * Requestless: the producer renders with route params and env only, never the
+     * caller's cookies/headers/session. Only routes that opted in via
+     * `Prerender(..., { onDemand })` are persistable; others return a skipped
+     * result. Configure the store via the `prerender` router option.
+     *
+     * @example
+     * ```ts
+     * const prerender = router.prerender({ env, ctx });
+     * await prerender("/products/42");
+     * await prerender(
+     *   { route: "products.detail", params: { id: "42" } },
+     *   { throwOnError: true },
+     * );
+     * await prerender.many(targets, { concurrency: 4 });
+     * await prerender.markStale(["product:42"]);
+     * ```
+     */
+    prerender: import("../prerender/on-demand.js").PrerenderFn<TEnv, TRoutes>;
 }
 /**
  * Internal Rango router interface — the full framework-facing API.
@@ -254,6 +276,12 @@ export interface RangoInternal<TEnv = any, TRoutes extends Record<string, unknow
      * Cache configuration
      */
     readonly cache?: RangoOptions<TEnv>["cache"];
+    /**
+     * Prerender store configuration (the writable durable overlay for on-demand
+     * prerender). Stored separately from the `prerender` trigger method so the RSC
+     * handler can resolve it per request. @internal
+     */
+    readonly _prerenderConfig?: RangoOptions<TEnv>["prerender"];
     /**
      * Not found component to render when no route matches
      */
@@ -357,7 +385,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;
     /**
@@ -470,6 +499,8 @@ export interface RangoInternal<TEnv = any, TRoutes extends Record<string, unknow
      * Handle an RSC request.
      */
     fetch(request: Request, input?: RouterRequestInput<TEnv>): Promise<Response>;
+    /** On-demand prerender binder: router.prerender({ env, ctx }) returns the runner. */
+    prerender: import("../prerender/on-demand.js").PrerenderFn<TEnv, TRoutes>;
 }
 /**
  * Assert a public Rango into the internal type.

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

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

package/dist/types/router/segment-resolution/fresh.d.ts

@@ -37,6 +37,13 @@ export interface ResolveSegmentOptions {
      * #918: resolved twice on a MISS, once and discarded on a HIT).
      */
     chain?: readonly EntryData[];
+    /**
+     * The matched chain entry being resolved: where the sync path catches a
+     * handler error, so a streamed handler (or slot owned by a routeless layout)
+     * recovers into the same boundary. resolveSegment sets it for the entry it
+     * resolves; nested resolutions keep the outer value.
+     */
+    boundaryEntry?: EntryData;
 }
 /**
  * Resolve segments from EntryData.

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

@@ -9,7 +9,8 @@
  *   1. options.key(requestCtx) — full override, stored namespaced as
  *      loader:{loaderId}:key:{encodeURIComponent(result)} (#1009)
  *   2. store.keyGenerator(requestCtx, defaultKey) — store-level modification
- *   3. loader:{loaderId}:{host}{pathname}:{sortedParams} — default
+ *   3. loader:{loaderId}:{routerId}@{host}{pathname}:{sortedParams} — default
+ *      (a loader's ctx is one router's: cache-key-utils.ts, the router rule)
  *
  * Values are serialized via RSC Flight (serializeResult/deserializeResult),
  * supporting ReactNode, Promises, null, and all RSC-serializable types.
@@ -42,6 +43,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 +54,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 +61,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/segment-resolution/revalidation.d.ts

@@ -51,6 +51,8 @@ export declare function resolveParallelSegmentsWithRevalidation<TEnv>(entry: Ent
      * to it: loader sub-ids are filtered out and slots are re-grouped by parent).
      */
     loaderOrder?: "after" | "before";
+    /** Matched chain entry being resolved; see ResolveSegmentOptions.boundaryEntry. */
+    boundaryEntry?: EntryData;
 }): Promise<SegmentRevalidationResult>;
 /**
  * Resolve entry handler (layout, cache, or route) with revalidation.
@@ -74,7 +76,9 @@ chain?: readonly EntryData[]): Promise<SegmentRevalidationResult>;
  */
 export declare function resolveOrphanLayoutWithRevalidation<TEnv>(orphan: EntryData, params: Record<string, string>, context: HandlerContext<any, TEnv>, clientSegmentIds: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, routeKey: string, belongsToRoute: boolean, deps: SegmentResolutionDeps<TEnv>, actionContext?: ActionContext, stale?: boolean, 
 /** Parent route entry — its loaders are inherited so parallel slots can access them. */
-parentRouteEntry?: EntryData): Promise<SegmentRevalidationResult>;
+parentRouteEntry?: EntryData, 
+/** Matched chain entry being resolved (see ResolveSegmentOptions.boundaryEntry); defaults to parentRouteEntry. */
+boundaryEntry?: EntryData | undefined): Promise<SegmentRevalidationResult>;
 /**
  * Resolve all segments for a route with revalidation logic (for matchPartial).
  */