@rangojs/router 0.16.0 → 0.18.0

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

@@ -104,6 +104,40 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     _rotateStateCookie(): void;
     /** @internal Set the keepClientCache() directive header on the response. */
     _setKeepCacheDirective(): void;
+    /**
+     * @internal This request carries the fresh-reads cookie: it follows an
+     * updateTag()/revalidateTag() by the same user, so the stores read tag
+     * markers and shells from the store, not from an isolate memo.
+     */
+    _freshReads?: boolean;
+    /**
+     * @internal Set the fresh-reads cookie on this response for `maxAgeMs`
+     * (rounded up to whole seconds; the longest stays). Called by
+     * updateTag()/revalidateTag().
+     */
+    _setFreshReadsCookie(maxAgeMs: number): void;
+    /**
+     * @internal The context createRequestContext() returned. A context derived
+     * from it with Object.create (a PPR HIT tail, a shell capture, a background
+     * revalidation render) inherits it, so per-request invalidation state
+     * (tag-invalidation.ts, the stores' masks) is keyed by the request, not by
+     * whichever derived object called or read (#973).
+     */
+    _requestRoot?: RequestContext<any, any>;
+    /**
+     * @internal The tags this request invalidated with
+     * updateTag()/revalidateTag(), each with its position in the invalidation
+     * order (tag-invalidation.ts currentCacheSeq). Kept on _requestRoot. A
+     * "use cache" execution that started before one of its own tags was
+     * invalidated is neither joined nor written (cache-runtime.ts, #973).
+     */
+    _tagInvalidations?: Map<string, number>;
+    /**
+     * @internal The handler has handed the response to the host (rsc/handler.ts
+     * `rango.response`): header and cookie writes after this are lost, as from
+     * a streaming loader or render.
+     */
+    _responseSent?: boolean;
     /**
      * Access loader data or push handle data.
      *
@@ -129,8 +163,13 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     };
     /** HTTP method (GET, POST, PUT, PATCH, DELETE, etc.) */
     method: string;
-    /** @internal Handle store for tracking handle data across segments */
-    _handleStore: HandleStore;
+    /**
+     * @internal Handle store for tracking handle data across segments.
+     * Readonly: a background render that needs its own store derives a context
+     * (rerenderAndCacheRoute, shell-capture.ts) instead of swapping this field,
+     * which the foreground still reads while it produces the page.
+     */
+    readonly _handleStore: HandleStore;
     /**
      * @internal transition({ when }) predicates for segments matched this request,
      * keyed by segment id. Collected during resolution (the function is stripped
@@ -178,15 +217,52 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     /**
      * @internal Bake-lane loader containers collected DURING a shell capture:
      * segment-key -> the loader's (pre-wrap) result promise. Populated by
-     * resolveLoaderData for loaders on entries with no renderable loading() (the
-     * bake lane — they execute at capture instead of being masked; see
-     * docs/design/loader-container-bake.md). Drained by captureAndStoreShell
-     * after the shell quiesces: settled containers are promise-elided,
-     * Flight-serialized, and pinned into the snapshot's loader family; a
-     * REJECTED container refuses the capture (error UI must never bake into the
-     * shared shell). Own property of the capture's derived context only.
+     * resolveLoaderData for bake-lane loaders (lane rule: see its JSDoc in
+     * loader-cache.ts). Drained by captureAndStoreShell after the shell
+     * quiesces: settled containers are promise-elided, Flight-serialized, and
+     * pinned into the snapshot's loader family; a REJECTED container refuses
+     * the capture (error UI must never bake into the shared shell). Own
+     * property of the capture's derived context only.
      */
     _shellCaptureLoaderRecords?: Map<string, Promise<unknown>>;
