@rangojs/router 0.20.0 → 0.22.0

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, } from "./serve-shell-request.js";
+export type { ServeShellRequestOptions, ServeShellRequestResult, ShellRequestHandles, } from "./serve-shell-request.js";

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

@@ -43,11 +43,17 @@ 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";
 export { assertPprReplayStatus, assertShellStatus, parsePprReplayStatus, parseShellStatus, PPR_REPLAY_STATUS_HEADER, shellCacheKey, SHELL_STATUS_HEADER, } from "./shell-status.js";
 export type { PprReplayBypassReason, PprReplayStatus, ShellCachePartition, ShellStatus, ShellStatusTarget, } from "./shell-status.js";
+export { setBuildVersions } from "./build-versions.js";
+export type { BuildVersions, RouterVersions } from "./build-versions.js";
 export { collectHandle } from "./collect-handle.js";
 export { withLocationStateKey } from "./location-state-key.js";
 export { diffGeneratedRoutes, assertGeneratedRoutesMatch, } from "./generated-routes.js";

package/dist/types/testing/internal/seed-vars.d.ts

@@ -7,6 +7,7 @@
  * client/browser modules).
  */
 import { type ContextVar } from "../../context-var.js";
+import { type RouterVersions } from "../../router-versions.js";
 export interface StateCookieSeed {
     /**
      * Cookie-name prefix, sanitized then composed with `routerId` exactly like
@@ -20,11 +21,15 @@ export interface StateCookieSeed {
      */
     routerId?: string;
     /**
-     * Build version used as the rotated value's prefix (`{version}:{timestamp}`).
-     * Defaults to `"0"` (resolved inside createRequestContext).
+     * The app's version, as `createRouter({ version })` would set it: the
+     * rotated value's prefix (`{version}:{timestamp}`) and the version a cache
+     * store keys with. Defaults to `"0"` for the prefix (resolved inside
+     * createRequestContext) and to the build versions for the store.
      */
     version?: string;
 }
 export declare function resolveSeededStateCookieName(seed?: StateCookieSeed): string;
+/** The request context's `versions` for a seeded `stateCookie.version`. */
+export declare function seededVersions(seed?: StateCookieSeed): RouterVersions | undefined;
 export type VarsInit = Record<string, unknown> | ReadonlyArray<readonly [ContextVar<unknown> | string, unknown]>;
 export declare function seedVariables(variables: Record<string, unknown>, vars?: VarsInit): Record<string, unknown>;

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/location-state-key.d.ts

@@ -6,11 +6,15 @@ import { type LocationStateDefinition } from "../browser/react/location-state-sh
  * use (`MyState(value)`, `useLocationState(MyState)`, `.read()`).
  *
  * - `withLocationStateKey(GridState, "GridState")` sets `__rsc_ls_GridState`
- *   (a name that already starts with `__rsc_ls_` is used as-is).
+ *   (a name that already starts with `__rsc_ls_` is used as-is). A definition
+ *   with `clearOnReload` appends its suffix, so read the stored key back from
+ *   `GridState.__rsc_ls_key` (`__rsc_ls_GridState~r`).
  * - Without a name, a key already set (by the plugin or an earlier call) is
  *   kept; otherwise the definition gets a synthetic `__rsc_ls_test_<n>` key,
  *   which then stays on it.
  *
+ * A name may not contain "~": that separator is reserved for the suffix.
+ *
  * Returns the definition.
  *
  * @example

package/dist/types/testing/render-route.d.ts

@@ -35,11 +35,19 @@
  *     useRouter().replace kind "replace", refresh() kind "revalidate".
  *     Back/forward, action and optimistic clientUrls() swap decisions are
  *     e2e territory.
+ *   - Location state reaches readers the way it does in production:
+ *     NavigationProvider holds the committed entry's state next to the
+ *     payload, so a navigation whose loader the test holds keeps the entry
+ *     being left on screen with its own state. A `popstate` event is a
+ *     back/forward onto the entry history.state holds; the tree has one
+ *     location, so no page is restored with it. A server action's state, a
+ *     redirect's and an intercept's are e2e territory.
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
  * useRouter, usePathname, useSearchParams, Outlet/useOutlet nesting and seeded
  * descendant pending state, useLoader/useFetchLoader (seeded data),
- * useLocationState (seeded), and useHandle (seeded).
+ * useLocationState (seeded, or written by a navigation), and useHandle
+ * (seeded).
  * Basename-mounted apps: pass the `basename` option so useRouter().basename,
  * <Link> prefixing, and useMount/useHref resolve against the mount prefix
  * (without it they resolve at the root "/"). For an include("/shop", ...)
@@ -48,10 +56,10 @@
  */
 import { type ComponentType } from "react";
 import type { RenderResult } from "@testing-library/react";
-import type { NavigationStore } from "../browser/types.js";
+import type { NavigateOptions, NavigationStore } from "../browser/types.js";
 import type { EventController } from "../browser/event-controller.js";
 import type { LoaderDefinition, TransitionConfig } from "../types.js";
