@rangojs/router 0.22.1 → 0.23.0

package/src/testing/internal/client-urls-projection.ts

@@ -0,0 +1,70 @@
+import {
+  projectClientUrlsModule,
+  setClientUrlProjection,
+  type ClientUrlProjection,
+} from "../../client-urls/server-projection.js";
+import { isHoistedRevalidateRef } from "../../client-urls/hoisted-revalidate.js";
+import { registerClientUrlRevalidators } from "../../client-urls/revalidate-registry.js";
+import type { ClientUrlPatterns } from "../../client-urls/types.js";
+import type { ShouldRevalidateFn } from "../../types.js";
+
+/**
+ * Install the projection of a `"use client"` clientUrls() module under its
+ * client reference id, as discovery installs it for an app
+ * (discoverClientUrlProjections in vite/discovery/client-urls-projection.ts):
+ * the same projection step, into the same registry include() materializes
+ * from. rangoUseClientTransform (testing/vitest.ts) appends a call to every
+ * such module, passing the module's own source evaluated without the
+ * transform, so a router under test mounts the group with no setup.
+ *
+ * A Vitest project runs no hoist plugin, so the source's revalidate()
+ * predicates are plain functions. Each is registered under a key named for
+ * its reference, route and loader, as the plugin's generated module registers
+ * its own, and the projection carries the keys: materialization attaches them
+ * and the server runs them, as in an app.
+ */
+export function installClientUrlsProjection(
+  referenceId: string,
+  source: Readonly<Record<string, unknown>>,
+): void {
+  const projection = projectClientUrlsModule(source);
+  if (!projection) {
+    throw new Error(
+      `Cannot install the client URL projection for reference "${referenceId}": ` +
+        'the module default export must be created by clientUrls() and have __brand === "client-urls"',
+    );
+  }
+  setClientUrlProjection(
+    referenceId,
+    withRevalidateKeys(
+      referenceId,
+      source.default as ClientUrlPatterns,
+      projection,
+    ),
+  );
+}
+
+function withRevalidateKeys(
+  referenceId: string,
+  definition: ClientUrlPatterns,
+  projection: ClientUrlProjection,
+): ClientUrlProjection {
+  const fns: Record<string, ShouldRevalidateFn<any, any>> = {};
+  const routes = projection.routes.map((route) => {
+    const record = definition.routes.find(({ id }) => id === route.id);
+    const loaderRevalidate = (record?.loaders ?? []).map(
+      ({ revalidate }, loaderIndex) =>
+        revalidate.map((entry, index) => {
+          if (isHoistedRevalidateRef(entry)) return entry.$$rangoRevalidate;
+          const key = `${referenceId}:${route.id}:${loaderIndex}:${index}`;
+          fns[key] = entry;
+          return key;
+        }),
+    );
+    return loaderRevalidate.some((keys) => keys.length > 0)
+      ? { ...route, loaderRevalidate }
+      : route;
+  });
+  registerClientUrlRevalidators(fns);
+  return { ...projection, routes };
+}

package/src/testing/internal/test-action.ts

@@ -0,0 +1,25 @@
+import * as RSDServer from "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge";
+import { registerServerModule } from "./server-modules.js";
+
+/**
+ * Register `action` under its reference id, `<module id>#<export name>`,
+ * tagged as a server reference like a built "use server" export so it keeps
+ * its `$$id`, where the plugin-rsc stub's decodeAction / loadServerAction
+ * resolve it. `primitive` names the caller in the error for a malformed id.
+ * Loads the react-server build: callers run under the react-server condition.
+ */
+export function registerTestAction(
+  action: (...args: any[]) => unknown,
+  id: string,
+  primitive: string,
+): void {
+  const [moduleId, name] = id.split("#");
+  if (!moduleId || !name) {
+    throw new Error(
+      `${primitive}: id must be "<module id>#<export name>", received ${JSON.stringify(id)}`,
+    );
+  }
+  registerServerModule(moduleId, {
+    [name]: RSDServer.registerServerReference(action, moduleId, name),
+  });
+}

package/src/testing/run-loader.ts

@@ -20,8 +20,9 @@
  * - `ctx.reverse()` throws unless `routeMap` is provided (it does NOT fall back
  *   to the global route map — that would leak whichever routes another test
  *   registered).
