@rangojs/router 0.16.0 → 0.18.0

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

@@ -0,0 +1,132 @@
+/**
+ * serveShellRequest — one request through the production PPR serve path.
+ *
+ * Builds the router's request handler as `router.fetch` does
+ * (`createRSCHandler` with the router's `nonce`, `version` and `cache`
+ * config) and serves one GET through it, so middleware, the shell serve path
+ * and a MISS's background capture all run production code, on real Flight
+ * (the vendored react-server-dom serializer). The call settles every
+ * background task the request scheduled before it returns, so a MISS's
+ * `putShell` has landed.
+ *
+ * The one stub is the SSR module (the HTML step): `react-dom/server` refuses
+ * to load under the react-server condition this project runs with.
+ * - `renderHTML` passes the Flight stream through: a document body is its
+ *   Flight payload.
+ * - `captureShellHTML` returns, as the prelude, the Flight text the capture
+ *   rendered before `quiesce` (plus the post-quiesce task hops the real
+ *   capture takes). `postponed` is always null. A capture that does not
+ *   quiesce within what `ppr.captureTimeout` leaves after the handler output
+ *   settled returns no shell; the real one goes on to its abort and returns
+ *   whatever prelude rendered by then.
+ * - `resumeShellHTML` passes the tail's Flight stream through: a HIT body is
+ *   the stored prelude followed by the tail's Flight payload.
+ * So there is no HTML: the prelude's `<body` sanity gate, SSR render errors
+ * (production refuses the capture on one), fizz resume of the holes,
+ * bootstrap scripts and nonce injection stay e2e-only. A route whose real
+ * capture refuses for a root postpone (a live loader read with no boundary
+ * above it) or an SSR render error is captured here.
+ *
+ * Must run under the `react-server` condition (the rsc Vitest project), with
+ * `rangoTestAliases()` resolving `@vitejs/plugin-rsc/rsc/server` to the stub
+ * that carries the Flight runtime.
+ */
+import { type Rango } from "../router/router-interfaces.js";
+import type { SegmentCacheStore, ShellCacheEntry } from "../cache/types.js";
+import { type PprReplayStatus, type ShellStatus } from "./shell-status.js";
+/** Options for {@link serveShellRequest}. */
+export interface ServeShellRequestOptions<TEnv = any> {
+    /**
+     * The shell and segment store for this request, in place of the router's
+     * `createRouter({ cache })` store. The rest of that config (`enabled`,
+     * `searchParams`) still applies. Omit it to serve through the router's own
+     * store.
+     */
+    cacheStore?: SegmentCacheStore;
+    /** Environment bindings, as `router.fetch(request, { env })` passes them. */
+    env?: TEnv;
+    /**
+     * Request headers. A document request defaults `accept` to `text/html`.
+     */
+    headers?: HeadersInit;
+    /**
+     * Serve the client navigation the browser sends (`?_rsc_partial`) instead
+     * of a document GET: from `from` (default `/`) with `segments` mounted
+     * (default none), advertising fragment passthrough. The replay decision is
+     * `result.replayStatus`.
+     */
+    partial?: true | {
+        from?: string;
+        segments?: readonly string[];
+    };
+}
+/** Result of {@link serveShellRequest}. */
+export interface ServeShellRequestResult {
+    /** The handler's Response. Its body is already read: see `body`. */
+    response: Response;
+    /** The response body text. */
+    body: string;
+    /** `x-rango-shell` (`HIT` | `MISS`), or null when the header is absent. */
+    shellStatus: ShellStatus | null;
+    /** `x-rango-ppr-replay` on a partial request, or null. */
+    replayStatus: PprReplayStatus | null;
+    /**
+     * The prelude a HIT served: the capture's Flight text at quiesce (the
+     * shell as captured). Undefined unless `shellStatus` is `HIT`.
+     */
+    prelude: string | undefined;
+    /**
+     * The Flight payload this request rendered: a HIT's tail, a document's
+     * render, or a Flight response. Undefined when no Flight was rendered (a
+     * redirect or a middleware response).
+     */
+    flight: string | undefined;
+    /**
+     * The shell key production resolved for this request: for a document the
+     * serve path read and captured (a MISS or a HIT), the key it used, request
+     * partition included (a route partitioned by `cache({ key })` or the
+     * store's `keyGenerator`). Otherwise (a route without `ppr`, a request
+     * passed to axis 1 before its key was resolved, a partial request) the
+     * document URL's key without a partition, as `shellCacheKey` builds it.
+     */
+    key: string;
+    /**
+     * Read the document shell entry under `key` from the request's store
+     * (a passive `getShell`), or null. A read, so on a store with a shell memo
+     * (CFCacheStore, VercelCacheStore) it warms the memo like any other read.
+     */
+    readEntry(): Promise<ShellCacheEntry | null>;
+}
+/**
+ * Reset the per-isolate PPR state requests leave behind, so the next test
+ * starts as a fresh worker would: the capture's stampede guard, its backoff
+ * (a refused capture backs its URL off for later tests too), the capture's
+ * and the serve path's once-per-key warnings, the build-shell manifest memo,
+ * and CFCacheStore's isolate memos (shells, tag markers, tag hints), which
+ * every CFCacheStore in the process shares by namespace and URL. Call it in
+ * `beforeEach`, never while a request is in flight. VercelCacheStore's memos
+ * live on the `cache` handle it is given: a new handle starts empty.
+ */
+export declare function resetShellTestState(): Promise<void>;
+/**
+ * Serve one GET for `url` through the router's production request handler
+ * and settle the background tasks it scheduled (a MISS's capture and
+ * `putShell` included). The first request for a `ppr` route is a MISS; the
+ * next one with the same store is a HIT from the stored shell. The HTML step
+ * is stubbed (see the module header), so `prelude` and `flight` are Flight
+ * text. The request starts in a later millisecond than the call: a store
+ * refuses a capture that starts in the millisecond of a tag invalidation, so
+ * an `updateTag()` made just before the call never refuses its recapture.
+ * Rejects when the handler throws or the response stream errors (a failing
+ * HIT tail), after settling the tasks scheduled so far.
+ *
+ * @example
+ * const store = new MemorySegmentCacheStore();
+ * const miss = await serveShellRequest(router, "/product/1", { cacheStore: store });
+ * expect(miss.shellStatus).toBe("MISS");
+ * const hit = await serveShellRequest(router, "/product/1", { cacheStore: store });
+ * expect(hit.shellStatus).toBe("HIT");
+ * expect(hit.prelude).toContain("Widget"); // captured shell
+ * expect(hit.flight).toContain("in stock"); // live hole, rendered now
+ */
+export declare function serveShellRequest<TEnv = any>(router: Rango<TEnv, any>, url: string | URL, options?: ServeShellRequestOptions<TEnv>): Promise<ServeShellRequestResult>;

