@rangojs/router 0.24.3 → 0.25.0

package/src/client.rsc.tsx

@@ -36,10 +36,20 @@ export {
 
 export { createLoader } from "./route-definition.js";
 
-export { clientUrls } from "./client-urls/client-urls.js";
+// A module that is not "use client" and declares a component's `.use` can
+// evaluate in the RSC realm too.
+export {
+  clientUrls,
+  loader,
+  loading,
+  revalidate,
+  transition,
+} from "./client-urls/client-urls.js";
 export type {
+  ClientUrlComponent,
   ClientUrlPatterns,
   ClientUrlRouteRecord,
+  ClientUrlUse,
 } from "./client-urls/client-urls.js";
 
 // "use client" hooks the default ./client entry exports. They are client

package/src/client.tsx

@@ -309,10 +309,18 @@ export {
   type UseLoaderOptions,
 } from "./use-loader.js";
 
-export { clientUrls } 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";
 
 /**

package/src/decode-loader-results.ts

@@ -1,6 +1,11 @@
 import type { ReactNode } from "react";
 import { createElement } from "react";
-import { isLoaderDataResult } from "./types.js";
+import {
+  isLoaderDataResult,
+  type ErrorInfo,
+  type ResolvedSegment,
+} from "./types.js";
+import { isPlaceholder } from "./types/segments.js";
 import { LoaderRedirect } from "./loader-redirect.js";
 
 /**
@@ -15,13 +20,13 @@ import { LoaderRedirect } from "./loader-redirect.js";
  * 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 const LOADER_NOT_FOUND_FALLBACK: unique symbol = Symbol(
   "rango.loaderNotFound",
@@ -65,6 +70,52 @@ function signalFallback(result: any): ReactNode | undefined {
   return undefined;
 }
 
+/**
+ * A failed loader entry's error, rebuilt with the ErrorInfo identity
+ * (name/stack/code/cause) instead of a stripped generic Error.
+ */
+export function loaderResultError(result: { error: ErrorInfo }): Error {
+  const info = result.error;
+  const err = new Error(
+    info.message,
+    info.cause !== undefined ? { cause: info.cause } : undefined,
+  );
+  if (info.name) err.name = info.name;
+  if (info.stack) err.stack = info.stack;
+  if (info.code !== undefined) (err as { code?: string }).code = info.code;
+  return err;
+}
+
+/** A loader that threw: not ok, and not a notFound()/redirect() signal. */
+export function isLoaderError(
+  result: unknown,
+): result is { error: ErrorInfo; fallback: ReactNode | null } {
+  return (
+    isLoaderDataResult(result) &&
+    !result.ok &&
+    !result.notFound &&
+    !result.redirect
+  );
+}
+
+/**
+ * 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 async function revalidationErrorOf(
+  segments: ResolvedSegment[] = [],
+): Promise<Error | undefined> {
+  for (const s of segments) {
+    if (s.type !== "loader" || isPlaceholder(s)) continue;
+    const entry = await s.loaderData;
+    if (isLoaderError(entry)) return loaderResultError(entry);
+  }
+  return undefined;
+}
+
 // Shared by segment-system (server) and LoaderResolver (client) so the
 // legacy/ok/error-fallback/throw decode of resolved loader values lives once.
 // Last failing loader wins errorFallback; an error without a fallback throws.
@@ -90,10 +141,9 @@ export function decodeLoaderResults(
     }
 
     // Authority signals take the errorFallback slot (this decode runs during
-    // the server tree build on forceAwait/action lanes — throwing here would
-    // collapse the payload). A signal outranks a plain error fallback and
-    // stops the scan: notFound renders the server-rendered 404 UI, redirect
-    // mounts LoaderRedirect which navigates.
+    // the tree build — throwing here would collapse the payload). A signal
+    // outranks a plain error fallback and stops the scan: notFound renders the
+    // server-rendered 404 UI, redirect mounts LoaderRedirect which navigates.
     const signal = signalFallback(result);
     if (signal !== undefined) {
       return { loaderData, errorFallback: signal };
@@ -108,17 +158,7 @@ export function decodeLoaderResults(
     if (result.fallback != null) {
       errorFallback = result.fallback;
     } else {
-      // No boundary: rethrow preserving the ErrorInfo identity (name/stack/
-      // code/cause) instead of a stripped generic Error.
-      const info = result.error;
-      const err = new Error(
-        info.message,
-        info.cause !== undefined ? { cause: info.cause } : undefined,
-      );
-      if (info.name) err.name = info.name;
-      if (info.stack) err.stack = info.stack;
-      if (info.code !== undefined) (err as { code?: string }).code = info.code;
-      throw err;
+      throw loaderResultError(result);
     }
   }
 
@@ -153,14 +193,7 @@ export function decodeLoaderEntry(result: any): any {
     return result.data;
   }
   throwSignal(result);
-  const info = result.error;
-  const err = new Error(
-    info.message,
-    info.cause !== undefined ? { cause: info.cause } : undefined,
-  );
-  if (info.name) err.name = info.name;
-  if (info.stack) err.stack = info.stack;
-  if (info.code !== undefined) (err as { code?: string }).code = info.code;
+  const err = loaderResultError(result);
   if (result.fallback != null) {
     (err as any)[LOADER_ERROR_FALLBACK] = result.fallback;
   }

package/src/href-client.ts

@@ -274,7 +274,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/src/index.rsc.ts

@@ -124,6 +124,7 @@ export {
   rewrite,
   type Rewrite,
   type RewriteFunction,
+  type RewriteShell,
 } from "./route-definition/rewrite.js";
 export { RewriteLoopError } from "./errors.js";
 

package/src/index.ts

@@ -134,6 +134,14 @@ function serverOnlyStubError(name: string): Error {
   );
 }
 
+/** A stub whose name `@rangojs/router/client` exports for clientUrls(). */
+function clientUrlsHelperStubError(name: string): Error {
+  return new Error(
+    `${name}() is only available from "@rangojs/router" in a react-server/RSC environment. ` +
+      `In a "use client" module (a clientUrls() component's .use), import ${name}() from "@rangojs/router/client".`,
+  );
+}
+
 /**
  * Error-throwing stub for server-only `urls` function.
  */
@@ -276,7 +284,7 @@ export function middleware(): never {
   throw serverOnlyStubError("middleware");
 }
 export function revalidate(): never {
-  throw serverOnlyStubError("revalidate");
+  throw clientUrlsHelperStubError("revalidate");
 }
 // Cache tag APIs are server-only (real implementations in index.rsc.ts). These
 // stubs keep the named-export shape identical under the default/non-react-server
@@ -291,10 +299,10 @@ export function revalidateTag(): never {
   throw serverOnlyStubError("revalidateTag");
 }
 export function loader(): never {
-  throw serverOnlyStubError("loader");
+  throw clientUrlsHelperStubError("loader");
 }
 export function loading(): never {
-  throw serverOnlyStubError("loading");
+  throw clientUrlsHelperStubError("loading");
 }
 export function parallel(): never {
   throw serverOnlyStubError("parallel");
@@ -309,7 +317,7 @@ export function notFoundBoundary(): never {
   throw serverOnlyStubError("notFoundBoundary");
 }
 export function transition(): never {
-  throw serverOnlyStubError("transition");
+  throw clientUrlsHelperStubError("transition");
 }
 
 // Request context type (safe for client)

package/src/loader-redirect.tsx

@@ -19,9 +19,8 @@ import { resolveSameOriginRedirect } from "./redirect-origin.js";
  *
  * 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 function LoaderRedirect({
   to,

package/src/outlet-context.ts

@@ -13,18 +13,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/src/prefetch-markers.ts

@@ -1,9 +1,9 @@
 /**
- * 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). */
@@ -11,3 +11,13 @@ export const PREFETCH_HEADER = "X-Rango-Prefetch";
 
 /** Query param of a fill request (browser/navigation-client.ts). */
 export 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 const PREFETCH_FAILED_ROW = ":H_0\n";

package/src/reverse.ts

@@ -406,9 +406,9 @@ export function createReverse<TRoutes extends Record<string, string>>(
       throw new Error(`Unknown route: ${name}`);
     }
 
-    let result = params
-      ? substitutePatternParams(pattern, params, name)
-      : pattern;
+    // Always substitute: a required param with no params object throws
+    // `Missing param` rather than returning the raw `:param` pattern.
+    let result = substitutePatternParams(pattern, params ?? {}, name);
 
     // Append search params as query string
     if (search) {

package/src/route-content-wrapper.tsx

@@ -18,6 +18,7 @@ import {
   useRevealAudit,
 } from "./suspense-audit-react.js";
 import { SETTLED_THENABLE } from "./thenable-status.js";
+import { shallowEqual } from "./browser/react/shallow-equal.js";
 
 /**
  * Router-owned error boundary for read-site loader errors. segment-system
@@ -40,12 +41,12 @@ import { SETTLED_THENABLE } from "./thenable-status.js";
  * Errors without any marker rethrow to the app's own boundaries.
  */
 export class StreamedLoaderErrorBoundary extends Component<
-  { children: ReactNode; resetKey?: string },
-  { error: unknown; resetKey?: string }
+  { children: ReactNode; reset: unknown[] },
+  { error: unknown; reset: unknown[] }
 > {
-  state: { error: unknown; resetKey?: string } = {
+  state: { error: unknown; reset: unknown[] } = {
     error: null,
-    resetKey: this.props.resetKey,
+    reset: this.props.reset,
   };
 
   static getDerivedStateFromError(error: unknown): { error: unknown } {
@@ -54,20 +55,21 @@ export class StreamedLoaderErrorBoundary extends Component<
 
   /**
    * 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 },
-    state: { error: unknown; resetKey?: string },
-  ): { error: unknown; resetKey?: string } | null {
-    if (props.resetKey !== state.resetKey) {
-      return { error: null, resetKey: props.resetKey };
-    }
-    return null;
+    { reset }: { reset: unknown[] },
+    state: { reset: unknown[] },
+  ): { error: null; reset: unknown[] } | null {
+    return shallowEqual(reset, state.reset) ? null : { error: null, reset };
   }
 
   render(): ReactNode {
@@ -311,7 +313,7 @@ function AuditedLoaderResolver({
  * Without streams, the pre-spike behavior is preserved: a pending aggregate
  * resolves ABOVE via use() (parallel/intercept slots still take this path —
  * ResolvedSegment carries only the aggregate for slots), and a resolved
- * array decodes synchronously (forceAwait/action lanes commit whole).
+ * array decodes synchronously (a slot on the forceAwait/action lanes).
  */
 function LoaderResolver({
   loaderDataPromise,

package/src/route-definition/dsl-helpers.ts

@@ -11,6 +11,7 @@ import type {
 import {
   getContext,
   getNamePrefix,
+  getReverseScope,
   getUrlPrefix,
   requireDslContext,
   stampStaticDefScope,
@@ -52,6 +53,7 @@ import {
   validateInterceptUseItems,
 } from "./resolve-handler-use.js";
 import { ALL_USE_ITEM_TYPES } from "./use-item-types.js";
+import { toShouldRevalidateFn } from "../router/revalidation.js";
 
 /**
  * Check if an item contains routes (directly or inside nested wrappers).
@@ -189,6 +191,10 @@ const revalidate: RouteHelpers<any, any>["revalidate"] = (fn) => {
   const { store, ctx } = requireDslContext(
     "revalidate() must be called inside urls()",
   );
+  invariant(
+    typeof fn === "function" || typeof fn === "boolean",
+    `revalidate() expects a predicate or a boolean, got ${fn === null ? "null" : typeof fn}`,
+  );
 
   // Attach to last entry in stack
   const parent = ctx.parent;
@@ -196,7 +202,7 @@ const revalidate: RouteHelpers<any, any>["revalidate"] = (fn) => {
     invariant(false, "No parent entry available for revalidate()");
   }
   const name = `$${store.getNextIndex("revalidate")}`;
-  parent.revalidate.push(fn);
+  parent.revalidate.push(toShouldRevalidateFn(fn));
   return { name, type: "revalidate" } as RevalidateItem;
 };
 
@@ -394,6 +400,7 @@ const cache: RouteHelpers<any, any>["cache"] = (
       cache: cacheConfig,
       handler: RootLayout,
       ...(urlPrefix ? { mountPath: urlPrefix } : {}),
+      reverseScope: getReverseScope(),
     } satisfies EntryData;
 
     // Attach to parent's layout array (cache entries are structural like layouts)
@@ -433,6 +440,7 @@ const cache: RouteHelpers<any, any>["cache"] = (
     // Cache entries render like layouts (with Outlet as default handler)
     handler: RootLayout, // RootLayout just renders <Outlet />
     ...(urlPrefix ? { mountPath: urlPrefix } : {}),
+    reverseScope: getReverseScope(),
   } satisfies EntryData;
 
   // Run children with cache entry as parent
@@ -522,6 +530,7 @@ const middleware: RouteHelpers<any, any>["middleware"] = (...args: any[]) => {
     handler: RootLayout,
     middleware: [...fns],
     ...(urlPrefix ? { mountPath: urlPrefix } : {}),
+    reverseScope: getReverseScope(),
   } satisfies EntryData;
 
   // Run children callback. If the second arg was actually a middleware fn
@@ -643,6 +652,7 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
     parent: null, // Parallels don't participate in parent chain traversal
     handler: unwrappedSlots,
     ...(parallelUrlPrefix ? { mountPath: parallelUrlPrefix } : {}),
+    reverseScope: getReverseScope(),
     ...(hasStaticSlot
       ? {
           isStaticPrerender: true as const,
@@ -777,12 +787,11 @@ const intercept = (
   const prefixedRouteName =
     isLocal && namePrefix ? `${namePrefix}.${bareRouteName}` : bareRouteName;
 
-  // Create intercept entry with its own loaders/middleware/when
+  // Create intercept entry with its own loaders/when
   const entry: InterceptEntry = {
     slotName: slotName as `@${string}`,
     routeName: prefixedRouteName,
     handler,
-    middleware: [],
     loader: [],
     when: [], // Selector conditions for conditional interception
   };
@@ -800,12 +809,12 @@ const intercept = (
   const handlerUseFn = resolveHandlerUse(handler);
   const mergedUse = mergeHandlerUse(handlerUseFn, useFn, null);
 
-  // Run merged use callback to collect loaders, middleware, etc.
+  // Run merged use callback to collect loaders, loading, layout, etc.
   if (mergedUse) {
     // Capture layout() calls into a temporary array
     const capturedLayouts: EntryData[] = [];
 
-    // Temporary parent so middleware/loader attach to the intercept entry;
+    // Temporary parent so loader() attaches to the intercept entry;
     // the loading get/set accessor mirrors writes onto `entry`. It is a
     // shallow spread of the enclosing entry, so every field a rejected helper
     // writes to points at a throwaway here: a helper called but not returned
@@ -814,8 +823,12 @@ const intercept = (
     // is a route.
     //
     // Why an intercept rejects these (validateInterceptUseItems):
+    // - middleware(): only the live render resolved the intercept's own
+    //   middleware; a cache() hit or a Prerender() target skipped it, so a
+    //   guard in it was bypassed. The target route's middleware runs on every
+    //   pass, the modal's included.
     // - revalidate(): an intercept only evaluates its loaders' revalidate()
-    //   (router/intercept-resolution.ts).
+    //   (loader segments of its slot, router/intercept-resolution.ts).
     // - errorBoundary()/notFoundBoundary(): error lookup walks EntryData
     //   parent chains (router/error-handling.ts), which never include an
     //   InterceptEntry; intercept loader errors resolve against the declaring
@@ -824,7 +837,7 @@ const intercept = (
     //   cache() scope, with its own "intercept:" key (cache/cache-scope.ts).
     const tempParent = {
       ...ctx.parent,
-      middleware: entry.middleware,
+      middleware: [],
       loader: entry.loader,
       layout: capturedLayouts,
       revalidate: [],
@@ -833,6 +846,8 @@ const intercept = (
       parallel: {},
       intercept: [],
       cache: undefined,
+      // Its loaders resolve `.name` like the intercept handler: from the route.
+      reverseScope: undefined,
       get loading() {
         return entry.loading;
       },
@@ -925,6 +940,10 @@ const loader: RouteHelpers<any, any>["loader"] = (
     ...(optionsGiven?.ssr === false &&
       ctx.isSSR && { awaitBeforeFlush: true as const }),
     ...(optionsGiven?.prefetch === false && { prefetch: false as const }),
+    // The declaring layout's / parallel's / cache()'s scope. A route's (and
+    // an intercept's) loaders have none: they resolve from the route's name,
+    // like the handler.
+    ...(ctx.parent.reverseScope && { reverseScope: ctx.parent.reverseScope }),
   };
 
   // Merge handler.use defaults (attached to the loader definition) with explicit use
@@ -1156,6 +1175,7 @@ const layout: RouteHelpers<any, any>["layout"] = (handler, use) => {
     parent: ctx.parent,
     handler: unwrappedHandler,
     ...(urlPrefix ? { mountPath: urlPrefix } : {}),
+    reverseScope: getReverseScope(),
     ...(isStatic
       ? {
           isStaticPrerender: true as const,

package/src/route-definition/helpers-types.ts

@@ -183,7 +183,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
@@ -288,6 +288,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
@@ -298,8 +301,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/src/route-definition/resolve-handler-use.ts

@@ -93,14 +93,7 @@ const MOUNT_SITE_ALLOWED_TYPES: Record<string, Set<string>> = {
   ]),
   // intercept() checks its whole merged use() (explicit and handler.use)
   // against this set via validateInterceptUseItems below.
-  intercept: new Set([
-    "middleware",
-    "loader",
-    "loading",
-    "layout",
-    "route",
-    "transition",
-  ]),
+  intercept: new Set(["loader", "loading", "layout", "route", "transition"]),
   // LoaderUseItem — only revalidate + cache can attach to a loader entry
   loader: new Set(["revalidate", "cache"]),
 };
@@ -113,6 +106,8 @@ const INTERCEPT_BOUNDARY_HINT =
  * hold them is documented at intercept() in dsl-helpers.ts.
  */
 const INTERCEPT_REJECTION_HINTS: Record<string, string> = {
+  middleware:
+    "move it to the route's middleware() (it runs for the modal too) or into the loaders",
   revalidate:
     "attach it to the intercept's loader: loader(YourLoader, () => [revalidate(...)])",
   errorBoundary: INTERCEPT_BOUNDARY_HINT,
@@ -134,7 +129,7 @@ function rejectInterceptItem(
 
 /**
  * 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;
@@ -142,13 +137,20 @@ function rejectInterceptItem(
  *   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 function validateInterceptUseItems(
   items: AllUseItems[],
-  capturedLayouts: readonly { type: string }[],
+  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[];
@@ -206,6 +208,17 @@ export function validateInterceptUseItems(
       routeName,
     );
   }
+  if (
+    sinks.middleware.length > 0 ||
+    capturedLayouts.some((l) => l.middleware?.length)
+  ) {
+    rejectInterceptItem(
+      "middleware()",
+      INTERCEPT_REJECTION_HINTS.middleware!,
+      slotName,
+      routeName,
+    );
+  }
   if (
     capturedLayouts.some((l) => l.type === "cache") ||
     sinks.cache !== undefined