@rangojs/router 0.22.1 → 0.24.0

package/src/route-definition/rewrite.ts

@@ -0,0 +1,146 @@
+/**
+ * `throw rewrite(target)`: middleware renders another route at the same URL.
+ *
+ * The value only: what middleware throws and how the router recognizes it.
+ * The pass loop that honors it lives in rsc/rewrite-passes.ts, the hop trail
+ * in server/rewrite-trail.ts.
+ */
+
+import type { GlobalReverseFunction } from "../reverse.js";
+import type { DefaultReverseRouteMap } from "../types/global-namespace.js";
+
+/**
+ * Cross-realm brand: a Vite dev server can load this module twice (the RSC
+ * and the SSR graph), so `instanceof` alone misses a Rewrite from the other
+ * copy.
+ */
+const REWRITE_BRAND: unique symbol = Symbol.for("rango.rewrite");
+
+/** The target as written: a path, or a global route name with its params. */
+export type RewriteTarget =
+  | { readonly path: string }
+  | {
+      readonly name: string;
+      readonly params?: Record<string, string>;
+      readonly search?: Record<string, unknown>;
+    };
+
+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.";
+
+export function describeRewriteTarget(target: RewriteTarget): string {
+  return "path" in target
+    ? `rewrite(${JSON.stringify(target.path)})`
+    : `rewrite(${JSON.stringify(target.name)})`;
+}
+
+/**
+ * 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.
+ */
+export class Rewrite extends Error {
+  name = "Rewrite" as const;
+  readonly target: RewriteTarget;
+
+  constructor(target: RewriteTarget) {
+    super(`${describeRewriteTarget(target)}: ${REWRITE_RULE}`);
+    Object.setPrototypeOf(this, Rewrite.prototype);
+    this.target = target;
+  }
+}
+Object.defineProperty(Rewrite.prototype, REWRITE_BRAND, { value: true });
+
+/** Whether `value` is a Rewrite thrown by `rewrite()` (ctx.isRewrite). */
+export function isRewrite(value: unknown): value is Rewrite {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { [REWRITE_BRAND]?: unknown })[REWRITE_BRAND] === true
+  );
+}
+
+/**
+ * `rewrite(path)` or `rewrite(name, params?, search?)`: a path in this app
+ * (basename-prefixed like `redirect()`, may carry `?search`), or a global
+ * route name with the params and search `ctx.reverse` takes.
+ */
+export type RewriteFunction<TRoutes = DefaultReverseRouteMap> = ((
+  path: `/${string}`,
+) => Rewrite) &
+  GlobalReverseFunction<TRoutes, Rewrite>;
+
+function createRewrite(
+  target: string,
+  params?: Record<string, string>,
+  search?: Record<string, unknown>,
+): Rewrite {
+  if (typeof target !== "string" || target === "") {
+    throw new TypeError(
+      'rewrite() takes a path starting with "/" or a global route name.',
+    );
+  }
+  if (target.startsWith("/")) {
+    if (params !== undefined || search !== undefined) {
+      throw new TypeError(
+        `rewrite(${JSON.stringify(target)}) takes params only with a route name, not with a path.`,
+      );
+    }
+    return new Rewrite({ path: target });
+  }
+  if (target.startsWith(".")) {
+    throw new TypeError(
+      `rewrite(${JSON.stringify(target)}): a rewrite resolves global route names only (no include() scope).`,
+    );
+  }
+  return new Rewrite({ name: target, params, search });
+}
+
+/**
+ * Render another route at the same URL. Throw it from middleware, before
+ * `await next()`:
+ *
+ * ```ts
+ * router.use(async (ctx, next) => {
+ *   if (!locked || ctx.pathname === "/maintenance") return next();
+ *   throw rewrite("maintenance");
+ * });
+ * ```
+ *
+ * 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.
+ */
+export const rewrite: RewriteFunction = createRewrite as RewriteFunction;
+
+/** A dispatch site that cannot honor a rewrite. */
+export type RewriteSite = "mutation" | "loader-fetch" | "intercept";
+
+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 }).',
+  "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.",
+};
+
+/** The error a rewrite becomes at a site that cannot honor it. */
+export function rewriteNotSupported(
+  rewrite: Rewrite,
+  site: RewriteSite,
+): Error {
+  return new Error(
+    `${describeRewriteTarget(rewrite.target)} is not supported here: ${SITE_MESSAGE[site]}`,
+    { cause: rewrite },
+  );
+}

