@rangojs/router 0.24.3 → 0.25.0

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

@@ -17,17 +17,29 @@ export interface ClientUrlItem {
 export type ClientUrlItemInput = ClientUrlItem | readonly ClientUrlItemInput[];
 export type ClientUrlItems = readonly ClientUrlItemInput[];
 export type ClientUrlUse = () => ClientUrlItems;
+/**
+ * A component path(), layout() or intercept() mounts. Its optional `use`
+ * carries its own items, as a server handler's `.use` does, built with the
+ * helpers `@rangojs/router/client` exports: they come before the mount
+ * site's explicit items (an explicit loading() or transition() wins, loaders
+ * accumulate). A page component may carry loader(), loading() and
+ * transition(); a layout or intercept component loader() and loading().
+ */
+export type ClientUrlComponent = ComponentType & {
+    readonly use?: ClientUrlUse;
+};
 export type ClientPathOptions<TName extends string = string, TSearch extends SearchSchema = SearchSchema> = Pick<PathOptions<TName, TSearch>, "name" | "search" | "trailingSlash" | "ppr">;
-export type ClientPathFn = <const TPattern extends string, const TName extends string = UnnamedRoute, const TSearch extends SearchSchema = {}>(pattern: TPattern, component: ComponentType, optionsOrUse?: ClientPathOptions<TName, TSearch> | ClientUrlUse, use?: ClientUrlUse) => ClientUrlItem & TypedRouteItem<TName, TPattern, unknown, TSearch>;
-export type ClientLayoutFn = <const TItems extends ClientUrlItems>(component: ComponentType, children: () => TItems) => ClientUrlItem & TypedLayoutItem<ExtractRoutes<TItems>>;
+export type ClientPathFn = <const TPattern extends string, const TName extends string = UnnamedRoute, const TSearch extends SearchSchema = {}>(pattern: TPattern, component: ClientUrlComponent, optionsOrUse?: ClientPathOptions<TName, TSearch> | ClientUrlUse, use?: ClientUrlUse) => ClientUrlItem & TypedRouteItem<TName, TPattern, unknown, TSearch>;
+export type ClientLayoutFn = <const TItems extends ClientUrlItems>(component: ClientUrlComponent, children: () => TItems) => ClientUrlItem & TypedLayoutItem<ExtractRoutes<TItems>>;
 export interface ClientUrlLoaderRecord {
     readonly loader: LoaderDefinition<any, any>;
     /**
      * Per-loader revalidate() predicates, run on the server; empty = the
      * router's defaults. Under the rango Vite plugin the browser and SSR copies
-     * hold the marker the build left in place of each hoisted predicate.
+     * hold the marker the build left in place of each hoisted predicate; a
+     * boolean literal stays in place.
      */
-    readonly revalidate: readonly (ShouldRevalidateFn<any, DefaultEnv> | HoistedRevalidateRef)[];
+    readonly revalidate: readonly (ShouldRevalidateFn<any, DefaultEnv> | HoistedRevalidateRef | boolean)[];
     /**
      * loader(Def, { ssr: false }): document renders await this loader before
      * first flush (see {@link LoaderOptions}). Projected into the server tree,
@@ -36,11 +48,10 @@ export interface ClientUrlLoaderRecord {
      */
     readonly ssr?: false;
     /**
-     * loader(Def, { prefetch: false }): a prefetch of the route defers this
-     * loader and the click that adopts it runs it in its fill request (see
-     * {@link LoaderOptions}). Projected onto the materialized stub. Inside
-     * intercept() it is not recorded: intercept loaders ignore the flag, as in
-     * urls().
+     * loader(Def, { prefetch: false }): a prefetch of the route, or of an
+     * intercept's target from its source, defers this loader and the click
+     * that adopts it runs it in its fill request (see {@link LoaderOptions}).
+     * Projected onto the materialized stub.
      */
     readonly prefetch?: false;
 }
@@ -78,7 +89,7 @@ export interface ClientUrlRouteRecord {
 }
 /**
  * A restricted intercept declared inside clientUrls(). Compared to the server
- * intercept() there is no `when` selector, no middleware, and the target must
+ * intercept() there is no `when` selector, and the target must
  * be a dot-local NAMED route in the same definition — every field is
  * JSON-projectable, which is what makes the declaration legal in a
  * "use client" module. `targetName` is stored bare (no leading dot).
@@ -111,8 +122,8 @@ export interface ClientUrlHelpers {
      * the destination at once, commits the adopted prefetch with the other
      * loaders' data, and runs only the flagged loaders in its one fill
      * request. A `layout()` loader with the flag is flagged on every route
-     * below it. Inside intercept() the flag is accepted and ignored, as in
-     * urls().
+     * below it. Inside intercept() it defers the loader in a prefetch of the
+     * intercept from its source, as in urls().
      */
     readonly loader: <TData>(definition: LoaderDefinition<TData>, optionsOrUse?: Pick<LoaderOptions, "ssr" | "prefetch"> | ClientUrlUse, use?: ClientUrlUse) => ClientUrlItem;
     readonly loading: (component: ReactNode) => ClientUrlItem;
@@ -123,22 +134,24 @@ export interface ClientUrlHelpers {
      * names, ...): the build moves it out of this "use client" module. It may
      * reference imports and globals only; a binding of this module, `this`,
      * `import()`, a browser global, an `async` function or an import from a
-     * "use client" module fails the build with its file and line.
+     * "use client" module fails the build with its file and line. A boolean
+     * is shorthand for `() => true` / `() => false`.
      */
-    readonly revalidate: (fn: ShouldRevalidateFn<any, DefaultEnv>) => ClientUrlItem;
+    readonly revalidate: (fn: ShouldRevalidateFn<any, DefaultEnv> | boolean) => ClientUrlItem;
     /**
      * Declare an intercept for a named route in THIS definition. The target is
      * dot-local (`.detail`); scoping is module-local — only navigations whose
      * origin is inside this clientUrls() group render the intercept. `use` may
      * contain loader() and loading() only.
      */
-    readonly intercept: (slotName: `@${string}`, targetName: `.${string}`, component: ComponentType, use?: ClientUrlUse) => ClientUrlItem;
+    readonly intercept: (slotName: `@${string}`, targetName: `.${string}`, component: ClientUrlComponent, use?: ClientUrlUse) => ClientUrlItem;
     /**
      * Opt THIS route into transition-driven navigation: the canonical commit
      * holds previous content instead of re-streaming the loading() fallback,
      * and on experimental React the config's ViewTransition classes apply.
      * Data-only — no `when` gate (server-executed; declare it in the server
-     * tree). Valid inside a path() use callback only.
+     * tree). Valid inside a path() use callback, or a page component's
+     * `.use`.
      */
     readonly transition: (config: ClientTransitionConfig) => ClientUrlItem;
 }