+    /**
+     * @internal Set on a capture's derived context when a loader pushed a
+     * value the record cannot keep (a deferred push, masked nested promises,
+     * or a push outside a loader body): the loader records then carry
+     * `runs: 1`, so a HIT still runs their bodies for those pushes.
+     */
+    _shellCaptureUnrecordedLoaderPush?: true;
+    /**
+     * @internal Record keys resolved for this request (CacheScope
+     * resolveKeyFrom): by the scope's `key()` (one result) or its store's
+     * keyGenerator (one per default key). A shell capture's derived context
+     * reads it through the prototype chain, so the capture reuses the
+     * partition its request resolved instead of running `key()` again.
+     */
+    _resolvedCacheKeys?: Map<unknown, Map<string, Promise<string>>>;
+    /**
+     * @internal The shell store key the PPR serve path resolved for this
+     * document request (rsc-rendering.ts shellServePlan), request partition
+     * included. Read by the testing helper serveShellRequest.
+     */
+    _shellKey?: string;
+    /**
+     * @internal The request carried the forced-MISS reload marker
+     * (shell-serve.ts SHELL_MISS_PARAM). The handler strips the marker from the
+     * request on entry and sets this; the shell gate renders the request like a
+     * cache miss.
+     */
+    _shellForcedMiss?: true;
+    /**
+     * @internal The freshness window of the route cache() records this
+     * request read or wrote (cache-scope.ts noteRouteRecordWindow), as ms
+     * timestamps: `freshUntil` is the record's `expiresAt`, `staleUntil` adds
+     * its scope's swr. The narrowest record wins. A shell capture caps its
+     * entry's ttl and ttl+swr to it (shell-capture.ts capShellWindow), so a
+     * shell is never fresher, or served longer, than the route cache() entry
+     * it replayed or wrote.
+     */
+    _routeRecordWindow?: RouteRecordWindow;
     /**
      * @internal Loader-family snapshot seed for a shell HIT's tail render:
      * segment-key -> the capture's elided container (already Flight-deserialized
@@ -194,21 +270,24 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * overlays it onto the fresh run's container (recorded paths pinned,
      * hole-marker paths keep the fresh nested promises) so the payload's baked
      * bytes match the frozen prelude; a hole-free entry resolves pin-first
-     * without gating on the fresh run. Own property of the HIT tail's derived
-     * context only.
+     * and does not run the loader. Two owners: serveShellHit sets it on the
+     * HIT tail's derived context, and matchPartialWithPprReplay sets it on the
+     * request context of a PPR partial replay once its doc record hits, and
+     * restores the previous value after the match.
      */
     _shellLoaderSeed?: Map<string, import("../cache/shell-snapshot.js").ShellLoaderSeedEntry>;
     /**
-     * @internal Shell fast-path marker: makes the next eligible match treat the
-     * whole matched route as an implicit doc-level cache() boundary (see
+     * @internal The doc record marker: makes the next match treat the whole
+     * matched route as an implicit doc-level cache() boundary (see
      * resolveShellImplicitCacheScope in cache/cache-scope.ts). Set ONLY on
      * (a) the capture's derived context — with a record-only store so the
      * capture's cacheRoute write lands in the snapshot, never the real store —
-     * (b) a HIT tail's seeded context, and (c) an eligible normal-route partial
-     * replay, where `store` is a request-local segment overlay. Handler-live holes
-     * and conditional transitions decline replay.
-     * Routes with their own cache() config are never overridden — their scope's
-     * store/key/ttl/swr/condition semantics stay authoritative. On the
+     * (b) a document HIT tail's seeded context (`docTail`), and (c) an eligible
+     * normal-route partial replay, where `store` is a request-local segment
+     * overlay.
+     * A document HIT tail replays the record even for a route with its own
+     * cache() config (the gate before the commit already evaluated that
+     * scope's opt-outs). Elsewhere the route's scope stays authoritative. On the
      * navigation-replay serve path (`onExplicitHit` set) the marker COMPOSES with
      * such a scope instead of being ignored: the seeded doc record supplies the match
      * only when the explicit tier misses (withCacheLookup). cache(false) and a
@@ -225,12 +304,17 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
          * segment record even when the triggering request is partial.
          */
         keyPrefix?: "doc";
