@rangojs/router 0.24.4 → 0.25.0

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

package/src/route-definition/rewrite.ts

@@ -27,11 +27,10 @@ export type RewriteTarget =
 
 const REWRITE_RULE =
   "rewrite() is for middleware: throw it from router.use() or route " +
-  "middleware (middleware() in urls()), before await next(), while it " +
-  "handles a GET or HEAD page request. Loaders and route handlers can't " +
-  "rewrite: throw rewrite() from the route's middleware instead. Intercept " +
-  "middleware and loader fetches can't either. In a server action use " +
-  "redirect(); for a mutation return a Response from middleware.";
+  "middleware (middleware() in urls()), before await next(). Loaders and " +
+  "route handlers can't rewrite: throw rewrite() from the route's " +
+  "middleware instead. Middleware in loader fetches can't either. In a " +
+  "server action use redirect().";
 
 export function describeRewriteTarget(target: RewriteTarget): string {
   return "path" in target
@@ -39,6 +38,17 @@ export function describeRewriteTarget(target: RewriteTarget): string {
     : `rewrite(${JSON.stringify(target.name)})`;
 }
 
+/**
+ * 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.
@@ -46,11 +56,60 @@ export function describeRewriteTarget(target: RewriteTarget): string {
 export class Rewrite extends Error {
   name = "Rewrite" as const;
   readonly 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) {
+  constructor(
+    target: RewriteTarget,
+    shellAudience?: RewriteShell,
+    mutationsDisallowed = false,
+  ) {
     super(`${describeRewriteTarget(target)}: ${REWRITE_RULE}`);
     Object.setPrototypeOf(this, Rewrite.prototype);
     this.target = target;
+    this.shellAudience = shellAudience;
+    this.mutationsDisallowed = mutationsDisallowed;
+  }
+
+  /**
+   * 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 {
+    if (audience !== "visitor" && audience !== "target") {
+      throw new TypeError(
+        `${describeRewriteTarget(this.target)}.shell() takes "visitor" or "target", not ${JSON.stringify(audience)}.`,
+      );
+    }
+    return new Rewrite(this.target, audience, this.mutationsDisallowed);
+  }
+
+  /**
+   * 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 {
+    if (arguments.length > 0) {
+      throw new TypeError(
+        `${describeRewriteTarget(this.target)}.disallowMutations() takes no arguments.`,
+      );
+    }
+    return new Rewrite(this.target, this.shellAudience, true);
   }
 }
 Object.defineProperty(Rewrite.prototype, REWRITE_BRAND, { value: true });
@@ -107,31 +166,39 @@ function createRewrite(
  * ```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 const rewrite: RewriteFunction = createRewrite as 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";
 
 const SITE_MESSAGE: Record<RewriteSite, string> = {
   mutation:
-    "middleware threw it while handling a non-GET request (a server action " +
-    "or a form post). Return a Response for mutations instead, e.g. " +
-    'new Response("Maintenance", { status: 503 }).',
+    "refused a mutation: .disallowMutations() was set, so a server action " +
+    "or form post (any request but GET and HEAD) fails before its action " +
+    "runs. To answer it instead, return a Response for mutations from " +
+    'middleware, e.g. new Response("Maintenance", { status: 503 }).',
+  "body-read":
+    "is not supported here: middleware read the request body before it " +
+    "threw it, and the request moves to the target with its body for the " +
+    "action to read. Read a copy instead: ctx.request.clone().formData().",
   "loader-fetch":
-    "middleware threw it during a loader fetch (useFetchLoader, load(), " +
-    "useRefreshLoaders). Return a Response there.",
-  intercept:
-    "intercept middleware threw it. Rewrite from router.use() or the " +
-    "route's middleware(), or return a Response.",
+    "is not supported here: middleware threw it during a loader fetch " +
+    "(useFetchLoader, load(), useRefreshLoaders). Return a Response there.",
 };
 
 /** The error a rewrite becomes at a site that cannot honor it. */
@@ -140,7 +207,7 @@ export function rewriteNotSupported(
   site: RewriteSite,
 ): Error {
   return new Error(
-    `${describeRewriteTarget(rewrite.target)} is not supported here: ${SITE_MESSAGE[site]}`,
+    `${describeRewriteTarget(rewrite.target)} ${SITE_MESSAGE[site]}`,
     { cause: rewrite },
   );
 }

package/src/route-types.ts

@@ -160,7 +160,7 @@ export type IncludeItem = {
      * include cannot collide with siblings declared outside it.
      */
     includeScope?: string;
-  };
+  } & import("./server/context.js").IncludeScopePosition;
 };
 
 /**
@@ -221,7 +221,6 @@ export type ParallelUseItem =
   | NotFoundBoundaryItem
   | TransitionItem;
 export type InterceptUseItem =
-  | MiddlewareItem
   | LoaderItem
   | LoadingItem
   | LayoutItem

package/src/router/find-match.ts

@@ -21,6 +21,30 @@ function cloneMatchResult<TEnv>(
   return r ? { ...r, params: { ...r.params } } : null;
 }
 
+function describeUnownedTrieRoute(
+  pathname: string,
+  routeKey: string,
+  sp: string,
+  entries: RouteEntry[],
+): string {
+  const includes = entries
+    .filter((e) => e.staticPrefix === sp)
+    .map((e) => {
+      const prefix = (e as { _lazyPrefix?: string })._lazyPrefix;
+      if (prefix === undefined) return "root routes";
+      const names = e.lazyContext?.namePrefix;
+      return `include("${prefix}")${names ? ` naming "${names}.*"` : ""}`;
+    });
+  return (
+    `[@rangojs/router] The route trie matched "${pathname}" to route ` +
+    `"${routeKey}" under static prefix "${sp}", but no include there ` +
+    `registered that name at runtime (checked: ${includes.join(", ")}). ` +
+    `Build discovery and the runtime named this route differently, so it ` +
+    `cannot render. If this follows a route edit, reload the page; if it ` +
+    `persists, please report it with your route configuration.`
+  );
+}
+
 export interface FindMatchDeps<TEnv = any> {
   routesEntries: RouteEntry<TEnv>[];
   // Returns a Promise only when it had to resolve an async include provider
@@ -100,7 +124,7 @@ export function createFindMatch<TEnv = any>(
             // this loop may evaluate a candidate that is NOT the route's owner.
             // Remember the failure and keep scanning: if another candidate owns
             // the route, this sibling's failure is correctly isolated (its
-            // _lazyInflight was cleared, so a later request retries). But if NO
+            // in-flight import was cleared, so a later request retries). But if NO
             // candidate ends up owning it, the failing one WAS the owner — a
             // real, trie-matched route whose module failed to import — and we
             // rethrow below as a 5xx rather than silently 404ing (see finding 3:
@@ -130,6 +154,18 @@ export function createFindMatch<TEnv = any>(
           throw candidateError;
         }
 
+        // No candidate owns the trie's key (#1104): dev throws, production keeps the 404 fallback.
+        if (!entry && fallbackEntry && process.env.NODE_ENV !== "production") {
+          throw new Error(
+            describeUnownedTrieRoute(
+              pathname,
+              trieResult.routeKey,
+              trieResult.sp,
+              deps.routesEntries,
+            ),
+          );
+        }
+
         if (!entry) entry = fallbackEntry;
 
         if (!entry) {