@rangojs/router 0.17.0 → 0.19.0

package/dist/types/testing/location-state-key.d.ts

@@ -0,0 +1,24 @@
+import { type LocationStateDefinition } from "../browser/react/location-state-shared.js";
+/**
+ * Assign a location-state key to a `createLocationState()` definition in a unit
+ * test that runs without the rango Vite plugin (which injects the key in dev
+ * and build). Outside production, a definition without a key throws on first
+ * use (`MyState(value)`, `useLocationState(MyState)`, `.read()`).
+ *
+ * - `withLocationStateKey(GridState, "GridState")` sets `__rsc_ls_GridState`
+ *   (a name that already starts with `__rsc_ls_` is used as-is).
+ * - Without a name, a key already set (by the plugin or an earlier call) is
+ *   kept; otherwise the definition gets a synthetic `__rsc_ls_test_<n>` key,
+ *   which then stays on it.
+ *
+ * Returns the definition.
+ *
+ * @example
+ * ```ts
+ * import { withLocationStateKey } from "@rangojs/router/testing";
+ * import { GridState } from "../src/location-states";
+ *
+ * withLocationStateKey(GridState);
+ * ```
+ */
+export declare function withLocationStateKey<TDefinition extends LocationStateDefinition<any, any>>(definition: TDefinition, name?: string): TDefinition;

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

@@ -30,6 +30,11 @@
  *     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).
+ *   - A spec's transition({ when }) decides every commit with production's
+ *     browser decision: navigate() and useRouter().push model kind "push",
+ *     useRouter().replace kind "replace", refresh() kind "revalidate".
+ *     Back/forward, action and optimistic clientUrls() swap decisions are
+ *     e2e territory.
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
  * useRouter, usePathname, useSearchParams, Outlet/useOutlet nesting and seeded