-        /** @internal Called only after the implicit cache hit decodes successfully. */
-        onHit?: () => void;
+        /**
+         * @internal Called only after the implicit cache hit decodes
+         * successfully; the lookup awaits it before returning the hit, so work
+         * it starts lands before the route's loaders resolve.
+         */
+        onHit?: () => void | Promise<void>;
         /**
          * @internal Called when the seeded document record fails server-side
          * deserialization. Partial replay uses it to replace the enclosing shell
-         * snapshot after serving the fresh fallback.
+         * snapshot after serving the fresh fallback. A document HIT tail does not
+         * set it: withCacheLookup throws ShellRecordUnavailableError instead.
          */
         onCorrupt?: () => void;
         /**
@@ -241,6 +325,21 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
          * require the exact consumable record instead of "any segment record".
          */
         docKey?: string;
+        /**
+         * @internal Set on a document HIT tail (serveShellHit). The implicit doc
+         * scope replaces any route-derived cache() scope for the tail's match
+         * (resolveShellImplicitCacheScope), and a lookup that does not hit throws
+         * ShellRecordUnavailableError instead of resolving segments
+         * (withCacheLookup): a HIT never runs a handler.
+         */
+        docTail?: true;
+        /**
+         * @internal The key a document HIT tail looks the doc record up by: the
+         * entry's own `docKey`. Recomputing it could name another key (a store
+         * keyGenerator folding request data, a build-time capture's synthetic
+         * host) and miss the record.
+         */
+        fixedDocKey?: string;
         /**
          * @internal Set ONLY by matchPartialWithPprReplay on the navigation-replay
          * serve path. Its presence arms the explicit-scope composition in
@@ -282,41 +381,19 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      */
     _shellFragmentPayload?: boolean;
     /**
-     * @internal Handler-layer liveness observed DURING a shell capture, from
-     * three sources: (a) the capture handle-store push wrapper (shell-capture.ts)
-     * when a push made OUTSIDE a DSL loader scope carries a nested thenable
-     * (masked to a never-filling hole); (b) still-pending top-level handler
-     * pushes (liveness unknowable at the barrier); (c) a handler-invoked loader
-     * executing during the capture (loader-resolution.ts — its consumption-lane
-     * value would freeze on a handler-free HIT). captureAndStoreShell folds it
-     * into ShellCacheEntry.handlerLiveHoles at the putShell barrier. Own
-     * property of the capture's derived context only.
-     */
-    _shellCaptureHandleLiveness?: {
-        holes: boolean;
-        pendingPushes: number;
-        handlerInvokedLoader: boolean;
-    };
-    /**
-     * @internal Handle values pushed from a DSL loader scope DURING a shell
-     * capture (identity set; populated by the capture push wrapper in
-     * shell-capture.ts). cacheRoute threads it into captureHandles so those
-     * values stay out of cache-write handle records — loaders re-run fresh on
-     * every HIT, so replaying their captured (masked) values would duplicate
-     * the fresh push and stall the Flight handle encode. Own property of the
-     * capture's derived context only; render-time handle consumers are
-     * unaffected (the exclusion applies only at the captureHandles call site).
-     */
-    _shellCaptureLoaderHandleValues?: WeakSet<object>;
-    /**
-     * @internal Set (to the offending fn name) by the cookies()/headers()
-     * capture guard when it throws DURING a capture render. Load-bearing for the
+     * @internal Set by the capture guard (server/context.ts
+     * tripShellCaptureGuard) when it throws DURING a capture render: the read
+     * ("cookies()", "headers()", "ctx.get()", "ctx.theme") and the fix the
+     * refusal warning gives for it. Load-bearing for the
      * bake lane: a guard throw inside an executing loader is swallowed by
      * wrapLoaderPromise into per-loader error UI, which would otherwise bake
      * silently into the shared shell — the capture checks this flag after the
      * render and refuses instead. Deterministic, so the capture does not retry.
      */
-    _shellCaptureGuardTripped?: string;
+    _shellCaptureGuardTripped?: {
+        surface: string;
+        fix: string;
+    };
     /**
      * @internal The loader $$id whose BODY was executing when the capture guard
      * tripped (read off the loader-body ALS scope at trip time), or undefined
@@ -343,6 +420,21 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * content used and can therefore be invalidated by updateTag()/revalidateTag().
      */
     _requestTags: Set<string>;