- * - `ctx.use(handle)` follows the production rule: reading a handle before
+ * - `ctx.get(handle)` follows the production rule: reading a handle before
  *   `await ctx.rendered()` throws (pass `rendered` to mock the barrier).
+ *   `ctx.use(handle)` is the push and needs no barrier.
  * - `use cache` functions only cache (and only fire their taint/profile guards)
  *   when a `cacheStore` is provided — without one, registerCachedFunction
  *   bypasses (it checks for a store first). Pass `cacheStore`/`cacheProfiles`

package/src/testing/run-revalidate.ts

@@ -0,0 +1,142 @@
+/**
+ * runRevalidate — unit-test revalidate() predicates: a urls() segment's, or a
+ * clientUrls() loader's (which the build moves to the server, where it runs
+ * the same way).
+ *
+ * Evaluates the predicate(s) through the router's own evaluateRevalidation
+ * (router/revalidation.ts) inside a seeded request context: the default
+ * decision, the argument object, boolean short-circuit, soft-verdict
+ * threading and the fail-open on a throw are the production code paths, not
+ * a re-implementation. Pass an array to test a chain in declaration order.
+ */
+
+import { evaluateRevalidation } from "../router/revalidation.js";
+import { runWithRequestContext } from "../server/request-context.js";
+import type { ResolvedSegment, ShouldRevalidateFn } from "../types.js";
+import {
+  normalizeTestAction,
+  resolveTestActionId,
+  type ImportedAction,
+} from "./internal/action-id.js";
+import { createTestRequestContext } from "./internal/context.js";
+import type { VarsInit } from "./internal/seed-vars.js";
+import { toURL } from "./to-url.js";
+
+type RevalidateArgs = Parameters<ShouldRevalidateFn<any, any>>[0];
+
+/** The action fields a predicate receives on an action request. */
+export interface RunRevalidateAction {
+  /** The triggering action: an imported server action or its actionId. */
+  ref?: ImportedAction | string;
+  /** `actionResult`: the action's return value. */
+  result?: unknown;
+  /** `formData`: the action's FormData argument. */
+  formData?: FormData;
+  /** `actionUrl`. Defaults to `currentUrl`. */
+  url?: string | URL;
+}
+
+/**
+ * Options for {@link runRevalidate}. Defaults model a same-URL navigation
+ * with no action, for a route-owned loader segment.
+ */
+export interface RunRevalidateOptions<TEnv = any> {
+  /** The page being left. Defaults to `http://localhost/`. */
+  currentUrl?: string | URL;
+  /** The destination. Defaults to `currentUrl`. */
+  nextUrl?: string | URL;
+  currentParams?: Record<string, string>;
+  /** Defaults to `currentParams`. */
+  nextParams?: Record<string, string>;
+  /**
+   * The triggering action: an imported server action (id via
+   * `$id ?? $$id`), an actionId string, or `{ ref, result, formData, url }`.
+   * Makes the request a POST, as an action request is.
+   */
+  action?: ImportedAction | string | RunRevalidateAction;
+  /** Overrides the request method (`POST` with `action`, else `GET`). */
+  method?: string;
+  /** The segment the predicate is attached to. Defaults to `"loader"`. */
+  segmentType?: RevalidateArgs["segmentType"];
+  /**
+   * The segment belongs to the matched route (a route's own loaders, a
+   * clientUrls() group loader). Defaults to true; false models a layout's
+   * loader, which a navigation keeps by default.
+   */
+  belongsToRoute?: boolean;
+  /** `stale`: a history-entry background revalidation. */
+  stale?: boolean;
+  /** `toRouteName` (and `routeName`). */
+  routeName?: string;
+  /** `fromRouteName`. */
+  fromRouteName?: string;
+  /** Environment bindings of the seeded context. */
+  env?: TEnv;
+  /** Variables a middleware would have set, readable with `context.get()`. */
+  vars?: VarsInit;
+  /** `context`, in place of the seeded request context. */
+  context?: RevalidateArgs["context"];
+}
+
+const DEFAULT_URL = "http://localhost/";
+
+/**
+ * Run one revalidate() predicate, or a chain in declaration order, the way
+ * the router does for a request. Resolves to the final decision: true
+ * re-runs the segment, false keeps the client's copy.
+ */
+export async function runRevalidate<TEnv = any>(
+  fn: ShouldRevalidateFn<any, TEnv> | readonly ShouldRevalidateFn<any, TEnv>[],
+  opts: RunRevalidateOptions<TEnv> = {},
+): Promise<boolean> {
+  const currentUrl = toURL(opts.currentUrl, new URL(DEFAULT_URL));
+  const nextUrl = toURL(opts.nextUrl, currentUrl);
+  const currentParams = opts.currentParams ?? {};
+  const nextParams = opts.nextParams ?? currentParams;
+  const action = normalizeTestAction(opts.action);
+  const method = opts.method ?? (action ? "POST" : "GET");
+  const request = new Request(nextUrl, { method });
+  const { ctx } = createTestRequestContext<TEnv>({
+    env: opts.env,
+    request,
+    vars: opts.vars,
+    params: nextParams,
+  });
+  if (opts.fromRouteName !== undefined) ctx._prevRouteKey = opts.fromRouteName;
+
+  const segment: ResolvedSegment = {
+    id: "runRevalidate",
+    namespace: "runRevalidate",
+    type: opts.segmentType ?? "loader",
+    index: 0,
+    component: null,
+    params: nextParams,
+    belongsToRoute: opts.belongsToRoute ?? true,
+  };
+  const fns = Array.isArray(fn) ? fn : [fn];
+  return runWithRequestContext(ctx as never, () =>
+    evaluateRevalidation({
+      segment,
+      prevParams: currentParams,
+      getPrevSegment: null,
+      request,
+      prevUrl: currentUrl,
+      nextUrl,
+      revalidations: fns.map((entry, index) => ({
+        name: `runRevalidate#${index}`,
+        fn: entry,
+      })),
+      routeKey: opts.routeName ?? "",
+      context: (opts.context ?? ctx) as RevalidateArgs["context"],
+      actionContext: action
+        ? {
+            actionId: resolveTestActionId(action.ref, "runRevalidate") ?? "",
+            actionUrl: toURL(action.url, currentUrl),
+            actionResult: action.result,
+            formData: action.formData,
+          }
+        : undefined,
+      stale: opts.stale ?? false,
+    }),
+  );
+}