package/src/route-map-builder.ts

@@ -8,6 +8,11 @@
  * See docs/manifests.md for the full data flow.
  */
 
+import {
+  nullPrototypeStaticChildren,
+  type TrieNode,
+} from "./router/route-trie-builder.js";
+
 let globalRouteMap: Record<string, string> = {};
 
 let cachedManifest: Record<string, string> | null = null;
@@ -86,8 +91,7 @@ export function clearCachedManifest(): void {
 // precomputed entries so multi-router setups (e.g. site + admin via
 // createHostRouter()) don't see each other's routes.
 const perRouterManifestMap: Map<string, Record<string, string>> = new Map();
-const perRouterTrieMap: Map<string, import("./build/route-trie.js").TrieNode> =
-  new Map();
+const perRouterTrieMap: Map<string, TrieNode> = new Map();
 const perRouterPrecomputedEntriesMap: Map<
   string,
   Array<{ staticPrefix: string; routes: Record<string, string> }>
@@ -132,11 +136,12 @@ export function getRouterManifest(
   return perRouterManifestMap.get(routerId);
 }
 
-export function setRouterTrie(
-  routerId: string,
-  trie: import("./build/route-trie.js").TrieNode,
-): void {
-  perRouterTrieMap.set(routerId, trie);
+/**
+ * Install a router's trie. A trie that arrives as JSON (the build manifest)
+ * or across the dev runner boundary gets null-prototype static maps first.
+ */
+export function setRouterTrie(routerId: string, trie: TrieNode): void {
+  perRouterTrieMap.set(routerId, nullPrototypeStaticChildren(trie));
 }
 
 // Routers whose trie came from the COMPLETE build manifest (deserialized via
@@ -156,9 +161,7 @@ export function isRouterTrieAuthoritative(routerId: string): boolean {
   return authoritativeTrieRouters.has(routerId);
 }
 
-export function getRouterTrie(
-  routerId: string,
-): import("./build/route-trie.js").TrieNode | undefined {
+export function getRouterTrie(routerId: string): TrieNode | undefined {
   return perRouterTrieMap.get(routerId);
 }
 
@@ -199,7 +202,7 @@ export async function ensureRouterManifest(routerId: string): Promise<void> {
   if (loader) {
     const mod = await loader();
     if (mod.trie) {
-      perRouterTrieMap.set(routerId, mod.trie);
+      setRouterTrie(routerId, mod.trie);
       // A trie serialized into the build manifest comes from complete
       // discovery — misses are authoritative 404s (see find-match.ts).
       markRouterTrieAuthoritative(routerId);

package/src/router/basename.ts

@@ -12,3 +12,23 @@ export function normalizeBasename(basename?: string): string | undefined {
   const trimmed = basename.replace(/^\/+|\/+$/g, "");
   return trimmed ? "/" + trimmed : undefined;
 }
+
+/**
+ * Prefix a root-relative path with the basename unless it already carries it
+ * (the basename followed by "/", "?", "#" or the end), so "/admin?tab=x" and
+ * "/admin#frag" under basename "/admin" are not prefixed twice. Shared by
+ * redirect(), rewrite() and useRouter().
+ */
+export function prefixBasename(path: string, basename?: string): string {
+  if (
+    !basename ||
+    !path.startsWith("/") ||
+    path === basename ||
+    path.startsWith(basename + "/") ||
+    path.startsWith(basename + "?") ||
+    path.startsWith(basename + "#")
+  ) {
+    return path;
+  }
+  return path === "/" ? basename : basename + path;
+}

package/src/router/handler-context.ts

@@ -30,6 +30,7 @@ import { isAutoGeneratedRouteName } from "../route-name.js";
 import { PRERENDER_PASSTHROUGH } from "../prerender.js";
 import { substitutePatternParams } from "./substitute-pattern-params.js";
 import { fireAndForgetWaitUntil } from "../types/request-scope.js";
+import { defineRewrittenFrom } from "../server/rewrite-trail.js";
 
 // Mutating Headers methods guarded so they throw inside "use cache" / cache()
 // scope. Module-level constant (read-only, .has() lookups) so it is allocated
@@ -87,19 +88,7 @@ export function guardHeaderWrites(
   });
 }
 
-/**
- * Strip internal _rsc* query params from a URL.
- * Returns a new URL with only user-facing params.
- */
-export function stripInternalParams(url: URL): URL {
-  const clean = new URL(url);
-  for (const key of [...clean.searchParams.keys()]) {
-    if (key.startsWith("_rsc")) {
-      clean.searchParams.delete(key);
-    }
-  }
-  return clean;
-}
+export { stripInternalParams } from "./internal-params.js";
 
 /**
  * Resolve route name with namespace prefix support.
@@ -362,6 +351,7 @@ export function createHandlerContext<TEnv>(
   (ctx as { [THEME_REQUEST_CONTEXT]?: unknown })[THEME_REQUEST_CONTEXT] =
     requestContext;
   Object.defineProperty(ctx, "theme", THEME_DESCRIPTOR);
+  defineRewrittenFrom(ctx, requestContext);
   // Brand with taint symbol so "use cache" excludes ctx from cache keys
   (ctx as any)[NOCACHE_SYMBOL] = true;
   return ctx;

package/src/router/intercept-resolution.ts

@@ -262,13 +262,23 @@ export async function resolveInterceptEntry<TEnv>(
 
   latchPprHeaderScopeForInterceptTarget(interceptEntry);
 
+  // The intercept segment's id: the tag scope its handler and layout record in
+  // (#957, cache-tag.ts runInSegmentTagScope) and the owner of its handler's
+  // and loaders' handle pushes, pinned before the loader kickoffs as
+  // fresh.ts/revalidation.ts pin theirs (createLoaderExecutor captures it at
+  // kickoff; a handler's ctx.use(Handle) reads it when called).
+  const slotSegmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}`;
+  (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+    slotSegmentId;
+  const hasLoaders = interceptEntry.loader.length > 0;
+
   const loaderPromises: Promise<any>[] = [];
   const loaderIds: string[] = [];
 
   for (let i = 0; i < interceptEntry.loader.length; i++) {
     const loaderEntry = interceptEntry.loader[i];
     const { loader, revalidate: loaderRevalidateFns } = loaderEntry;
-    const segmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}D${i}.${loader.$$id}`;
+    const segmentId = `${slotSegmentId}D${i}.${loader.$$id}`;
 
     if (revalidationContext) {
       const {
@@ -282,8 +292,7 @@ export async function resolveInterceptEntry<TEnv>(
         stale,
       } = revalidationContext;
 
-      const interceptSegmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}`;
-      if (clientSegmentIds.has(interceptSegmentId)) {
+      if (clientSegmentIds.has(slotSegmentId)) {
         const dummySegment: ResolvedSegment = {
           id: segmentId,
           namespace: `intercept:${interceptEntry.routeName}`,
@@ -331,8 +340,9 @@ export async function resolveInterceptEntry<TEnv>(
       deps.wrapLoaderPromise(
         // The DSL binding's funnel, as for route loaders: a loader's own
         // cache() applies here too.
-        runInsideLoaderScope(() =>
-          resolveLoaderData(loaderEntry, context, context.pathname),
+        runInsideLoaderScope(
+          () => resolveLoaderData(loaderEntry, context, context.pathname),
+          loader.$$id,
         ),
         parentEntry,
         segmentId,
@@ -344,9 +354,6 @@ export async function resolveInterceptEntry<TEnv>(
     );
   }
 
-  // The intercept segment's id, and the tag scope its handler and layout
-  // record in (#957, cache-tag.ts runInSegmentTagScope).
-  const slotSegmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}`;
   let handlerResult: ReactNode;
   try {
     const handler = interceptEntry.handler;
@@ -398,7 +405,7 @@ export async function resolveInterceptEntry<TEnv>(
   const streamedComponent = (promise: Promise<unknown>): ReactNode =>
     trackStreamedHandler(deps, promise, {
       boundaryEntry: parentEntry,
-      segmentId: `${parentEntry.shortCode}.${interceptEntry.slotName}`,
+      segmentId: slotSegmentId,
       segmentType: "parallel",
       context,
       routeKey: interceptEntry.routeName,
@@ -441,6 +448,13 @@ export async function resolveInterceptEntry<TEnv>(
     }
   }
 
+  // The aggregate lists the loaders that ran; empty, not absent, when the
+  // client holds the slot and all skipped. Absent replaces the client's
+  // aggregate, empty merges into it (merge-segment-loaders.ts).
+  if (hasLoaders && loaderPromises.length === 0) {
+    loaderDataPromise = [];
+  }
+
   const interceptSegment = {
     id: slotSegmentId,
     namespace: `intercept:${interceptEntry.routeName}`,
@@ -454,7 +468,7 @@ export async function resolveInterceptEntry<TEnv>(
     belongsToRoute,
     parallelName: `intercept:${interceptEntry.routeName}.${interceptEntry.slotName}`,
     loaderDataPromise,
-    loaderIds: loaderIds.length > 0 ? loaderIds : undefined,
+    loaderIds: hasLoaders ? loaderIds : undefined,
   };
   segments.push(interceptSegment);
 
@@ -497,6 +511,10 @@ export async function resolveInterceptLoadersOnly<TEnv>(
 
   latchPprHeaderScopeForInterceptTarget(interceptEntry);
 
+  // The loaders' handle push owner, as in resolveInterceptEntry.
+  const slotSegmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}`;
+  (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+    slotSegmentId;
   const loaderPromises: Promise<any>[] = [];
   const loaderIds: string[] = [];
 
@@ -514,10 +532,9 @@ export async function resolveInterceptLoadersOnly<TEnv>(
   for (let i = 0; i < interceptEntry.loader.length; i++) {
     const loaderEntry = interceptEntry.loader[i];
     const { loader, revalidate: loaderRevalidateFns } = loaderEntry;
-    const segmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}D${i}.${loader.$$id}`;
+    const segmentId = `${slotSegmentId}D${i}.${loader.$$id}`;
 
-    const interceptSegmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}`;
-    if (clientSegmentIds.has(interceptSegmentId)) {
+    if (clientSegmentIds.has(slotSegmentId)) {
       const dummySegment: ResolvedSegment = {
         id: segmentId,
         namespace: `intercept:${interceptEntry.routeName}`,
@@ -564,8 +581,9 @@ export async function resolveInterceptLoadersOnly<TEnv>(
       deps.wrapLoaderPromise(
         // The DSL binding's funnel, as for route loaders: a loader's own
         // cache() applies here too.
-        runInsideLoaderScope(() =>
-          resolveLoaderData(loaderEntry, context, context.pathname),
+        runInsideLoaderScope(
+          () => resolveLoaderData(loaderEntry, context, context.pathname),
+          loader.$$id,
         ),
         parentEntry,
         segmentId,
@@ -579,8 +597,9 @@ export async function resolveInterceptLoadersOnly<TEnv>(
     );
   }
 
+  // Every loader held: the empty aggregate (see resolveInterceptEntry).
   if (loaderPromises.length === 0) {
-    return null;
+    return { loaderDataPromise: [], loaderIds };
   }
 
   // Match fresh-path semantics: only defer (no await) when loading is truthy.

package/src/router/internal-params.ts

@@ -0,0 +1,16 @@
+/**
+ * Strip internal _rsc* query params from a URL.
+ * Returns a new URL with only user-facing params.
+ *
+ * A leaf, so request-scoped modules (server/rewrite-trail.ts) can strip
+ * without importing the handler context's graph.
+ */
+export function stripInternalParams(url: URL): URL {
+  const clean = new URL(url);
+  for (const key of [...clean.searchParams.keys()]) {
+    if (key.startsWith("_rsc")) {
+      clean.searchParams.delete(key);
+    }
+  }
+  return clean;
+}

package/src/router/is-action.ts

@@ -1,5 +1,6 @@
 /**
- * Shared `isAction()` matcher for revalidate predicates (server + clientUrls).
+ * Shared `isAction()` matcher for revalidate() predicates (server) and
+ * transition({ when }) (browser).
  *
  * Action identity is `actionId`. The helper resolves an imported reference the
  * same way the action boundary derives that id (`$id ?? $$id`), so a

package/src/router/loader-resolution.ts

@@ -55,6 +55,13 @@ import {
 } from "../server/handle-store.js";
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
 import { _getRequestContext } from "../server/request-context.js";
+import { defineRewrittenFrom } from "../server/rewrite-trail.js";
+import {
+  firstUnitCandidate,
+  loaderOwner,
+  startDeferredLoader,
+  type PrefetchDeferral,
+} from "./segment-resolution/prefetch-deferral.js";
 import {
   assertNonCacheableReadAllowed,
   isInsideLoaderScope,
@@ -372,6 +379,29 @@ function detectLoaderCycle(
   return dfs(to);
 }
 
+const warnedRenderedBesideUnit = new Set<string>();
+
+/**
+ * Dev only, once per loader: a loader that is not deferrable awaits
+ * ctx.rendered() in a tree where a prefetch can skip a handler. The prefetch
+ * rejects that call (see rendered() below); saying so on a document or a
+ * navigation shows it before production, where prefetch is automatic.
+ */
+function warnRenderedBesideUnit(
+  deferral: PrefetchDeferral,
+  loaderId: string,
+): void {
+  if (warnedRenderedBesideUnit.has(loaderId)) return;
+  const unit = firstUnitCandidate(deferral);
+  if (!unit) return;
+  warnedRenderedBesideUnit.add(loaderId);
+  console.warn(
+    `[rango] loader "${loaderId}" awaits ctx.rendered() on a route where "${unit.shortCode}" (${unit.id}) has loading(fallback, { prefetch: false }). ` +
+      `A prefetch of this route skips that handler, so ctx.rendered() throws in the prefetch and this loader is an error on the click that adopts it. ` +
+      `Remove { prefetch: false } from that loading(), or stop calling ctx.rendered() in this loader.`,
+  );
+}
+
 /**
  * Creates a memoizing loader executor with cycle detection.
  * Shared by setupLoaderAccess and setupLoaderAccessSilent; only the handle
@@ -397,7 +427,9 @@ function createLoaderExecutor<TEnv>(
     /**
      * A stale refresh's executor (setupLoaderAccess _runLoaderIsolated): its
      * runs' pushes are diverted from the page's store, so a run's end says
-     * nothing about the page's replayed values (HandleStore.settleLoaderRun).
+     * nothing about the page's replayed values (HandleStore.settleLoaderRun),
+     * and it never starts a loader the page's prefetch deferred
+     * (startDeferredLoader): a refresh reads each loader fresh.
      */
     detached?: boolean;
     /**
@@ -472,7 +504,14 @@ function createLoaderExecutor<TEnv>(
     const bound =
       callerLoaderId !== null &&
       internal._loaderCacheOverrides?.get(loader.$$id);
-    const memo = bound || loaderPromises.get(loader.$$id);
+    // A loader the prefetch deferred starts through its registration, cache()
+    // binding included, as a navigation's run of it does.
+    const memo =
+      bound ||
+      loaderPromises.get(loader.$$id) ||
+      (executorOptions?.detached
+        ? undefined
+        : startDeferredLoader(ctx, loader.$$id));
     if (memo) {
       if (recordTags) readValueTags(memo);
       // A "use cache" body reading it refuses an identity read the run made
@@ -511,8 +550,9 @@ function createLoaderExecutor<TEnv>(
     // resolution continues — by the time the async body pushes, it would be
     // stale. Attributing to the owning route/layout segment gives handle
     // pushes the same granularity handler pushes have (segmentOrder-correct
-    // for breadcrumb accumulation).
-    const owningSegmentId = internal._currentSegmentId;
+    // for breadcrumb accumulation). A loader a prefetch deferred and a reader
+    // starts anyway keeps the segment that registers it (loaderOwner).
+    const owningSegmentId = loaderOwner(ctx, loader.$$id);
 
     let renderedResolved = false;
     let renderedPromise: Promise<void> | null = null;
@@ -633,6 +673,32 @@ function createLoaderExecutor<TEnv>(
           );
         }
 
+        // prefetch: false (segment-resolution/prefetch-deferral.ts). A
+        // deferrable loader runs in a fill request, where its entry is held
+        // and its handler does not run: there is no render to wait for.
+        // Refused on every request kind, so it is seen on a document load.
+        const deferral = internal._prefetchDeferral;
+        if (deferral?.scope.loaderIds.has(currentLoaderId)) {
+          throw new Error(
+            `ctx.rendered() is not available to loader "${currentLoaderId}": it is deferred in prefetches ` +
+              `(registered with loader(Def, { prefetch: false }), or behind a loading(fallback, { prefetch: false })), ` +
+              `and the fill request that runs it afterwards does not re-run its entry's handler, so there is no render to wait for and no handle data to read. ` +
+              `Remove { prefetch: false } from the loader (or from the loading() above it), or stop calling ctx.rendered() in this loader.`,
+          );
+        }
+        if (deferral?.mode === "fill") {
+          throw new Error(
+            `ctx.rendered() is not available to loader "${currentLoaderId}" in a fill request: the handlers the client already holds do not run, so their handle data is missing.`,
+          );
+        }
+        if (
+          process.env.NODE_ENV !== "production" &&
+          deferral &&
+          !deferral.mode
+        ) {
+          warnRenderedBesideUnit(deferral, currentLoaderId);
+        }
+
         // awaitBeforeFlush cycle: segment resolution awaits this loader
         // (loader(Def, { ssr: false })), the barrier awaits segment
         // resolution, and rendered() awaits the barrier — waiting here can
@@ -684,6 +750,17 @@ function createLoaderExecutor<TEnv>(
         // keeps a handler from depending on this loader.
         const streaming = reqCtx._treeHasStreaming === true;
         renderedPromise = reqCtx._renderBarrier.then(async () => {
+          // A prefetch that skipped a handler unit has none of that handler's
+          // pushes, and the fill never re-runs this loader: an error, never
+          // a handle list with a hole in it. Known only once resolution has
+          // decided the unit, which is what the barrier waits for.
+          if (deferral?.mode === "prefetch" && deferral.deferredUnit) {
+            throw new Error(
+              `ctx.rendered() in loader "${currentLoaderId}" cannot settle in a prefetch of this route: segment "${deferral.deferredUnit}" has loading(fallback, { prefetch: false }), ` +
+                `so the prefetch skipped its handler and its handle data does not exist. ` +
+                `Remove { prefetch: false } from that loading(), or stop calling ctx.rendered() in this loader.`,
+            );
+          }
           if (streaming) {
             reqCtx._handleStore.seal();
             await reqCtx._handleStore.settled;
@@ -701,6 +778,7 @@ function createLoaderExecutor<TEnv>(
         return renderedPromise;
       },
     };
+    defineRewrittenFrom(loaderCtx, reqCtxRef ?? _getRequestContext());
     (loaderCtx as any)[NOCACHE_SYMBOL] = true;
 
     // Meter this loader once via observePhase (loader:<id> perf metric +
@@ -807,6 +885,9 @@ export function setupLoaderAccess<TEnv>(
   // pushes, and a later run here replaces them (HandleStore.pushReplayed).
   const claimed = new Set<string>();
   const internal = ctx as InternalHandlerContext<any, TEnv>;
+  internal._loaderStarted = (loaderId) =>
+    loaderPromises.has(loaderId) ||
+    internal._loaderCacheOverrides?.has(loaderId) === true;
   internal._claimLoaderPushes = (loaderId) => {
     if (loaderPromises.has(loaderId) || claimed.has(loaderId)) return false;
     claimed.add(loaderId);

package/src/router/match-api.ts

@@ -32,7 +32,12 @@ import {
   getContext,
   type InterceptSelectorContext,
 } from "../server/context";
-import type { ErrorBoundaryHandler, ErrorInfo, MatchResult } from "../types";
+import type {
+  ErrorBoundaryHandler,
+  ErrorInfo,
+  InternalHandlerContext,
+  MatchResult,
+} from "../types";
 import type { ReactNode } from "react";
 import type { MatchContext } from "./match-context.js";
 import type { MatchApiDeps, ActionContext } from "./types.js";
@@ -49,6 +54,11 @@ import {
   type RouteSnapshot,
 } from "./route-snapshot.js";
 import { resolveNavigation } from "./navigation-snapshot.js";
+import {
+  partialDeferralMode,
+  planPrefetchDeferral,
+  requestKind,
+} from "./segment-resolution/prefetch-deferral.js";
 
 /**
  * Create match context for full requests (document/SSR).
@@ -174,6 +184,9 @@ export async function createMatchContextForFull<TEnv>(
   if (reqCtx?._shellCaptureRun) {
     reqCtx._shellCaptureLoaderLanes = routeLoaderLanes(snapshot.entries);
   }
+  // A document never defers; the plan feeds the ctx.rendered() guards.
+  (handlerContext as InternalHandlerContext<any, TEnv>)._prefetchDeferral =
+    planPrefetchDeferral(snapshot.entries, undefined, matched, cacheScope);
 
   return {
     request,
@@ -453,6 +466,28 @@ export async function createMatchContextForPartial<TEnv>(
   if (cacheScope) armRecordTagOwners();
   if (bindsLoaderCache(snapshot.entries)) armLoaderTagSets();
 
+  // `prefetch: false` (segment-resolution/prefetch-deferral.ts). With no
+  // request context (a match run on its own) the request is asked directly.
+  const kind = reqCtx ? reqCtx._requestKind : requestKind(request, rawUrl);
+  const deferral = planPrefetchDeferral(
+    snapshot.entries,
+    partialDeferralMode({
+      fill: kind === "fill",
+      prefetch: kind === "prefetch",
+      method: request.method,
+      isAction,
+      isIntercept,
+      isShellCapture: reqCtx?._shellCaptureRun === true,
+    }),
+    matched,
+    cacheScope,
+    // As the request listed them, not the copy forced above: see
+    // prefetch-deferral.ts.
+    nav.clientSegmentSet,
+  );
+  (handlerContext as InternalHandlerContext<any, TEnv>)._prefetchDeferral =
+    deferral;
+
   return {
     request,
     url: cleanUrl,