+    /**
+     * @internal This request can write a route cache() record: its match
+     * resolved a cache scope (match-api.ts). Arms the record tag owners
+     * (cache-tag.ts armRecordTagOwners); off, the segment scopes, loader links
+     * and owned tag sets are skipped entirely. A capture's or background
+     * re-render's derived context (Object.create) inherits it.
+     */
+    _recordTagOwners?: true;
+    /**
+     * @internal This request resolves a loader bound with its own cache()
+     * (match-api.ts, or the binding's funnel). Arms the per-execution loader
+     * tag sets (cache-tag.ts armLoaderTagSets); off, a loader execution
+     * allocates no set and a read links nothing. Derived contexts inherit it.
+     */
+    _recordLoaderTags?: true;
     /** @internal Cache profiles for "use cache" profile resolution (per-router) */
     _cacheProfiles?: Record<string, import("../cache/profile-registry.js").CacheProfile>;
     /**
@@ -383,6 +475,11 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * Returns the theme value from the cookie, or the default theme if not set.
      * This is the user's preference ("light", "dark", or "system"), not the resolved value.
      *
+     * The visitor's cookie, so it is guarded like `cookies()`: reading it
+     * refuses a ppr shell capture and throws inside a `cache()` boundary or a
+     * `"use cache"` function (#971). A non-enumerable getter: a spread or
+     * `Object.assign` copy of the context does not carry it.
+     *
      * @example
      * ```typescript
      * route("settings", (ctx) => {
@@ -391,7 +488,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * });
      * ```
      */
-    theme?: Theme;
+    readonly theme?: Theme;
     /**
      * Set the theme (only available when theme is enabled in router config)
      *
@@ -412,6 +509,14 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     setTheme?: (theme: Theme) => void;
     /** @internal Theme configuration (null if theme not enabled) */
     _themeConfig?: ResolvedThemeConfig | null;
+    /**
+     * @internal The theme cookie (or the default) read with no identity guard.
+     * The guarded reads (`theme` here, the handler and middleware `ctx.theme`)
+     * call it after assertThemeReadAllowed; the router's own payload read goes
+     * through payloadInitialTheme (rsc/full-payload.ts). Undefined without
+     * theme config.
+     */
+    _readTheme(): Theme | undefined;
     /**
      * Attach location state entries to the current response.
      *
@@ -535,6 +640,16 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     _renderBarrierGuardClosed?: boolean;
     /** @internal Per-request error dedup set for onError reporting */
     _reportedErrors: WeakSet<object>;
+    /**
+     * @internal Errors this response's Flight or Fizz render reported through
+     * onError: a component that threw does not fail the stream, which completes
+     * with an error row or an errored Suspense boundary. Whole-response captures
+     * (document-cache.ts, captureAndStoreShell) store nothing while it is
+     * non-empty (issue #915). An array so a render under a derived context (the
+     * shell HIT tail) pushes into the request's own list through the prototype;
+     * deriveShellCaptureContext gives the capture its own.
+     */
+    _renderErrors?: unknown[];
     /**
      * @internal Report a non-fatal background error through the router's
      * onError callback. Wired by the RSC handler / router during request
@@ -592,13 +707,27 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      */
     _cacheSignal?: import("../router/telemetry.js").CacheSegmentSignal[];
 }
+/**
+ * @internal The freshness window of a route cache() record, as ms
+ * timestamps: fresh until `freshUntil` (its `expiresAt`), stale until
+ * `staleUntil` (plus its scope's swr). `ttl`, `swr` and `written` describe
+ * the record that sets `staleUntil`: its cache() config, and whether this
+ * request wrote it (cacheRoute) rather than read it.
+ */
+export interface RouteRecordWindow {
+    freshUntil: number;
+    staleUntil: number;
+    ttl: number;
+    swr: number;
+    written: boolean;
+}
 /**
  * Public view of RequestContext, without internal methods and fields.
  *
  * 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" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_pprTransitionDecisions" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
+export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_pprTransitionDecisions" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureUnrecordedLoaderPush" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_routeRecordWindow" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_freshReads" | "_setFreshReadsCookie" | "_requestRoot" | "_tagInvalidations" | "_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:

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

@@ -20,6 +20,7 @@ interface RenderToReadableStreamOptions {
     nonce?: string;
     formState?: unknown;
     progressiveChunkSize?: number;
+    onError?: (error: unknown) => void;
 }
 /**
  * ReadableStream with the allReady promise added by react-dom/server.edge.
@@ -99,6 +100,12 @@ export interface SSRRenderOptions {
      * prerender pass (host-agnostic bare captures).
      */
     origin?: string;
