@rangojs/router 0.21.0 → 0.22.1

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

@@ -94,6 +94,16 @@
 import type { ResolvedSegment } from "../../types.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/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
      */
@@ -471,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.

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.

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).
  */

package/dist/types/router/segment-resolution/streamed-handler-boundary.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Streamed handlers (loading()): track, observe, and recover a rejection into
+ * the declared errorBoundary() / notFoundBoundary() fallback.
+ *
+ * Invariants:
+ * - No status write and no onError call: the status is committed at first
+ *   flush, and trackHandler already reports each rejection once.
+ * - The recovered promise resolves, so Flight reports no error. The writers
+ *   that refuse a failed render through Flight errors need the failure
+ *   recorded here: `_renderErrors` for the document cache and a prerender
+ *   warm, `_recoveredHandlerErrors` for cacheRoute (cache(), and the doc record
+ *   a PPR capture needs). The shell capture and the SWR re-render own both,
+ *   so a derived render never writes into (or reads) the foreground's.
+ * - Nothing to render to rethrows the original rejection: no boundary found, a
+ *   thrown Response (redirect), a Skip, a throwing fallback.
+ * - No recovery when `recover` is false (prerender throwOnError, the intercept
+ *   background re-render): those lanes must reject so nothing is baked/cached.
+ */
+import type { ReactNode } from "react";
+import type { EntryData } from "../../server/context.js";
+import type { ErrorInfo, HandlerContext } from "../../types/index.js";
+import type { SegmentResolutionDeps } from "../types.js";
+export interface StreamedHandlerOptions<TEnv> {
+    /**
+     * Entry to look boundaries up from: the matched chain entry being resolved
+     * (where the sync path catches, whatever routeless layout owns a slot), or
+     * the intercept's declaring entry.
+     */
+    boundaryEntry: EntryData;
+    segmentId: string;
+    segmentType: ErrorInfo["segmentType"];
+    context: HandlerContext<any, TEnv>;
+    routeKey?: string;
+    params: Record<string, string>;
+    /** False where the rejection must reach the caller (prerender, intercept background re-render). */
+    recover: boolean;
+}
+/**
+ * Track a streamed handler promise and return the segment component: the
+ * tracked promise itself when there is nothing to recover to, else a promise
+ * that resolves to the declared fallback on rejection.
+ */
+export declare function trackStreamedHandler<TEnv>(deps: SegmentResolutionDeps<TEnv>, result: Promise<unknown>, options: StreamedHandlerOptions<TEnv>): ReactNode;

package/dist/types/router/trie-matching.d.ts