-import type { LocationStateDefinition } from "../browser/react/location-state-shared.js";
+import { type LocationStateDefinition } from "../browser/react/location-state-shared.js";
 import type { Handle } from "../handle.js";
 import type { ThemeConfig } from "../theme/types.js";
 import type { PrefetchStrategy } from "../router/prefetch-default.js";
@@ -159,6 +167,8 @@ export interface RenderRouteOptions {
      * `useLocationState(StateDef)`. Like loaders, a real `createLocationState()`
      * handle has an empty injected key in a bare test, so pass `[def, value]`
      * pairs; renderRoute assigns a synthetic key and writes it to `history.state`.
+     * With `hydrate: true` a `clearOnReload` definition's seed is removed before
+     * hydration, as on a document load.
      *
      * @example
      * renderRoute([{ path: "/", Component: FlashBanner }], {
@@ -192,6 +202,24 @@ export interface RenderRouteOptions {
      * computes the segment id for you). Merged with `handles`.
      */
     handle?: HandleDataSeed;
+    /**
+     * Handle values a document delivers after hydration, as a loader's push
+     * that is not in the document's handle snapshot is (a push made after the
+     * handler output settled, or any loader push on a PPR shell HIT). Each
+     * entry is `[handle, values]`: the handle's values after the update, which
+     * replace its `handles` seed once the root has hydrated (or mounted). With
+     * `hydrate: true` the server HTML is rendered from `handles`, and a reader
+     * inside a `<Suspense>` boundary hydrates after the update was applied, as
+     * a boundary that hydrates after the root does in production.
+     *
+     * @example
+     * const { serverHtml, recoverableErrors } = await renderRoute(routes, {
+     *   hydrate: true,
+     *   handles: [[Notes, ["from-handler"]]],
+     *   lateHandles: [[Notes, ["from-handler", "from-loader"]]],
+     * });
+     */
+    lateHandles?: ReadonlyArray<readonly [Handle<any, any>, unknown[]]>;
     /**
      * Route name -> pattern map. Informational for parity with the server test
      * context; client useReverse takes its map directly as an argument, so this
@@ -253,6 +281,25 @@ export interface RenderRouteOptions {
      * not override a `"none"` default.
      */
     defaultPrefetch?: PrefetchStrategy;
+    /**
+     * Hydrate instead of mounting fresh: the same element is rendered to HTML
+     * (react-dom/server `renderToString`), placed in the container and hydrated.
+     * The result gains `serverHtml` and `recoverableErrors`
+     * (RenderRouteHydrateResult). `data-hydrated` is set on `<html>` after
+     * hydration, as production's root does, and removed on unmount.
+     *
+     * Limits:
+     * - The server pass runs without `window` and `document`, and only those. A
+     *   hook that reads a global that stays defined there (`history`,
+     *   `localStorage`, `navigator`) outside a server snapshot renders the same
+     *   in both passes here and can still mismatch in real SSR.
+     * - Content that suspends in the server pass (`lazy`, a pending or untracked
+     *   `use()` promise) is emitted as its fallback and client-rendered, not
+     *   hydrated; React reports the boundary in `recoverableErrors`. Outside any
+     *   `<Suspense>` it rejects.
+     * - Needs @testing-library/react >= 16.2.0; throws on older versions.
+     */
+    hydrate?: boolean;
 }
 /**
  * Imperative handle returned alongside the RTL result.
@@ -282,10 +329,17 @@ export interface TestRouterHandle {
      * `options.transition: false` is the per-navigation opt-out
      * (`router.push(url, { transition: false })`, `<Link transition={false}>`):
      * the commit is urgent and no transition({ when }) predicate is called.
+     *
+     * `options.state` and `options.replace: true` write the history entry the
+     * way `useRouter().push(url, { state })` and `.replace(url, { state })` do,
+     * so a test can carry location state on a navigation whose loader it
+     * holds: `state` pushes an entry with it, `replace: true` replaces the
+     * current entry (with `state`, or with none, which drops the entry's
+     * location state as a production replace does). With neither, history is
+     * left alone and readers keep the state they have: `navigate(url)` and
+     * `navigate(url, { replace: false })` are the same call.
      */
-    navigate(url: string, options?: Pick<RenderRouteOptions, "loaders"> & {
-        transition?: boolean;
-    }): Promise<void>;
+    navigate(url: string, options?: Pick<RenderRouteOptions, "loaders"> & Pick<NavigateOptions, "state" | "replace" | "transition">): Promise<void>;
     /**
      * Re-render the current location, as router.refresh() does: a spec's
      * transition({ when }) decides it with kind "revalidate" (`to` is `from`).
@@ -304,4 +358,21 @@ export interface TestRouterHandle {
 export type RenderRouteResult = RenderResult & {
     router: TestRouterHandle;
 };
+/** Result of renderRoute with `hydrate: true`. */
+export type RenderRouteHydrateResult = RenderRouteResult & {
+    /** The HTML the server pass produced, as placed in the container. */
+    serverHtml: string;
+    /**
+     * Messages of the errors React recovered from (`onRecoverableError`): a
+     * hydration mismatch that made it re-render on the client, or a boundary the
+     * server pass could not finish. Empty means the tree hydrated as rendered.
+     * Live: React appends for as long as the root is mounted. An attribute-only
+     * mismatch is NOT here — React keeps the server attribute and only logs it
+     * with `console.error` in development.
+     */
+    recoverableErrors: string[];
+};
+export declare function renderRoute(routes: RenderRouteSpec[], options: RenderRouteOptions & {
+    hydrate: true;
+}): Promise<RenderRouteHydrateResult>;
 export declare function renderRoute(routes: RenderRouteSpec[], options?: RenderRouteOptions): Promise<RenderRouteResult>;

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

@@ -27,12 +27,21 @@
  * 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.
  */
 import { type Rango } from "../router/router-interfaces.js";
 import type { SegmentCacheStore, ShellCacheEntry } from "../cache/types.js";
+import type { HandleData } from "../server/handle-store.js";
 import { type PprReplayStatus, type ShellStatus } from "./shell-status.js";
 /** Options for {@link serveShellRequest}. */
 export interface ServeShellRequestOptions<TEnv = any> {
@@ -59,6 +68,29 @@ 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 {
+    /**
+     * What the document hydrates with: `metadata.handles`, read to its end
+     * before hydration starts. For a `partial` request, the last state the
+     * navigation streamed.
+     */
+    hydration: HandleData;
+    /**
+     * The states `metadata.handlesLate` delivered, in order. Each one replaces
+     * the client's handle data after hydration. Empty when nothing arrived
+     * late, and for a `partial` request.
+     */
+    late: HandleData[];
 }
 /** Result of {@link serveShellRequest}. */
 export interface ServeShellRequestResult {
@@ -96,17 +128,36 @@ export interface ServeShellRequestResult {
      * (CFCacheStore, VercelCacheStore) it warms the memo like any other read.
      */
     readEntry(): Promise<ShellCacheEntry | null>;
+    /**
+     * Decode the handle data of `flight` as the browser reads it, deferred
+     * 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/testing/vitest-stubs/version.d.ts

@@ -1 +1,2 @@
 export declare const VERSION = "";
+export declare const ROUTER_VERSIONS: 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
@@ -342,11 +349,14 @@ export type InternalHandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch exte
      */
     _loaderCacheOriginalUse?: (item: any) => any;
     /**
-     * @internal A loader-cache HIT asks before replaying a loader's recorded
-     * pushes: true when that loader has not run in this request and no other
-     * replay delivered it; its later run then replaces the replayed values
-     * (HandleStore.pushReplayed). One copy per loader per request. See
-     * setupLoaderAccess.
+     * @internal A loader-cache or "use cache" HIT asks before replaying a
+     * loader's recorded pushes: true when that loader has not run in this
+     * request and no other replay delivered it; its later run then replaces
+     * the replayed values (HandleStore.pushReplayed). One copy per loader per
+     * request. A record's restore does not ask (restoreHandles): its copies
+     * are the pinned loader's own, or placeholders the claimed replay
+     * replaces. Absent on a stale refresh's ctx, whose pushes are diverted
+     * (handle-snapshot.ts appendHandles). See setupLoaderAccess.
      */
     _claimLoaderPushes?: (loaderId: string) => boolean;
     /**

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.

package/dist/types/urls/path-helper.d.ts

@@ -1,4 +1,22 @@
+import type { Handler } from "../types.js";
 import type { PathFn, ResponsePathFn, JsonResponsePathFn, TextResponsePathFn } from "./path-helper-types.js";
+/**
+ * A retained on-demand producer must never render on a live production
+ * request: bundle eviction is skipped for onDemand routes (the producer body
+ * stays available for router.prerender()), so without this gate an
+ * overlay+manifest miss on a plain Prerender(..., { onDemand }) route would
+ * execute the producer in-request — uncached per-request renders with the
+ * personalization guard unarmed. Keep the pre-retention miss contract instead
+ * (DataNotFoundError -> 404). Producer runs (build-time bake and
+ * router.prerender()) arrive with ctx.build true (createPrerenderContext);
+ * Vite dev keeps the documented live fall-through on a dev-store miss, except
+ * for a page the overlay marks removed (`_prerenderRemoved`): a live render
+ * would show in dev a page production answers with a 404.
+ * Pass-through when the route is not onDemand.
+ *
+ * @internal Exported for the unit test.
+ */
+export declare function gateOnDemandProducer<TEnv>(producer: Handler<any, any, TEnv>, isOnDemand: boolean): Handler<any, any, TEnv>;
 export declare function createPathHelper<TEnv>(): PathFn<TEnv>;
 export declare function attachPathResponseTags<TEnv>(pathFn: PathFn<TEnv>): PathFn<TEnv> & {
     json: JsonResponsePathFn<TEnv>;