@rangojs/router 0.15.1 → 0.17.0

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

@@ -50,10 +50,11 @@ declare function delay(ms: number): Promise<void>;
  * mode's ceiling (60s in production, {@link REFUSED_CAPTURE_DEV_MAX_MS} in dev).
  *
  * Why exponential and not a flat 60s: a flat long window conflates two very
- * different failures. A STRUCTURALLY ineligible route (no loading(), a cookie
- * reader) fails forever and wants the long 60s cap. But a cold-but-ELIGIBLE route
- * can also fail the in-place retry under a truly cold graph (dev module transform,
- * or a cold worker under parallel load) — and it must recover FAST, on the next
+ * different failures. A STRUCTURALLY ineligible route (a boundary-less live
+ * loader read, a cookie reader) fails forever and wants the long 60s cap. But a
+ * cold-but-ELIGIBLE route can also fail the in-place retry under a truly cold
+ * graph (dev module transform, or a cold worker under parallel load) — and it
+ * must recover FAST, on the next
  * request or two, not be frozen for 60s (that would re-break the very cold-start DX
  * the retry fixes; it bit the cloudflare dev e2e). Escalating from 1s means the
  * eligible route re-probes almost immediately (warm now → HIT and clear), while the

package/dist/types/rsc/ssr-setup.d.ts

@@ -33,11 +33,11 @@ export interface SsrHtmlStageOptions<TEnv> {
     /** Metrics store for ssr:module-load / ssr:stream-mode timing (per call site). */
     metricsStore: MetricsStore | undefined;
     /**
-     * renderHTML options minus streamMode (the stage resolves streamMode). Carries
-     * the per-site nonce and, for the PE action re-render, formState. Spread
-     * verbatim so each call site's exact key set is preserved.
+     * renderHTML options minus streamMode and onError (the stage owns both).
+     * Carries the per-site nonce and, for the PE action re-render, formState.
+     * Spread verbatim so each call site's exact key set is preserved.
      */
-    render: Omit<SSRRenderOptions, "streamMode">;
+    render: Omit<SSRRenderOptions, "streamMode" | "onError">;
     /** ResponseInit merged into the prepared render (e.g. content-type). */
     init?: ResponseInit;
 }
@@ -59,8 +59,8 @@ export declare function getSSRSetup<TEnv>(ctx: HandlerContext<TEnv>, request: Re
  * Classify whether a request may require SSR (HTML rendering).
  *
  * Returns false for requests that are definitively RSC-only: transport
- * params (partial/action/loader/__rsc), prerender collection, or an explicit
- * Accept: text/x-component. Must never return false for a request whose
+ * params (partial/action/loader/__rsc) or an explicit Accept:
+ * text/x-component. Must never return false for a request whose
  * render-time decision (isRscRequest) will be HTML — the two share
  * acceptsFlightExplicitly so the Accept rule cannot drift. document-cache.ts
  * keys its HTML/RSC response slots off this function, so any divergence from

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

@@ -181,6 +181,12 @@ export interface SSRRenderOptions {
      * the browser across hydration. Absent on host-agnostic build 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 module interface for HTML rendering
@@ -200,6 +206,8 @@ export interface SSRModule {
         maxWaitMs?: number;
         search?: string;
         origin?: string;
+        /** Each component error the prerender reports (never the capture's own abort). */
+        onError?: (error: unknown) => void;
     }) => Promise<{
         prelude: Uint8Array;
         postponed: string | null;
@@ -217,6 +225,8 @@ export interface SSRModule {
         nonce?: string;
         search?: string;
         origin?: string;
+        /** Each component error the resumed holes report. */
+        onError?: (error: unknown) => void;
     }) => Promise<ReadableStream<Uint8Array>>;
 }
 /**

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

@@ -2,6 +2,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 { DefaultRouteName } from "../types/global-namespace.js";
+import type { ContextVar } from "../context-var.js";
 /**
  * Performance metric entry for a single measured operation
  *
@@ -44,6 +45,17 @@ export type EntryPropCommon = {
     id: string;
     shortCode: string;
     parent: EntryData | null;
+    /**
+     * Orphan siblings only (attachOrphanSibling in
+     * route-definition/dsl-helpers.ts): the entry whose `layout[]` holds this
+     * one. `parent` stays null on an orphan (matchError's matched-id stack in
+     * router/match-api.ts starts at the boundary-holding entry, possibly an
+     * orphan, and must stop there), so the boundary walkers in
+     * router/error-handling.ts follow this instead. A lookup that starts at an
+     * orphan (its loaders, an intercept it declares) then reaches the owner's
+     * boundaries and the owner's ancestors.
+     */
+    orphanOwner?: EntryData;
     /** Cache configuration for this entry (set by cache() DSL) */
     cache?: EntryCacheConfig;
     /** URL prefix from include() scope, used for MountContext on client */