package/dist/types/testing/shell-status.d.ts

@@ -18,11 +18,15 @@
  *    Secondary unit signal: `store.getShell(shellCacheKey(url))` after a real
  *    capture flush (background `putShell`). There is no Flight flag for shell HIT.
  *
- * 3. **Stays e2e-only:** live MISS → background capture → HIT (needs real
- *    `captureShellHTML` / React `prerender` + resume fizz), browser resume of
- *    holes, Cloudflare/Vercel live stores, nonce/eligibility fall-open, and
- *    build-time producer B bake. Unit layer dogfoods the **store family + key
- *    identity + header assert**; it must never stub a shell HIT response.
+ * 3. **A real MISS → capture → HIT in unit tests:** `serveShellRequest`
+ *    (`@rangojs/router/testing/flight`, serve-shell-request.ts) serves one
+ *    request through the router's production handler and settles its
+ *    background capture; a later request with the same store is a real HIT or
+ *    partial replay. Its only stub is the HTML step (the SSR module).
+ *    **Stays e2e-only:** real HTML (the prelude's `<body` gate, fizz resume of
+ *    holes), browser resume of holes, live Cloudflare/Vercel runtimes (store
+ *    test doubles work in unit), and build-time producer B bake. The unit layer
+ *    must never stub a shell HIT response.
  *
  * Import from `@rangojs/router/testing` (Vitest) or `@rangojs/router/testing/e2e`
  * (Playwright — same pure helpers, no Vite virtuals).