@@ -273,8 +278,19 @@ export interface TestRouterHandle {
      * // reader: isLoading true, old data
      * await act(async () => resolve({ name: "Product 2" }));
      * // reader: isLoading false, new data
+     *
+     * `options.transition: false` is the per-navigation opt-out
+     * (`router.push(url, { transition: false })`, `<Link transition={false}>`):
+     * the commit is urgent and no transition({ when }) predicate is called.
+     */
+    navigate(url: string, options?: Pick<RenderRouteOptions, "loaders"> & {
+        transition?: boolean;
+    }): Promise<void>;
+    /**
+     * Re-render the current location, as router.refresh() does: a spec's
+     * transition({ when }) decides it with kind "revalidate" (`to` is `from`).
      */
-    navigate(url: string, options?: Pick<RenderRouteOptions, "loaders">): Promise<void>;
+    refresh(): Promise<void>;
     /** The current committed pathname. */
     pathname(): string;
     /** The current committed params. */

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

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

package/dist/types/testing/run-transition-when.d.ts

@@ -1,78 +1,53 @@
 /**
- * runTransitionWhen — unit-test a transition({ when }) predicate in isolation.
+ * runTransitionWhen — unit-test a transition({ when }) browser predicate.
  *
- * Runs the SAME server functions the router uses — the PPR pre-handler evaluator
- * when `ppr: true`, applyViewTransitionDefault (which strips the server-only
- * function), and gateTransitions. So the
- * predicate sees exactly the navigation/action metadata it would at runtime
- * (currentUrl/currentParams/fromRouteName, nextUrl/nextParams/toRouteName,
- * actionId/actionUrl/actionResult/formData/method, get/env), and `kept` reflects
- * whether the transition would apply this request. The result also exposes the
- * assembled `whenContext` so tests can assert the exact fields without reaching
- * into private request-context state.
+ * Builds the context and evaluates the predicate through the SAME browser
+ * functions the router uses at navigation time (browser/transition-when.ts):
+ * a throw counts as false and is logged. `from`/`to` take a URL string or a
+ * partial RouteLocation; a `state` given as location-state entries
+ * (`[Def(value)]`, what Link/push take) is stored the way a push stores it,
+ * so `Def.read(ctx.to)` reads it back. Accepts the predicate or a whole
+ * TransitionConfig.
  *
- * This is the public way to exercise a transition gate: the full
- * match -> render pipeline that wires these together only runs under real RSC
- * rendering (which the Flight primitives do not drive), so without this primitive
- * a consumer could not test their predicate through @rangojs/router/testing.
- *
- * Synchronous: a transition predicate returns a boolean and the gate has no I/O.
- */
-import { type RequestContext } from "../server/request-context.js";
-import { type VarsInit } from "./internal/context.js";
-import type { TransitionConfig, TransitionWhenContext } from "../types/segments.js";
-import type { OnErrorCallback } from "../types/error-types.js";
-/**
- * Options for runTransitionWhen. All navigation/action fields are optional and
- * default to "absent", matching what the gate sees for an initial full load with
- * no action: omit `currentUrl`/`currentParams`/`fromRouteName` to model the
- * navigation source being unavailable, and omit the `action*` fields to model a
- * plain (non-action) navigation.
+ * Synchronous: a transition predicate returns a boolean and has no I/O.
  */
-export interface RunTransitionWhenOptions<TEnv = any> {
-    /** The navigation TARGET request (drives `nextUrl`): a Request or URL/path string. Defaults to `http://localhost/`. */
-    request?: Request | string;
-    /** Route params for the target (`nextParams`). */
-    params?: Record<string, string>;
-    /** Target route name (`toRouteName`). */
-    toRouteName?: string;
-    /** Environment bindings surfaced as `env` (and `ctx.env`). */
-    env?: TEnv;
-    /** Variables readable via the predicate's `get()`. With `ppr`, these model pre-handler middleware/input state. */
-    vars?: VarsInit;
-    /** Navigation SOURCE url (`currentUrl`): a URL or path string. */
-    currentUrl?: string | URL;
-    /** Source route params (`currentParams`). */
-    currentParams?: Record<string, string>;
-    /** Source route name (`fromRouteName`). */
-    fromRouteName?: string;
-    /** Id of the action that triggered a revalidation (`actionId`). */
-    actionId?: string;
-    /** Url the action was submitted from (`actionUrl`). */
-    actionUrl?: string | URL;
-    /** The action's return value (`actionResult`). */
-    actionResult?: unknown;
-    /** FormData from a form action (`formData`). */
+import type { RouteLocation, TransitionConfig, TransitionWhenContext, TransitionWhenFn, TransitionWhenKind } from "../types/segments.js";
+type ImportedAction = (...args: never[]) => unknown;
+/** A navigation side: a URL, or a partial RouteLocation. */
+export type RunTransitionWhenLocation = string | URL | (Partial<Omit<RouteLocation, "url">> & {
+    url?: string | URL;
+});
+/** The action fields of a `kind: "action"` context. */
+export interface RunTransitionWhenAction {
+    /** The triggering action: an imported server action or its actionId. */
+    ref?: ImportedAction | string;
     formData?: FormData;
-    /** Receives an error thrown by the predicate (the gate reports to `router.onError`, phase `"rendering"`). */
-    onError?: OnErrorCallback;
-    /** Model a route with `ppr`, where the predicate runs before route handlers and cache lookup. */
-    ppr?: boolean;
+    /** The action's return value on success. */
+    result?: unknown;
+    /** What a failed action threw (the error lane). */
+    error?: unknown;
 }
-/**
- * Result of runTransitionWhen.
- */
-export interface RunTransitionWhenResult<TEnv = any> {
-    /** True if the transition would apply this request (predicate returned non-false, or there is no `when`). */
-    kept: boolean;
-    /** Convenience inverse of `kept`. */
-    dropped: boolean;
+export interface RunTransitionWhenOptions {
+    /** Defaults to `"action"` when `action` is given, `"push"` otherwise. */
+    kind?: TransitionWhenKind;
+    /** The committed location being left. Defaults to `http://localhost/`. */
+    from?: RunTransitionWhenLocation;
+    /** The destination. Defaults to `from`; always `from` for "action" and "revalidate". */
+    to?: RunTransitionWhenLocation;
     /**
-     * The production-assembled predicate context. Undefined when the config has
-     * no `when` predicate.
+     * The triggering action (like runClientRevalidate's): an imported server
+     * action (id via `$id ?? $$id`), an actionId string, or
+     * `{ ref, formData, result, error }`.
      */
-    whenContext?: TransitionWhenContext<Record<string, string>, TEnv>;
-    /** The underlying RequestContext, for additional assertions (`ctx.get(...)`, etc.). */
-    ctx: RequestContext<TEnv>;
+    action?: ImportedAction | string | RunTransitionWhenAction;
+}
+export interface RunTransitionWhenResult {
+    /** True when the navigation holds (the predicate did not return false or throw, or there is none). */
+    applied: boolean;
+    /** Inverse of `applied`. */
+    gatedOff: boolean;
+    /** The context the predicate received. */
+    context: TransitionWhenContext;
 }
-export declare function runTransitionWhen<TEnv = any>(config: TransitionConfig, opts?: RunTransitionWhenOptions<TEnv>): RunTransitionWhenResult<TEnv>;
+export declare function runTransitionWhen(whenOrConfig: TransitionWhenFn | TransitionConfig, opts?: RunTransitionWhenOptions): RunTransitionWhenResult;
+export {};

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

@@ -0,0 +1,133 @@
+/**
+ * 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 shell path's
+ * once-per-key warnings, the build-shell manifest memo, the "use cache"
+ * in-flight leaders and warnings, and CFCacheStore's isolate memos (shells,
+ * tag markers, tag hints) and warnings, 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,25 +18,25 @@
  *    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).
  */
+import { PPR_REPLAY_STATUS_HEADER, SHELL_STATUS_HEADER, type PprReplayBypassReason } from "../rsc/shell-capture-constants.js";
 import { type CacheSearchParams } from "../cache/search-params-filter.js";
-/** Production header name (`rsc/shell-serve.ts` `SHELL_STATUS_HEADER`). */
-export declare const SHELL_STATUS_HEADER: string;
-/** Partial-navigation replay decision header from `rsc/rsc-rendering.ts`. */
-export declare const PPR_REPLAY_STATUS_HEADER: string;
+export { PPR_REPLAY_STATUS_HEADER, SHELL_STATUS_HEADER };
+export type { PprReplayBypassReason };
 /** 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"];
-/** 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. */
 export type PprReplayStatus = {
     outcome: "HIT";
@@ -50,17 +50,43 @@ export type ShellStatusTarget = Response | {
     headers: Headers;
 };
 /**
- * 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.
+ * What partitions a ppr route's shell, for {@link shellCacheKey}: the
+ * request's results of the functions that partition the route's cache()
+ * record.
+ */
+export interface ShellCachePartition {
+    /** The route's cache() `key()` results, outermost first. */
+    keys?: readonly string[];
+    /**
+     * Store `keyGenerator` results, one per store, outermost first: an
+     * enclosing cache() on another store's, then the store's of the route's
+     * own cache() when it sets no `key()` (with no route cache(), the app
+     * store's). When every one returns the default key they partition
+     * nothing: leave them out. Otherwise each keeps its position, and one
+     * that returns the default key is `""`.
+     */
+    generated?: readonly string[];
+}
+/**
+ * Shell store key for a document URL: the production `buildShellKey` (host +
+ * pathname + sorted search + `:shell`) and `partitionShellKey`, both from the
+ * React-free leaf `rsc/shell-capture-constants.ts`, so the testing barrel never
+ * imports the shell-serve module (it pulls React).
  *
  * 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 shell is too: pass what partitions it as
+ * `partition`, composed as production composes it (`composeCacheKeys`,
+ * which namespaces each `key()` result):
+ * - its `cache({ key })` result, as a string;
+ * - nested keyed `cache()` scopes' `key()` results, as an array, outermost
+ *   first;
+ * - store `keyGenerator` results, with or without `key()` results, as
+ *   `{ keys, generated }` (see {@link ShellCachePartition}).
  */
-export declare function shellCacheKey(url: URL | string, searchParams?: CacheSearchParams): string;
+export declare function shellCacheKey(url: URL | string, searchParams?: CacheSearchParams, partition?: string | readonly string[] | ShellCachePartition): string;
 /**
  * Read `x-rango-shell` from a response. Returns `null` when the header is
  * absent (axis-1 / non-ppr / ineligible request).
@@ -78,4 +104,3 @@ export declare function assertShellStatus(target: ShellStatusTarget, expected: S
 export declare function parsePprReplayStatus(target: ShellStatusTarget): PprReplayStatus | null;
 /** Assert a partial response's PPR replay outcome and freshness/reason. */
 export declare function assertPprReplayStatus(target: ShellStatusTarget, expected: PprReplayStatus): void;
-export {};

package/dist/types/transition-when-ref.d.ts

@@ -0,0 +1,79 @@
+/**
+ * transition({ when }) references: what a route definition may carry as a
+ * `when`, how definitions are validated, and how the browser turns the carried
+ * value back into a callable predicate.
+ *
+ * `when` is a BROWSER predicate. The server never calls it; it only carries it
+ * to the browser inside the segment's transition config, as one of:
+ *
+ * - a React client reference: a function exported from a `"use client"`
+ *   module and imported into a server `urls()` file, or an inline literal the
+ *   build hoisted into one (vite/plugins/transition-when-hoist.ts). Flight
+ *   serializes it as a module reference and the browser resolves it to the
+ *   real function;
+ * - a clientUrls() when reference, synthesized by the projection materializer
+ *   (client-urls/server-projection.ts): the group's definition client
+ *   reference plus the route id. The browser resolves it to the `when` the
+ *   route declared in its `"use client"` module.
+ *
+ * A plain function (a server function) cannot cross Flight, and a
+ * non-function is never callable. Both are LOUD errors: route discovery
+ * (generateManifestFull `validateTransitionWhen`) fails dev startup, the
+ * build and HMR re-discovery, and attachTransitionWhen (rsc/) throws the same
+ * error at render time for a route discovery did not see.
+ *
+ * Telling a client reference apart from a server function needs the
+ * react-server module graph, where a `"use client"` import IS a client
+ * reference. Outside it (a node/DOM unit-test project that aliases the router
+ * entry) the import is the plain function, so strict validation is enabled
+ * only by the Vite plugin: discovery passes the option, and the generated
+ * routes-manifest module calls enableTransitionWhenValidation() in the app's
+ * RSC realm (vite/discovery/virtual-module-codegen.ts).
+ */
+import type { TransitionWhenFn } from "./types/segments.js";
+export declare function isClientReference(value: unknown): boolean;
+export declare function createClientUrlsWhenRef(definition: unknown, routeId: string): TransitionWhenFn;
+/**
+ * Turn on server-function rejection for this realm. Called by the Vite
+ * plugin's generated routes-manifest module, never by tests: see the module
+ * comment for why it cannot be on by default.
+ */
+export declare function enableTransitionWhenValidation(): void;
+export declare function isTransitionWhenValidationEnabled(): boolean;
+/** @internal Reset for unit tests. */
+export declare function resetTransitionWhenValidation(): void;
+/** Thrown for an invalid transition({ when }); recognized by the dev HMR overlay. */
+export declare class TransitionWhenError extends Error {
+    readonly name: string;
+}
+/**
+ * The TransitionWhenError in an error's cause chain, matched by name: discovery
+ * throws it from the module runner's copy of this module (another class
+ * object), and include resolution wraps it (build/generate-manifest.ts).
+ */
+export declare function findTransitionWhenError(error: unknown): Error | undefined;
+/** Where an invalid `when` was declared, for the error message. */
+export interface TransitionWhenSite {
+    /** The route the entry belongs to (the matched or enumerated route). */
+    readonly routeName?: string;
+    readonly pattern?: string;
+    /** The declaring entry's type when it is not the route itself. */
+    readonly entryType?: string;
+}
+/**
+ * The problem with a `when` value, or null when it is valid. Non-functions
+ * are always invalid; a plain function is invalid only under strict
+ * validation (see the module comment).
+ */
+export declare function transitionWhenProblem(when: unknown, strict: boolean): "not-a-function" | "server-function" | null;
+export declare function createTransitionWhenError(when: unknown, problem: "not-a-function" | "server-function", site: TransitionWhenSite): TransitionWhenError;
+/**
+ * Definition-time shape check (the DSL's transition()). Runs in every
+ * environment, so it rejects only what is invalid everywhere: a non-function.
+ */
+export declare function assertTransitionWhenShape(when: unknown): void;
+/**
+ * Browser: turn a transition config's `when` into the predicate to call.
+ * Undefined when there is none (or a clientUrls route no longer declares it).
+ */
+export declare function resolveTransitionWhen(when: unknown): TransitionWhenFn | undefined;

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

@@ -69,7 +69,13 @@ export interface CacheOptions<TEnv = unknown> {
     /**
      * Override the cache store for this boundary.
      * When specified, this boundary and its children use this store
-     * instead of the app-level store from handler config.
+     * instead of the app-level store from handler config. The records of a
+     * boundary with a store here are partitioned by the `keyGenerator` of each
+     * enclosing cache() without a `key` whose store differs, the app-level
+     * store included: under `cache(() => [...])` on an app store with a
+     * `keyGenerator`, `cache({ store })` records are split by its result too.
+     * Likewise, without a `key` of its own, this store's `keyGenerator`
+     * partitions a nested cache() on another store.
      *
      * Useful for:
      * - Different backends per route section (memory vs KV vs Redis)
@@ -104,6 +110,8 @@ export interface CacheOptions<TEnv = unknown> {
     /**
      * Conditional cache read function.
      * Return false to skip cache for this request (always fetch fresh).
+     * It gates every cache() nested under this one too: a nested boundary
+     * caches only when every enclosing condition allows it.
      *
      * Has access to full RequestContext including env, request, params, cookies, etc.
      * Runs after global and route middleware on RSC routes; on response routes,
@@ -123,7 +131,10 @@ export interface CacheOptions<TEnv = unknown> {
     condition?: (ctx: import("../server/request-context.js").RequestContext<TEnv>) => boolean;
     /**
      * Custom cache key function - FULL OVERRIDE.
-     * Bypasses default key generation AND store's keyGenerator.
+     * Bypasses default key generation AND store's keyGenerator. The result is
+     * stored namespaced (`key:` plus its URI encoding), so no value it returns
+     * names another route's record; a nested cache() keys its records within
+     * this partition.
      *
      * Has access to full RequestContext including env, request, params, cookies, etc.
      * Runs after global and route middleware on RSC routes; on response routes,
@@ -144,7 +155,8 @@ export interface CacheOptions<TEnv = unknown> {
     key?: (ctx: import("../server/request-context.js").RequestContext<TEnv>) => string | Promise<string>;
     /**
      * Tags for cache invalidation.
-     * Can be a static array or a function that returns tags.
+     * Can be a static array or a function that returns tags. They tag the
+     * records of every cache() nested under this one too.
      *
      * The built-in `MemorySegmentCacheStore`, `CFCacheStore`, and
      * `VercelCacheStore` index by tag.

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.
@@ -349,6 +355,13 @@ export type InternalHandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch exte
      * 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/index.d.ts

@@ -4,7 +4,7 @@ export type { DocumentProps, ExtractParams, TrailingSlashMode, RouteConfig, Rout
 export type { ErrorInfo, ErrorBoundaryFallbackProps, ErrorBoundaryHandler, ClientErrorBoundaryFallbackProps, LoaderDataResult, NotFoundInfo, NotFoundBoundaryFallbackProps, NotFoundBoundaryHandler, } from "./boundaries.js";
 export { isLoaderDataResult } from "./boundaries.js";
 export type { MiddlewareFn, ScopedRouteMap, Handler, HandlerContext, InternalHandlerContext, GenericParams, RevalidateParams, ShouldRevalidateFn, ActionRef, IsActionFn, RouteKeys, ExtractRouteParams, HandlersForRouteMap, Revalidate, Middleware, } from "./handler-context.js";
-export type { ViewTransitionClass, TransitionConfig, TransitionWhenFn, TransitionWhenContext, ResolvedSegment, SegmentMetadata, SlotState, RootLayoutProps, MatchResult, } from "./segments.js";
+export type { ViewTransitionClass, TransitionConfig, TransitionWhenFn, TransitionWhenContext, TransitionWhenKind, RouteLocation, ServerRouteLocation, ResolvedSegment, SegmentMetadata, SlotState, RootLayoutProps, MatchResult, } from "./segments.js";
 export type { LazyIncludeContext, RouteEntry } from "./route-entry.js";
 export type { LoaderContext, LoaderFn, FetchableLoaderOptions, LoaderOptions, LoadOptions, LoaderDefinition, } from "./loader-types.js";
 export type { CacheContext, CacheOptions, PartialCacheOptions, EntryCacheConfig, } from "./cache-types.js";