@@ -156,9 +168,6 @@ export type InterceptEntry = {
     routeName: string;
     handler: ReactNode | Handler<any, any, any>;
     middleware: MiddlewareFn<any, any>[];
-    revalidate: ShouldRevalidateFn<any, any>[];
-    errorBoundary: (ReactNode | ErrorBoundaryHandler)[];
-    notFoundBoundary: (ReactNode | NotFoundBoundaryHandler)[];
     loader: LoaderEntry[];
     loading?: ReactNode | false;
     transition?: TransitionConfig;
@@ -403,6 +412,20 @@ export declare function track(label: string, depth?: number): () => void;
  * (never cached), so non-cacheable reads are safe.
  */
 export declare function isInsideCacheScope(): boolean;
+/**
+ * Read guard for a non-cacheable variable (`createVar({ cache: false })` or a
+ * `ctx.set(..., { cache: false })` write). Callers check isNonCacheable() first
+ * so ordinary reads never reach the scope lookups.
+ *
+ * Throws inside a "use cache" body: the key does not include the value, so the
+ * first caller's value would be stored and served to later callers (#925). A
+ * loader body entered INSIDE the cached function is exempt, the same baked-copy
+ * trade isInsideCacheScope() makes for cache(). A cached function called FROM a
+ * loader is not: the loader re-runs, the cached body does not. The body scope
+ * records the exec scope it was entered in, so the exemption holds only while
+ * that is still the innermost one.
+ */
+export declare function assertNonCacheableReadAllowed(keyOrVar: string | ContextVar<unknown>): void;
 /**
  * Check if the current execution is inside a DSL loader scope
  * (wrapped by runInsideLoaderScope). Used by rendered() barrier
@@ -498,6 +521,13 @@ export declare function runInsideLoaderBodyScope<T>(fn: () => T, loaderId?: stri
  * (issue #672, secondary).
  */
 export declare function getCurrentLoaderBodyId(): string | undefined;
+/**
+ * True while `loaderId`'s body, or a loader it awaits via ctx.use at any
+ * depth, is executing. The loader-level cache records these pushes
+ * (loader-cache.ts): a HIT skips the cached body, so a dep that no other
+ * reader runs in that request only reaches the page through the replay.
+ */
+export declare function isInsideLoaderBody(loaderId: string): boolean;
 /**
  * True while a HANDLER-invoked loader body (`await ctx.use(Loader)` from a
  * handler, not the DSL segment funnel) is executing. The consumption-lane

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

@@ -71,8 +71,23 @@ export interface HandleStore {
      * Push handle data for a specific handle and segment.
      * Multiple pushes to the same handle/segment accumulate in an array.
      * Each push triggers an emission on the stream.
+     *
+     * `loaderPush` overrides the push-time DSL-loader tag
+     * (isInsideLoaderScope()) that getDataForSegment(id, true) excludes. The
+     * PPR shell capture passes false for the bake-lane pushes its record keeps
+     * (shell-capture.ts deriveShellCaptureContext), with `owner` set to the
+     * pushing loader's id so the record can restore them through pushReplayed
+     * (getRecordOwners).
      */
-    push(handleName: string, segmentId: string, data: unknown): void;
+    push(handleName: string, segmentId: string, data: unknown, loaderPush?: boolean, owner?: string): void;
+    /**
+     * push() a loader-cache HIT's replayed value, recorded from `loaderId`'s
+     * body (loader-cache.ts replayLoaderHandles). If that loader then runs live
+     * in this request, its first push removes every value replayed for it and
+     * takes the first one's position (later live pushes follow it), so the
+     * handle output stays live without a duplicate.
+     */
+    pushReplayed(handleName: string, segmentId: string, data: unknown, loaderId: string): void;
     /**
      * Get all collected handle data after all handlers have settled.
      * Waits for `settled` (handler lane), then returns the data at that point.
@@ -100,8 +115,17 @@ export interface HandleStore {
     /**
      * Get handle data for a specific segment (for caching).
      * Returns data in format: { handleName: [values...] }
+     *
+     * `excludeLoaderPushes` drops values tagged as DSL-loader pushes at push
+     * time (see push); see captureHandles.
+     */
+    getDataForSegment(segmentId: string, excludeLoaderPushes?: boolean): Record<string, unknown[]>;
+    /**
+     * The push `owner` of each value in getDataForSegment(segmentId, true),
+     * index-aligned per handle (null: no owner). Handles without an owned
+     * value are omitted; undefined when none has one.
      */
-    getDataForSegment(segmentId: string): Record<string, unknown[]>;
+    getRecordOwners(segmentId: string): Record<string, (string | null)[]> | undefined;
     /**
      * 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

@@ -129,8 +129,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,13 +183,12 @@ 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>>;
     /**
@@ -297,17 +301,6 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
         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
@@ -535,6 +528,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
@@ -598,7 +601,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
  * 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" | "_shellCaptureHandleLiveness" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_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" | "_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,12 @@ 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;
 }
 /**
  * Result of a successful shell capture. `prelude` is the raw prelude bytes;
@@ -253,6 +266,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/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/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/vitest-stubs/plugin-rsc.d.ts

@@ -1,9 +1,32 @@
-export declare const createFromReadableStream: () => never;
-export declare const renderToReadableStream: () => never;
+/**
+ * Stub for `@vitejs/plugin-rsc/rsc` and the split `/rsc/server`, `/rsc/client`
+ * entries, shipped so consumers do not have to write a per-file `vi.mock(...)`.
+ * The real entries top-level import Vite virtuals that do not resolve in plain
+ * node.
+ *
+ * Under the `react-server` condition (the Flight project) the "use cache"
+ * codec runs on real Flight: the vendored react-server-dom `server.edge` /
+ * `client.edge` builds that plugin-rsc's `react/rsc/server` and
+ * `react/rsc/client` wrap, with the same manifests and the same server-side
+ * reference loader (`@vitejs/plugin-rsc/core/rsc` `setRequireModule`), so
+ * keys, writes, hits, value round trips and error rows match a build. The
+ * wrappers are not reused: their manifests read `import.meta.env.DEV`, which
+ * is undefined in a module node loads directly (vitest externalizes
+ * node_modules).
+ *
+ * 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.
+ */
+export declare const renderToReadableStream: (value: unknown, options?: object) => ReadableStream<Uint8Array>;
+export declare const createTemporaryReferenceSet: () => unknown;
+export declare const createFromReadableStream: (stream: ReadableStream<Uint8Array>, options?: object, extraOptions?: {
+    preserveServerReferences?: boolean;
+}) => 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 createTemporaryReferenceSet: () => Record<string, never>;
-export declare const encodeReply: () => never;
-export declare const createClientTemporaryReferenceSet: () => Record<string, never>;

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

@@ -170,6 +170,7 @@ interface FlightTransformPlugin {
  * import { defineConfig } from "vitest/config";
  * import {
  *   rangoUseClientTransform,
+ *   rangoUseCacheTransform,
  *   rangoTestAliases,
  *   rangoInlineDeps,
  * } from "@rangojs/router/testing/vitest";
@@ -179,7 +180,7 @@ interface FlightTransformPlugin {
  * process.env.NODE_ENV = "production";
  *
  * export default defineConfig({
- *   plugins: [rangoUseClientTransform()],
+ *   plugins: [rangoUseClientTransform(), rangoUseCacheTransform()],
  *   resolve: {
  *     conditions: ["react-server"],
  *     // Bare `@rangojs/router` -> its react-server build, so a handler/component
@@ -203,4 +204,37 @@ interface FlightTransformPlugin {
  * so `renderToFlightString` of pure leaf trees is unaffected.
  */
 export declare function rangoUseClientTransform(): FlightTransformPlugin;
+/** The Vite plugin shape {@link rangoUseCacheTransform} returns. */
+interface UseCacheTransformPlugin {
+    name: string;
+    enforce: "post";
+    configResolved(config: {
+        root: string;
+    }): void;
+    transform(this: {
+        warn(message: string): void;
+    }, code: string, id: string): Promise<{
+        code: string;
+        map: unknown;
+    } | undefined>;
+}
+/**
+ * A Vite plugin that applies the rango plugin's `"use cache"` transform in a
+ * Vitest project, so a function written with the directive is wrapped with
+ * `registerCachedFunction` as in dev and a build. `rango()` runs that transform
+ * only in its `rsc` environment and Vitest transforms in `ssr`, so without this
+ * plugin the directive is an inert string and the function runs on every call.
+ *
+ * Add it to the react-server project next to {@link rangoUseClientTransform}
+ * (see that function's config). There, with a seeded `cacheStore`,
+ * `renderHandler` / `runLoader` observe real hits. In the node project the
+ * wrap applies too, but the stubbed Flight serializer cannot write an entry.
+ *
+ * Ids are the ones `vite dev` emits: `<path relative to the Vitest root>#<name>`
+ * (a function-level directive gives `src/data.ts#$$hoist_0_getData`), not the
+ * build's hashed path, so store keys stay readable. `configResolved` sets that
+ * root. If `@vitejs/plugin-rsc/transforms` fails to load, the transform throws
+ * instead of leaving the module unwrapped (which the rango plugin does).
+ */
+export declare function rangoUseCacheTransform(): UseCacheTransformPlugin;
 export {};

package/dist/types/theme/ThemeScript.d.ts

@@ -8,14 +8,14 @@
  *
  * Must be placed in the <head> element of your document, before any stylesheets.
  *
- * Note: when theme is enabled in the router config, `<MetaTags />` ALREADY
+ * Note: when theme is enabled in the router config, `<Html.Meta />` ALREADY
  * renders this FOUC script. Use `<ThemeScript />` only if you do NOT render
- * `<MetaTags />`. Rendering both is safe — the inline script guards the
+ * `<Html.Meta />`. Rendering both is safe — the inline script guards the
  * matchMedia listener registration against double-running — but it is redundant.
  *
  * @example
  * ```tsx
- * // In your document component. Use ThemeScript only when you do not render MetaTags.
+ * // In your document component. Use ThemeScript only when you do not render Html.Meta.
  * import { ThemeScript } from "@rangojs/router/theme";
  *
  * export function Document({ children }) {

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

@@ -0,0 +1,9 @@
+/**
+ * Thenable statuses React's `use()` unwraps without suspending: React's
+ * re-check after `.then()` handles "fulfilled", and Flight chunks in the
+ * resolved_* states initialize synchronously inside that same call. Anything
+ * else (pending, blocked, an unstamped native promise) suspends at least once.
+ * Shared by the dev SSR-suspension diagnostic and the held-navigation
+ * isLoading registration (loader-store.ts), which must agree on "settled".
+ */
+export declare function unwrapsSynchronously(stream: Promise<unknown>): boolean;

package/dist/types/types/cache-types.d.ts

@@ -1,12 +1,13 @@
 /**
- * Context passed to cache condition/key/tags functions.
+ * Context passed to cache condition/key/tags functions (the full
+ * RequestContext).
  *
- * This is a subset of RequestContext that's guaranteed to be available
- * during cache key generation (before middleware runs).
- *
- * Note: While the full RequestContext is passed, middleware-set variables
- * read via `ctx.get()` may not be populated yet since cache lookup happens
- * before middleware execution.
+ * Ordering: global middleware wraps the whole request, and on RSC routes route
+ * middleware wraps the match/render pipeline (rsc/handler.ts executeRender), so
+ * variables they set before `next()` are readable via `ctx.get()`. On response
+ * routes the cache lookup runs BEFORE route middleware, which wraps only the
+ * handler run on a miss (rsc/response-route-handler.ts); only global-middleware
+ * variables are populated there.
  */
 export type { RequestContext as CacheContext } from "../server/request-context.js";
 /**
@@ -105,7 +106,8 @@ export interface CacheOptions<TEnv = unknown> {
      * Return false to skip cache for this request (always fetch fresh).
      *
      * Has access to full RequestContext including env, request, params, cookies, etc.
-     * Note: Middleware-set variables read via `ctx.get()` may not be populated yet.
+     * Runs after global and route middleware on RSC routes; on response routes,
+     * before route middleware (see CacheContext).
      *
      * @example
      * ```typescript
@@ -124,7 +126,8 @@ export interface CacheOptions<TEnv = unknown> {
      * Bypasses default key generation AND store's keyGenerator.
      *
      * Has access to full RequestContext including env, request, params, cookies, etc.
-     * Note: Middleware-set variables read via `ctx.get()` may not be populated yet.
+     * Runs after global and route middleware on RSC routes; on response routes,
+     * before route middleware (see CacheContext).
      *
      * @example
      * ```typescript
@@ -143,7 +146,8 @@ export interface CacheOptions<TEnv = unknown> {
      * Tags for cache invalidation.
      * Can be a static array or a function that returns tags.
      *
-     * The built-in `MemorySegmentCacheStore` and `CFCacheStore` index by tag.
+     * The built-in `MemorySegmentCacheStore`, `CFCacheStore`, and
+     * `VercelCacheStore` index by tag.
      * Invalidate on demand with `updateTag(...tags)` (awaitable, read-your-own-writes;
      * for server actions) or `revalidateTag(...tags)` (background hard-purge, not
      * awaited; for route handlers / webhooks). For `CFCacheStore`, distributed

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

@@ -335,6 +335,20 @@ export type InternalHandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch exte
      * table (so a loader cannot await its own in-flight memoized promise).
      */
     _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.
+     */
+    _claimLoaderPushes?: (loaderId: string) => boolean;
+    /**
+     * @internal Run a loader on a fresh executor (own memo map): a loader-cache
+     * stale refresh, whose diverted pushes must not take a dependency's run
+     * from the page. See setupLoaderAccess.
+     */
+    _runLoaderIsolated?: (loader: any) => Promise<any>;
 };
 /**
  * Generic params type - flexible object with string keys