@@ -149,6 +162,11 @@ export interface ClientUrlPatterns<TRoutes extends Record<string, any> = Record<
     readonly intercepts: readonly ClientUrlInterceptRecord[];
     readonly [CLIENT_URL_PATTERNS_BRAND]: void;
     readonly _routes?: TRoutes;
-    match(pathname: string): TrieMatchResult | null;
+    /**
+     * Match an absolute pathname against the routes joined to `mount`, the
+     * include() mount pattern (default "/"); params include the mount's. A
+     * `foreign` pattern that wins is a match whose routeKey is that pattern.
+     */
+    match(pathname: string, mount?: string, foreign?: readonly string[]): TrieMatchResult | null;
 }
 export {};

package/dist/types/client.d.ts

@@ -95,8 +95,8 @@ export interface OutletState {
 }
 export declare function useOutlet(): OutletState;
 export { useLoader, useFetchLoader, useRefreshLoaders, type LoadFunction, type UseLoaderResult, type UseFetchLoaderResult, type UseLoaderOptions, } from "./use-loader.js";
-export { clientUrls } from "./client-urls/client-urls.js";
-export type { ClientUrlPatterns, ClientUrlRouteRecord, } from "./client-urls/client-urls.js";
+export { clientUrls, loader, loading, revalidate, transition, } from "./client-urls/client-urls.js";
+export type { ClientUrlComponent, ClientUrlPatterns, ClientUrlRouteRecord, ClientUrlUse, } from "./client-urls/client-urls.js";
 /**
  * Props for the ErrorBoundary component
  */

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

@@ -12,8 +12,8 @@ import * as Html from "./html.js";
 export { Outlet, ParallelOutlet, useOutlet, type OutletState, useLoader, ErrorBoundary, type ErrorBoundaryProps, } from "./client.js";
 export { useFetchLoader, useRefreshLoaders, type LoadFunction, type UseLoaderResult, type UseFetchLoaderResult, type UseLoaderOptions, } from "./use-loader.js";
 export { createLoader } from "./route-definition.js";