@@ -34,7 +38,7 @@ export declare const SHELL_STATUS_HEADER: string;
 export declare const PPR_REPLAY_STATUS_HEADER: string;
 /** Values the serve path writes on `x-rango-shell`. */
 export type ShellStatus = "HIT" | "MISS";
-declare const PPR_REPLAY_BYPASS_REASONS: readonly ["method", "dynamic", "nonce", "store-unavailable", "passive-read-unsupported", "no-navigation-context", "prerender-store", "intercept", "cache-disabled", "read-error", "no-entry", "invalid-version", "corrupt-entry", "handler-live-holes", "transition-when", "no-segment-snapshot", "snapshot-miss", "explicit-cache-hit", "stale-build-entry"];
+declare const PPR_REPLAY_BYPASS_REASONS: readonly ["method", "dynamic", "nonce", "store-unavailable", "passive-read-unsupported", "no-navigation-context", "prerender-store", "intercept", "cache-disabled", "read-error", "no-entry", "invalid-version", "corrupt-entry", "no-segment-snapshot", "snapshot-miss", "explicit-cache-hit", "stale-build-entry"];
 /** Bounded reasons a PPR partial request can fall open to ordinary matching. */
 export type PprReplayBypassReason = (typeof PPR_REPLAY_BYPASS_REASONS)[number];
 /** Parsed `x-rango-ppr-replay` value. */