@@ -18,6 +18,8 @@ export interface TrieMatchResult {
     pr?: true;
     /** Passthrough: handler kept for live fallback on unknown params */
     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/rsc/shell-build-manifest.d.ts

@@ -36,7 +36,7 @@ export interface BuildShellEntry {
     tags?: string[];
 }
 interface ShellManifestModule {
-    /** Manifest key (pathname — see shell-manifest-key.ts) -> asset specifier. */
+    /** Manifest key (router id + pathname, shell-manifest-key.ts) -> asset specifier. */
     default: Record<string, string>;
     loadShellAsset: (spec: string) => Promise<{
         default: BuildShellEntry;
@@ -80,11 +80,13 @@ export interface DevShellLookup {
  * request is search-less, like the entries lookupBuildShell serves): a
  * manifest entry for the path in production, a Prerender route in dev. No
  * asset load and no dev capture: it only decides whether a request that
- * cannot read the build shell deserves a warning.
+ * cannot read the build shell deserves a warning. The manifest entry is the
+ * one staged for the router `routerId` (shell-manifest-key.ts).
  */
-export declare function hasBuildShell(pathname: string, dev?: DevShellLookup): Promise<boolean>;
+export declare function hasBuildShell(routerId: string, pathname: string, dev?: DevShellLookup): Promise<boolean>;
 /**
  * Look up the baked shell entry for a request, applying every serve gate:
+ * the serving router's own entry only (`routerId`, shell-manifest-key.ts),
  * search-less requests only (the build captured the bare pathname; a
  * search-bearing URL has its own shell identity owned by runtime capture),
  * version validity, payload integrity, and tag-invalidation markers. Returns
@@ -96,5 +98,5 @@ export declare function hasBuildShell(pathname: string, dev?: DevShellLookup): P
  * exclusion) matches the baked shell — ad-click traffic is exactly the
  * traffic the shell was prerendered for.
  */
-export declare function lookupBuildShell(url: URL, buildVersion: string, store: SegmentCacheStore, dev?: DevShellLookup, filter?: SearchParamsFilter): Promise<BuildShellHit | null>;
+export declare function lookupBuildShell(routerId: string, url: URL, buildVersion: string, store: SegmentCacheStore, dev?: DevShellLookup, filter?: SearchParamsFilter): Promise<BuildShellHit | null>;
 export {};

package/dist/types/rsc/shell-capture-constants.d.ts

@@ -56,13 +56,14 @@ export type PprReplayBypassReason = (typeof PPR_REPLAY_BYPASS_REASONS)[number];
  */
 export declare function shellSearchSeed(url: URL, filter?: SearchParamsFilter): string;
 /**
- * Shell cache key: host + pathname + sorted search + a `:shell` namespace suffix
- * (so it can never collide with a document-cache key; the store further isolates
- * the shell family internally).
+ * Shell cache key: router id + host + pathname + sorted search + a `:shell`
+ * namespace suffix (so it can never collide with a document-cache key; the
+ * store further isolates the shell family internally).
  *
  * The key includes the request HOST: in a multi-tenant host-router deployment
  * (one worker, one shared KV/runtime-cache store) a host-less key would serve
- * tenant A's captured shell to tenant B's users.
+ * tenant A's captured shell to tenant B's users. It starts with the serving
+ * ROUTER for the same reason (cache-key-utils.ts, the router rule).
  *
  * `filter` is the request's compiled `cache.searchParams` config
  * (ctx._searchParamsFilter): excluded params collapse onto one shell slot.
@@ -70,7 +71,7 @@ export declare function shellSearchSeed(url: URL, filter?: SearchParamsFilter):
  * and lookup makes every shell request a permanent miss. The testing helper
  * `shellCacheKey` (testing/shell-status.ts) builds its key with it too.
  */
-export declare function buildShellKey(url: URL, filter?: SearchParamsFilter): string;
+export declare function buildShellKey(routerId: string, url: URL, filter?: SearchParamsFilter): string;
 /**
  * The shell key for one request partition (cache-scope.ts
  * resolveShellPartition): the route cache() `key()` or store keyGenerator
@@ -133,6 +134,20 @@ export declare const POST_QUIESCE_TASK_HOPS = 16;
  * check on the stampede guard, keyed off the same constant.
  */
 export declare const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25000;
+/**
+ * Why a capture attempt refused to store its shell
+ * (ShellCaptureDebugEvent.refusal, `caches.refusal` on a `router.prerender()`
+ * result): `identity` (a request-scoped read: cookies(), headers(), the
+ * theme, a `{ cache: false }` variable), `dynamic` (`ctx.dynamic()`),
+ * `loader` (a `{ ssr: false }` loader rejected, or settled with
+ * redirect()/notFound()), `no-record` (no doc record: the route's cache()
+ * refused the write, or the handler output failed), `handles` (a pushed
+ * handle value did not finish encoding), `size` (over the store's value
+ * limit), `record-expired` (the route cache() record the capture wrote ran
+ * out first), `invalidated` (a tag of the shell was invalidated after the
+ * capture started), `uncacheable` (the store cannot hold the entry).
+ */
+export type ShellCaptureRefusal = "identity" | "dynamic" | "loader" | "no-record" | "handles" | "size" | "record-expired" | "invalidated" | "uncacheable";
 /**
  * Shared PPR loader-lane hint, appended to every capture warning or error
  * whose fix depends on the lane (shell-capture.ts warnings, the cookie-store.ts

package/dist/types/rsc/shell-capture.d.ts

@@ -19,6 +19,7 @@
  * (variables, cache store). Guarding is serve-time.
  */
 import { type MatchResult } from "../types.js";
+import { type ShellCaptureRefusal } from "./shell-capture-constants.js";
 import { type RequestContext, type RouteRecordWindow } from "../server/request-context.js";
 import { type HandleStore } from "../server/handle-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
@@ -170,6 +171,8 @@ export interface ShellCaptureDebugEvent {
     untaggedBake?: true;
     /** Outcome reported by a store that supports shell-write acknowledgements. */
     storeWrite?: "stored" | "invalidated" | "uncacheable";
+    /** Why a `refused` attempt refused. */
+    refusal?: ShellCaptureRefusal;
     /** Consecutive failure count in the key's backoff entry, when one exists. */
     backoffFailures?: number;
     /** Ms remaining in the key's backoff window, when one exists. */
@@ -335,6 +338,15 @@ export interface ShellCaptureDescriptor {
      * re-render the page and drop the isolate's memo of the shell just stored.
      */
     storedSeqAtRead?: number;
+    /**
+     * A `router.prerender()` warm's capture (rsc-rendering.ts shellServePlan):
+     * one explicit call that must store, so the guards that shed a herd of
+     * visitors do not apply to it. scheduleShellCapture skips the in-flight
+     * dedup and the refused-capture backoff, and attemptCapture waits longer on
+     * the write barrier. Every correctness guard, the inert-store skip and the
+     * queue limits still decide.
+     */
+    force?: true;
 }
 /** The latest stored capture's sequence number for `key` in this isolate, or 0. */
 export declare function lastStoredCaptureSeq(key: string): number;
@@ -400,7 +412,7 @@ type CaptureTaskOutcome = "stored" | "redirect" | "no-shell";
  * the warning. A plain mutable bag, not a return value: captureAndStoreShell's
  * outcome type stays a string union producer B consumes unchanged.
  */
-type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "untaggedBake" | "storeWrite" | "recordSettleMs" | "entryBytes"> & {
+type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "untaggedBake" | "storeWrite" | "refusal" | "recordSettleMs" | "entryBytes"> & {
     /**
      * Why a no-shell attempt ran out of ppr.captureTimeout (the match, the
      * handler output, or the prerender after them). A set cause skips the
@@ -462,6 +474,7 @@ export type CaptureRecordOutcome = {
     reason: string;
 } | {
     kind: "refused";
+    refusal: ShellCaptureRefusal;
 };
 /**
  * Record-first capture: the doc record is both the settle signal and the

package/dist/types/rsc/shell-serve.d.ts

@@ -274,7 +274,7 @@ export declare function warnPprWindowCappedOnce(routeName: string, ppr: {
  * Whether a partitioned request needs no build-shell probe: its route was
  * already warned, or its path was already found without one.
  */
-export declare function partitionBuildShellCheckDone(pathname: string, routeName: string | undefined): boolean;
+export declare function partitionBuildShellCheckDone(routerId: string, pathname: string, routeName: string | undefined): boolean;
 /**
  * Record a partitioned request's build-shell probe, and warn once per route
  * when it found one: the route has a build-time shell its requests cannot
@@ -285,7 +285,7 @@ export declare function partitionBuildShellCheckDone(pathname: string, routeName
  * declared-intent-cannot-be-honored doctrine as the warnings above; a path
  * with no build shell stays silent.
  */
-export declare function notePartitionBuildShellCheck(pathname: string, routeName: string | undefined, found: boolean): void;
+export declare function notePartitionBuildShellCheck(routerId: string, pathname: string, routeName: string | undefined, found: boolean): void;
 /**
  * @internal Reset the serve path's once-per-key warnings (the shell path's
  * one registry), its build-shell probe memo and buffered tail timings. Tests

package/dist/types/rsc/ssr-module-loader.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The SSR module loader a handler created without `loadSSRModule` falls back
+ * to in tests (`router.fetch` creates its handler that way). A leaf with no
+ * runtime imports: testing/serve-shell-request.ts installs its stub here when
+ * it loads, without importing rsc/handler.ts (which binds build-only virtual
+ * modules a flight-only test config does not alias).
+ */
+import type { LoadSSRModule } from "./types.js";
+/**
+ * @internal Tests only: `router.prerender()` warms through `router.fetch`,
+ * and the rsc Vitest project cannot run `import.meta.viteRsc.loadModule`.
+ */
+export declare function setDefaultSSRModuleLoaderForTests(loader: LoadSSRModule | undefined): void;
+/** @internal Undefined everywhere but in tests. */
+export declare function defaultSSRModuleLoaderForTests(): LoadSSRModule | undefined;

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

@@ -103,6 +103,14 @@ export interface RscPayload {
         ok: boolean;
         data: unknown;
     };
+    /**
+     * useActionState form state of a progressive-enhancement POST re-render
+     * (the value the SSR render received). Present only on that document; the
+     * browser entry passes it to hydrateRoot so the hydrated hook matches the
+     * server HTML instead of resetting to its initial state. A promise so a
+     * state Flight cannot serialize rejects this slot alone.
+     */
+    formState?: Promise<ReactFormState>;
 }
 /**
  * React form state type for useActionState progressive enhancement

package/dist/types/segment-boundary-content.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from "react";
+/**
+ * What a RouteContentWrapper receives as `content`.
+ *
+ * Browser: hand over the settled value. React treats a promise as fulfilled
+ * only after it has read it, and a boundary on screen handed a promise it has
+ * not read, in a render that cannot wait, shows its fallback. A component that
+ * is already a promise (a Flight-streamed segment) is returned as is, since
+ * it can really be pending.
+ *
+ * Server: a fresh `Promise.resolve(component)` per call, so Suspense emits the
+ * fallback in the streamed HTML. A shared resolved promise would carry React's
+ * `.status` across requests and skip it.
+ *
+ * @internal
+ */
+export declare function getBoundaryContent(component: ReactNode): ReactNode;

package/dist/types/segment-loader-promise.d.ts

@@ -10,12 +10,8 @@ import type { ResolvedSegment } from "./types.js";
  */
 export declare function buildLoaderPromise(loaders: ResolvedSegment[]): Promise<any[]>;
 /**
- * Memoize an aggregate Promise.all for a set of loader segments. Reusing the
- * same aggregate across renders — invalidated only when any underlying
- * loader.loaderData ref changes — keeps React's `use()` in "known fulfilled"
- * state and prevents a fresh Promise.all from suspending (and briefly
- * committing the Suspense fallback) on every partial update that doesn't
- * actually change loader data.
+ * The aggregate for a set of loader segments, memoized on their `loaderData`
+ * refs: the settled array once it has fulfilled, the promise before that.
  *
  * @internal
  */

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

@@ -8,6 +8,15 @@ import { type RouterVersions, type RouterVersionsTable } from "../router-version
  * 3. `VERSION` for both: the dev stamp, bumped on every RSC module edit.
  */
 export declare function resolveRouterVersions(routerId: string | undefined, override?: string): RouterVersions;
+/**
+ * The version an on-demand prerender overlay key carries: the router's data
+ * version, because the overlay stores segment data, as the segment cache does
+ * (a client-only deploy keeps both). The write side (`router.prerender`,
+ * router.ts) and the read side (rsc/handler.ts) both call this with
+ * `createRouter({ version })`, the only override the trigger can see, so they
+ * cannot disagree; a `createRSCHandler({ version })` does not move it.
+ */
+export declare function resolvePrerenderVersion(routerId: string | undefined, routerVersion: string | undefined): string;
 /**
  * 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