@rangojs/router 0.15.1 → 0.17.0

package/src/prerender/build-shell-capture.ts

@@ -44,7 +44,7 @@ import { isRouteNotFoundError } from "../errors.js";
 import { createReverseFunction } from "../router/handler-context.js";
 import { executeMiddleware, matchMiddleware } from "../router/middleware.js";
 import type { MiddlewareEntry } from "../router/middleware.js";
-import { getGlobalRouteMap, isRouteRootScoped } from "../route-map-builder.js";
+import { getGlobalRouteMap } from "../route-map-builder.js";
 import {
   resolvePprConfig,
   type ResolvedPprConfig,
@@ -234,14 +234,11 @@ async function attemptBuildCapture(
       setRequestContextParams(preview.params ?? {}, preview.routeKey);
     }
 
-    const routeReverse = createReverseFunction(
-      getGlobalRouteMap(),
-      preview?.routeKey,
-      preview?.params ?? {},
-      preview?.routeKey
-        ? isRouteRootScoped(preview.routeKey, router.id)
-        : undefined,
-    );
+    // Global-only, like the live request's middleware reverse
+    // (rsc/handler.ts: createReverseFunction(getRequiredRouteMap())): no
+    // include() scope, no param auto-fill. A scoped reverse here resolved
+    // `.name` at build while the live request threw `Unknown route`.
+    const middlewareReverse = createReverseFunction(getGlobalRouteMap());
 
     const runCapture = () =>
       runBuildCaptureFinal({
@@ -268,7 +265,7 @@ async function attemptBuildCapture(
         env,
         variables,
         runCapture,
-        routeReverse,
+        middlewareReverse,
         baseCtx,
       );
 
@@ -281,7 +278,7 @@ async function attemptBuildCapture(
       env,
       variables,
       runRouteMiddleware,
-      routeReverse,
+      middlewareReverse,
       baseCtx,
     );
   });

package/src/reverse.ts

@@ -207,6 +207,43 @@ export type ScopedReverseFunction<
   ): string;
 };
 