package/src/testing/run-transition-when.ts

@@ -22,7 +22,11 @@ import {
   resolveNavigationState,
 } from "../browser/history-state.js";
 import { isLocationStateEntry } from "../browser/react/location-state-shared.js";
-import { resolveTestActionId } from "./internal/action-id.js";
+import {
+  normalizeTestAction,
+  resolveTestActionId,
+  type ImportedAction,
+} from "./internal/action-id.js";
 import type {
   RouteLocation,
   TransitionConfig,
@@ -31,8 +35,6 @@ import type {
   TransitionWhenKind,
 } from "../types/segments.js";
 
-type ImportedAction = (...args: never[]) => unknown;
-
 /** A navigation side: a URL, or a partial RouteLocation. */
 export type RunTransitionWhenLocation =
   | string
@@ -58,7 +60,7 @@ export interface RunTransitionWhenOptions {
   /** The destination. Defaults to `from`; always `from` for "action" and "revalidate". */
   to?: RunTransitionWhenLocation;
   /**
-   * The triggering action (like runClientRevalidate's): an imported server
+   * The triggering action (like runRevalidate's): an imported server
    * action (id via `$id ?? $$id`), an actionId string, or
    * `{ ref, formData, result, error }`.
    */
@@ -105,10 +107,7 @@ export function runTransitionWhen(
   whenOrConfig: TransitionWhenFn | TransitionConfig,
   opts: RunTransitionWhenOptions = {},
 ): RunTransitionWhenResult {
-  const actionOption =
-    typeof opts.action === "function" || typeof opts.action === "string"
-      ? { ref: opts.action }
-      : opts.action;
+  const actionOption = normalizeTestAction(opts.action);
   const from = toLocation(opts.from, DEFAULT_URL);
   const context = createTransitionWhenContext({
     kind: opts.kind ?? (actionOption ? "action" : "push"),

package/src/testing/serve-shell-request.ts

@@ -57,7 +57,9 @@ import {
   SHELL_CAPTURE_MAX_WAIT_MS,
 } from "../rsc/shell-capture-constants.js";
 import { SEGMENT_FRAGMENT_CAPABILITY_HEADER } from "../segment-fragments.js";
+import { FILL_PARAM, PREFETCH_HEADER } from "../prefetch-markers.js";
 import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
+import { withoutPushedBy } from "../handles/pushed-by.js";
 import type { HandleData } from "../server/handle-store.js";
 import { _getRequestContext } from "../server/request-context.js";
 import {
@@ -88,8 +90,22 @@ export interface ServeShellRequestOptions<TEnv = any> {
    * of a document GET: from `from` (default `/`) with `segments` mounted
    * (default none), advertising fragment passthrough. The replay decision is
    * `result.replayStatus`.
+   *
+   * `prefetch: true` sends it as a `<Link>` prefetch does (the
+   * `X-Rango-Prefetch` header), so `prefetch: false` loaders and `loading()`
+   * entries are deferred: `result.readDeferred()` lists them. `fill: true`
+   * sends the request the browser follows an adopted prefetch with
+   * (`_rsc_fill`): pass the ids the prefetch delivered, without the deferred
+   * ones, as `segments`, and the same URL as `from`.
    */
-  partial?: true | { from?: string; segments?: readonly string[] };
+  partial?:
+    | true
+    | {
+        from?: string;
+        segments?: readonly string[];
+        prefetch?: boolean;
+        fill?: boolean;
+      };
   /**
    * POST this form as a submit before hydration: the no-JS request the
    * progressive-enhancement path runs the action for and re-renders the page
@@ -98,6 +114,30 @@ export interface ServeShellRequestOptions<TEnv = any> {
    * Not with `partial`.
    */
   form?: FormData;
+  /**
+   * Send the request a JS server action call makes from the page at `url`:
+   * a POST of `args` (encoded as the browser encodes them) for `ref`, with
+   * the page's mounted `segments` (default none), as
+   * browser/server-action-bridge.ts sends it. The response is the action's
+   * Flight payload (its return value and the re-rendered segments).
+   * Not with `partial` or `form`.
+   */
+  action?: ServeShellRequestAction;
+}
+
+/** The JS server action call of {@link ServeShellRequestOptions.action}. */
+export interface ServeShellRequestAction {
+  /** The server action. */
+  ref: (...args: any[]) => unknown;
+  /**
+   * Its reference id, `<module id>#<export name>`, as the build gives a
+   * "use server" export; registered so the handler loads `ref` by it.
+   */
+  id: string;
+  /** The arguments the page calls it with. */
+  args?: readonly unknown[];
+  /** The segment ids the page holds (`_rsc_segments`). */
+  segments?: readonly string[];
 }
 
 /** A response's handle data, as the browser consumes it. */
@@ -157,6 +197,12 @@ export interface ServeShellRequestResult {
    * values resolved. Undefined when no Flight was rendered.
    */
   readHandles(): Promise<ShellRequestHandles | undefined>;
+  /**
+   * The ids of the segments `flight` marks deferred (a prefetch skipped
+   * them; the fill request renders them), in payload order. Empty when
+   * nothing was deferred, undefined when no Flight was rendered.
+   */
+  readDeferred(): Promise<string[] | undefined>;
   /**
    * The form state the SSR render received (the `formState` render option),
    * or undefined when it received none.
@@ -297,9 +343,22 @@ async function decodePayloadHandles(
   for await (const data of metadata?.handles ?? []) hydration = data;
   const late: HandleData[] = [];
   for await (const data of metadata?.handlesLate ?? []) {
-    late.push(await resolveDeferredHandleValues(data));
+    late.push(withoutPushedBy(await resolveDeferredHandleValues(data)));
   }
-  return { hydration: await resolveDeferredHandleValues(hydration), late };
+  return {
+    hydration: withoutPushedBy(await resolveDeferredHandleValues(hydration)),
+    late,
+  };
+}
+
+/** The ids of the segments a payload marks deferred. */
+async function decodeDeferredIds(flight: string): Promise<string[]> {
+  const { metadata } = await decodePayload<{
+    metadata?: { segments?: Array<{ id: string; deferred?: boolean }> };
+  }>(flight);
+  return (metadata?.segments ?? [])
+    .filter((segment) => segment.deferred === true)
+    .map((segment) => segment.id);
 }
 
 /**
@@ -435,9 +494,46 @@ async function getHandler(
   return handler;
 }
 
-function buildRequest(url: URL, options: ServeShellRequestOptions): Request {
+async function buildActionRequest(
+  url: URL,
+  headers: Headers,
+  action: ServeShellRequestAction,
+): Promise<Request> {
+  const [{ registerTestAction }] = await Promise.all([
+    import("./internal/test-action.js"),
+    import("./internal/flight-client-globals.js"),
+  ]);
+  const { encodeReply } =
+    await import("@vitejs/plugin-rsc/vendor/react-server-dom/client.edge");
+  registerTestAction(action.ref, action.id, "serveShellRequest");
+  const target = new URL(url);
+  target.searchParams.set("_rsc_action", action.id);
+  target.searchParams.set("_rsc_segments", (action.segments ?? []).join(","));
+  headers.set("rsc-action", action.id);
+  if (!headers.has("X-RSC-Router-Client-Path")) {
+    headers.set("X-RSC-Router-Client-Path", url.href);
+  }
+  return new Request(target, {
+    method: "POST",
+    headers,
+    body: await encodeReply([...(action.args ?? [])]),
+  });
+}
+
+async function buildRequest(
+  url: URL,
+  options: ServeShellRequestOptions,
+): Promise<Request> {
   const headers = new Headers(options.headers);
   const partial = options.partial;
+  if (options.action) {
+    if (partial || options.form) {
+      throw new Error(
+        "serveShellRequest: action cannot be combined with partial or form",
+      );
+    }
+    return buildActionRequest(url, headers, options.action);
+  }
   if (options.form) {
     if (partial) {
       throw new Error(
@@ -454,10 +550,21 @@ function buildRequest(url: URL, options: ServeShellRequestOptions): Request {
     if (!headers.has("accept")) headers.set("accept", "text/html");
     return new Request(url, { headers });
   }
-  const { from = "/", segments = [] } = partial === true ? {} : partial;
+  const {
+    from = "/",
+    segments = [],
+    prefetch = false,
+    fill = false,
+  } = partial === true ? {} : partial;
   const target = new URL(url);
   target.searchParams.set("_rsc_partial", "true");
   target.searchParams.set("_rsc_segments", segments.join(","));
+  // As the browser sends them: browser/navigation-client.ts (fill) and
+  // browser/prefetch/fetch.ts (prefetch).
+  if (fill) target.searchParams.set(FILL_PARAM, "1");
+  if (prefetch && !headers.has(PREFETCH_HEADER)) {
+    headers.set(PREFETCH_HEADER, "1");
+  }
   if (!headers.has("X-RSC-Router-Client-Path")) {
     headers.set("X-RSC-Router-Client-Path", new URL(from, url).href);
   }
@@ -536,7 +643,7 @@ export async function serveShellRequest<TEnv = any>(
   const target = new URL(url, "http://localhost");
   await ensureRouterManifest(router.id);
   const handler = await getHandler(router, options.cacheStore);
-  const request = buildRequest(target, options);
+  const request = await buildRequest(target, options);
   const executionContext = createCollectingExecutionContext();
   const { tasks } = executionContext;
   const recorder: Recorder = {};
@@ -594,6 +701,9 @@ export async function serveShellRequest<TEnv = any>(
     async readHandles() {
       return flight ? decodePayloadHandles(flight) : undefined;
     },
+    async readDeferred() {
+      return flight ? decodeDeferredIds(flight) : undefined;
+    },
     formState: recorder.formState,
     async readPayloadFormState() {
       if (!flight) return undefined;

package/src/testing/vitest.ts

@@ -139,6 +139,37 @@ function resolveFromRouter(spec: string): string | undefined {
 const rsdServerEdgePath: string | undefined =
   resolveFromRouter(RSD_SERVER_EDGE_SPEC);
 
+/** Marks the import of a clientUrls() module's untransformed source. */
+const CLIENT_URLS_SOURCE_QUERY = "rango-client-urls-source";
+
+/** `@rangojs/router/client` under the react-server condition. */
+const CLIENT_ENTRY_RSC_PATH: string = here("src/client.rsc.tsx").replaceAll(
+  "\\",
+  "/",
+);
+
+/**
+ * Imported by absolute path so it shares the registry instance the router
+ * source under test materializes include() from.
+ */
+const CLIENT_URLS_INSTALLER_PATH: string = here(
+  "src/testing/internal/client-urls-projection.ts",
+).replaceAll("\\", "/");
+
+/**
+ * Appended to a transformed `"use client"` clientUrls() module: install the
+ * projection of its own source under its default export's reference id
+ * (`<id>#default`, as registerClientReference composes it).
+ */
+function clientUrlsProjectionInstall(id: string): string {
+  const source = `${id}${id.includes("?") ? "&" : "?"}${CLIENT_URLS_SOURCE_QUERY}`;
+  return (
+    `\nimport * as $$RangoClientUrlsSource from ${JSON.stringify(source)};\n` +
+    `import { installClientUrlsProjection as $$rangoInstallClientUrlsProjection } from ${JSON.stringify(CLIENT_URLS_INSTALLER_PATH)};\n` +
+    `$$rangoInstallClientUrlsProjection(${JSON.stringify(`${id}#default`)}, $$RangoClientUrlsSource);\n`
+  );
+}
+
 /**
  * Build the `resolve.alias` entries a consumer's node/DOM Vitest project needs to
  * import a real @rangojs/router app's router/loaders/middleware. Spread into a
@@ -241,6 +272,10 @@ export function rangoTestConfig(
 /** A minimal Vite plugin shape (avoids a hard dependency on Vite's types). */
 interface FlightTransformPlugin {
   name: string;
+  resolveId: {
+    order: "pre";
+    handler(source: string, importer: string | undefined): string | undefined;
+  };
   transform(
     code: string,
     id: string,
@@ -298,12 +333,39 @@ interface FlightTransformPlugin {
  * by the module's absolute path (the boundary id), the export name becoming the
  * boundary name. Modules without the directive (server components) are untouched,
  * so `renderToFlightString` of pure leaf trees is unaffected.
+ *
+ * A `"use client"` module whose default export is a `clientUrls()` definition
+ * also installs its server projection, as the rango plugin's discovery does for
+ * an app: the module imports its own source without this transform and projects
+ * it under its client reference. A router that mounts the group
+ * (`include("/shop", shopUrls)` or `.routes(shopUrls)`) then serves its routes
+ * through `serveShellRequest` and `dispatch` with no setup.
  */
 export function rangoUseClientTransform(): FlightTransformPlugin {
   return {
     name: "rango:testing-use-client",
+    resolveId: {
+      // Before Vite's resolver, which resolves the bare specifier first.
+      order: "pre",
+      handler(source, importer) {
+        // A clientUrls() module's source resolves the router's client entry
+        // as the RSC environment does (the react-server condition): this
+        // project resolves it to client.tsx, a "use client" module whose
+        // clientUrls is a client reference here. Both entries export the
+        // same clientUrls.
+        if (
+          source === "@rangojs/router/client" &&
+          importer?.includes(CLIENT_URLS_SOURCE_QUERY)
+        ) {
+          return CLIENT_ENTRY_RSC_PATH;
+        }
+        return undefined;
+      },
+    },
     async transform(code, id) {
       if (id.includes("/node_modules/")) return undefined;
+      // A clientUrls() module's own source, imported by its transformed copy.
+      if (id.includes(CLIENT_URLS_SOURCE_QUERY)) return undefined;
       // Fast path: only parse modules that mention the directive.
       if (!code.includes("use client")) return undefined;
       const { parseAstAsync } = await import("vite");
@@ -329,7 +391,7 @@ export function rangoUseClientTransform(): FlightTransformPlugin {
           `${JSON.stringify(id)}, ${JSON.stringify(name)})`,
       });
       if (!result) return undefined;
-      const { output } = result;
+      const { output, exportNames } = result;
       // Absolute file URL, not the bare specifier: the consumer's "use client"
       // module cannot resolve @vitejs/plugin-rsc (it is a router dependency).
       const rsdHref = rsdServerEdgePath
@@ -338,6 +400,10 @@ export function rangoUseClientTransform(): FlightTransformPlugin {
       output.prepend(
         `import * as $$RangoRSD from ${JSON.stringify(rsdHref)};\n`,
       );
+      // The modules discovery records (recordClientUrlsModule).
+      if (code.includes("clientUrls(") && exportNames.includes("default")) {
+        output.append(clientUrlsProjectionInstall(id));
+      }
       return {
         code: output.toString(),
         map: output.generateMap({ hires: true }),

package/src/types/boundaries.ts

@@ -104,6 +104,18 @@ export function isLoaderDataResult(value: unknown): value is LoaderDataResult {
   );
 }
 
+/**
+ * A loading skeleton is renderable only when it is a real ReactNode value;
+ * `false` counts as "not renderable". This is the three-term gate. The
+ * distinct two-term gate at the LoaderBoundary site (segment-system.tsx)
+ * deliberately treats `false` as "create a boundary without a
+ * RouteContentWrapper" (tree-structure.md), so it must NOT use this helper.
+ * Leaf module: shared by client (segment-system) and server (DSL, resolution).
+ */
+export function isRenderableLoading(loading: unknown): boolean {
+  return loading !== undefined && loading !== null && loading !== false;
+}
+
 export interface NotFoundInfo {
   message: string;
   segmentId: string;

package/src/types/handler-context.ts

@@ -492,6 +492,20 @@ export type InternalHandlerContext<
    * setupLoaderAccess.
    */
   _bindLoaderCacheTags?: (loaderId: string, tags: Set<string>) => void;
+  /**
+   * @internal This match's `prefetch: false` plan: what a prefetch defers,
+   * whether the request is a fill, and the loaders that cannot call
+   * ctx.rendered(). Set by match-api.ts when the tree declares a flag or the
+   * request is a fill. See router/segment-resolution/prefetch-deferral.ts.
+   */
+  _prefetchDeferral?: import("../router/segment-resolution/prefetch-deferral.js").PrefetchDeferral;
+  /**
+   * @internal Whether a loader was started in this request: a run of it (a
+   * handler's or another loader's ctx.use()) or its cache() binding. A
+   * prefetch delivers such a loader instead of deferring it. See
+   * setupLoaderAccess.
+   */
+  _loaderStarted?: (loaderId: string) => boolean;
 };
 
 /**

package/src/types/loader-types.ts

@@ -200,6 +200,36 @@ export type LoaderFn<
  */
 export type LoaderOptions = {
   ssr?: boolean;
+  /**
+   * `prefetch: false` keeps this loader out of prefetches. A `<Link>`
+   * prefetch (a partial request with `X-Rango-Prefetch`) does not execute it;
+   * the payload marks it deferred. A document request and a navigation with
+   * no prefetch to adopt run it as usual.
+   *
+   * A deferred loader never blocks the navigation that adopts the prefetch:
+   * it behaves like a loader that is still streaming. Its own `<Suspense>`
+   * shows at once; if the nearest boundary is the route's `loading()`, that
+   * shows; with no boundary React holds the page until the fill returns. The
+   * fill is the one follow-up request that runs the loader.
+   *
+   * The fill reads through the loader's own `cache()` and any `"use cache"`
+   * function it calls. A prefetch reads neither, by intent: looking would
+   * mean running the loader on a miss.
+   *
+   * The flag applies only to a segment the client does not have yet. A
+   * loader the client already holds (the same route with new params, say)
+   * runs in the prefetch when it revalidates, exactly as without the flag:
+   * a click that adopts a prefetch is never worse than the same click with
+   * no prefetch at all.
+   *
+   * Limits: a handler that awaits the loader with `ctx.use()` makes it run in
+   * the prefetch anyway; the loader cannot call `ctx.rendered()` (it throws
+   * on every request); on a `ppr` route the flag is ignored for an
+   * `ssr: false` loader (the bake lane), with a dev warning. In the fill
+   * request only deferred work and middleware run, so values a held handler
+   * would have set with `ctx.set()` are not visible.
+   */
+  prefetch?: boolean;
 };
 
 /**