+    /**
+     * Called for each error Fizz reports through its onError: a component that
+     * threw inside a Suspense boundary, which leaves the boundary errored in an
+     * otherwise completed document. React's default console.error is kept.
+     */
+    onError?: (error: unknown) => void;
 }
 /**
  * SSR dependencies from external packages
@@ -225,6 +232,21 @@ interface ShellCaptureOptions {
      * capture, resume, and browser hydration.
      */
     origin?: string;
+    /**
+     * Called for each component error the prerender reports (an errored
+     * boundary in the prelude), never for the capture's own abort. The caller
+     * refuses to store the shell (issue #915).
+     */
+    onError?: (error: unknown) => void;
+    /**
+     * Called with React's errorInfo for each task still pending when the
+     * capture's own abort froze the prelude; its componentStack is computed
+     * when read. The dev no-shell warning prints the stacks: one of them is what
+     * suspended above <body> (issue #941).
+     */
+    onAbortedTask?: (errorInfo: {
+        componentStack?: string;
+    } | undefined) => void;
 }
 /**
  * Result of a successful shell capture. `prelude` is the raw prelude bytes;
@@ -253,6 +275,8 @@ interface ShellResumeOptions {
     search?: string;
     /** The HIT request's origin — same host as the capture's (key-scoped). */
     origin?: string;
+    /** Called for each component error the resumed holes report. */
+    onError?: (error: unknown) => void;
 }
 /**
  * Create an SSR handler that converts RSC streams to HTML.

package/dist/types/ssr/ssr-root.d.ts

@@ -54,14 +54,15 @@ export interface SsrRootOptions {
     nonce?: string;
     /**
      * Fires once when the Flight payload root settles (resolve OR reject) — the
-     * signal that every client-module load the payload references completed and
-     * fizz can start emitting the tree. The capture pass gates its abort on
-     * this: a fully REPLAYED (prerendered) route's Flight stream goes
-     * byte-quiet in ~1-3ms, but fizz cannot render even <html> until the
-     * module loads finish (real module-runner I/O in dev; 100ms+ on a cold
-     * graph), so an abort gated on Flight quiet alone fires first and freezes
-     * a zero-byte prelude. Masked-loader holes do NOT block this signal —
-     * they postpone below the root.
+     * signal that fizz can start emitting the tree. A client component used as
+     * an element type resolves lazily, so its module load can still be in
+     * flight (captureShellHTML waits for those separately, issue #949). The
+     * capture pass gates its abort on this: a fully REPLAYED (prerendered)
+     * route's Flight stream goes byte-quiet in ~1-3ms, but fizz cannot render
+     * even <html> until the module loads finish (real module-runner I/O in dev;
+     * 100ms+ on a cold graph), so an abort gated on Flight quiet alone fires
+     * first and freezes a zero-byte prelude. Masked-loader holes do NOT block
+     * this signal — they postpone below the root.
      */
     onPayloadSettled?: () => void;
     /**

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

@@ -21,11 +21,14 @@
  * ```ts
  * export const DocsNav = Static((ctx) => <Nav docs={readDocsSync()} />);
  * export const DocShell = Static((ctx) => <Shell />);
+ * // Prerender/Static must be exported consts; an inline call inside path()
+ * // gets no build-injected $$id and throws.
+ * export const DocPage = Prerender(getParams, DocPageHandler);
  *
  * urls(({ path, layout }) => [
  *   layout(DocsNav, () => [
  *     path("/getting-started", DocShell, { name: "doc.gs" }),
- *     path("/:slug", Prerender(getParams, DocPageHandler)),
+ *     path("/:slug", DocPage),
  *   ]),
  * ]);
  * ```

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

@@ -18,6 +18,11 @@
  * element tree, so you can assert typed prop fidelity across the client boundary
  * (a `Date` comes back a `Date`) and detect inlined-vs-island. Serialize +
  * deserialize only — no hydration/interaction (that is the e2e tier).
+ *
+ * `serveShellRequest` serves one request through the router's production
+ * handler, so a `ppr` route's MISS runs the real shell capture and a later
+ * request is a real HIT; only the HTML step is stubbed. `resetShellTestState`
+ * clears the per-isolate PPR state between tests.
  */
 export { renderToFlightString, normalizeFlight, assertFlightRuntimeAvailable, } from "./flight.js";
 export type { RenderToFlightStringOptions } from "./flight.js";
