@rangojs/router 0.22.1 → 0.24.0

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/thenable-status.ts

@@ -24,3 +24,14 @@ export const SETTLED_THENABLE: Promise<undefined> = Object.assign(
   Promise.resolve(undefined),
   { status: "fulfilled", value: undefined, _debugInfo: [] },
 );
+
+/**
+ * The value React reads from `value` without suspending: `value` itself when
+ * it is not a promise, a promise's `value` once it carries React's or Flight's
+ * `status: "fulfilled"`. Undefined while it is pending or rejected.
+ */
+export function settledValue<T>(value: T | Promise<T>): T | undefined {
+  if (!(value instanceof Promise)) return value;
+  const thenable = value as Promise<T> & { status?: string; value?: T };
+  return thenable.status === "fulfilled" ? thenable.value : undefined;
+}

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;
 };
 
 /**

package/src/types/request-scope.ts

@@ -63,6 +63,14 @@ export interface RequestScope<TEnv = DefaultEnv> {
    */
   originalUrl: URL;
 
+  /**
+   * The visitor's URL (the address bar, search included) when middleware
+   * rewrote this request with `throw rewrite()`; `undefined` otherwise. `url`,
+   * `pathname` and `searchParams` are the rewrite target's. After several
+   * rewrites this is still the first URL. Each context gets its own copy.
+   */
+  rewrittenFrom?: URL;
+
   /** URL pathname (same as `url.pathname`). */
   pathname: string;
 

package/src/types/segments.ts

