@rangojs/router 0.24.4 → 0.26.0

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

@@ -2,7 +2,7 @@
  * serveShellRequest — one request through the production PPR serve path.
  *
  * Builds the router's request handler as `router.fetch` does
- * (`createRSCHandler` with the router's `nonce`, `version` and `cache`
+ * (`createRSCHandler` with the router's `nonce` and `cache`
  * config) and serves one GET through it, so middleware, the shell serve path
  * and a MISS's background capture all run production code, on real Flight
  * (the vendored react-server-dom serializer). The call settles every
@@ -62,6 +62,8 @@ 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 type { ResolvedSegment } from "../types.js";
+import { revalidationErrorOf } from "../decode-loader-results.js";
 import { _getRequestContext } from "../server/request-context.js";
 import {
   parsePprReplayStatus,
@@ -97,15 +99,22 @@ export interface ServeShellRequestOptions<TEnv = any> {
    * 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`.
+   * ones, as `segments`, and the same URL as `from`. `interceptSource` sends
+   * the intercept source (`X-RSC-Router-Intercept-Source`) the browser sends
+   * from an open modal and with the fill of an intercept, whose `from` is
+   * that source. `rewriteTarget` sends the `metadata.rewriteTarget` the page at
+   * `from` carried when middleware rewrote it (`_rsc_rt`), as the browser
+   * does: the server then diffs against the route that rendered that page.
    */
   partial?:
     | true
     | {
         from?: string;
+        rewriteTarget?: string;
         segments?: readonly string[];
         prefetch?: boolean;
         fill?: boolean;
+        interceptSource?: string;
       };
   /**
    * POST this form as a submit before hydration: the no-JS request the
@@ -139,6 +148,8 @@ export interface ServeShellRequestAction {
   args?: readonly unknown[];
   /** The segment ids the page holds (`_rsc_segments`). */
   segments?: readonly string[];
+  /** The page's payload `metadata.rewriteTarget`, as for `partial`. */
+  rewriteTarget?: string;
 }
 
 /** A response's handle data, as the browser consumes it. */
@@ -157,6 +168,25 @@ export interface ShellRequestHandles {
   late: HandleData[];
 }
 
+/**
+ * An `action` request's answer, as browser/server-action-bridge.ts reads it.
+ */
+export interface ShellRequestAction {
+  /** False when the action threw: the call rejects with `result`. */
+  ok: boolean;
+  /** What the call resolves (or rejects) with. */
+  result: unknown;
+  /**
+   * The error of the first loader that threw while it re-ran in the action's
+   * revalidation, the value `useAction(action).revalidationError` reports.
+   * That loader throws at its `useLoader` read, where the nearest boundary
+   * catches it, and the call still resolves. `null` when every loader
+   * answered (a `notFound()` or `redirect()` is not an error), or `ok` is
+   * false, as `useAction` reports it.
+   */
+  revalidationError: Error | null;
+}
+
 /** Result of {@link serveShellRequest}. */
 export interface ServeShellRequestResult {
   /** The handler's Response. Its body is already read: see `body`. */
@@ -182,9 +212,12 @@ export interface ServeShellRequestResult {
    * The shell key production resolved for this request: for a document the
    * serve path read and captured (a MISS or a HIT), the key it used, request
    * partition included (a route partitioned by `cache({ key })` or the
-   * store's `keyGenerator`). Otherwise (a route without `ppr`, a request
-   * passed to axis 1 before its key was resolved, a partial request) the
-   * document URL's key without a partition, as `shellCacheKey` builds it.
+   * store's `keyGenerator`), and for a request middleware rewrote with
+   * `rewrite(...).shell("visitor")` the visitor's key, as
+   * `visitorShellCacheKey` builds it. Otherwise (a route without `ppr`, a
+   * request passed to axis 1 before its key was resolved, a rewritten
+   * request whose rewrite chose no shell, a partial request) the document
+   * URL's key without a partition, as `shellCacheKey` builds it.
    */
   key: string;
   /**
@@ -217,6 +250,13 @@ export interface ServeShellRequestResult {
    * hydrates without it.
    */
   readPayloadFormState(): Promise<unknown>;
+  /**
+   * For an `action` request, the call's answer as the browser reads it: its
+   * result and the `revalidationError` its loaders' reruns report.
+   * Undefined when no Flight was rendered or the payload carries no action
+   * result.
+   */
+  readAction(): Promise<ShellRequestAction | undefined>;
 }
 
 type ShellHandler = ReturnType<typeof createRSCHandler>;
@@ -352,6 +392,24 @@ async function decodePayloadHandles(
   };
 }
 
+/** An action payload's answer, read as the browser's action bridge reads it. */
+async function decodeAction(
+  flight: string,
+): Promise<ShellRequestAction | undefined> {
+  const { returnValue, metadata } = await decodePayload<{
+    returnValue?: { ok: boolean; data: unknown };
+    metadata?: { segments?: ResolvedSegment[] };
+  }>(flight);
+  if (!returnValue) return undefined;
+  return {
+    ok: returnValue.ok,
+    result: returnValue.data,
+    revalidationError:
+      (returnValue.ok && (await revalidationErrorOf(metadata?.segments))) ||
+      null,
+  };
+}
+
 /** The ids of the segments a payload marks deferred. */
 async function decodeDeferredIds(flight: string): Promise<string[]> {
   const { metadata } = await decodePayload<{
@@ -479,10 +537,7 @@ async function getHandler(
   const { resolveRouterVersions } =
     await import("../server/build-version-table.js");
   // What createRSCHandler would resolve for this router now.
-  const { document: versions } = resolveRouterVersions(
-    internal.id,
-    internal.version,
-  );
+  const { document: versions } = resolveRouterVersions(internal.id);
   const cached = byStore.get(cacheStore ?? router);
   if (cached?.versions === versions) return cached.handler;
 
@@ -522,6 +577,9 @@ async function buildActionRequest(
   const target = new URL(url);
   target.searchParams.set("_rsc_action", action.id);
   target.searchParams.set("_rsc_segments", (action.segments ?? []).join(","));
+  if (action.rewriteTarget) {
+    target.searchParams.set("_rsc_rt", action.rewriteTarget);
+  }
   headers.set("rsc-action", action.id);
   if (!headers.has("X-RSC-Router-Client-Path")) {
     headers.set("X-RSC-Router-Client-Path", url.href);
@@ -565,13 +623,16 @@ async function buildRequest(
   }
   const {
     from = "/",
+    rewriteTarget,
     segments = [],
     prefetch = false,
     fill = false,
+    interceptSource,
   } = partial === true ? {} : partial;
   const target = new URL(url);
   target.searchParams.set("_rsc_partial", "true");
   target.searchParams.set("_rsc_segments", segments.join(","));
+  if (rewriteTarget) target.searchParams.set("_rsc_rt", rewriteTarget);
   // As the browser sends them: browser/navigation-client.ts (fill) and
   // browser/prefetch/fetch.ts (prefetch).
   if (fill) target.searchParams.set(FILL_PARAM, "1");
@@ -581,6 +642,12 @@ async function buildRequest(
   if (!headers.has("X-RSC-Router-Client-Path")) {
     headers.set("X-RSC-Router-Client-Path", new URL(from, url).href);
   }
+  if (interceptSource !== undefined) {
+    headers.set(
+      "X-RSC-Router-Intercept-Source",
+      new URL(interceptSource, url).href,
+    );
+  }
   if (!headers.has(SEGMENT_FRAGMENT_CAPABILITY_HEADER)) {
     headers.set(SEGMENT_FRAGMENT_CAPABILITY_HEADER, "1");
   }
@@ -725,5 +792,8 @@ export async function serveShellRequest<TEnv = any>(
       }>(flight);
       return payload.formState;
     },
+    async readAction() {
+      return flight ? decodeAction(flight) : undefined;
+    },
   };
 }

package/src/testing/shell-status.ts

@@ -39,6 +39,7 @@ import {
   SHELL_STATUS_HEADER,
   buildShellKey,
   partitionShellKey,
+  visitorShellKey,
   type PprReplayBypassReason,
 } from "../rsc/shell-capture-constants.js";
 import {
@@ -119,6 +120,45 @@ export function shellCacheKey(
     resolved,
     compileSearchParamsFilter(searchParams),
   );
+  return withPartition(key, partition);
+}
+
+/**
+ * Shell store key of a request middleware rewrote with
+ * `throw rewrite(...).shell("visitor")`: the visitor's `url`, partitioned by
+ * the rewrite's `target` (its path and search), as production builds it
+ * (`visitorShellKey`, `rsc/shell-capture-constants.ts`). `searchParams` is
+ * the target route's `cache.searchParams` config, applied to the visitor's
+ * search; `partition` is the target route's own, as for
+ * {@link shellCacheKey}, composed after the target's.
+ *
+ * ```ts
+ * const hit = await serveShellRequest(router, "/summer", { cacheStore });
+ * expect(hit.key).toBe(visitorShellCacheKey(router, "/summer", "/item/1"));
+ * ```
+ */
+export function visitorShellCacheKey(
+  router: { readonly id: string },
+  url: URL | string,
+  target: URL | string,
+  searchParams?: CacheSearchParams,
+  partition?: string | readonly string[] | ShellCachePartition,
+): string {
+  const visitor =
+    typeof url === "string" ? new URL(url, "http://localhost") : url;
+  const key = visitorShellKey(
+    router.id,
+    visitor,
+    new URL(target, visitor),
+    compileSearchParamsFilter(searchParams),
+  );
+  return withPartition(key, partition);
+}
+
+function withPartition(
+  key: string,
+  partition: string | readonly string[] | ShellCachePartition | undefined,
+): string {
   if (partition === undefined) return key;
   const { keys = [], generated = [] }: ShellCachePartition =
     typeof partition === "string"

package/src/testing/vitest-stubs/version.ts

@@ -6,3 +6,4 @@
 // for a test that needs per-router versions.
 export const VERSION = "";
 export const ROUTER_VERSIONS: undefined = undefined;
+export const PACKAGE_VERSION = "0.0.0-test";

package/src/testing/vitest.ts

@@ -76,8 +76,10 @@
  *   a focused include, or use e2e.
  */
 
+import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { parseLang } from "../vite/plugins/hoist/literal.js";
 import {
   isUseCacheCandidate,
   transformUseCache,
@@ -156,6 +158,41 @@ const CLIENT_URLS_INSTALLER_PATH: string = here(
   "src/testing/internal/client-urls-projection.ts",
 ).replaceAll("\\", "/");
 
+/**
+ * Whether a clientUrls() source's import loads as source too: a
+ * `"use client"` module, or a barrel (imports and `export ... from` only).
+ * Vite loads lazily, as in the transform: this module must load where it is
+ * not installed (installed-vitest-config.test.ts).
+ */
+async function loadsAsSource(code: string, file: string): Promise<boolean> {
+  if (!code.includes("use client") && !code.includes("export")) return false;
+  const { parseAstAsync } = await import("vite");
+  const { hasDirective } = await import("@vitejs/plugin-rsc/transforms");
+  type Body = Parameters<typeof hasDirective>[0];
+  let body: Body;
+  try {
+    // The file as it is on disk, TypeScript included.
+    body = (
+      (await parseAstAsync(code, { lang: parseLang(file) })) as unknown as {
+        body: Body;
+      }
+    ).body;
+  } catch {
+    return false;
+  }
+  if (hasDirective(body, "use client")) return true;
+  const nodes = body as unknown as { type: string; source?: unknown }[];
+  return (
+    nodes.some((node) => node.type !== "ImportDeclaration") &&
+    nodes.every(
+      (node) =>
+        node.type === "ImportDeclaration" ||
+        node.type === "ExportAllDeclaration" ||
+        (node.type === "ExportNamedDeclaration" && node.source != null),
+    )
+  );
+}
+
 /**
  * Appended to a transformed `"use client"` clientUrls() module: install the
  * projection of its own source under its default export's reference id
@@ -270,11 +307,24 @@ export function rangoTestConfig(
 }
 
 /** A minimal Vite plugin shape (avoids a hard dependency on Vite's types). */
+/** The part of a Vite plugin context {@link rangoUseClientTransform} resolves with. */
+interface SourceResolveContext {
+  resolve(
+    source: string,
+    importer?: string,
+    options?: { skipSelf?: boolean },
+  ): Promise<{ id: string; external?: boolean | string } | null>;
+}
+
 interface FlightTransformPlugin {
   name: string;
   resolveId: {
     order: "pre";
-    handler(source: string, importer: string | undefined): string | undefined;
+    handler(
+      this: SourceResolveContext,
+      source: string,
+      importer: string | undefined,
+    ): Promise<string | undefined>;
   };
   transform(
     code: string,
@@ -347,19 +397,36 @@ export function rangoUseClientTransform(): FlightTransformPlugin {
     resolveId: {
       // Before Vite's resolver, which resolves the bare specifier first.
       order: "pre",
-      handler(source, importer) {
+      async handler(source, importer) {
+        if (!importer?.includes(CLIENT_URLS_SOURCE_QUERY)) return undefined;
         // 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.
+        // same clientUrls and helpers.
+        if (source === "@rangojs/router/client") return CLIENT_ENTRY_RSC_PATH;
+        // Its "use client" project imports load as source too, as the app's
+        // SSR copy runs them: a component's `.use` and its name are
+        // unreadable on a client reference. So do the barrels between them,
+        // which hold no state; any other module stays one shared instance.
+        const resolved = await this.resolve(source, importer, {
+          skipSelf: true,
+        });
+        if (!resolved || resolved.external) return undefined;
+        const { id } = resolved;
+        const file = id.split("?", 1)[0]!;
         if (
-          source === "@rangojs/router/client" &&
-          importer?.includes(CLIENT_URLS_SOURCE_QUERY)
+          id.startsWith("\0") ||
+          id.includes("/node_modules/") ||
+          id.includes(CLIENT_URLS_SOURCE_QUERY) ||
+          !/\.[cm]?[jt]sx?$/.test(file)
         ) {
-          return CLIENT_ENTRY_RSC_PATH;
+          return undefined;
         }
-        return undefined;
+        const code = await readFile(file, "utf-8").catch(() => "");
+        return (await loadsAsSource(code, file))
+          ? `${id}${id.includes("?") ? "&" : "?"}${CLIENT_URLS_SOURCE_QUERY}`
+          : undefined;
       },
     },
     async transform(code, id) {

package/src/thenable-status.ts

@@ -24,14 +24,3 @@ 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/handler-context.ts

@@ -89,7 +89,13 @@ type AutofillSearchFromEntry<TMap, TKey> = TKey extends keyof TMap
     : Record<string, unknown>
   : Record<string, unknown>;
 
-type AutofillAwareReverseFunction<TLocalRoutes, TGlobalRoutes> =
+/**
+ * `ScopedReverseFunction` whose global-name params are optional: the runtime
+ * fills missing ones from the matched route's params (`createReverseFunction`
+ * in `router/handler-context.ts`, explicit params win). Shared by handler,
+ * loader and request-context `reverse`.
+ */
+export type AutofillAwareReverseFunction<TLocalRoutes, TGlobalRoutes> =
   ScopedReverseFunction<TLocalRoutes, TGlobalRoutes> & {
     <TName extends keyof TGlobalRoutes & string>(
       name: TName,
@@ -449,6 +455,11 @@ export type InternalHandlerContext<
   _responseType?: string;
   /** Route name for cache key scoping (prevents cross-route collisions). */
   _routeName?: string;
+  /**
+   * The segment's ReverseScope on a layout's / parallel's ctx and its
+   * loaders' (withReverseScope): keys a "use cache" call taking the ctx.
+   */
+  _reverseScope?: import("../server/context.js").ReverseScope;
   /**
    * @internal The on-demand overlay holds a "removed" marker for this request
    * (tryPrerenderLookup, cache-lookup.ts); gateOnDemandProducer reads it. On

package/src/types/loader-types.ts

@@ -2,7 +2,7 @@ import type { ContextVar } from "../context-var.js";
 import type { Handle } from "../handle.js";
 import type { HandlePush } from "../defer.js";
 import type { MiddlewareFn } from "../router/middleware.js";
-import type { ScopedReverseFunction } from "../reverse.js";
+import type { AutofillAwareReverseFunction } from "./handler-context.js";
 import type { SearchSchema, ResolveSearchSchema } from "../search-params.js";
 import type { UseItems, LoaderUseItem } from "../route-types.js";
 import type {
@@ -134,9 +134,10 @@ export type LoaderContext<
   /**
    * Generate URLs from route names.
    * Same scoped reverse as route handlers — `.name` resolves within the
-   * current include() scope, `name` resolves globally.
+   * current include() scope, `name` resolves globally, and params the matched
+   * route already carries (e.g. include() mount params) are filled in.
    */
-  reverse: ScopedReverseFunction<
+  reverse: AutofillAwareReverseFunction<
     Record<string, string>,
     DefaultReverseRouteMap
   >;
@@ -188,7 +189,12 @@ export type LoaderFn<
  * deterministically precedes Response construction, where the streamed
  * default only wins that race opportunistically). Under ppr it is also the
  * BAKE lane: the loader executes at shell capture and its settled return is
- * shell material (nested promises stay live holes) — see the ppr docs.
+ * shell material (nested promises stay live holes), and so are its handle
+ * pushes, a pushed promise or `.defer()` included: the capture awaits it and
+ * every HIT serves the value it settled to (#1182). A pushed promise that
+ * rejects, or misses `ppr.captureTimeout`, keeps the route on MISS. A value
+ * that must stay per request belongs to a loader without `ssr: false` — see
+ * the ppr docs.
  *
  * Scoped per LOADER, not per segment: an `ssr: false` loader alongside a
  * deliberately streaming sibling awaits only itself, and the sibling keeps

package/src/types/route-entry.ts

@@ -1,7 +1,8 @@
 import type { AllUseItems } from "../route-types.js";
+import type { IncludeScopePosition } from "../server/context.js";
 import type { TrailingSlashMode, ResolvedRouteMap } from "./route-config.js";
 
-export interface LazyIncludeContext {
+export interface LazyIncludeContext extends IncludeScopePosition {
   urlPrefix: string;
   namePrefix: string | undefined;
   parent: unknown; // EntryData - avoid circular import

package/src/urls/include-helper.ts

@@ -3,6 +3,7 @@ import {
   getUrlPrefix,
   getNamePrefix,
   requireDslContext,
+  type IncludeScopePosition,
 } from "../server/context";
 import {
   INTERNAL_INCLUDE_SCOPE_PREFIX,
@@ -21,13 +22,32 @@ function hasExplicitNameOption(options: IncludeOptions | undefined): boolean {
   return !!options && Object.prototype.hasOwnProperty.call(options, "name");
 }
 
-function allocateInternalIncludeScopeId(
+/**
+ * This include's index among the includes its handler run has called. The
+ * counter is keyed by the run's scopePath, which no ancestor run's counter
+ * snapshot holds, so every run counts from 0 in every realm (build discovery,
+ * runtime expansion, render-time manifest).
+ */
+function nextIncludePosition(
   counters: Record<string, number>,
-): string {
-  const key = "__include_scope__";
+  scopePath: string | undefined,
+): number {
+  const key = `__include_position__:${scopePath ?? ""}`;
   const index = counters[key] ?? 0;
   counters[key] = index + 1;
-  return `${INTERNAL_INCLUDE_SCOPE_PREFIX}${index}`;
+  return index;
+}
+
+function joinScopePath(parent: string | undefined, index: number): string {
+  return parent ? `${parent}_${index}` : `${index}`;
+}
+
+function joinNames(
+  prefix: string | undefined,
+  segment: string | undefined,
+): string | undefined {
+  if (!segment) return prefix;
+  return prefix ? `${prefix}.${segment}` : segment;
 }
 
 /**
@@ -100,15 +120,20 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
         ? capturedUrlPrefix + prefix.slice(1)
         : capturedUrlPrefix + prefix
       : prefix;
+    // Route names are a pure function of the route tree: an unnamed include's
+    // hidden segment is its position path since the nearest include that added
+    // a name segment (a transparent { name: "" } adds none), e.g. `$prefix_1_0`.
+    const index = nextIncludePosition(ctx.counters, ctx.scopePath);
+    const hiddenSoFar = joinScopePath(ctx.hiddenScopePath, index);
     const nextSegment = hasExplicitName
       ? explicitName
-      : allocateInternalIncludeScopeId(ctx.counters);
-    const fullNamePrefix =
-      nextSegment !== undefined && nextSegment !== ""
-        ? capturedNamePrefix
-          ? `${capturedNamePrefix}.${nextSegment}`
-          : nextSegment
-        : capturedNamePrefix;
+      : `${INTERNAL_INCLUDE_SCOPE_PREFIX}${hiddenSoFar}`;
+    const fullNamePrefix = joinNames(capturedNamePrefix, nextSegment);
+    const position: IncludeScopePosition = {
+      scopePath: joinScopePath(ctx.scopePath, index),
+      // A name segment restarts the hidden path for this include's children.
+      hiddenScopePath: nextSegment ? "" : hiddenSoFar,
+    };
 
     // Track this include for build-time manifest generation
     if (ctx.trackedIncludes) {
@@ -118,6 +143,7 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
         namePrefix: fullNamePrefix,
         patterns,
         lazy: true,
+        ...position,
       });
     }
 
@@ -171,6 +197,7 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
         rootScoped: capturedRootScoped,
         routerId: ctx.routerId,
         includeScope,
+        ...position,
       },
     } as IncludeItem;
   };

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

@@ -346,9 +346,11 @@ export type PathHelpers<TEnv> = {
   };
 
   /**
-   * Control when a segment should revalidate during navigation
+   * Control when a segment should revalidate during navigation.
+   * `revalidate(true)` / `revalidate(false)` are shorthand for
+   * `revalidate(() => true)` / `revalidate(() => false)`.
    */
-  revalidate: (fn: ShouldRevalidateFn<any, TEnv>) => RevalidateItem;
+  revalidate: (fn: ShouldRevalidateFn<any, TEnv> | boolean) => RevalidateItem;
 
   /**
    * Attach a data loader to the current route/layout.