@@ -25,3 +30,5 @@ 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 { serveShellRequest, resetShellTestState, } from "./serve-shell-request.js";
+export type { ServeShellRequestOptions, ServeShellRequestResult, } from "./serve-shell-request.js";

package/dist/types/testing/generated-routes.d.ts

@@ -56,10 +56,10 @@ export declare function diffGeneratedRoutes(router: RouterWithRouteMap, generate
  *
  * @example
  * ```ts
- * import generated from "./router.named-routes.gen";
+ * import { NamedRoutes } from "./router.named-routes.gen";
  * import { router } from "./router";
  *
- * await assertGeneratedRoutesMatch(router, generated);
+ * await assertGeneratedRoutesMatch(router, NamedRoutes);
  * ```
  */
 export declare function assertGeneratedRoutesMatch(router: RouterWithRouteMap, generatedMap?: Record<string, unknown>): Promise<void>;

package/dist/types/testing/internal/context.d.ts

@@ -205,7 +205,7 @@ export declare function buildRunSnapshot<TEnv>(ctx: RequestContext<TEnv>, thrown
  *
  * @example
  * ```ts
- * const { result, cookies, response, thrown } = await runInRequestContext(
+ * const { cookies, headers, response, thrown } = await runInRequestContext(
  *   () => loginAction(input), // sets a session cookie, then `throw redirect("/app")`
  *   {
  *     env,

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

@@ -23,10 +23,13 @@
  *     SEEDED directly into client context (see the `loaders` / `locationState` /
  *     `handles` / `outletPending` options) — nothing is executed on the server.
  *     This exercises the context read path, not the run path.
- *   - navigate() commits synchronously, so it does NOT drive the navigation
- *     lifecycle: useNavigation().state, useLinkStatus().pending, and
- *     useAction().state stay "idle". Assert pending/loading/submitting transition
- *     states with renderServerTree / e2e instead (navigate() warns once if used).
+ *   - navigate() does NOT drive the navigation lifecycle: useNavigation().state,
+ *     useLinkStatus().pending, and useAction().state stay "idle". Assert
+ *     pending/loading/submitting transition states with renderServerTree / e2e
+ *     instead (navigate() warns once if used). The one pending state it does
+ *     model is the held-navigation useLoader().isLoading: a `transition` spec
+ *     plus a pending Promise seeded via navigate(url, { loaders }) commits
+ *     through production's commitInTransition (browser/partial-update.ts).
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
  * useRouter, usePathname, useSearchParams, Outlet/useOutlet nesting and seeded
@@ -42,7 +45,7 @@ import { type ComponentType } from "react";
 import type { RenderResult } from "@testing-library/react";
 import type { NavigationStore } from "../browser/types.js";
 import type { EventController } from "../browser/event-controller.js";
-import type { LoaderDefinition } from "../types.js";
+import type { LoaderDefinition, TransitionConfig } from "../types.js";
 import type { LocationStateDefinition } from "../browser/react/location-state-shared.js";
 import type { Handle } from "../handle.js";
 import type { ThemeConfig } from "../theme/types.js";
@@ -78,6 +81,14 @@ export interface RenderRouteSpec {
     loaderIds?: string[];
     /** Optional route name (informational; not used for matching). */
     name?: string;
+    /**
+     * The `transition()` config this node declares (`{}` for a bare
+     * `transition()`), attached to its segment as the DSL does. Puts the chain in
+     * a transition scope: param-agnostic keys (segment-system.tsx) and a held
+     * navigate() commit, so a pending loader seed passed to
+     * `router.navigate(url, { loaders })` pins `useLoader().isLoading`.
+     */
+    transition?: TransitionConfig;
 }
 /**
  * Options for renderRoute.
@@ -247,8 +258,23 @@ export interface TestRouterHandle {
      * updates params + location, and re-renders the segment tree. This is a
      * client-only navigation: no server fetch occurs, so only the components in
      * `routes` can be reached.
+     *
+     * `options.loaders` seeds loader data for THIS navigation, merged over the
+     * render-time seeds (the data a real navigation's response would carry). A
+     * pending Promise suspends the read like a streaming Flight chunk. When a
+     * spec in the chain has `transition`, the commit goes through production's
+     * commitInTransition: the reader stays on screen with
+     * `useLoader().isLoading === true` until the promise settles. Settle it
+     * inside RTL's `act()` to flush the commit. Without `transition` the commit
+     * is urgent and the read suspends to the nearest Suspense boundary.
+     *
+     * @example
+     * await router.navigate("/products/2", { loaders: [[ProductLoader, next]] });
+     * // reader: isLoading true, old data
+     * await act(async () => resolve({ name: "Product 2" }));
+     * // reader: isLoading false, new data
      */
-    navigate(url: string): Promise<void>;
+    navigate(url: string, options?: Pick<RenderRouteOptions, "loaders">): Promise<void>;
     /** The current committed pathname. */
     pathname(): string;
     /** The current committed params. */

package/dist/types/testing/run-loader.d.ts

@@ -38,6 +38,7 @@ import { type Handle } from "../handle.js";
 import type { ThemeConfig } from "../theme/types.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { CacheProfile } from "../cache/profile-registry.js";
+import type { PartialCacheOptions } from "../types/cache-types.js";
 import { type VarsInit, type StateCookieSeed } from "./internal/context.js";
 /**
  * The loader context surfaced to a `runLoader` body. It mirrors the runtime
@@ -81,9 +82,11 @@ export interface RunLoaderOptions<TEnv = any> {
     basename?: string;
     /**
      * Theme config in the same shape `createRouter({ theme })` takes (e.g. `true`
-     * or `{ themes: [...] }`). Seeds the request's theme config so nested handler
-     * or cache contexts created from this loader observe it. Loaders themselves do
-     * not expose `ctx.theme`/`ctx.setTheme` (those are handler/middleware-only).
+     * or `{ themes: [...] }`). Seeds the request's theme config, so the loader
+     * body reads the visitor's theme (the Cookie on `request`, or the default)
+     * with `getRequestContext().theme`. That read is guarded like `cookies()`: it
+     * throws inside a `"use cache"` function (#971). The loader ctx has no
+     * `theme`/`setTheme` (those are handler/middleware-only).
      */
     theme?: ThemeConfig | true;
     /** Environment bindings surfaced as `ctx.env`. */
@@ -121,6 +124,18 @@ export interface RunLoaderOptions<TEnv = any> {
     cacheStore?: SegmentCacheStore;
     /** Cache profiles (the `createRouter({ cacheProfiles })` shape). */
     cacheProfiles?: Record<string, CacheProfile>;
+    /**
+     * Run the loader through the `cache()` a route binds it with — the options
+     * `loader(Loader, () => [cache({...})])` takes — using the production
+     * read-through against `cache.store`, else `cacheStore`. A HIT returns the
+     * stored value without running the body and records the tags the body
+     * recorded when the entry was written, so `updateTag()` of any of them drops
+     * the entry. The write is a background task the call does not await (spy
+     * on the store's `setItem` to wait for it). A raw loader body is keyed by
+     * its function reference. `handlePushes` lists the body's pushes, so a HIT
+     * reports none: the replay into the page's handle store is not modeled.
+     */
+    cache?: PartialCacheOptions;
     /**
      * Customize the rango state cookie a loader that calls
      * `invalidateClientCache()` rotates (the name is always seeded — default