@rangojs/router 0.16.0 → 0.17.0

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

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

@@ -23,9 +23,10 @@ import type { RequestScope } from "./request-scope.js";
  *   return await db.cart.get(user.id);
  * });
  *
- * // With typed params:
- * const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
- *   const { slug } = ctx.params;  // slug is typed as string
+ * // createLoader's one type parameter is the data type; params are
+ * // Record<string, string | undefined>:
+ * const ProductLoader = createLoader<Product>(async (ctx) => {
+ *   const { slug } = ctx.params;  // string | undefined
  *   return await db.products.findBySlug(slug);
  * });
  * ```
@@ -213,9 +214,10 @@ export type LoadOptions = {
  *   return await db.cart.get(ctx.get("user").id);
  * });
  *
- * // With typed params:
- * export const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
- *   const { slug } = ctx.params;  // slug is typed as string
+ * // createLoader's one type parameter is the data type; params are
+ * // Record<string, string | undefined>:
+ * export const ProductLoader = createLoader<Product>(async (ctx) => {
+ *   const { slug } = ctx.params;  // string | undefined
  *   return await db.products.findBySlug(slug);
  * });
  *

package/dist/types/urls/response-types.d.ts

@@ -1,18 +1,8 @@
 import type { ContextVar } from "../context-var.js";
-import type { ReverseFunction } from "../reverse.js";
+import type { GlobalReverseFunction } from "../reverse.js";
 import type { DefaultReverseRouteMap, DefaultVars } from "../types/global-namespace.js";
 import type { UseItems, ResponseRouteUseItem } from "../route-types.js";
 import type { RequestScope } from "../types/request-scope.js";
-/**
- * Reverse function for response handler contexts.
- * Global names get autocomplete and param validation from the generated route map.
- * Local `.name` calls are accepted but not validated (scope unknown at type level).
- */
-type ResponseReverseFunction = [DefaultReverseRouteMap] extends [
-    Record<string, string>
-] ? (name: string, params?: Record<string, string>, search?: Record<string, unknown>) => string : ReverseFunction<DefaultReverseRouteMap> & {
-    (name: `.${string}`, params?: Record<string, string>, search?: Record<string, unknown>): string;
-};
 /**
  * Symbol marking a route as a response route (non-RSC).
  * Stored on PathOptions and UrlPatterns to signal the trie to short-circuit.
@@ -56,7 +46,8 @@ export interface ResponseHandlerContext<TParams = Record<string, string>, TEnv =
     params: TParams;
     /** @internal Phantom property for params type invariance. Prevents mounting handlers on wrong routes. */
     readonly _paramCheck?: (params: TParams) => TParams;
-    reverse: ResponseReverseFunction;
+    /** Global route names only; see {@link GlobalReverseFunction}. */
+    reverse: GlobalReverseFunction<DefaultReverseRouteMap>;
     /** Read a variable set by middleware via ctx.set(key, value) or ctx.set(ContextVar, value). */
     get: {
         <T>(contextVar: ContextVar<T>): T | undefined;

package/dist/types/use-loader.d.ts

@@ -2,6 +2,14 @@ import type { LoaderDefinition, LoadOptions } from "./types.js";
 export type LoadFunction<T> = (options?: LoadOptions) => Promise<T>;
 export interface UseLoaderResult<T> {
     data: T;
+    /**
+     * True while this loader family (`loader.$$id`) is in flight: a `load()` /
+     * group refresh, or a held navigation still streaming a re-run of this
+     * loader. Family-keyed, not segment-keyed: a layout `useLoader` of the same
+     * `createLoader` the child route is re-running also reports true, even if
+     * the layout copy is not replaced. Not used for the initial streamed read
+     * (that suspends).
+     */
     isLoading: boolean;
     error: Error | null;
     load: LoadFunction<T>;
@@ -9,6 +17,7 @@ export interface UseLoaderResult<T> {
 }
 export interface UseFetchLoaderResult<T> {
     data: T | undefined;
+    /** Same family-keyed contract as {@link UseLoaderResult.isLoading}. */
     isLoading: boolean;
     error: Error | null;
     load: LoadFunction<T>;
@@ -36,7 +45,7 @@ export interface UseLoaderOptions {
  * @example Basic usage - accessing route loader data
  * ```tsx
  * "use client";