-export { clientUrls } from "./client-urls/client-urls.js";
-export type { ClientUrlPatterns, ClientUrlRouteRecord, } from "./client-urls/client-urls.js";
+export { clientUrls, loader, loading, revalidate, transition, } from "./client-urls/client-urls.js";
+export type { ClientUrlComponent, ClientUrlPatterns, ClientUrlRouteRecord, ClientUrlUse, } from "./client-urls/client-urls.js";
 export { useRouter } from "./browser/react/use-router.js";
 export { usePathname } from "./browser/react/use-pathname.js";
 export { useSearchParams } from "./browser/react/use-search-params.js";

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

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import { type ErrorInfo, type ResolvedSegment } from "./types.js";
 /**
  * Markers for loader-thrown AUTHORITY SIGNALS (notFound()/redirect()) on the
  * reconstructed read-site error. Siblings of LOADER_ERROR_FALLBACK, routed
@@ -11,16 +12,36 @@ import type { ReactNode } from "react";
  * Only decodeLoaderEntry (the read-site path — client components, so the
  * throw lands in the router-owned boundary; during document SSR, Fizz emits
  * the Suspense fallback and replays the throw at hydration) throws these.
- * decodeLoaderResults runs during the SERVER tree build on forceAwait/action
- * lanes, where a throw would collapse the whole payload — it routes signals
- * through the errorFallback slot instead (same visual: the slot replaces the
- * children under OutletProvider). The document lane's `{ ssr: false }`
- * results take the same non-throwing route (segment-system
- * buildLoaderStreams): they are settled before the tree is built, and the
- * read-site throw would land in the Fizz shell with no boundary to absorb it.
+ * decodeLoaderResults runs during the tree build on settled results, where a
+ * throw would collapse the whole payload — it routes signals through the
+ * errorFallback slot instead (same visual: the slot replaces the children
+ * under OutletProvider). The document lane's `{ ssr: false }` results take
+ * this route (segment-system buildLoaderStreams): they are settled before the
+ * tree is built, and the read-site throw would land in the Fizz shell with no
+ * boundary to absorb it.
  */
 export declare const LOADER_NOT_FOUND_FALLBACK: unique symbol;
 export declare const LOADER_REDIRECT: unique symbol;
