@rangojs/router 0.21.0 → 0.22.1

package/dist/types/server/context.d.ts

@@ -3,6 +3,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import type { ReactNode } from "react";
 import type { PartialCacheOptions, ErrorBoundaryHandler, Handler, LoaderDefinition, MiddlewareFn, NotFoundBoundaryHandler, ShouldRevalidateFn, TransitionConfig } from "../types";
 import type { ContextVar } from "../context-var.js";
+import { type WarmContext } from "../prerender/warm-request.js";
 /**
  * Performance metric entry for a single measured operation
  *
@@ -219,8 +220,11 @@ export type EntryData = ({
         getParams?: (ctx: any) => Promise<any[]> | any[];
         options?: {
             concurrency?: number;
+            onDemand?: import("../prerender/on-demand.js").OnDemandOption;
         };
     };
+    /** Set when the route opted into on-demand prerender (Prerender(..., { onDemand })) */
+    isOnDemand?: true;
     /** Set when route is wrapped with Passthrough() — has a separate live handler */
     isPassthrough?: true;
     /** Live handler for runtime fallback (only set on Passthrough routes) */
@@ -341,6 +345,7 @@ export declare const getContext: () => {
     getStore: () => HelperContext;
     getParent: () => EntryData | null;
     getOrCreateStore: (forRoute?: string) => HelperContext;
+    runIsolated: <T>(forRoute: string, callback: () => T) => T;
     getNextIndex: (type: (string & {}) | "layout" | "parallel" | "middleware" | "revalidate") => string;
     getShortCode: (type: "layout" | "parallel" | "route" | "loader" | "cache") => string;
     run: <T>(namespace: string, parent: EntryData | null, callback: (...args: any[]) => T) => T;
@@ -483,12 +488,12 @@ export interface IdentityReadWording {
  * response directives (invalidateClientCache(), keepClientCache()) record
  * nothing and are not captured reads: they take refuseInCacheScope alone.
  */
-export declare function guardIdentityRead(ctx: unknown, surface: string, wording: IdentityReadWording): void;
+export declare function guardIdentityRead(ctx: WarmContext | null | undefined, surface: string, wording: IdentityReadWording): void;
 /**
  * Steps 2 and 3 of guardIdentityRead: throw when a "use cache" body or a
  * cache() boundary would store what `surface` produces.
  */
-export declare function refuseInCacheScope(surface: string, { verb, fix }: IdentityReadWording): void;
+export declare function refuseInCacheScope(surface: string, { verb, fix }: IdentityReadWording, ctx?: WarmContext | null): void;
 /**
  * The capture refusal for a request-scoped read (cookies(), headers(), a
  * { cache: false } variable): the message after the surface, and the fix the
@@ -502,7 +507,7 @@ export declare function requestReadCaptureFix(what: string): Pick<IdentityReadWo
  * scope lookups. `requestCtx` is the ambient request context, whose capture
  * flag the guard reads.
  */
-export declare function assertNonCacheableReadAllowed(keyOrVar: string | ContextVar<unknown>, requestCtx?: unknown): void;
+export declare function assertNonCacheableReadAllowed(keyOrVar: string | ContextVar<unknown>, requestCtx?: WarmContext | null): void;
 /** How the identity error words a read: a function call or a property read. */
 export type LoaderIdentityReadVerb = "called" | "read";
 /** A request-identity read a loader execution made (recordLoaderIdentityRead). */
@@ -598,7 +603,10 @@ export declare function latchCachedHeaderScope(kind: CachedHeaderScope["kind"],
 export declare function isInsideAnyLoaderScope(): boolean;
 /**
  * The one ppr opt-in predicate: a page route entry that DECLARED `ppr`
- * (`false` and undefined mean plain axis 1). Shared by the serve path
+ * (`false`, undefined, and on-demand routes mean plain axis 1). A writable
+ * prerender refresh cannot atomically replace the separate document shell, so
+ * combining those lanes would pair a fresh tail with a stale prelude. Shared by
+ * the serve path
  * (rsc/shell-serve.ts resolvePprConfig) and the header-write latch below so
  * the two layers can never drift on what counts as a ppr route.
  */

package/dist/types/server/handle-store.d.ts

@@ -218,6 +218,8 @@ export interface HandleStore {
      * value are omitted; undefined when none has one.
      */
     getRecordOwners(segmentId: string): Record<string, (string | null)[]> | undefined;
+    /** The segment ids for which getRecordOwners returns an entry. */
+    getOwnedSegmentIds(): string[];
     /**
      * Replay cached handle data back into the store (for cache hits).
      * Used to restore handle data when serving cached segments.

package/dist/types/server/request-context.d.ts

@@ -19,7 +19,7 @@ import type { Handle } from "../handle.js";
 import { type ContextVar } from "../context-var.js";
 import { type HandleStore, type HandleData } from "./handle-store.js";
 import { type MetricsStore } from "./context.js";
-import type { SegmentCacheStore } from "../cache/types.js";
+import type { SegmentCacheStore, ShellSnapshotHandlesValue } from "../cache/types.js";
 import type { RouterVersions } from "../router-versions.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
@@ -204,6 +204,25 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     _pprReplayPostMatchReason?: "prerender-store" | "intercept";
     /** @internal Cache store for segment caching (optional, used by CacheScope) */
     _cacheStore?: SegmentCacheStore;
+    /**
+     * @internal Env-scoped writable prerender store (the durable overlay) plus the
+     * deployment identity for build-scoped keys, resolved per request from the
+     * `prerender` router option. Read by the serve-path overlay lookup before the
+     * bundled build manifest. Absent when no prerender store is configured.
+     */
+    _prerender?: import("../prerender/on-demand.js").ResolvedPrerender<any>;
+    /**
+     * @internal Set only on the requestless on-demand producer's context. When
+     * present, the standalone request-scoped READS — `cookies()`, `headers()`,
+     * `invalidateClientCache()`, `keepClientCache()` — throw a
+     * PrerenderPersonalizationError so a personalized render is skipped rather than
+     * baked into a shared payload. Response MUTATIONS on the producer context
+     * (`ctx.setStatus`/`header`/`setCookie`) stay silent no-op stubs, matching
+     * build-time prerender (the design's "throw or skip" contract permits skip):
+     * they write to a discarded synthetic response, so there is nothing to leak.
+     * Never set on the live request path.
+     */
+    _onDemandProducer?: true;
     /**
      * @internal Compiled `cache.searchParams` filter for default cache-key
      * generation (undefined = "all", the byte-stable unfiltered format). Set
@@ -272,6 +291,20 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * cache miss.
      */
     _shellForcedMiss?: true;
+    /**
+     * @internal This request is a router.prerender() warm
+     * (prerender/warm-request.ts). In `replace` mode every runtime cache read
+     * misses (isWarmReplace); the layers report into the record. A capture's
+     * derived context inherits it through the prototype.
+     */
+    _prerenderWarm?: import("../prerender/warm-request.js").PrerenderWarmRecord;
+    /**
+     * @internal Runs a callback in the async context this request entered the
+     * handler with (captureRequestEntryContext). router.prerender() dispatches
+     * a warm through it when called from inside a request. Absent where the
+     * runtime has no AsyncLocalStorage.snapshot.
+     */
+    _runAtRequestEntry?: <T>(fn: () => T) => T;
     /**
      * @internal The freshness window of the route cache() records this
      * request read or wrote (cache-scope.ts noteRouteRecordWindow), as ms
@@ -361,6 +394,8 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
          * host) and miss the record.
          */
         fixedDocKey?: string;
+        /** @internal The snapshot's `handles` record (ShellSnapshotHandlesValue). */
+        prerenderHandles?: ShellSnapshotHandlesValue;
         /**
          * @internal Set ONLY by matchPartialWithPprReplay on the navigation-replay
          * serve path. Its presence arms the explicit-scope composition in
@@ -672,6 +707,17 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * deriveShellCaptureContext gives the capture its own.
      */
     _renderErrors?: unknown[];
+    /**
+     * @internal Rejections of streamed (loading()) handlers that were recovered
+     * into a declared errorBoundary()/notFoundBoundary() fallback, by segment id.
+     * The recovered promise resolves, so Flight reports nothing; cacheRoute
+     * (cache-scope.ts) refuses a write only when one of ITS segments is listed,
+     * the granularity a Flight error row has. The same errors are also pushed to
+     * `_renderErrors` for the document cache and PPR shell capture. A render
+     * under a derived context (shell capture, SWR re-render) owns its own map.
+     * Allocated on the first recovery.
+     */
+    _recoveredHandlerErrors?: Map<string, unknown>;
     /**
      * @internal Report a non-fatal background error through the router's
      * onError callback. Wired by the RSC handler / router during request
@@ -757,7 +803,7 @@ export interface RouteRecordWindow {
  * This is the type exported to library consumers. Internal code should
  * use the full RequestContext interface directly.
  */
-export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "_readCookie" | "_readCookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhenRefs" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureUnrecordedLoaderPush" | "_shellCaptureLoaderLanes" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_routeRecordWindow" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "_locationState" | "_routeName" | "_prevRouteKey" | "_inActionRevalidation" | "_reportedErrors" | "_renderErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_versions" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_freshReads" | "_setFreshReadsCookie" | "_requestRoot" | "_requestStart" | "_responseSent" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
+export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "_readCookie" | "_readCookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhenRefs" | "_pprReplayPostMatchReason" | "_cacheStore" | "_prerender" | "_onDemandProducer" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureUnrecordedLoaderPush" | "_shellCaptureLoaderLanes" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_prerenderWarm" | "_runAtRequestEntry" | "_routeRecordWindow" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "_locationState" | "_routeName" | "_prevRouteKey" | "_inActionRevalidation" | "_reportedErrors" | "_renderErrors" | "_recoveredHandlerErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_versions" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_freshReads" | "_setFreshReadsCookie" | "_requestRoot" | "_requestStart" | "_responseSent" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
 /**
  * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
  * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:
@@ -766,6 +812,15 @@ export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, str
  * @internal
  */
 export declare const UNTRACKED_BACKGROUND_TASK: unique symbol;
+/**
+ * Capture the current async context (RequestContext._runAtRequestEntry), taken
+ * on handler entry before any router scope, so a nested dispatch (a
+ * router.prerender() warm called from a handler, loader or action) does not
+ * inherit the caller's route-definition, loader and cache-scope state. Per
+ * request: workerd refuses a snapshot outside the request that created it.
+ * See docs/design/prerender-every-route.md.
+ */
+export declare function captureRequestEntryContext(): (<T>(fn: () => T) => T) | undefined;
 /**
  * Run a function within a request context
  * Used by the RSC handler to provide context to server actions
@@ -813,6 +868,12 @@ export interface CreateRequestContextOptions<TEnv> {
     initialResponse?: Response;
     /** Optional cache store for segment caching (used by CacheScope) */
     cacheStore?: SegmentCacheStore;
+    /**
+     * Optional env-scoped writable prerender store + deployment identity (the
+     * durable overlay), resolved per request by the RSC handler from the
+     * `prerender` router option.
+     */
+    prerender?: import("../prerender/on-demand.js").ResolvedPrerender<any>;
     /**
      * Compiled `cache.searchParams` filter from the resolved handler cache
      * config (handler.ts). Stored as _searchParamsFilter.

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

@@ -0,0 +1,26 @@
+import { type ReactNode } from "react";
+import { type BoundaryAudit } from "./suspense-audit.js";
+/**
+ * One boundary: what each render hands it, what each commit carries, and its
+ * mount. Called above the Suspense, which commits while the content waits.
+ * `streams` and `nodes` are what else its content waits for (I3 only).
+ */
+export declare function useBoundaryAudit(boundary: string, segmentId: string, value: unknown, streams?: Record<string, unknown>, nodes?: unknown): BoundaryAudit;
+/** The boundary's content is on screen. */
+export declare function useRevealAudit(rec: BoundaryAudit): void;
+/**
+ * One `useLoader` read of a per-loader stream (I1, I2 at the read site). A
+ * read that suspends while mounting keeps no record: only a reader on screen
+ * is audited.
+ */
+export declare function useReadAudit(loaderId: string, stream: unknown): void;
+/** Wraps a boundary's fallback: mounted means the fallback is on screen. */
+export declare function AuditedFallback({ audit, children, }: {
+    audit: BoundaryAudit;
+    children: ReactNode;
+}): ReactNode;
+/** Wraps a segment's outlet children: the segment's mount (I4). */
+export declare function AuditedOutlet({ segmentId, children, }: {
+    segmentId: string;
+    children: ReactNode;
+}): ReactNode;

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

@@ -0,0 +1,157 @@
+export type SuspenseAuditKind = "swap" | "untracked" | "idle-fallback" | "resuspended" | "remount" | "drift" | "uncaused" | "mutated";
+/** What may hand React a tree (I6). */
+export type TreeUpdateCause = "navigation" | "popstate" | "stale-revalidation" | "action" | "error" | "hmr";
+export interface SuspenseAuditEvent {
+    /** I1 swap, I2 untracked, I3 idle-fallback and resuspended, I4 remount, I5 drift, I6 uncaused, I7 mutated. */
+    kind: SuspenseAuditKind;
+    /** `content:<segment id>`, `loaders:<outlet key>`, `outlet:<segment id>`, `read:<loader id>`, `segment:<segment id>`. */
+    boundary: string;
+    detail: string;
+    url: string;
+    at: number;
+}
+export interface SuspenseAuditReport {
+    swaps: number;
+    untracked: number;
+    idleFallbacks: number;
+    resuspended: number;
+    remounts: number;
+    drifts: number;
+    uncaused: number;
+    mutations: number;
+    /**
+     * Not a violation: fallbacks the router cannot attribute. Nothing it handed
+     * the boundary was a promise React read, so the content's own suspension
+     * put the fallback up: an app's use(), a React.lazy, a client reference.
+     */
+    unattributedFallbacks: number;
+    /** Not a violation: tree updates React was handed, by cause ("none" without one). */
+    treeUpdates: Record<string, number>;
+    /**
+     * Not a violation: the distinct thenables each boundary or read was handed.
+     * One per value it waited for; two for one navigation is a gate replaced
+     * by the real promise.
+     */
+    readonly handed: Record<string, number>;
+    /**
+     * Not a violation: fallbacks shown over content on screen while what the
+     * boundary waits for was pending. An urgent commit does that by design.
+     */
+    shownWhilePending: number;
+    /** Mounts per boundary since the document loaded. */
+    readonly mounts: Record<string, number>;
+    /** The last events, oldest first. */
+    events: SuspenseAuditEvent[];
+    reset(): void;
+}
+/** One boundary, or one `useLoader` read. Lives as long as its fiber. */
+export interface BoundaryAudit {
+    boundary: string;
+    /** Segment id, for the place in the tree. */
+    segmentId: string;
+    /** The React key the segment was mounted under (I4 identity). */
+    key: string;
+    /** 0 until the boundary is on screen. */
+    mountId: number;
+    /** Last value a render ran with, and the URL it ran under. */
+    seen: unknown;
+    hasSeen: boolean;
+    seenUrl: string;
+    /** Last value a commit carried. */
+    committed: unknown;
+    hasCommitted: boolean;
+    /** What else the boundary's content waits for: per-loader streams, nodes. */
+    streams: Record<string, unknown> | undefined;
+    nodes: unknown;
+    /** The content has been on screen. */
+    revealed: boolean;
+    /** The fallback's effect was cleaned up in this task (auditFallback). */
+    fallbackGone: boolean;
+}
+export declare function createBoundaryAudit(boundary: string, segmentId: string): BoundaryAudit;
+/**
+ * Render phase: the value this render hands the boundary.
+ *
+ * I1: a boundary on screen was handed a thenable that is still pending, and
+ * is handed another one that is not already settled, for the same URL. React
+ * starts waiting again. A settled replacement is read at once, and another
+ * URL is another navigation: both are exempt.
+ * I2: a boundary whose content has been on screen is handed a native promise
+ * React has not read, and React finds it settled when it reads it. A render
+ * that cannot wait suspends on it and commits the fallback over the content,
+ * which React keeps up for 300 ms. Judged from the status React leaves on
+ * the promise when it reads it in the same task.
+ */
+export declare function auditHandover(rec: BoundaryAudit, value: unknown): void;
+/** Commit phase: what the boundary on screen now reads. */
+export declare function auditCommit(rec: BoundaryAudit, value: unknown, streams?: Record<string, unknown>, nodes?: unknown): void;
+export declare function auditReveal(rec: BoundaryAudit): void;
+/** One `useLoader` read on screen: it has a mount and reveals with it. */
+export declare function auditRead(rec: BoundaryAudit, stream: unknown): void;
+/**
+ * How the audit learns that a payload is still streaming: the event
+ * controller, set at boot (browser/rsc-router.tsx). Not read from
+ * NavigationStoreContext in AuditedFallback: see the header.
+ */
+export declare function setSuspenseAuditStreamProbe(probe: () => boolean): void;
+/**
+ * I3: the boundary's fallback is on screen with nothing to wait for: nothing
+ * the router handed the boundary is pending, no payload is streaming and no
+ * client reference is loading. `idle-fallback` on a boundary new to the page,
+ * `resuspended` when the fallback replaced content that had been on screen.
+ *
+ * Reported only when the router owns the fallback: React suspended on a
+ * promise the router handed unread that was already settled (`needless`).
+ * Any other fallback is the content's own (an app's use(), a React.lazy, a
+ * client reference) and is counted as `unattributedFallbacks`, not reported,
+ * also when the boundary holds a promise React has read.
+ *
+ * A fallback over content on screen while something is pending is counted
+ * (`shownWhilePending`) and not reported: an urgent commit does that by
+ * design (transition({ when }) gated off, #995), and so does dev while a
+ * client reference loads.
+ */
+export declare function auditFallback(rec: BoundaryAudit): () => void;
+/** One renderSegments call, collected while it builds. */
+export interface TreeAudit {
+    /** Segment ids, leaf first while building, root first once finished. */
+    order: string[];
+    keys: Map<string, string>;
+    types: Map<string, string>;
+    chains: Map<string, string[]>;
+    /** Segments this tree remounts by the documented rules. */
+    replaced: Set<string>;
+    /** The segment objects the tree is built from (I7), until it is held. */
+    segments: object[];
+}
+export declare function startTreeAudit(): TreeAudit | undefined;
+/** The element renderSegments built for one segment, leaf first. */
+export declare function auditSegmentElement(tree: TreeAudit | undefined, id: string, type: string, key: string, element: unknown, outletTransition: boolean, slots: readonly string[], segments: readonly object[]): void;
+/**
+ * A finished tree. The first is the document's, which React holds from
+ * hydration; any later one is held when an emit hands its root to React
+ * (auditTreeUpdate).
+ */
+export declare function finishTreeAudit(tree: TreeAudit | undefined, root: unknown): void;
+/**
+ * I4: a boundary that stays on the page under the same React key is
+ * unmounted and mounted again. A different key is the documented remount.
+ */
+export declare function auditMount(rec: BoundaryAudit): void;
+export declare function auditUnmount(rec: BoundaryAudit): void;
+/**
+ * I6: the cause of the tree update the caller emits next, in the same task.
+ * It does not outlive the task: an emit after an await names its cause again,
+ * or a cause left behind would cover an emitter that names none.
+ */
+export declare function auditTreeCause(cause: TreeUpdateCause): void;
+/**
+ * I6: a tree update reached React (the store.onUpdate subscriber in
+ * browser/react/NavigationProvider.tsx), with the root it hands React. Only a
+ * navigation, a back/forward, its stale revalidation, an action, an error and
+ * HMR hand React a tree; anything else updates in place through a store its
+ * readers subscribe to, or through a pending promise read with use().
+ */
+export declare function auditTreeUpdate(root?: unknown): void;
+/** Forget every tree and mount seen so far. For tests of the audit itself. */
+export declare function forgetSuspenseAudit(): void;

package/dist/types/testing/action-form.d.ts

@@ -0,0 +1,34 @@
+/**
+ * createActionForm: the FormData a browser posts when a form is submitted
+ * before hydration (no JavaScript), for a server action.
+ *
+ * React's server render writes hidden fields on the form so the POST names its
+ * action and carries the bound state; decodeAction / decodeFormState read them
+ * back. A test cannot render those fields (react-dom/server does not load under
+ * the react-server condition), so this builds the same wire format and
+ * registers the action where the plugin-rsc stub's decodeAction resolves it,
+ * tagged as a server reference like a built "use server" export so the bound
+ * action keeps its `$$id` (onError's actionId, the action phase label).
+ * Post the result with `serveShellRequest(router, url, { form })`.
+ */
+/** Options for {@link createActionForm}. */
+export interface CreateActionFormOptions {
+    /**
+     * The action's reference id, `<module id>#<export name>`, as the build gives
+     * a "use server" export. Any unique string of that shape in a test.
+     */
+    id: string;
+    /**
+     * A `useActionState` form (default): the action runs as `(prevState, formData)`
+     * and the POST carries the state key. false: a plain `<form action={fn}>`
+     * ($ACTION_ID_), the action runs as `(formData)`.
+     */
+    useActionState?: boolean;
+    /** The form's own fields, as the person filled them. */
+    fields?: Record<string, string>;
+}
+/**
+ * Build a no-JS form POST body for `action` and register it so a handler
+ * decodes it back to `action`.
+ */
+export declare function createActionForm(action: (...args: any[]) => unknown, options: CreateActionFormOptions): FormData;

package/dist/types/testing/flight.entry.d.ts

@@ -30,5 +30,7 @@ export { renderServerTree, findClientBoundaries, findElements, textContent, asse
 export type { RenderServerTreeOptions, RenderServerTreeResult, ClientBoundary, BoundarySelector, FoundElement, ElementSelector, } from "./flight-tree.js";
 export { renderHandler } from "./render-handler.js";
 export type { TestableHandler, RenderHandlerOptions, RenderHandlerResult, StateCookieSeed, } from "./render-handler.js";
+export { createActionForm } from "./action-form.js";
+export type { CreateActionFormOptions } from "./action-form.js";
 export { serveShellRequest, resetShellTestState, } from "./serve-shell-request.js";
 export type { ServeShellRequestOptions, ServeShellRequestResult, ShellRequestHandles, } from "./serve-shell-request.js";

package/dist/types/testing/index.d.ts

@@ -43,6 +43,10 @@ export { runClientRevalidate } from "./run-client-revalidate.js";
 export type { RunClientRevalidateOptions } from "./run-client-revalidate.js";
 export { dispatch } from "./dispatch.js";
 export type { DispatchOptions } from "./dispatch.js";
+export { createMemoryPrerenderStore } from "../prerender/memory-prerender-store.js";
+export type { MemoryPrerenderStore, MemoryPrerenderStoreOptions, } from "../prerender/memory-prerender-store.js";
+export type { WritablePrerenderStore, PrerenderStoredEntry, PrerenderKey, } from "../prerender/writable-store.js";
+export type { PrerenderConfig, PrerenderResult, PrerenderWarmCaches, } from "../prerender/on-demand.js";
 export { assertCacheStatus, assertCacheDecision, parseCacheHeader, createCacheSink, filterCacheDecisions, } from "./cache-status.js";
 export type { ExpectedCacheStatus, CacheStatusTarget, CacheSink, } from "./cache-status.js";
 export type { TelemetryEvent, TelemetrySink, CacheDecisionEvent, CacheSegmentSignal, CacheSegmentStatus, } from "../router/telemetry.js";

package/dist/types/testing/internal/server-modules.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Register `exports` as the server module `id`, merging into an earlier call.
+ * The module object is kept and mutated: the stub's require is memoized per
+ * id, so a later export must appear on the object it first returned.
+ */
+export declare function registerServerModule(id: string, exports: Record<string, unknown>): void;
+/** The module a decoded server reference resolves to. */
+export declare function loadServerModule(id: string): Record<string, unknown>;

package/dist/types/testing/serve-shell-request.d.ts

@@ -27,6 +27,14 @@
  * capture refuses for a root postpone (a live loader read with no boundary
  * above it) or an SSR render error is captured here.
  *
+ * A `Prerender` route serves its handler layer from the artifact
+ * `router.matchForPrerender` bakes for the URL (on its first request, kept
+ * until resetShellTestState), through the production prerender store. Its
+ * first `ppr` request is a MISS with a runtime capture, as a URL without a
+ * build-time shell is in production; build-time shells are e2e-only. An
+ * on-demand route (`Prerender(..., { onDemand })`) bakes nothing here: it
+ * serves from its prerender store, as a refresh-only page does in production.
+ *
  * Must run under the `react-server` condition (the rsc Vitest project), with
  * `rangoTestAliases()` resolving `@vitejs/plugin-rsc/rsc/server` to the stub
  * that carries the Flight runtime.
@@ -60,6 +68,14 @@ export interface ServeShellRequestOptions<TEnv = any> {
         from?: string;
         segments?: readonly string[];
     };
+    /**
+     * POST this form as a submit before hydration: the no-JS request the
+     * progressive-enhancement path runs the action for and re-renders the page
+     * after. Build it with `createActionForm`. The response is the document
+     * (`flight` is its payload, `formState` what the SSR render received).
+     * Not with `partial`.
+     */
+    form?: FormData;
 }
 /** A response's handle data, as the browser consumes it. */
 export interface ShellRequestHandles {
@@ -117,17 +133,31 @@ export interface ServeShellRequestResult {
      * values resolved. Undefined when no Flight was rendered.
      */
     readHandles(): Promise<ShellRequestHandles | undefined>;
+    /**
+     * The form state the SSR render received (the `formState` render option),
+     * or undefined when it received none.
+     */
+    formState: unknown;
+    /**
+     * The payload's `formState` as the browser reads it, the value the entry
+     * hands `hydrateRoot`. Undefined when the payload carries none (or no
+     * Flight was rendered). Rejects when the action's state is not
+     * Flight-serializable: the document still renders, and the entry
+     * hydrates without it.
+     */
+    readPayloadFormState(): Promise<unknown>;
 }
 /**
  * Reset the per-isolate PPR state requests leave behind, so the next test
  * starts as a fresh worker would: the capture's stampede guard, its backoff
  * (a refused capture backs its URL off for later tests too), the shell path's
  * once-per-key warnings, the build-shell manifest memo, the "use cache"
- * in-flight leaders and warnings, and CFCacheStore's isolate memos (shells,
+ * in-flight leaders and warnings, CFCacheStore's isolate memos (shells,
  * tag markers, tag hints) and warnings, which every CFCacheStore in the
- * process shares by namespace and URL. Call it in `beforeEach`, never while
- * a request is in flight. VercelCacheStore's memos live on the `cache`
- * handle it is given: a new handle starts empty.
+ * process shares by namespace and URL, and the Prerender artifacts baked so
+ * far. Call it in `beforeEach`, never while a request is in flight.
+ * VercelCacheStore's memos live on the `cache` handle it is given: a new
+ * handle starts empty.
  */
 export declare function resetShellTestState(): Promise<void>;
 /**

package/dist/types/testing/shell-status.d.ts

@@ -15,7 +15,7 @@
  * 2. **Smallest status signals:** `x-rango-shell` (`HIT` | `MISS`) on document
  *    GETs, and `x-rango-ppr-replay` on partial requests to ppr routes. A replay
  *    HIT is reported only when matching consumes the captured segment record.
- *    Secondary unit signal: `store.getShell(shellCacheKey(url))` after a real
+ *    Secondary unit signal: `store.getShell(shellCacheKey(router, url))` after a real
  *    capture flush (background `putShell`). There is no Flight flag for shell HIT.
  *
  * 3. **A real MISS → capture → HIT in unit tests:** `serveShellRequest`
@@ -68,10 +68,16 @@ export interface ShellCachePartition {
     generated?: readonly string[];
 }
 /**
- * Shell store key for a document URL: the production `buildShellKey` (host +
- * pathname + sorted search + `:shell`) and `partitionShellKey`, both from the
- * React-free leaf `rsc/shell-capture-constants.ts`, so the testing barrel never
- * imports the shell-serve module (it pulls React).
+ * Shell store key of `router` for a document URL: the production
+ * `buildShellKey` (router id + host + pathname + sorted search + `:shell`)
+ * and `partitionShellKey`, both from the React-free leaf
+ * `rsc/shell-capture-constants.ts`, so the testing barrel never imports the
+ * shell-serve module (it pulls React).
+ *
+ * `router` is the router that serves the URL, or anything carrying its `id`
+ * (`{ id }` where the router cannot be imported, as in a Playwright test). A
+ * shell belongs to one router: two routers serving one host and path keep
+ * two entries.
  *
  * Accepts a `URL` or an absolute/relative request URL string (relative strings
  * resolve against `http://localhost`). Pass the router's `cache.searchParams`
@@ -86,7 +92,9 @@ export interface ShellCachePartition {
  * - store `keyGenerator` results, with or without `key()` results, as
  *   `{ keys, generated }` (see {@link ShellCachePartition}).
  */
-export declare function shellCacheKey(url: URL | string, searchParams?: CacheSearchParams, partition?: string | readonly string[] | ShellCachePartition): string;
+export declare function shellCacheKey(router: {
+    readonly id: string;
+}, url: URL | string, searchParams?: CacheSearchParams, partition?: string | readonly string[] | ShellCachePartition): string;
 /**
  * Read `x-rango-shell` from a response. Returns `null` when the header is
  * absent (axis-1 / non-ppr / ineligible request).

package/dist/types/testing/vitest-stubs/plugin-rsc.d.ts

@@ -16,8 +16,11 @@
  *
  * Without the condition React's server build refuses to load, so the codec
  * functions throw and a "use cache" call runs uncached. Any other load failure
- * (a moved vendored path, a missing peer) throws. The action entries stay
- * inert either way: no primitive decodes an action request.
+ * (a moved vendored path, a missing peer) throws. decodeAction and
+ * decodeFormState decode a no-JS form POST under the condition, resolving its
+ * action from the modules createActionForm() registered, as do
+ * `loadServerAction` and `decodeReply` for a plain form action. Without the
+ * condition they stay inert.
  */
 export declare const renderToReadableStream: (value: unknown, options?: object) => ReadableStream<Uint8Array>;
 export declare const createTemporaryReferenceSet: () => unknown;
@@ -26,7 +29,7 @@ export declare const createFromReadableStream: (stream: ReadableStream<Uint8Arra
 }) => Promise<unknown>;
 export declare const encodeReply: (value: unknown, options?: object) => Promise<string | FormData>;
 export declare const createClientTemporaryReferenceSet: () => unknown;
-export declare const loadServerAction: () => undefined;
-export declare const decodeReply: () => undefined;
-export declare const decodeAction: () => undefined;
-export declare const decodeFormState: () => undefined;
+export declare const loadServerAction: (id: string) => Promise<unknown> | undefined;
+export declare const decodeReply: (body: string | FormData, options?: object) => Promise<unknown> | undefined;
+export declare const decodeAction: (body: FormData) => Promise<unknown> | null | undefined;
+export declare const decodeFormState: (actionResult: unknown, body: FormData) => Promise<unknown> | undefined;

package/dist/types/thenable-status.d.ts

@@ -7,3 +7,9 @@
  * isLoading registration (loader-store.ts), which must agree on "settled".
  */
 export declare function unwrapsSynchronously(stream: Promise<unknown>): boolean;
+/**
+ * A resolved thenable for a use() whose result is ignored: React reads the
+ * "fulfilled" stamp and returns at once. `_debugInfo` keeps React DevTools from
+ * listing a 0 ms promise on every reader that calls it.
+ */
+export declare const SETTLED_THENABLE: Promise<undefined>;

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

@@ -329,6 +329,13 @@ export type InternalHandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch exte
     _responseType?: string;
     /** Route name for cache key scoping (prevents cross-route collisions). */
     _routeName?: string;
+    /**
+     * @internal The on-demand overlay holds a "removed" marker for this request
+     * (tryPrerenderLookup, cache-lookup.ts); gateOnDemandProducer reads it. On
+     * this context, not the request's: withCacheLookup documents that the
+     * request ALS can be lost mid-pipeline on workerd.
+     */
+    _prerenderRemoved?: true;
     /**
      * @internal Loader-cache override table: loaderId -> memoized data promise.
      * A single stable ctx.use interceptor consults this instead of chaining one

package/dist/types/types/route-entry.d.ts

@@ -72,6 +72,11 @@ export interface RouteEntry<TEnv = any> {
      * Used by the non-trie match path to set the `pt` flag.
      */
     passthroughRouteKeys?: Set<string>;
+    /**
+     * Route keys in this entry that opted into on-demand prerender.
+     * Used by the non-trie match path to set the `od` flag.
+     */
+    onDemandRouteKeys?: Set<string>;
     /**
      * Whether this entry is lazily evaluated.
      * When true, routes are populated on first matching request.