@rangojs/router 0.20.0 → 0.22.0

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/router-versions.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Per-router cache versions: the shapes shared by the build (which computes
+ * them, vite/discovery/build-versions.ts) and the runtime (which reads them,
+ * server/build-version-table.ts). No imports, so the Vite plugin bundle can
+ * use it without resolving the `@rangojs/router:version` virtual module.
+ *
+ * Design: docs/design/per-app-cache-version.md.
+ */
+/**
+ * The two versions one `createRouter()` serves with.
+ *
+ * - `data` keys cached RSC data: segment entries, `"use cache"` values and
+ *   loader data. It follows the router's server code only.
+ * - `document` keys stored HTML (PPR shells, document-cache responses), is the
+ *   value the browser echoes as `_rsc_v`, and stamps `ShellCacheEntry.buildVersion`.
+ *   It follows the server code and the client asset URLs.
+ */
+export interface RouterVersions {
+    readonly data: string;
+    readonly document: string;
+}
+/**
+ * The build's table as the `@rangojs/router:version` module exports it:
+ * router id to `[data, document]`. {@link DEFAULT_ROUTER_VERSIONS_KEY} holds
+ * the whole-build pair, used for a router the build could not attribute.
+ */
+export type RouterVersionsTable = Readonly<Record<string, readonly [data: string, document: string]>>;
+/** Table key of the whole-build versions. Not a legal `$$id` (8 hex chars). */
+export declare const DEFAULT_ROUTER_VERSIONS_KEY = "*";
+/** One value for both versions: a consumer-set `version`, or the dev stamp. */
+export declare function uniformVersions(version: string): RouterVersions;
+/**
+ * The versions a router serves with under `table`: a consumer-set `version`
+ * for both; else the router's own entry; else the whole-build pair, for a
+ * router the table does not list. `undefined` when there is no table (dev,
+ * tests) or it has neither entry. One function for the request handler and
+ * the build's shell capture, which must stamp what the handler will check.
+ */
+export declare function resolveVersionsFrom(table: RouterVersionsTable | undefined, routerId: string | undefined, override: string | undefined): RouterVersions | undefined;

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

@@ -12,6 +12,11 @@ import type { RSCDependencies, LoadSSRModule } from "./types.js";
 import type { SSRStreamMode } from "../router/router-options.js";
 export interface HandlerContext<TEnv = unknown> {
     router: RangoInternal<TEnv, any>;
+    /**
+     * The router's DOCUMENT version (router-versions.ts): payload metadata, the
+     * `_rsc_v` reload check, and PPR shell stamping and gating. The data version
+     * is not here; cache stores read it from the request context.
+     */
     version: string;
     devDiscoveryEpoch?: number;
     renderToReadableStream: RSCDependencies["renderToReadableStream"];

package/dist/types/rsc/shell-build-manifest.d.ts

@@ -11,8 +11,9 @@
  * served through the same serveShellHit as a captured one.
  *
  * Lifecycle:
- * - No expiry until the next deploy — the buildVersion gate retires entries
- *   the moment a new build ships (a new manifest replaces them anyway).
+ * - No expiry until the next deploy: every build ships its own manifest, and
+ *   its entries carry that build's document version for the router, which is
+ *   what the buildVersion gate compares.
  * - `ppr.ttl` drives STALENESS ONLY: past createdAt + ttl the entry still
  *   serves, but a runtime recapture is scheduled — SWR is the UPGRADE path
  *   from build entry to fresher runtime entry, not the bootstrap path. The
@@ -35,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;
@@ -79,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
@@ -95,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
@@ -321,13 +329,11 @@ export interface CreateRSCHandlerOptions<TEnv = unknown, TRoutes extends Record<
      */
     cache?: HandlerCacheConfig | ((env: TEnv) => HandlerCacheConfig);
     /**
-     * RSC version string included in metadata.
-     * The browser sends this back on partial requests to detect version mismatches.
-     *
-     * Defaults to the auto-generated VERSION from `rsc-router:version` virtual module.
-     * Only set this if you need a custom versioning strategy.
+     * Version override for this handler. Same meaning as
+     * `createRouter({ version })`, which it takes precedence over: this exact
+     * value is used for both of the router's versions.
      *
-     * @default VERSION from rsc-router:version
+     * @default createRouter({ version }), else the router's build versions
      */
     version?: string;
     /**

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

@@ -0,0 +1,53 @@
+import { type RouterVersions, type RouterVersionsTable } from "../router-versions.js";
+/**
+ * The versions a router serves with, in order:
+ *
+ * 1. `override`, a consumer-set `version` (createRouter or createRSCHandler):
+ *    that exact value for both.
+ * 2. The router's entry in the build table, else the whole-build entry.
+ * 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
+ * that lost the ALS) gets the whole-build versions: it misses the request's
+ * entries instead of reading another version's. When routers have versions of
+ * their own that is a write no router reads back, so it is logged, once per
+ * process: `ctx.waitUntil()` re-enters the request context for every task it
+ * runs (server/request-context.ts), and this line in a production log means
+ * some other path lost it.
+ *
+ * Public from `@rangojs/router/cache`, for a custom persistent store to key
+ * the way the built-in ones do. Prefix cached RSC data (segment entries, items) with
+ * `data` and stored HTML or responses (shells, document responses) with
+ * `document`, and leave tag-invalidation records unversioned; an empty string
+ * means "no version" (tests). Call it per operation, inside the request, not
+ * in the store's constructor: the cache factory runs before the request
+ * context exists.
+ */
+export declare function getCacheVersions(): RouterVersions;
+/** Which of the serving router's versions a store key carries; `null`: none. */
+export type KeyVersion = keyof RouterVersions | null;
+/**
+ * The `v/{version}/` prefix of a persistent store key, or "" for an
+ * unversioned one. A store-level `version` is used for every versioned kind;
+ * otherwise the version is the serving router's, read per operation because
+ * the cache factory builds the store before the request context exists.
+ */
+export declare function versionKeyPrefix(storeVersion: string | undefined, kind: KeyVersion): string;
+/**
+ * @internal Install a table, or restore the build's with `undefined`. A
+ * request handler resolves its router's versions once, when it is created, so
+ * a test that swaps the table (a "deploy") needs new handlers.
+ */
+export declare function installRouterVersionsTable(next: RouterVersionsTable | undefined): void;

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