+/**
+ * A failed loader entry's error, rebuilt with the ErrorInfo identity
+ * (name/stack/code/cause) instead of a stripped generic Error.
+ */
+export declare function loaderResultError(result: {
+    error: ErrorInfo;
+}): Error;
+/** A loader that threw: not ok, and not a notFound()/redirect() signal. */
+export declare function isLoaderError(result: unknown): result is {
+    error: ErrorInfo;
+    fallback: ReactNode | null;
+};
+/**
+ * The error of the first loader that threw while it re-ran in an action's
+ * revalidation, for useAction()'s `revalidationError`. The loader itself
+ * throws at its read (segment-system buildLoaderStreams), and the action
+ * resolves. A stale revalidation rejects with it instead and commits nothing
+ * (partial-update.ts). A notFound()/redirect() is a signal, not an error.
+ */
+export declare function revalidationErrorOf(segments?: ResolvedSegment[]): Promise<Error | undefined>;
 export declare function decodeLoaderResults(resolvedData: any[], loaderIds: string[]): {
     loaderData: Record<string, any>;
     errorFallback: ReactNode;

package/dist/types/href-client.d.ts

@@ -169,7 +169,9 @@ declare global {
  * Type-safe href function for client-side use
  *
  * Without mount: identity function, validates absolute paths at compile time.
- * With mount: prepends mount path, for use with useMount() inside include() scopes.
+ * With mount: prepends the mount as given. `useMount()` under a parameterized
+ * include returns its pattern (`/:accountId`), which this does not fill: use
+ * `useHref()` there, which substitutes the mount params.
  *
  * @param path - A valid path matching one of the registered route patterns
  * @param mount - Optional mount prefix from useMount() for include-scoped paths

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

@@ -14,7 +14,7 @@ export type { RangoOptions, SSRStreamMode, SSROptions, ResolveStreamingContext,
 export type { OriginCheckConfig, OriginCheckContext, OriginCheckPhase, } from "./rsc/origin-guard.js";
 export type { ShellCaptureDebug, ShellCaptureDebugEvent, } from "./rsc/shell-capture.js";
 export { createLoader, redirect, type RouteHelpers, type RouteHandlers, layout, cache, middleware, revalidate, loader, loading, parallel, intercept, errorBoundary, notFoundBoundary, transition, } from "./route-definition.js";
-export { rewrite, type Rewrite, type RewriteFunction, } from "./route-definition/rewrite.js";
+export { rewrite, type Rewrite, type RewriteFunction, type RewriteShell, } from "./route-definition/rewrite.js";
 export { RewriteLoopError } from "./errors.js";
 export type { RouteUseItem, LayoutUseItem, AllUseItems, UseItems, HandlerUseItem, } from "./route-types.js";
 export { createHandle, isHandle, type Handle } from "./handle.js";

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

@@ -9,9 +9,8 @@ import type { ReactNode } from "react";
  *
  * Own module (not route-content-wrapper.tsx) because BOTH consumers need it
  * without a cycle: the StreamedLoaderErrorBoundary redirect branch (read-site
- * throw path) and decodeLoaderResults (aggregate forceAwait/action path, which
- * runs during the server tree build and cannot throw — it plants this element
- * in the errorFallback slot instead).
+ * throw path) and decodeLoaderResults (the tree build's settled results, which
+ * cannot throw — it plants this element in the errorFallback slot instead).
  */
 export declare function LoaderRedirect({ to, state, }: {
     to: string;

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

@@ -12,18 +12,19 @@ export interface OutletContextValue {
      * $$id. A value may be a pending Promise (loader still streaming) or an
      * already-settled result entry. useLoader `use()`es a pending value at the
      * read site — implicit suspension to the nearest consumer Suspense boundary —
-     * and decodes via decodeLoaderEntry. Populated instead of `loaderData` on
-     * streaming lanes (plain navs, document SSR); forceAwait/action lanes keep
-     * the resolved `loaderData` record.
+     * and decodes via decodeLoaderEntry. Populated instead of `loaderData` for
+     * a route's or layout's loaders on every lane; forceAwait/action lanes hand
+     * settled entries. `loaderData` is a slot's decoded aggregate.
      */
     loaderStreams?: Record<string, unknown>;
     /**
      * Loader $$ids on this segment that the render awaited before first flush
      * (loader(Def, { ssr: false })). Dev-diagnostic input only: useLoader uses
      * it to warn when a read still suspends during SSR on a render that awaited
-     * flagged loaders (ssr-suspension-warning.ts). Present only on streaming
-     * lanes with flagged loaders (document and shell-capture renders); absent
-     * on forceAwait/action lanes.
+     * flagged loaders (ssr-suspension-warning.ts). Present only where a
+     * segment carries flagged loaders (document and shell-capture renders, and
+     * a client lane that re-renders their segments); a settled read never
+     * suspends, so it never warns.
      */
     awaitedLoaderIds?: readonly string[];
     parent?: OutletContextValue | null;

package/dist/types/prefetch-markers.d.ts

@@ -1,11 +1,20 @@
 /**
- * The wire markers of `prefetch: false` (docs/design/prefetch-false.md):
- * shared by the browser that sends them and the server that reads them
- * (router/segment-resolution/prefetch-deferral.ts requestKind). Dependency
- * free, like segment-fragments.ts: the browser must not import the server
- * module that reads them.
+ * The wire markers of prefetches and of `prefetch: false`
+ * (docs/design/prefetch-false.md): shared by the browser and the server
+ * (router/segment-resolution/prefetch-deferral.ts requestKind,
+ * rsc/prefetch-render-error.ts). Dependency free, like segment-fragments.ts:
+ * the browser must not import the server modules that use them.
  */
 /** Request header of a `<Link>` prefetch (browser/prefetch/fetch.ts). */
 export declare const PREFETCH_HEADER = "X-Rango-Prefetch";
 /** Query param of a fill request (browser/navigation-client.ts). */
 export declare const FILL_PARAM = "_rsc_fill";
+/**
+ * The last row of a prefetch whose render reported an error
+ * (rsc/prefetch-render-error.ts): a Flight hint with a code React does not
+ * dispatch, so the decoder skips it (pinned by
+ * src/__tests__/flight-unknown-hint.test.ts), and browser/response-adapter.ts
+ * reads the stream as not ended cleanly. Five bytes: teeWithCompletion keeps
+ * the last five.
+ */
+export declare const PREFETCH_FAILED_ROW = ":H_0\n";

package/dist/types/route-content-wrapper.d.ts

@@ -23,34 +23,37 @@ import type { ResolvedSegment } from "./types.js";
  */
 export declare class StreamedLoaderErrorBoundary extends Component<{
     children: ReactNode;
-    resetKey?: string;
+    reset: unknown[];
 }, {
     error: unknown;
-    resetKey?: string;
+    reset: unknown[];
 }> {
     state: {
         error: unknown;
-        resetKey?: string;
+        reset: unknown[];
     };
     static getDerivedStateFromError(error: unknown): {
         error: unknown;
     };
     /**
      * A caught marker (redirect, notFound, error fallback) belongs to ONE route
-     * + params. Group-keyed segments (ResolvedSegment.clientGroup) keep this
-     * instance alive across in-group navigations, so the error must clear when
-     * the route or params change — otherwise a redirect caught for /legacy
-     * keeps rendering LoaderRedirect for /state. `resetKey` is the segment's
-     * id-params identity, the cadence the per-route remount used to provide.
+     * + params and ONE delivery of the segment's loader data. `reset` is the
+     * segment's id-params identity followed by each of its loaders' data; the
+     * error clears when any of them changes. Group-keyed segments
+     * (ResolvedSegment.clientGroup) keep this instance alive across in-group
+     * navigations, so a redirect caught for /legacy must not keep rendering
+     * LoaderRedirect for /state. A rerun hands a loader new data, a held loader
+     * keeps its own: a later action or navigation that re-ran the loader clears
+     * an error fallback left by an earlier failure, and a tree that re-ran
+     * nothing here keeps it.
      */
-    static getDerivedStateFromProps(props: {
-        resetKey?: string;
+    static getDerivedStateFromProps({ reset }: {
+        reset: unknown[];
     }, state: {
-        error: unknown;
-        resetKey?: string;
+        reset: unknown[];
     }): {
-        error: unknown;
-        resetKey?: string;
+        error: null;
+        reset: unknown[];
     } | null;
     render(): ReactNode;
 }

package/dist/types/route-definition/helpers-types.d.ts

@@ -105,7 +105,7 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      * // With loaders and revalidation (revalidate() goes on the loader;
      * // an intercept-level revalidate() throws)
      * intercept("@modal", "card", () => <CardModal />, () => [
-     *   loader(CardModalLoader, () => [revalidate(() => false)]),
+     *   loader(CardModalLoader, () => [revalidate(false)]),
      * ])
      *
      * // Conditional activation via the config object's `when` selector
@@ -186,6 +186,9 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      * revalidate(({ defaultShouldRevalidate }) =>
      *   ({ defaultShouldRevalidate: true })
      * )
+     *
+     * // Shorthand for a constant hard decision: revalidate(() => false)
+     * revalidate(false)
      * ```
      * Not valid directly inside intercept() use() (throws at definition time):
      * intercepts only revalidate their loaders, so attach it there with
@@ -196,8 +199,10 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *     for downstream revalidators),
      *   - or nothing / `null` / `undefined` (defer — leaves the suggestion
      *     unchanged and continues to the next revalidator).
+     *   Or `true` / `false`: shorthand for `() => true` / `() => false`. A
+     *   defer has no shorthand; write the function.
      */
-    revalidate: (fn: ShouldRevalidateFn<any, TEnv>) => RevalidateItem;
+    revalidate: (fn: ShouldRevalidateFn<any, TEnv> | boolean) => RevalidateItem;
     /**
      * Attach a data loader to the current route/layout
      * ```typescript

package/dist/types/route-definition/resolve-handler-use.d.ts

@@ -8,7 +8,7 @@ import type { AllUseItems } from "../route-types.js";
 export declare function resolveHandlerUse(handler: unknown): (() => any[]) | undefined;
 /**
  * Validate every item an intercept's merged use() returned (explicit use()
- * and handler.use) against MOUNT_SITE_ALLOWED_TYPES.intercept, plus two
+ * and handler.use) against MOUNT_SITE_ALLOWED_TYPES.intercept, plus three
  * structural rules:
  * - a nested layout() is only the modal chrome (intercept() keeps its
  *   handler), so it may not carry use() items of its own;
@@ -16,10 +16,15 @@ export declare function resolveHandlerUse(handler: unknown): (() => any[]) | und
  *   it was not returned; its orphan form re-parents the following siblings
  *   onto that entry, so it is rejected the same way. Inside a path, cache()
  *   writes `sinks.cache` instead (dsl-helpers.ts cache()).
+ * - middleware on a `capturedLayouts` entry is rejected like `sinks.middleware`:
+ *   it is an unreturned middleware(fn, () => [...]) or one called inside the
+ *   chrome layout's use(), and nothing would run it.
  */
 export declare function validateInterceptUseItems(items: AllUseItems[], capturedLayouts: readonly {
     type: string;
+    middleware?: readonly unknown[];
 }[], slotName: string, routeName: string, sinks: {
+    readonly middleware: readonly unknown[];
     readonly revalidate: readonly unknown[];
     readonly errorBoundary: readonly unknown[];
     readonly notFoundBoundary: readonly unknown[];

package/dist/types/route-definition/rewrite.d.ts

@@ -16,6 +16,16 @@ export type RewriteTarget = {
     readonly search?: Record<string, unknown>;
 };
 export declare function describeRewriteTarget(target: RewriteTarget): string;
+/**
+ * Which PPR shell a rewritten request reads and captures
+ * (`rewrite(...).shell()`); without a call, none.
+ * - `"visitor"`: its own, keyed by the visitor's URL and the target, captured
+ *   with the visitor's location and `ctx.rewrittenFrom`.
+ * - `"target"`: the target's shared shell. `usePathname()` reads the target's
+ *   path on a HIT, and values set before the throw are baked in: for a page
+ *   that renders neither (a lock or promo page).
+ */
+export type RewriteShell = "visitor" | "target";
 /**
  * The value `rewrite()` returns, thrown by middleware. An Error, so a throw
  * where a rewrite is not supported fails loudly with the rule in its message.
@@ -23,7 +33,34 @@ export declare function describeRewriteTarget(target: RewriteTarget): string;
 export declare class Rewrite extends Error {
     name: "Rewrite";
     readonly target: RewriteTarget;
-    constructor(target: RewriteTarget);
+    /** The `shell()` choice; undefined: no shell. */
+    readonly shellAudience: RewriteShell | undefined;
+    /** `disallowMutations()`: a mutation is refused, not moved, before its action runs. */
+    readonly mutationsDisallowed: boolean;
+    constructor(target: RewriteTarget, shellAudience?: RewriteShell, mutationsDisallowed?: boolean);
+    /**
+     * A copy that picks the PPR shell of a `ppr` target ({@link RewriteShell}),
+     * so a rewrite kept in a module constant keeps its own choice:
+     *
+     * ```ts
+     * throw rewrite("item", { id }).shell("visitor");
+     * ```
+     */
+    shell(audience: RewriteShell): Rewrite;
+    /**
+     * A copy for a lock: global middleware's rewrite of a mutation (a server
+     * action, a form post, any non-GET request) is an error before the action
+     * runs, instead of moving the mutation to the target. GET and HEAD rewrite
+     * as usual.
+     *
+     * ```ts
+     * throw rewrite("maintenance").disallowMutations();
+     * ```
+     *
+     * Route middleware runs after the action, so there it cannot refuse it: the
+     * render moves to the target, dev warns, and production logs one error.
+     */
+    disallowMutations(): Rewrite;
 }
 /** Whether `value` is a Rewrite thrown by `rewrite()` (ctx.isRewrite). */
 export declare function isRewrite(value: unknown): value is Rewrite;
@@ -40,17 +77,23 @@ export type RewriteFunction<TRoutes = DefaultReverseRouteMap> = ((path: `/${stri
  * ```ts
  * router.use(async (ctx, next) => {
  *   if (!locked || ctx.pathname === "/maintenance") return next();
- *   throw rewrite("maintenance");
+ *   throw rewrite("maintenance").disallowMutations();
  * });
  * ```
  *
  * The request runs again as the target (global middleware, route
  * middleware, render) with the same request context: values set before the
  * throw stay readable. `ctx.url` is the target; `ctx.rewrittenFrom` is the
- * visitor's URL. See the `/middleware` skill.
+ * visitor's URL. A mutation that global middleware rewrites moves to the
+ * target before its action runs, so the page's forms keep working; a lock
+ * refuses it with `.disallowMutations()`. A `ppr` target gets no shell unless
+ * `.shell()` picks one ({@link RewriteShell}). See the `/middleware` skill.
  */
 export declare const rewrite: RewriteFunction;
-/** A dispatch site that cannot honor a rewrite. */
-export type RewriteSite = "mutation" | "loader-fetch" | "intercept";
+/**
+ * A dispatch site that cannot honor a rewrite. "mutation" is the refusal
+ * `.disallowMutations()` asked for, not a misuse.
+ */
+export type RewriteSite = "mutation" | "body-read" | "loader-fetch";
 /** The error a rewrite becomes at a site that cannot honor it. */
 export declare function rewriteNotSupported(rewrite: Rewrite, site: RewriteSite): Error;

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

@@ -134,7 +134,7 @@ export type IncludeItem = {
          * include cannot collide with siblings declared outside it.
          */
         includeScope?: string;
-    };
+    } & import("./server/context.js").IncludeScopePosition;
 };
 /**
  * Typed include item that carries nested routes as phantom type
@@ -156,7 +156,7 @@ export type RouteUseItem = LayoutItem | ParallelItem | InterceptItem | Middlewar
 /** Items that can be used inside a response route (path.json(), etc.) */
 export type ResponseRouteUseItem = MiddlewareItem | CacheItem;
 export type ParallelUseItem = RevalidateItem | LoaderItem | LoadingItem | ErrorBoundaryItem | NotFoundBoundaryItem | TransitionItem;
-export type InterceptUseItem = MiddlewareItem | LoaderItem | LoadingItem | LayoutItem | RouteItem | TransitionItem;
+export type InterceptUseItem = LoaderItem | LoadingItem | LayoutItem | RouteItem | TransitionItem;
 export type LoaderUseItem = RevalidateItem | CacheItem;
 /**
  * Allow composition factories in use() callbacks.

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

@@ -4,6 +4,7 @@
  * Creates the handler context object passed to route handlers, middleware, and loaders.
  */
 import type { InternalHandlerContext } from "../types";
+import { type ReverseScope, type ScopableReverse } from "../server/context.js";
 /**
  * `headers` whose mutating methods run `assertWrite(method)` first. Shared by
  * the handler ctx (createHandlerContext) and the middleware ctx
@@ -11,6 +12,16 @@ import type { InternalHandlerContext } from "../types";
  */
 export declare function guardHeaderWrites(headers: Headers, assertWrite: (method: string | symbol) => void): Headers;
 export { stripInternalParams } from "./internal-params.js";
+/**
+ * The ctx a layout's or parallel slot's handler gets: a prototype child of
+ * the request's one handler ctx with its own `reverse` in the segment's
+ * ReverseScope, so `.name` resolves in the module that declared the segment.
+ * The scope rides the object, not the call frame: it holds after an `await`
+ * and in a component the ctx is handed to. Every other field reads through
+ * live (`_currentSegmentId` as resolution moves it, ctx.set values).
+ * `_reverseScope` keys a "use cache" call that takes this ctx (cache-runtime.ts).
+ */
+export declare function withReverseScope<C>(ctx: C, scope: ReverseScope | undefined): C;
 /**
  * Create a reverse function for URL generation from route names.
  * Used by both HandlerContext and MiddlewareContext.
@@ -19,9 +30,10 @@ export { stripInternalParams } from "./internal-params.js";
  * generation. This enables auto-filling mount params from include() prefixes:
  * inner handlers can call ctx.reverse(".sibling") without explicitly passing
  * params that are already known from the current URL match.
- * Explicitly passed hrefParams take priority over currentParams.
+ * Explicitly passed hrefParams take priority over currentParams. A required
+ * param that neither supplies throws `Missing param`.
  */
-export declare function createReverseFunction(routeMap: Record<string, string>, currentRoutePrefix?: string, currentParams?: Record<string, string>, rootScoped?: boolean): (name: string, hrefParams?: Record<string, string>, search?: Record<string, unknown>) => string;
+export declare function createReverseFunction(routeMap: Record<string, string>, currentRoutePrefix?: string, currentParams?: Record<string, string>, rootScoped?: boolean): ScopableReverse;
 /**
  * Create HandlerContext with typed env/var/get/set
  */

package/dist/types/router/intercept-resolution.d.ts

@@ -7,6 +7,7 @@
 import type { EntryData, InterceptEntry, InterceptSelectorContext } from "../server/context";
 import type { HandlerContext, ResolvedSegment } from "../types";
 import type { SegmentResolutionDeps } from "./types.js";
+import type { RevalidationContext } from "./router-context.js";
 /**
  * Check if an intercept's when conditions are satisfied.
  * All when() functions must return true for the intercept to activate.
@@ -37,57 +38,29 @@ export declare function findInterceptForRoute(targetRouteKey: string, fromEntry:
     intercept: InterceptEntry;
     entry: EntryData;
 } | null;
+/** The segment id of `intercept`'s slot on `parentEntry`. */
+export declare function interceptSlotId(parentEntry: EntryData, intercept: InterceptEntry): string;
 /**
- * Resolve an intercept entry and emit segment with the slot name.
+ * Every segment id an intercept's slot owns, in order: the slot, then one
+ * loader segment per loader in declaration order, run or not. A request that
+ * resolves the intercept lists them in `matched` (match-result.ts).
  */
-export declare function resolveInterceptEntry<TEnv>(interceptEntry: InterceptEntry, parentEntry: EntryData, params: Record<string, string>, context: HandlerContext<any, TEnv>, belongsToRoute: boolean, deps: SegmentResolutionDeps<TEnv>, revalidationContext?: {
-    clientSegmentIds: Set<string>;
-    prevParams: Record<string, string>;
-    request: Request;
-    prevUrl: URL;
-    nextUrl: URL;
-    routeKey: string;
-    actionContext?: {
-        actionId?: string;
-        actionUrl?: URL;
-        actionResult?: any;
-        formData?: FormData;
-    };
-    stale?: boolean;
-}, options?: {
+export declare function interceptSegmentIds(parentEntry: EntryData, intercept: InterceptEntry): string[];
+/**
+ * Resolve an intercept entry: its slot segment, then its loader segments.
+ */
+export declare function resolveInterceptEntry<TEnv>(interceptEntry: InterceptEntry, parentEntry: EntryData, params: Record<string, string>, context: HandlerContext<any, TEnv>, belongsToRoute: boolean, deps: SegmentResolutionDeps<TEnv>, revalidationContext?: RevalidationContext, options?: {
     /**
-     * Skip the intercept's middleware execution. Set ONLY by the post-response
-     * background re-render paths (proactive caching, stale background
+     * Set ONLY by the post-response background re-render (stale background
      * revalidation), whose sole purpose is to re-render the segment tree to
-     * populate the cache. The foreground request already ran the intercept
-     * middleware before the response was sent — it validated auth, set cookies,
-     * and wrote context vars into the request context's shared `_variables`,
-     * which the background render reuses. Re-running middleware here would fire
-     * its side effects a SECOND time, and a middleware that short-circuits with
-     * a Response would `throw` and silently abort the cache write. Never set on
-     * the foreground path.
+     * populate the cache: a handler error rejects instead of rendering the
+     * error boundary, so a failure is never cached. Never set on the
+     * foreground path.
      */
-    skipMiddleware?: boolean;
+    background?: boolean;
 }): Promise<ResolvedSegment[]>;
 /**
- * Resolve only the loaders for a cached intercept segment.
- * Used on intercept cache hit to get fresh loader data while keeping cached component/layout.
+ * The loader segments of a cached intercept slot, on a cache hit: the slot
+ * keeps its cached component and layout, its loaders are never cached.
  */
-export declare function resolveInterceptLoadersOnly<TEnv>(interceptEntry: InterceptEntry, parentEntry: EntryData, params: Record<string, string>, context: HandlerContext<any, TEnv>, belongsToRoute: boolean, deps: SegmentResolutionDeps<TEnv>, revalidationContext: {
-    clientSegmentIds: Set<string>;
-    prevParams: Record<string, string>;
-    request: Request;
-    prevUrl: URL;
-    nextUrl: URL;
-    routeKey: string;
-    actionContext?: {
-        actionId?: string;
-        actionUrl?: URL;
-        actionResult?: any;
-        formData?: FormData;
-    };
-    stale?: boolean;
-}): Promise<{
-    loaderDataPromise: Promise<any[]> | any[];
-    loaderIds: string[];
-} | null>;
+export declare function resolveInterceptLoadersOnly<TEnv>(interceptEntry: InterceptEntry, parentEntry: EntryData, context: HandlerContext<any, TEnv>, belongsToRoute: boolean, deps: SegmentResolutionDeps<TEnv>, revalidationContext: RevalidationContext): Promise<ResolvedSegment[]>;

package/dist/types/router/lazy-includes.d.ts

@@ -24,3 +24,10 @@ export declare function findLazyIncludes<TEnv = any>(items: AllUseItems[]): Arra
  * Also detects nested lazy includes and registers them as new entries
  */
 export declare function evaluateLazyEntry<TEnv = any>(entry: RouteEntry<TEnv>, deps: LazyEvalDeps<TEnv>): void | Promise<void>;
+/**
+ * Resolve an async include entry's provider once and cache the patterns on
+ * `entry.lazyPatterns`. Concurrent callers (match-time expansion and
+ * render-time loadManifest) share one in-flight import; it clears when it
+ * settles, so a rejected import is retried by the next request.
+ */
+export declare function resolveEntryPatterns<TEnv = any>(entry: RouteEntry<TEnv>): Promise<UrlPatterns<TEnv>>;