@@ -172,6 +172,15 @@ export interface ResolvedSegment {
    */
   awaitBeforeFlush?: true;
   parallelLoading?: ReactNode; // For parallel-owned loaders: the parallel's loading fallback
+  /**
+   * A prefetch skipped this segment's work (`prefetch: false`): a loader
+   * carries no `loaderData`, a layout/route/parallel unit carries
+   * `component: null` and its fallback. The browser shows the fallback and
+   * sends a fill request for it (browser/partial-update.ts); until that
+   * lands the segment is a placeholder, never a held copy. Only ever on a
+   * prefetch response: see docs/design/prefetch-false.md.
+   */
+  deferred?: true;
   // Intercept loader fields (for streaming loader data in parallel segments)
   loaderDataPromise?: Promise<any[]> | any[]; // Loader data promise or resolved array
   loaderIds?: string[]; // IDs ($$id) of loaders for this segment
@@ -253,10 +262,12 @@ export interface MatchResult {
   /**
    * Every segment id whose handler actually ran on the server this request,
    * including ones with `component === null` that get filtered out of
-   * `segments`/`diff` to avoid wasted bytes. Drives the client's handle-
-   * cleanup pass — a slot that re-resolves and pushes nothing must clear
-   * its previous handle bucket, but `diff` doesn't carry it because the
-   * segment payload doesn't either. A superset of `diff`.
+   * `segments`/`diff` to avoid wasted bytes, and every loader segment that
+   * ran. Drives the client's handle merge (handles/pushed-by.ts) — a slot
+   * that re-resolves and pushes nothing must clear its previous handle
+   * bucket, but `diff` doesn't carry it because the segment payload doesn't
+   * either; a loader that ran replaces its pushes, one that did not keeps
+   * them. A superset of `diff`.
    */
   resolvedIds: string[];
   /**
@@ -304,3 +315,14 @@ export interface MatchResult {
     params: Record<string, string>;
   }>;
 }
+
+/**
+ * A `prefetch: false` placeholder (ResolvedSegment.deferred): a segment whose
+ * work a prefetch skipped, waiting for its fill. Never a held copy of the
+ * segment it stands for.
+ */
+export function isPlaceholder(
+  segment: Pick<ResolvedSegment, "deferred">,
+): boolean {
+  return segment.deferred === true;
+}

package/src/urls/path-helper-types.ts

@@ -30,7 +30,6 @@ import type {
   InterceptUseItem,
   LoaderUseItem,
   TypedCacheItem,
-  TransitionItem,
   TypedTransitionItem,
   TypedRouteItem,
   TypedIncludeItem,
@@ -362,6 +361,12 @@ export type PathHelpers<TEnv> = {
    * flag BAKES: the loader executes at shell capture and its settled return
    * freezes into the shell (nested promises stay live holes) — the pre-flush
    * promise applied to the prelude.
+   *
+   * Pass `{ prefetch: false }` to keep the loader out of prefetches: a
+   * prefetch skips it and the click that adopts the prefetch fetches it in
+   * one follow-up request (see {@link LoaderOptions}). Only on a segment the
+   * client does not have yet: a loader the client already holds runs in the
+   * prefetch when it revalidates.
    */
   loader: <TData>(
     loaderDef: LoaderDefinition<TData>,
@@ -370,11 +375,25 @@ export type PathHelpers<TEnv> = {
   ) => LoaderItem;
 
   /**
-   * Attach a loading component to the current route/layout
+   * Attach a loading component to the current route/layout.
+   *
+   * `{ ssr: false }` skips the fallback on document requests. `{ prefetch:
+   * false }` keeps what the fallback covers out of prefetches, when this
+   * entry's segment is new to the client: the entry's handler, its loaders,
+   * its orphan layouts and parallel slots and, for a layout, every deeper
+   * entry. The click that adopts the prefetch shows the fallback and fetches
+   * them in one follow-up request, which reads cache() and "use cache" as
+   * any request does (a prefetch reads neither for skipped work). A segment
+   * the client already holds is never deferred: a prefetch renders it as
+   * usual when it revalidates, and what is below it follows its own flags.
+   * To keep a child out of prefetches while moving inside a section, flag
+   * the child's own loading(). An entry whose handler output is stored
+   * (cache(), ppr, Prerender/Static) is served as usual and only its loaders
+   * are skipped.
    */
   loading: (
     component: ReactNode | (() => ReactNode),
-    options?: { ssr?: boolean },
+    options?: { ssr?: boolean; prefetch?: boolean },
   ) => LoadingItem;
 
   /**
@@ -422,8 +441,11 @@ export type PathHelpers<TEnv> = {
    * the browser (never on the server); see TransitionWhenFn.
    */
   transition: {
-    (): TransitionItem;
-    (config: TransitionConfig): TransitionItem;
+    // Typed {} phantoms, not bare TransitionItem: a phantom-less item matches
+    // `TypedTransitionItem<infer R>` with R inferred as Record<string, any>,
+    // which disables route-name checking for the sibling map.
+    (): TypedTransitionItem<{}, {}>;
+    (config: TransitionConfig): TypedTransitionItem<{}, {}>;
     <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
       children: () => TChildren,
     ): TypedTransitionItem<

package/src/urls/type-extraction.ts

@@ -12,6 +12,11 @@ import type { LocalOnlyInclude, UnnamedRoute } from "./pattern-types.js";
 // Route Type Extraction Utilities
 // ============================================================================
 
+/** Drops string index signatures, keeping literal and template keys. */
+type StripStringIndex<T> = {
+  [K in keyof T as string extends K ? never : K]: T[K];
+};
+
 /**
  * Prefix route names with a given prefix (e.g., "blog" + "post" = "blog.post")
  *
@@ -117,15 +122,21 @@ type ExtractRoutesFromItem<T> =
           : TUrlPrefix extends string
             ? PrefixPatterns<TRoutes, TUrlPrefix>
             : TRoutes
-      : // TypedLayoutItem: extract child routes from phantom type
+      : // Phantom-less items (global transition/cache/layout, factories typed
+        // as a use item) match the Typed* shapes with the child map inferred
+        // as the Record<string, any> constraint; the string index signature
+        // turns route-name checking off for the whole map. Strip only the
+        // index and keep literal keys, so a loosely typed include() beside
+        // named routes still contributes those names.
+        // TypedLayoutItem: extract child routes from phantom type
         T extends TypedLayoutItem<infer TChildRoutes>
-        ? TChildRoutes
+        ? StripStringIndex<TChildRoutes>
         : // TypedCacheItem: extract child routes from phantom type
           T extends TypedCacheItem<infer TChildRoutes>
-          ? TChildRoutes
+          ? StripStringIndex<TChildRoutes>
           : // TypedTransitionItem: extract child routes from phantom type
             T extends TypedTransitionItem<infer TChildRoutes>
-            ? TChildRoutes
+            ? StripStringIndex<TChildRoutes>
             : // Fallback (won't extract routes)
               {};
 
@@ -206,16 +217,25 @@ type ExtractResponsesFromItem<T> =
             ? TResponses
             : {}
       : T extends TypedLayoutItem<any, infer TChildResponses>
-        ? TChildResponses extends Record<string, unknown>
-          ? TChildResponses
+        ? StripStringIndex<TChildResponses> extends infer R extends Record<
+            string,
+            unknown
+          >
+          ? R
           : {}
         : T extends TypedCacheItem<any, infer TChildResponses>
-          ? TChildResponses extends Record<string, unknown>
-            ? TChildResponses
+          ? StripStringIndex<TChildResponses> extends infer R extends Record<
+              string,
+              unknown
+            >
+            ? R
             : {}
           : T extends TypedTransitionItem<any, infer TChildResponses>
-            ? TChildResponses extends Record<string, unknown>
-              ? TChildResponses
+            ? StripStringIndex<TChildResponses> extends infer R extends Record<
+                string,
+                unknown
+              >
+              ? R
               : {}
             : {};
 

package/src/use-loader.tsx

@@ -20,6 +20,7 @@ import {
   type LoaderStore,
 } from "./loader-store.js";
 import { NavigationStoreContext } from "./browser/react/context.js";
+import { Defer, readDefer } from "./browser/defer.js";
 import { decodeLoaderEntry } from "./decode-loader-results.js";
 import { warnAwaitedSsrSuspension } from "./ssr-suspension-warning.js";
 import { SETTLED_THENABLE } from "./thenable-status.js";
@@ -51,12 +52,14 @@ const NOT_FOUND = Symbol("not-found");
  * available value from a still-streaming per-loader promise. A pending stream
  * is `use()`d at the read site (implicit suspension); the promise identity is
  * stable per commit (it comes from the provider's memoized context value /
- * element props), which use() requires across replays.
+ * element props), which use() requires across replays. A `prefetch: false`
+ * hole is a Defer (browser/defer.ts), read by its rule: every reader of the
+ * loader reads the one defer.
  */
 type LoaderLookup =
   | typeof NOT_FOUND
   | { value: unknown }
-  | { stream: Promise<unknown> };
+  | { stream: Promise<unknown> | Defer<unknown> };
 
 function lookupLoaderStreams(
   loaderStreams: Record<string, unknown> | undefined,
@@ -64,9 +67,9 @@ function lookupLoaderStreams(
 ): LoaderLookup {
   if (!loaderStreams || !(loaderId in loaderStreams)) return NOT_FOUND;
   const entry = loaderStreams[loaderId];
-  // Within the loaderStreams channel a Promise always means "still streaming";
-  // settled entries are undecoded result values, never promises.
-  return entry instanceof Promise
+  // Within the loaderStreams channel a Promise or a Defer always means "still
+  // streaming"; settled entries are undecoded result values, never promises.
+  return entry instanceof Promise || entry instanceof Defer
     ? { stream: entry }
     : { value: decodeLoaderEntry(entry) };
 }
@@ -163,7 +166,7 @@ function useLoaderInternal<T>(
   const walk = useMemo((): {
     contextData: T | undefined;
     hasContextData: boolean;
-    pendingStream?: Promise<unknown>;
+    pendingStream?: Promise<unknown> | Defer<unknown>;
     /** { ssr: false } loader ids seen on the chain up to (and including) the
      *  level that owned the read — input for the dev SSR suspension warning. */
     awaitedLoaderIds?: string[];
@@ -217,18 +220,20 @@ function useLoaderInternal<T>(
   // every COMPLETED render.
   const { hasContextData } = walk;
   let contextData = walk.contextData;
+  const stream = walk.pendingStream;
   // Dev only (suspense-audit.ts): the stream this reader is handed. The test
   // is a build-time constant, so the hook is called on every render or never.
   if (process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT) {
-    useReadAudit(loader.$$id, walk.pendingStream);
-  }
-  if (walk.pendingStream) {
-    warnAwaitedSsrSuspension(
+    useReadAudit(
       loader.$$id,
-      walk.awaitedLoaderIds,
-      walk.pendingStream,
+      stream instanceof Defer ? stream.promise : stream,
     );
-    contextData = decodeLoaderEntry(use(walk.pendingStream)) as T;
+  }
+  if (stream instanceof Defer) {
+    contextData = decodeLoaderEntry(readDefer(stream)) as T;
+  } else if (stream) {
+    warnAwaitedSsrSuspension(loader.$$id, walk.awaitedLoaderIds, stream);
+    contextData = decodeLoaderEntry(use(stream)) as T;
   } else if (hasContextData) {
     // React logs a render that finishes without use() at a place whose reader
     // suspended in use() on mount, so every read with route context calls it.

package/src/vite/discovery/client-urls-projection.ts

@@ -2,10 +2,9 @@ import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import { normalizePath, parseAst } from "vite";
 import {
-  serializeClientUrlPatterns,
+  projectClientUrlsModule,
   type ClientUrlProjection,
 } from "../../client-urls/server-projection.js";
-import type { ClientUrlPatterns } from "../../client-urls/types.js";
 import {
   computeProductionHash,
   hashRefKey,
@@ -191,22 +190,19 @@ export async function refreshRecordedClientUrlProjections(
   }
 
   for (const [source, referenceIds] of referenceIdsBySource) {
-    let definition: unknown;
+    let module: Record<string, unknown>;
     try {
-      definition = (await ssrEnv.runner.import(source)).default;
+      module = await ssrEnv.runner.import(source);
     } catch {
       continue;
     }
-    if (
-      (typeof definition !== "object" && typeof definition !== "function") ||
-      definition === null ||
-      (definition as { __brand?: unknown }).__brand !== "client-urls"
-    ) {
+    let projection: ClientUrlProjection | undefined;
+    try {
+      projection = projectClientUrlsModule(module, { hoisted: true });
+    } catch {
       continue;
     }
-    const projection = serializeClientUrlPatterns(
-      definition as ClientUrlPatterns,
-    );
+    if (!projection) continue;
     debug?.(
       "pre-entry refresh %s -> [%s]",
       source,
@@ -288,21 +284,24 @@ export async function discoverClientUrlProjections(
         cause,
       );
     }
-    const definition = module.default;
-    if (
-      (typeof definition !== "object" && typeof definition !== "function") ||
-      definition === null ||
-      (definition as { __brand?: unknown }).__brand !== "client-urls"
-    ) {
+    let projection: ClientUrlProjection | undefined;
+    try {
+      projection = projectClientUrlsModule(module, { hoisted: true });
+    } catch (cause) {
+      throw projectionError(
+        referenceIds[0],
+        source,
+        cause instanceof Error ? cause.message : String(cause),
+        cause,
+      );
+    }
+    if (!projection) {
       throw projectionError(
         referenceIds[0],
         source,
         'the module default export must be created by clientUrls() and have __brand === "client-urls"',
       );
     }
-    const projection = serializeClientUrlPatterns(
-      definition as ClientUrlPatterns,
-    );
     for (const referenceId of referenceIds) {
       nextProjections.set(referenceId, projection);
     }