- * import { useLoader } from "rsc-router/client";
+ * import { useLoader } from "@rangojs/router/client";
  * import { CartLoader } from "../loaders/cart";
  *
  * // In route definition: loader(CartLoader)
@@ -67,7 +76,7 @@ export declare function useLoader<T>(loader: LoaderDefinition<T>, options?: UseL
  * @example On-demand fetching
  * ```tsx
  * "use client";
- * import { useFetchLoader } from "rsc-router/client";
+ * import { useFetchLoader } from "@rangojs/router/client";
  * import { SearchLoader } from "../loaders/search";
  *
  * export function SearchResults() {
@@ -121,7 +130,7 @@ export declare function useFetchLoader<T>(loader: LoaderDefinition<T>, options?:
  * @example
  * ```tsx
  * "use client";
- * import { useLoader, useRefreshLoaders } from "rsc-router/client";
+ * import { useLoader, useRefreshLoaders } from "@rangojs/router/client";
  *
  * function Profile() {
  *   const { data } = useLoader(ProfileLoader, { key: userId, refreshGroup: "account" });

package/dist/types/vite/plugins/use-cache-transform.d.ts

@@ -15,6 +15,37 @@
  * - transformWrapExport() for file-level wrapping
  * - transformHoistInlineDirective() for function-level hoisting
  */
-import type { Plugin } from "vite";
+import type { Plugin, Rollup } from "vite";
+import type { Counter } from "../debug.js";
 export declare const USE_CACHE_DIRECTIVE_RE: RegExp;
-export declare function useCacheTransform(): Plugin;
+/**
+ * @param counter `rango:transform` timing counter, created by `rango()`
+ *   (`createCounter` in ../debug.js); omitted when debugging is off.
+ */
+export declare function useCacheTransform(counter?: Counter): Plugin;
+/** Options for {@link transformUseCache}. */
+export interface UseCacheTransformOptions {
+    /** Root the ids are relative to (Vite's `config.root`). */
+    root: string;
+    /** Build ids hash the path (`hashId`); dev ids are `<path>#<export>`. */
+    isBuild: boolean;
+    /** Sink for the near-miss directive warning. */
+    warn: (message: string) => void;
+    /**
+     * Called when `@vitejs/plugin-rsc/transforms` fails to load; the module is
+     * then left unwrapped. The rango plugin omits it (skip silently).
+     */
+    onTransformsError?: (error: unknown) => void;
+}
+/** Whether a module may carry a `"use cache"` directive the transform wraps. */
+export declare function isUseCacheCandidate(code: string, id: string): boolean;
+/**
+ * Wrap a module's `"use cache"` functions with `registerCachedFunction`. The
+ * rango plugin runs it in the rsc environment; `rangoUseCacheTransform()`
+ * (testing/vitest.ts) runs it in a Vitest project, whose environment is `ssr`.
+ * Call it only for an {@link isUseCacheCandidate} module.
+ */
+export declare function transformUseCache(code: string, id: string, options: UseCacheTransformOptions): Promise<{
+    code: string;
+    map: Rollup.ExistingRawSourceMap;
+} | undefined>;

package/dist/types/vite/rango.d.ts

@@ -21,7 +21,7 @@ export { hasUseClientDirective };
  *   plugins: [
  *     react(),
  *     rango({ preset: 'cloudflare' }),
- *     cloudflare({ viteEnvironment: { name: 'rsc' } }),
+ *     cloudflare({ viteEnvironment: { name: 'rsc', childEnvironments: ['ssr'] } }),
  *   ],
  * });
  * ```