+/**
+ * Reverse function that resolves global route names only: no include() scope,
+ * no param auto-fill.
+ *
+ * This is the `ctx.reverse` of middleware (`MiddlewareContext`) and
+ * response-route handlers (`ResponseHandlerContext`). On a live request both
+ * get `createReverseFunction(routeMap)` with no route name or params (the
+ * middleware callers in rsc/handler.ts and rsc/loader-fetch.ts,
+ * handleResponseRoute, router/intercept-resolution.ts; mirrored by
+ * testing/run-middleware.ts and testing/dispatch.ts), so a dot-local `.name`
+ * has no scope to resolve against and throws `Unknown route`. Build-time PPR
+ * shell capture (prerender/build-shell-capture.ts) gives global and route
+ * middleware the same global-only reverse.
+ *
+ * - Route map with a string index signature (no generated map, the permissive
+ *   `Record<string, string>` fallback): any name except a dot-prefixed literal.
+ *   `Exclude` is required because `keyof` collapses to `string` there, so the
+ *   global overloads of `ScopedReverseFunction` would accept `.name` too.
+ * - Concrete route map: the global overloads of `ScopedReverseFunction`, with
+ *   name and param validation. The empty local map (`{}`) leaves no dot-prefixed
+ *   overload that can match.
+ *
+ * @example
+ * ```typescript
+ * reverse("blog.post", { slug: "hello" }) // ok: global route + params
+ * reverse(".post", { slug: "hello" })     // compile error: no include() scope
+ * ```
+ */
+export type GlobalReverseFunction<TGlobalRoutes> =
+  string extends keyof TGlobalRoutes
+    ? <TName extends string>(
+        name: Exclude<TName, `.${string}`>,
+        params?: Record<string, string>,
+        search?: Record<string, unknown>,
+      ) => string
+    : ScopedReverseFunction<{}, TGlobalRoutes>;
+
 /**
  * Extract local routes type from UrlPatterns
  * Used with scopedReverse() to get the routes type from patterns
@@ -290,11 +327,14 @@ export type { RouteResponse } from "./urls.js";
  * Get a locally-typed reverse function from ctx.reverse for composable modules.
  *
  * This is a type-only cast - ctx.reverse already resolves names at runtime.
- * Provides type safety: `.name` validates against local routes,
- * `name` validates against global named-routes.
+ * Only the module's LOCAL routes are typed: `.name` and bare `name` both
+ * validate against the local map (the global map parameter defaults to it).
+ * Always dot-prefix local names — a bare name type-checks against the local
+ * map but resolves as a global name at runtime. For global names, call
+ * ctx.reverse directly.
  *
  * @param reverse - The ctx.reverse function from HandlerContext
- * @returns The same reverse function, typed with local + global routes
+ * @returns The same reverse function, typed with the module's local routes
  *
  * @example
  * ```typescript
@@ -305,7 +345,7 @@ export type { RouteResponse } from "./urls.js";
  *
  *     reverse(".index");              // ✓ Local route
  *     reverse(".post", { slug: "x" }); // ✓ Local with params
- *     reverse("shop.cart");           // ✓ Global route
+ *     ctx.reverse("shop.cart");       // Global route: use ctx.reverse
  *
  *     return <BlogIndex />;
  *   }, { name: "index" }),

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

@@ -44,12 +44,25 @@ import type {
   UseItems,
 } from "../route-types.js";
 import type { RouteHelpers } from "./helpers-types.js";
-import { resolveHandlerUse, mergeHandlerUse } from "./resolve-handler-use.js";
+import {
+  resolveHandlerUse,
+  mergeHandlerUse,
+  validateInterceptUseItems,
+} from "./resolve-handler-use.js";
 import { ALL_USE_ITEM_TYPES } from "./use-item-types.js";
 
 /**
- * Check if an item contains routes (directly or inside nested structures like cache).
+ * Check if an item contains routes (directly or inside nested wrappers).
  * Used to determine if a layout or cache should be treated as an orphan.
+ *
+ * Recurses through ANY item carrying `uses` (cache, layout, middleware,
+ * wrapper-form transition) rather than an enumerated list: a wrapper helper
+ * that returns `uses` is covered the moment it exists. Scar tissue: the list
+ * form missed `transition`, so `layout(Shell, () => [transition(cfg, () =>
+ * [routes])])` was classified orphan and pushed onto its PARENT's layout[] —
+ * rendering around every sibling route (test-app TxBlockShell wrapped "/").
+ * parallel()/intercept() register their children by side effect and return
+ * no `uses`, so a layout whose only children are those still reads as orphan.
  */
 const hasRoutesInItem = (item: AllUseItems): boolean => {
   if (item.type === "route") return true;
@@ -57,16 +70,8 @@ const hasRoutesInItem = (item: AllUseItems): boolean => {
   // to prevent the parent layout from being misclassified as orphan,
   // which would clear its parent pointer and break the middleware chain.
   if (item.type === "include") return true;
-  if (item.type === "cache" && item.uses) {
-    return item.uses.some((child) => hasRoutesInItem(child));
-  }
-  if (item.type === "layout" && item.uses) {
-    return item.uses.some((child) => hasRoutesInItem(child));
-  }
-  if (item.type === "middleware" && item.uses) {
-    return item.uses.some((child) => hasRoutesInItem(child));
-  }
-  return false;
+  const uses = (item as { uses?: AllUseItems[] }).uses;
+  return uses ? uses.some(hasRoutesInItem) : false;
 };
 
 /**
@@ -130,16 +135,37 @@ const isOrphan = (result: AllUseItems[]): boolean =>
  * pointer so it leaves the middleware/parent-pointer chain (LOAD-BEARING — see
  * docs/tree-structure.md) and push it onto the parent's layout[] so it renders
  * as a wrapper. Used by cache()/middleware()/transition(); layout() runs extra
- * validation and registers inline.
+ * validation and registers inline. `orphanOwner` keeps the owner reachable for
+ * boundary lookup only (router/error-handling.ts).
  */
 const attachOrphanSibling = (
   parent: EntryData | null,
   entry: EntryData,
 ): void => {
   entry.parent = null;
-  if (parent && "layout" in parent) parent.layout.push(entry);
+  if (parent && "layout" in parent) {
+    parent.layout.push(entry);
+    entry.orphanOwner = parent;
+  }
 };
 
+/**
+ * The route whose use() list `parent` sits in: `parent` itself, or the route
+ * above a chain of layout-typed wrappers (layout(), middleware()/transition()
+ * wrapper form). Inside a path those wrappers never hold routes (path-in-path
+ * is rejected), so the route is the only cacheable unit there. An intercept()
+ * scope (its temporary parent: a spread of the declaring entry with an own
+ * `cache` sink) stops the walk, so its cache() stays rejected by
+ * validateInterceptUseItems instead of configuring the path around it.
+ */
+function enclosingRoute(parent: EntryData | null): EntryData | undefined {
+  for (let entry = parent; entry; entry = entry.parent) {
+    if (entry.type === "route") return entry;
+    if (entry.type !== "layout" || "cache" in entry) return undefined;
+  }
+  return undefined;
+}
+
 /**
  * Run `fn` with `ctx.parent` temporarily redirected to `temp` — a satellite
  * entry that captures the attachments declared by a use() callback — restoring
@@ -178,7 +204,7 @@ const revalidate: RouteHelpers<any, any>["revalidate"] = (fn) => {
  * When an error occurs during rendering of this segment or its children,
  * the fallback will be rendered instead. The fallback can be:
  * - A static ReactNode (e.g., <ErrorPage />)
- * - A handler function that receives error info and reset function
+ * - A handler function that receives `{ error }` (server fallbacks get no reset)
  *
  * Error boundaries catch errors from:
  * - Middleware execution
@@ -194,11 +220,11 @@ const revalidate: RouteHelpers<any, any>["revalidate"] = (fn) => {
  *
  * // Or with handler for dynamic error UI:
  * route("products.detail", ProductDetail, () => [
- *   errorBoundary(({ error, reset }) => (
+ *   errorBoundary(({ error }) => (
  *     <div>
  *       <h2>Product failed to load</h2>
  *       <p>{error.message}</p>
- *       <button onClick={reset}>Retry</button>
+ *       <a href="/products">Back to products</a>
  *     </div>
  *   )),
  * ])
@@ -316,6 +342,30 @@ const cache: RouteHelpers<any, any>["cache"] = (
   const name = `$${cacheIndex}`;
   const cacheConfig = { options };
 
+  // Among a path's children, cache() configures that path: the route entry
+  // carries the config, so buildEntriesAndCacheScope (router/route-snapshot.ts)
+  // makes the route the boundary and its own segments (handler, layouts,
+  // parallels) the cached unit. Both forms leave ctx.parent unchanged, so
+  // every sibling and wrapped item still attaches where it was. Issue #912: a
+  // cache entry here was never an ancestor of the route (no scope, no store
+  // write). The same holds inside a routeless layout()/middleware()/
+  // transition() wrapper in a path (issue #918): a route's record is
+  // all-or-nothing, so the path is the only thing such a cache() can cache.
+  const route = enclosingRoute(ctx.parent);
+  if (route && ctx.parent) {
+    route.cache = cacheConfig;
+    if (!children) return { name, type: "cache" } as CacheItem;
+    const uses = runAndValidateUseItems(
+      store,
+      `${ctx.namespace}.${cacheIndex}`,
+      ctx.parent,
+      children,
+      "cache",
+      "children",
+    );
+    return { name, type: "cache", uses } as CacheItem;
+  }
+
   // If no children, create an orphan cache entry (like orphan layouts)
   // This allows cache() to wrap subsequent siblings
   if (!children) {
@@ -490,7 +540,19 @@ const middleware: RouteHelpers<any, any>["middleware"] = (...args: any[]) => {
     "children",
   );
 
-  if (isOrphan(result)) attachOrphanSibling(ctx.parent, entry);
+  if (isOrphan(result)) {
+    // Its middleware runs for every route of the enclosing entry
+    // (collectRouteMiddleware walks orphans), so the wrapper scopes nothing;
+    // the flat form says what runs. Issue #918: the nested layout() was
+    // dropped at render.
+    invariant(
+      !result.some((item) => item?.type === "layout"),
+      `middleware(fn, () => [...]) with no routes inside cannot contain layout() [${namespace}]. ` +
+        "The middleware runs for every route of the enclosing path or layout either way; " +
+        "list them as siblings instead: middleware(fn), layout(...)",
+    );
+    attachOrphanSibling(ctx.parent, entry);
+  }
 
   return {
     name: namespace,
@@ -713,15 +775,12 @@ const intercept = (
   const prefixedRouteName =
     isLocal && namePrefix ? `${namePrefix}.${bareRouteName}` : bareRouteName;
 
-  // Create intercept entry with its own loaders/revalidate/middleware/when
+  // Create intercept entry with its own loaders/middleware/when
   const entry: InterceptEntry = {
     slotName: slotName as `@${string}`,
     routeName: prefixedRouteName,
     handler,
     middleware: [],
-    revalidate: [],
-    errorBoundary: [],
-    notFoundBoundary: [],
     loader: [],
     when: [], // Selector conditions for conditional interception
   };
@@ -734,25 +793,44 @@ const intercept = (
     entry.when.push(...selectors);
   }
 
-  // Merge handler.use defaults with explicit use
+  // Merge handler.use defaults with explicit use. mountSite null: the merged
+  // items are validated once below, so both sources get the same message.
   const handlerUseFn = resolveHandlerUse(handler);
-  const mergedUse = mergeHandlerUse(handlerUseFn, useFn, "intercept");
+  const mergedUse = mergeHandlerUse(handlerUseFn, useFn, null);
 
-  // Run merged use callback to collect loaders, revalidate, middleware, etc.
+  // Run merged use callback to collect loaders, middleware, etc.
   if (mergedUse) {
     // Capture layout() calls into a temporary array
     const capturedLayouts: EntryData[] = [];
 
-    // Temporary parent so middleware/loader/revalidate/when attach to the
-    // intercept entry; the loading get/set accessor mirrors writes onto `entry`.
+    // Temporary parent so middleware/loader attach 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
+    // from use() never lands on the enclosing layout. cache() writes into
+    // `layout` (capturedLayouts), or into `cache` when the enclosing entry
+    // is a route.
+    //
+    // Why an intercept rejects these (validateInterceptUseItems):
+    // - revalidate(): an intercept only evaluates its loaders' revalidate()
+    //   (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
+    //   entry's boundaries instead.
+    // - cache(): an intercept navigation is cached under the target route's
+    //   cache() scope, with its own "intercept:" key (cache/cache-scope.ts).
     const tempParent = {
       ...ctx.parent,
       middleware: entry.middleware,
-      revalidate: entry.revalidate,
-      errorBoundary: entry.errorBoundary,
-      notFoundBoundary: entry.notFoundBoundary,
       loader: entry.loader,
-      layout: capturedLayouts, // Capture layout() calls
+      layout: capturedLayouts,
+      revalidate: [],
+      errorBoundary: [],
+      notFoundBoundary: [],
+      parallel: {},
+      intercept: [],
+      cache: undefined,
       get loading() {
         return entry.loading;
       },
@@ -761,19 +839,29 @@ const intercept = (
       },
     };
 
-    const result = withParent(ctx, tempParent as EntryData, () =>
-      mergedUse()?.flat(3),
+    const result = validateUseItems(
+      withParent(ctx, tempParent as EntryData, () => mergedUse()?.flat(3)),
+      namespace,
+      "intercept",
+      "use",
+    );
+    validateInterceptUseItems(
+      result,
+      capturedLayouts,
+      slotName,
+      routeName,
+      tempParent,
     );
 
-    // Extract layout from captured layouts (use first one if multiple)
-    // Layout inside intercept should always be ReactNode or Handler, not Record slots
-    if (capturedLayouts.length > 0 && capturedLayouts[0].type === "layout") {
-      entry.layout = capturedLayouts[0].handler as
-        | ReactNode
-        | Handler<any, any, any>;
+    // The modal chrome is the first returned layout() item. Match it by id so
+    // an entry pushed into capturedLayouts without being returned is never
+    // taken as the chrome. It carries no use() items (validated above).
+    const chromeItem = result.find((item) => item?.type === "layout");
+    const chrome =
+      chromeItem && capturedLayouts.find((l) => l.id === chromeItem.name);
+    if (chrome) {
+      entry.layout = chrome.handler as ReactNode | Handler<any, any, any>;
     }
-
-    validateUseItems(result, namespace, "intercept", "use");
   }
 
   ctx.parent.intercept.push(entry);
@@ -958,7 +1046,11 @@ const transition = (
 
   if (isOrphan(result)) attachOrphanSibling(ctx.parent, entry);
 
-  return { name: namespace, type: "transition" } as TransitionItem;
+  return {
+    name: namespace,
+    type: "transition",
+    uses: result,
+  } as TransitionItem;
 };
 
 const route: RouteHelpers<any, any>["route"] = (name, handler, use) => {

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

@@ -180,10 +180,10 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   intercept("@modal", "card", () => <CardModal />),
    * ])
    *
-   * // With loaders and revalidation
+   * // 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
@@ -205,7 +205,11 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * @param handler - Component or handler for intercepted render
    * @param config - Optional InterceptConfig (e.g. `{ when }`), or the use
    *   callback directly when there is no config
-   * @param use - Optional callback for loaders, middleware, revalidate, etc.
+   * @param use - Optional callback for loader(), middleware(), loading(),
+   *   transition() and a layout() modal chrome without use() items.
+   *   revalidate() (goes on the loader), errorBoundary()/notFoundBoundary()
+   *   (go on the enclosing layout) and cache() (goes on the target route)
+   *   throw here.
    */
   intercept: {
     // Local: dot-prefixed, params inferred from local route definition
@@ -285,6 +289,9 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   ({ defaultShouldRevalidate: true })
    * )
    * ```
+   * Not valid directly inside intercept() use() (throws at definition time):
+   * intercepts only revalidate their loaders, so attach it there with
+   * `loader(Def, () => [revalidate(...)])`.
    * @param fn - Function returning either:
    *   - `boolean` (hard decision — short-circuits the chain),
    *   - `{ defaultShouldRevalidate: boolean }` (soft — updates the suggestion
@@ -352,16 +359,19 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * ```typescript
    * errorBoundary(<ErrorFallback />)
    *
-   * // With dynamic error handler
-   * errorBoundary(({ error, reset }) => (
+   * // With dynamic error handler (server fallback: receives only { error })
+   * errorBoundary(({ error }) => (
    *   <div>
    *     <h2>Something went wrong</h2>
    *     <p>{error.message}</p>
-   *     <button onClick={reset}>Try again</button>
+   *     <a href="/">Go home</a>
    *   </div>
    * ))
    * ```
-   * @param fallback - Static JSX or handler receiving error info and reset function
+   * Not valid inside intercept() use() (throws at definition time): an
+   * intercept has no boundary of its own, and its loader errors resolve
+   * against the enclosing layout/path boundary.
+   * @param fallback - Static JSX or handler receiving `{ error }`
    */
   errorBoundary: (
     fallback: ReactNode | ErrorBoundaryHandler,
@@ -379,6 +389,9 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   </div>
    * ))
    * ```
+   * Not valid inside intercept() use() (throws at definition time): an
+   * intercept has no boundary of its own, and notFound() from its loaders
+   * resolves against the enclosing layout/path boundary.
    * @param fallback - Static JSX or handler receiving not-found info
    */
   notFoundBoundary: (
@@ -396,6 +409,9 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * Note: Loaders are NOT cached by default. Use cache() inside loader()
    * to explicitly opt-in to loader caching.
    *
+   * Not valid inside intercept() use() (throws at definition time): an
+   * intercept navigation is cached under the target route's cache() scope.
+   *
    * ```typescript
    * // Using app-level defaults (ttl inherited from store.defaults)
    * cache(() => [
@@ -430,6 +446,12 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   route("archive/:year"),     // uses KV store
    * ])
    *
+   * // Among a path's children: caches that path (handler, layouts, parallels)
+   * path("/product/:id", ProductPage, { name: "product" }, () => [
+   *   cache({ ttl: 60 }),
+   *   layout(<ProductChrome />),  // cached with the path
+   * ])
+   *
    * // Opt-in loader caching
    * route("product/:id", ProductHandler, () => [
    *   loader(ProductLoader),               // NOT cached (default)
@@ -457,8 +479,12 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *    through React's startTransition, so a same-route nav (same route,
    *    different params, e.g. /product/1 -> /product/2) holds the previous
    *    content while the new loader resolves instead of flashing the route's
-   *    loading() skeleton (see segment-system.tsx inTransitionScope). This is
-   *    also the precondition for any view-transition animation.
+   *    loading() skeleton (see segment-system.tsx inTransitionScope). Held
+   *    useLoader readers of the re-run loaders report isLoading: true until
+   *    the new data commits (use-loader.tsx). The pin is per loader family
+   *    (`$$id`), not per segment — a layout reader of the same createLoader
+   *    the child is re-running is flagged too. This is also the precondition
+   *    for any view-transition animation.
    * 2. <ViewTransition> (experimental React only): the segment content is also
    *    wrapped in React's <ViewTransition>, so the held swap cross-fades/morphs.
    *    Layered on by default; pass { viewTransition: false } to keep #1 without

package/src/route-definition/resolve-handler-use.ts

@@ -91,13 +91,12 @@ const MOUNT_SITE_ALLOWED_TYPES: Record<string, Set<string>> = {
     "notFoundBoundary",
     "transition",
   ]),
+  // intercept() checks its whole merged use() (explicit and handler.use)
+  // against this set via validateInterceptUseItems below.
   intercept: new Set([
     "middleware",
-    "revalidate",
     "loader",
     "loading",
-    "errorBoundary",
-    "notFoundBoundary",
     "layout",
     "route",
     "transition",
@@ -106,6 +105,120 @@ const MOUNT_SITE_ALLOWED_TYPES: Record<string, Set<string>> = {
   loader: new Set(["revalidate", "cache"]),
 };
 
+const INTERCEPT_BOUNDARY_HINT =
+  "put it on the enclosing layout or path; it handles the intercept's handler and loader errors";
+
+/**
+ * Where each item intercept() rejects goes instead. Why an intercept cannot
+ * hold them is documented at intercept() in dsl-helpers.ts.
+ */
+const INTERCEPT_REJECTION_HINTS: Record<string, string> = {
+  revalidate:
+    "attach it to the intercept's loader: loader(YourLoader, () => [revalidate(...)])",
+  errorBoundary: INTERCEPT_BOUNDARY_HINT,
+  notFoundBoundary: INTERCEPT_BOUNDARY_HINT,
+  cache:
+    'put cache() on the target route (intercept navigations get their own "intercept:" cache key) or use "use cache" in the handler',
+};
+
+function rejectInterceptItem(
+  what: string,
+  hint: string,
+  slotName: string,
+  routeName: string,
+): never {
+  throw new Error(
+    `${what} is not valid inside intercept("${slotName}", "${routeName}") use() (including the handler's .use): ${hint}.`,
+  );
+}
+
+/**
+ * Validate every item an intercept's merged use() returned (explicit use()
+ * and handler.use) against MOUNT_SITE_ALLOWED_TYPES.intercept, plus two
+ * structural rules:
+ * - a nested layout() is only the modal chrome (intercept() keeps its
+ *   handler), so it may not carry use() items of its own;
+ * - a cache entry in `capturedLayouts` means cache() ran in the scope even if
+ *   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()).
+ */
+export function validateInterceptUseItems(
+  items: AllUseItems[],
+  capturedLayouts: readonly { type: string }[],
+  slotName: string,
+  routeName: string,
+  sinks: {
+    readonly revalidate: readonly unknown[];
+    readonly errorBoundary: readonly unknown[];
+    readonly notFoundBoundary: readonly unknown[];
+    readonly intercept: readonly unknown[];
+    readonly parallel: Readonly<Record<string, unknown>>;
+    /** Set by cache() when the intercept is declared inside a path. */
+    readonly cache?: unknown;
+  },
+): void {
+  const allowed = MOUNT_SITE_ALLOWED_TYPES.intercept!;
+  for (const item of items) {
+    if (item == null) continue;
+    const type = (item as { type: string }).type;
+    if (!allowed.has(type)) {
+      rejectInterceptItem(
+        `${type}()`,
+        INTERCEPT_REJECTION_HINTS[type] ??
+          `allowed items are ${[...allowed].join(", ")}`,
+        slotName,
+        routeName,
+      );
+    }
+    if (type === "layout" && (item as { uses?: unknown[] }).uses?.length) {
+      rejectInterceptItem(
+        "layout() with its own use() items",
+        "put the modal chrome in the layout component and attach loaders to the intercept itself",
+        slotName,
+        routeName,
+      );
+    }
+  }
+  // A rejected helper called without being returned still wrote into its
+  // throwaway field on the temporary parent; reject it the same way.
+  for (const type of [
+    "revalidate",
+    "errorBoundary",
+    "notFoundBoundary",
+    "intercept",
+  ] as const) {
+    if (sinks[type].length > 0) {
+      rejectInterceptItem(
+        `${type}()`,
+        INTERCEPT_REJECTION_HINTS[type] ??
+          `allowed items are ${[...allowed].join(", ")}`,
+        slotName,
+        routeName,
+      );
+    }
+  }
+  if (Object.keys(sinks.parallel).length > 0) {
+    rejectInterceptItem(
+      "parallel()",
+      `allowed items are ${[...allowed].join(", ")}`,
+      slotName,
+      routeName,
+    );
+  }
+  if (
+    capturedLayouts.some((l) => l.type === "cache") ||
+    sinks.cache !== undefined
+  ) {
+    rejectInterceptItem(
+      "cache()",
+      INTERCEPT_REJECTION_HINTS.cache!,
+      slotName,
+      routeName,
+    );
+  }
+}
+
 /**
  * Validate that items from handler.use() are valid for the given mount site.
  * Throws a descriptive error if any item is not allowed.
@@ -135,7 +248,7 @@ export function validateHandlerUseItems(
 export function mergeHandlerUse(
   handlerUse: (() => any[]) | undefined,
   explicitUse: (() => any[]) | undefined,
-  mountSite: string,
+  mountSite: string | null,
 ): (() => any[]) | undefined {
   if (!handlerUse && !explicitUse) return undefined;
   // Validation asymmetry (intentional, pre-1.0): only handler.use() items are
@@ -144,17 +257,19 @@ export function mergeHandlerUse(
   // branch here and the merged branch, so a structurally-valid-but-prohibited
   // item (e.g. middleware() inside a parallel slot) is not rejected at this seam.
   // Documented rather than enforced for now; revisit before 1.0 (#569).
+  // intercept() is the exception: it passes mountSite null and validates the
+  // merged items itself (validateInterceptUseItems).
   if (!handlerUse) return explicitUse;
   if (!explicitUse) {
     return () => {
       const items = handlerUse().flat(3);
-      validateHandlerUseItems(items, mountSite);
+      if (mountSite) validateHandlerUseItems(items, mountSite);
       return items;
     };
   }
   return () => {
     const hItems = handlerUse().flat(3);
-    validateHandlerUseItems(hItems, mountSite);
+    if (mountSite) validateHandlerUseItems(hItems, mountSite);
     return [...hItems, ...explicitUse()];
   };
 }