@@ -52,15 +56,24 @@ export type ShellStatusTarget = Response | {
 /**
  * Shell store key for a document URL — same formula as production
  * `buildShellKey` in `rsc/shell-serve.ts` (host + pathname + sorted search +
- * `:shell`). Kept here so the testing barrel never imports the shell-serve
- * module (it pulls React). A parity test pins the two implementations.
+ * `:shell`), then the production `partitionShellKey` itself (the leaf
+ * `rsc/shell-capture-constants.ts`). The base is kept here so the testing
+ * barrel never imports the shell-serve module (it pulls React). A parity test
+ * pins the two implementations.
  *
  * Accepts a `URL` or an absolute/relative request URL string (relative strings
  * resolve against `http://localhost`). Pass the router's `cache.searchParams`
  * config as `searchParams` when the app under test sets one — the production
- * key applies it, so the expected key must too.
+ * key applies it, so the expected key must too. When the route's record is
+ * partitioned by the request — its `cache({ key })`, or the store's
+ * `keyGenerator` — its shell is too: pass the key that function returns for
+ * the request as `partition` (appended URI-encoded; a result equal to the
+ * default key partitions nothing, so pass none). Under nested keyed
+ * `cache()` scopes, pass their `key()` results as an array, outermost first:
+ * they compose as the production record key composes them
+ * (`composeCacheKeys`).
  */
-export declare function shellCacheKey(url: URL | string, searchParams?: CacheSearchParams): string;
+export declare function shellCacheKey(url: URL | string, searchParams?: CacheSearchParams, partition?: string | readonly string[]): string;
 /**
  * Read `x-rango-shell` from a response. Returns `null` when the header is
  * absent (axis-1 / non-ppr / ineligible request).

package/dist/types/testing/vitest-stubs/plugin-rsc.d.ts

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

@@ -235,6 +235,12 @@ export type HandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch extends Sear
      * Current theme (from cookie or default).
      * Only available when theme is enabled in router config.
      *
+     * The visitor's cookie, so it is guarded like `cookies()`: reading it on a
+     * `ppr` route refuses the shell capture, and inside a `cache()` boundary or
+     * a `"use cache"` function it throws (#971). Read it with `useTheme()` in a
+     * client component, or in a live loader, on those routes. A read-only,
+     * non-enumerable getter: `{ ...ctx }` does not carry it.
+     *
      * @example
      * ```typescript
      * route("settings", (ctx) => {
@@ -243,7 +249,7 @@ export type HandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch extends Sear
      * });
      * ```
      */
-    theme?: Theme;
+    readonly theme?: Theme;
     /**
      * Set the theme (only available when theme is enabled in router config).
      * Sets a cookie with the new theme value.
@@ -335,6 +341,27 @@ 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>;
+    /**
+     * @internal A loader's cache() binding started with these cache() tags: an
+     * execution of that loader outside the binding (a reader started it first,
+     * or a stale refresh runs it) answers for them too (#964). See
+     * setupLoaderAccess.
+     */
+    _bindLoaderCacheTags?: (loaderId: string, tags: Set<string>) => void;
 };
 /**
  * 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/pattern-types.d.ts

@@ -53,30 +53,34 @@ export interface PartialPrerenderProps {
     /**
      * Operational tags attached to the captured shell entry for
      * `updateTag()`/`revalidateTag()`-driven eviction. UNIONED with the tags the
-     * capture render auto-collects (the shell's own non-loader request tags).
+     * capture collects: its doc record's tags (what the handler layer and the
+     * server components it rendered recorded) and its bake-lane loaders'.
      */
     tags?: string[];
     /**
-     * Upper bound (serialized UTF-8 bytes) on the capture data snapshot riding
-     * inside the shell entry. The snapshot duplicates every cache-store value
-     * the capture pinned, so a page over a large cache() segment can push the
-     * entry toward store value limits (Cloudflare KV caps a value at 25 MiB).
-     * Over the cap the snapshot is skipped: the shell is still stored and
-     * served, but pinned reads fall back to the live store, so drifted cached
-     * content can hydration-mismatch and be repaired client-side (the
-     * pre-snapshot behavior). Reported once per key. Defaults to 8 MiB.
+     * Upper bound (serialized UTF-8 bytes) on the loader pins in the capture
+     * data snapshot: the loader records and the cache values loaders read,
+     * duplicated into the shell entry. The doc record (the handler layer every
+     * HIT replays) is exempt. Over the cap the pins are dropped: the shell is
+     * still stored and every HIT still replays the handler layer, but the
+     * pinned loaders read the live store, so drifted cached content can
+     * hydration-mismatch and be repaired client-side. Reported once per key.
+     * Defaults to 8 MiB. The whole entry is bounded separately by the store's
+     * value limit (Cloudflare KV: 25 MiB); an entry over it is refused.
      */
     maxSnapshotBytes?: number;
     /**
-     * Capture settle budget in MILLISECONDS (default 15000). Bounds the whole
-     * background capture: the wait for deferred shell material — top-level
-     * pushed handle promises (`ctx.use(Meta)(promise.then(...))` and friends)
-     * are AWAITED and their settled values baked into the stored shell — AND
-     * the fizz prerender deadline. Declare it to tighten the budget below the
-     * default or when a route's shell material takes longer than 15s to
-     * settle. A budget that expires with pushes still pending REFUSES the
-     * capture (the route stays MISS with the once-per-key warning) — a shell
-     * with missing head material is never stored. Capture is background work
+     * Capture settle budget in MILLISECONDS (default 15000). One deadline for
+     * the whole background capture: the match (the handlers, and the loaders
+     * they await), the wait for handler output (handle pushes and the promises
+     * nested in them, bake-lane loaders, and the doc record's encode, which
+     * awaits handler promises and async server components), AND the fizz
+     * prerender. Everything a handler produces is
+     * awaited and baked into the stored shell. Declare it to tighten the
+     * budget below the default or when a route's shell material takes longer
+     * than 15s to settle. A budget that expires before the doc record is
+     * written REFUSES the capture (the route stays MISS with the once-per-key
+     * warning): a shell with missing handler output is never stored. Capture is background work
      * (waitUntil), so a longer budget costs latency-to-HIT only, never a served
      * response; the platform waitUntil lifetime (workerd: ~30s past response
      * completion) is the physical ceiling — the default's derivation lives in

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'] } }),
  *   ],
  * });
  * ```