@rangojs/router 0.24.4 → 0.26.0

package/src/ssr/ssr-root.tsx

@@ -16,9 +16,10 @@ import type { NavigationStoreContextValue } from "../browser/react/context.js";
 import type { HandleData } from "../browser/types.js";
 import type { ResolvedSegment } from "../types.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
-import type {
-  EventController,
-  DerivedNavigationState,
+import {
+  DEFAULT_ACTION_STATE,
+  type EventController,
+  type DerivedNavigationState,
 } from "../browser/event-controller.js";
 
 /**
@@ -111,16 +112,11 @@ function createSsrEventController(opts: {
     getState: () => state,
     getLocation: () => location,
     subscribe: () => () => {},
-    getActionState: () => ({
-      state: "idle",
-      actionId: null,
-      payload: null,
-      error: null,
-      result: null,
-    }),
+    getActionState: () => DEFAULT_ACTION_STATE,
     subscribeToAction: () => () => {},
     subscribeToHandles: () => () => {},
     flushRouteState: () => {},
+    releaseRouteState: () => {},
     setHandleData: () => {},
     getHandleState: () => handleState,
     lockHydration: () => {},

package/src/testing/build-versions.ts

@@ -35,9 +35,6 @@ export interface BuildVersions extends RouterVersions {
  * Install the cache versions of a simulated build, or remove them with no
  * argument (routers serve unversioned again, the default in tests).
  *
- * A router that sets `createRouter({ version })` keeps that value for both
- * versions, exactly as in production.
- *
  * @example A deploy that changes the client only keeps cached data
  * ```ts
  * setBuildVersions({ data: "d1", document: "h1" });

package/src/testing/dispatch.ts

@@ -129,7 +129,7 @@ import type { CacheProfile } from "../cache/profile-registry.js";
 // onto the whole testing barrel's eager graph and break every consumer suite
 // that imports `@rangojs/router/testing` without mocking plugin-rsc.
 import type { EntryData } from "../server/context.js";
-import { setRouterManifest } from "../route-map-builder.js";
+import { ensureRouterTrie } from "../rsc/manifest-init.js";
 import { RESPONSE_TYPE_MIME } from "../router/content-negotiation.js";
 import { RouterError } from "../errors.js";
 import { createProblemDetails } from "../rsc/response-error.js";
@@ -167,9 +167,9 @@ import { applyStreamIdleTimeout } from "../rsc/stream-idle.js";
 interface DispatchableRouter<TEnv> {
   id?: string;
   routerId?: string;
-  /** createRouter({ version }), the consumer-set version. */
-  version?: string;
   routeMap: Record<string, unknown>;
+  /** The routes() patterns the dev trie is rebuilt from (rsc/manifest-init.ts). */
+  urlpatterns?: unknown;
   middleware: MiddlewareEntry<TEnv>[];
   onError?: OnErrorCallback<TEnv>;
   /**
@@ -409,11 +409,8 @@ export async function dispatch<TEnv = any>(
   const url = new URL(req.url);
   const env = (opts.env ?? {}) as TEnv;
 
-  // Seed the per-router manifest so reverse() resolves during handler execution.
   const routerId = router.id ?? router.routerId;
-  if (routerId) {
-    setRouterManifest(routerId, router.routeMap as Record<string, string>);
-  }
+  await ensureRouterTrie(router);
 
   // The visitor's URL is matched before any middleware runs, so an RSC route
   // fails here, before a middleware side effect. A rewrite target is matched
@@ -449,7 +446,7 @@ export async function dispatch<TEnv = any>(
     cacheProfiles: router.cacheProfiles,
     // The store keys with the router's versions, resolved as the production
     // handler resolves them (rsc/handler.ts).
-    versions: resolveRouterVersions(routerId, router.version),
+    versions: resolveRouterVersions(routerId),
   });
   // Wire background error reporting so cache degradation (reportCacheError ->
   // _reportBackgroundError) reaches the router's onError, mirroring the production

package/src/testing/e2e/index.ts

@@ -51,6 +51,7 @@ export {
   PPR_REPLAY_STATUS_HEADER,
   shellCacheKey,
   SHELL_STATUS_HEADER,
+  visitorShellCacheKey,
   type PprReplayBypassReason,
   type PprReplayStatus,
   type ShellCachePartition,

package/src/testing/flight.entry.ts

@@ -67,5 +67,6 @@ export type {
   ServeShellRequestAction,
   ServeShellRequestOptions,
   ServeShellRequestResult,
+  ShellRequestAction,
   ShellRequestHandles,
 } from "./serve-shell-request.js";

package/src/testing/index.ts

@@ -112,6 +112,7 @@ export {
   PPR_REPLAY_STATUS_HEADER,
   shellCacheKey,
   SHELL_STATUS_HEADER,
+  visitorShellCacheKey,
 } from "./shell-status.js";
 export type {
   PprReplayBypassReason,

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

@@ -19,9 +19,10 @@ import type { ShouldRevalidateFn } from "../../types.js";
  *
  * 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.
+ * its reference, route or intercept, 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. A
+ * boolean rides in the projection as itself, as the plugin leaves a literal.
  */
 export function installClientUrlsProjection(
   referenceId: string,
@@ -50,21 +51,40 @@ function withRevalidateKeys(
   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(
+  // A route's or an intercept's loaders, keyed under `owner`.
+  const withKeys = <T extends object>(
+    projected: T,
+    owner: string,
+    loaders: ClientUrlPatterns["routes"][number]["loaders"] | undefined,
+  ): T => {
+    const loaderRevalidate = (loaders ?? []).map(
       ({ revalidate }, loaderIndex) =>
         revalidate.map((entry, index) => {
           if (isHoistedRevalidateRef(entry)) return entry.$$rangoRevalidate;
-          const key = `${referenceId}:${route.id}:${loaderIndex}:${index}`;
+          if (typeof entry === "boolean") return entry;
+          const key = `${referenceId}:${owner}:${loaderIndex}:${index}`;
           fns[key] = entry;
           return key;
         }),
     );
     return loaderRevalidate.some((keys) => keys.length > 0)
-      ? { ...route, loaderRevalidate }
-      : route;
-  });
+      ? { ...projected, loaderRevalidate }
+      : projected;
+  };
+  const routes = projection.routes.map((route) =>
+    withKeys(
+      route,
+      route.id,
+      definition.routes.find(({ id }) => id === route.id)?.loaders,
+    ),
+  );
+  const intercepts = projection.intercepts?.map((intercept, index) =>
+    withKeys(
+      intercept,
+      `intercept${index}`,
+      definition.intercepts[index]?.loaders,
+    ),
+  );
   registerClientUrlRevalidators(fns);
-  return { ...projection, routes };
+  return { ...projection, routes, ...(intercepts && { intercepts }) };
 }

package/src/testing/internal/seed-vars.ts

@@ -23,10 +23,10 @@ export interface StateCookieSeed {
    */
   routerId?: string;
   /**
-   * The app's version, as `createRouter({ version })` would set it: the
-   * rotated value's prefix (`{version}:{timestamp}`) and the version a cache
-   * store keys with. Defaults to `"0"` for the prefix (resolved inside
-   * createRequestContext) and to the build versions for the store.
+   * The app's version: the rotated value's prefix (`{version}:{timestamp}`)
+   * and the request's cache versions, which a store keys with. Defaults to
+   * `"0"` for the prefix (resolved inside createRequestContext) and to the
+   * build versions for the store.
    */
   version?: string;
 }

package/src/testing/render-route.tsx

@@ -23,13 +23,16 @@
  *     SEEDED directly into client context (see the `loaders` / `locationState` /
  *     `handles` / `outletPending` options) — nothing is executed on the server.
  *     This exercises the context read path, not the run path.
- *   - navigate() does NOT drive the navigation lifecycle: useNavigation().state,
- *     useLinkStatus().pending, and useAction().state stay "idle". Assert
- *     pending/loading/submitting transition states with renderServerTree / e2e
- *     instead (navigate() warns once if used). The one pending state it does
- *     model is the held-navigation useLoader().isLoading: a `transition` spec
- *     plus a pending Promise seeded via navigate(url, { loaders }) commits
- *     through production's commitInTransition (browser/partial-update.ts).
+ *   - navigate() drives the navigation lifecycle as a click does:
+ *     useNavigation() reads loading from the call and idle with the commit,
+ *     and useLinkStatus().pending is true for a link to the destination until
+ *     the commit is handed to React. A `transition` spec plus a pending
+ *     Promise seeded via navigate(url, { loaders }) commits through
+ *     production's commitInTransition (browser/partial-update.ts), which React
+ *     holds: useNavigation() stays loading and the held reader's
+ *     useLoader().isLoading reads true until the data lands. Without
+ *     `transition` the commit is urgent (production's same-structure hold is
+ *     not modeled). useAction().state stays idle: no action runs.
  *   - A spec's transition({ when }) decides every commit with production's
  *     browser decision: navigate() and useRouter().push model kind "push",
  *     useRouter().replace kind "replace", refresh() kind "revalidate".
@@ -81,7 +84,10 @@ import type {
   NavigationBridge,
   UpdateSubscriber,
 } from "../browser/types.js";
-import type { EventController } from "../browser/event-controller.js";
+import type {
+  EventController,
+  NavigationHandle,
+} from "../browser/event-controller.js";
 import type { ResolvedSegment, RscMetadata } from "../browser/types.js";
 import { NavigationProvider } from "../browser/react/NavigationProvider.js";
 import {
@@ -407,9 +413,10 @@ export interface TestRouterHandle {
    * pending Promise suspends the read like a streaming Flight chunk. When a
    * spec in the chain has `transition`, the commit goes through production's
    * commitInTransition: the reader stays on screen with
-   * `useLoader().isLoading === true` until the promise settles. Settle it
-   * inside RTL's `act()` to flush the commit. Without `transition` the commit
-   * is urgent and the read suspends to the nearest Suspense boundary.
+   * `useLoader().isLoading === true`, and `useNavigation().state` reads
+   * "loading", until the promise settles. Settle it inside RTL's `act()` to
+   * flush the commit. Without `transition` the commit is urgent and the read
+   * suspends to the nearest Suspense boundary.
    *
    * @example
    * await router.navigate("/products/2", { loaders: [[ProductLoader, next]] });
@@ -429,10 +436,16 @@ export interface TestRouterHandle {
    * location state as a production replace does). With neither, history is
    * left alone and readers keep the state they have: `navigate(url)` and
    * `navigate(url, { replace: false })` are the same call.
+   *
+   * `options.handles` are the destination's handle pushes (`[handle,
+   * values]`, attached to its leaf route as in `renderRoute`'s own
+   * `handles`). They arrive on the response's handle stream, so `useHandle`
+   * readers take them with the page's commit: while React holds the page,
+   * readers keep the values of the page being left.
    */
   navigate(
     url: string,
-    options?: Pick<RenderRouteOptions, "loaders"> &
+    options?: Pick<RenderRouteOptions, "loaders" | "handles"> &
       Pick<NavigateOptions, "state" | "replace" | "transition">,
   ): Promise<void>;
   /**
@@ -791,17 +804,36 @@ export async function renderRoute(
     };
   }
 
-  let warnedNavLifecycle = false;
+  type NavigateCall = Pick<RenderRouteOptions, "loaders" | "handles"> & {
+    history?: Pick<NavigateOptionsInternal, "state" | "replace" | "transition">;
+    kind?: TransitionWhenKind;
+    transition?: boolean;
+  };
+  // The navigation's lifecycle, as navigation-transaction.ts drives it:
+  // useNavigation() reads loading from the call, delivered before the commit
+  // as a click's notification goes out while its response is in flight, and
+  // idle with the location at the commit, which React may hold.
   const navigate = async (
     target: string,
-    navOptions?: Pick<RenderRouteOptions, "loaders"> & {
-      history?: Pick<
-        NavigateOptionsInternal,
-        "state" | "replace" | "transition"
-      >;
-      kind?: TransitionWhenKind;
-      transition?: boolean;
-    },
+    navOptions?: NavigateCall,
+  ): Promise<void> => {
+    const handle = eventController.startNavigation(
+      new URL(target, TEST_ORIGIN).href,
+    );
+    // Synchronous, in the caller's task: a <Link> click's own act() scope
+    // takes it, and no act() of the caller's can overlap it.
+    act(() => eventController.flushRouteState());
+    try {
+      await commitNavigation(handle, target, navOptions);
+    } finally {
+      // Back to idle when the commit never came (a render that threw).
+      handle[Symbol.dispose]();
+    }
+  };
+  const commitNavigation = async (
+    handle: NavigationHandle,
+    target: string,
+    navOptions?: NavigateCall,
   ): Promise<void> => {
     // A useRouter().push/replace or <Link> navigation (`history`) writes its
     // entry the way production does (navigation-bridge.ts navigate ->
@@ -819,21 +851,6 @@ export async function renderRoute(
             : undefined,
         )
       : undefined;
-    // No server fetch, so the navigation lifecycle never starts: the state
-    // useNavigation()/useLinkStatus()/useAction() read stays "idle" — asserting
-    // a pending/loading/submitting state here proves nothing. Warn once (per
-    // render) under the test runner so that false-confidence trap is loud.
-    if (isUnderTestRunner() && !warnedNavLifecycle) {
-      warnedNavLifecycle = true;
-      console.warn(
-        "renderRoute: navigate()/useRouter().push do NOT drive the navigation " +
-          "lifecycle. useNavigation().state, useLinkStatus().pending, and " +
-          'useAction().state stay "idle" here. Assert params/pathname/content ' +
-          "after navigate(); use renderServerTree or e2e to assert " +
-          "pending/loading/submitting transition states. A held " +
-          "useLoader().isLoading is modeled: see navigate(url, { loaders }).",
-      );
-    }
     const nextUrl = new URL(target, TEST_ORIGIN);
     const match = resolve(nextUrl.pathname);
     const segments = buildSegments(
@@ -843,6 +860,23 @@ export async function renderRoute(
       mount,
     );
     const metadata = makeMetadata(nextUrl.pathname, segments, match.params);
+    // The destination's handle pushes arrive on the response's handle
+    // stream, as production's do, behind the page's commit.
+    const navHandles = navOptions?.handles;
+    if (navHandles) {
+      const leafId =
+        [...segments].reverse().find((s) => s.type === "route")?.id ??
+        segments[segments.length - 1]?.id;
+      const pushed: HandleDataSeed = {};
+      for (const [h, values] of navHandles) {
+        if (leafId === undefined) continue;
+        const id = (h as unknown as { $$id: string }).$$id;
+        (pushed[id] ??= {})[leafId] = values;
+      }
+      metadata.handles = (async function* () {
+        yield pushed;
+      })();
+    }
     // Production's browser-run transition({ when }) decision
     // (browser/partial-update.ts): the committed location is the source.
     const kind: TransitionWhenKind =
@@ -872,7 +906,10 @@ export async function renderRoute(
       outletPending: options.outletPending,
       transitionGatedOff: gatedOff,
     });
-    eventController.setLocation(nextUrl);
+    // A newer navigate() started meanwhile: this one commits nothing, as
+    // production's (browser/partial-update.ts) returns on its aborted signal.
+    if (handle.signal.aborted) return;
+    handle.complete(nextUrl);
     eventController.setParams(match.params);
     store.setCurrentUrl(nextUrl.href);
     store.setSegmentIds(segments.map((s) => s.id));
@@ -892,9 +929,14 @@ export async function renderRoute(
       // same-structure / fully-prefetched / optimistic hold lanes are not
       // modeled: without transition() the commit stays urgent.
       if (shouldStartViewTransition(segments, gatedOff)) {
-        commitInTransition(store.loaders, emit, segments, { root, metadata }, [
-          "navigation",
-        ]);
+        commitInTransition(
+          store.loaders,
+          emit,
+          segments,
+          { root, metadata },
+          kind,
+          ["navigation"],
+        );
       } else {
         emit({ root, metadata });
       }
@@ -1024,6 +1066,7 @@ export async function renderRoute(
     navigate: (target, navOptions) =>
       navigate(target, {
         loaders: navOptions?.loaders,
+        handles: navOptions?.handles,
         transition: navOptions?.transition,
         history:
           navOptions?.state !== undefined || navOptions?.replace

package/src/testing/run-loader.ts

@@ -39,6 +39,7 @@ import {
   type RequestContext,
 } from "../server/request-context.js";
 import { createReverseFunction } from "../router/handler-context.js";
+import { scopeReverse, type ReverseScope } from "../server/context.js";
 import { NOCACHE_SYMBOL } from "../cache/taint.js";
 import { defineRewrittenFrom } from "../server/rewrite-trail.js";
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
@@ -134,6 +135,13 @@ export interface RunLoaderOptions<TEnv = any> {
   routeMap?: Record<string, string>;
   /** Matched route name for scoped `.name` reverse resolution. */
   routeName?: string;
+  /**
+   * Include name prefix of the module whose `layout()` / `parallel()` /
+   * `cache()` declares the loader (`"account"`, or `""` for the root module).
+   * `ctx.reverse(".name")` then resolves in that module, as such a loader's
+   * does in production, instead of from `routeName`.
+   */
+  declaredIn?: string;
   /** HTTP method surfaced as `ctx.method`. Defaults to "GET". */
   method?: string;
   /** Request body surfaced as `ctx.body`. */
@@ -279,9 +287,21 @@ function runWithLoaderContext<R>(
   const loaderSeeds = new Map<unknown, unknown>(opts.loaders ?? []);
   let renderedResolved = false;
 
+  // A layout's / parallel's loader: `.name` resolves in its declaring module.
+  const reverseScope: ReverseScope | undefined =
+    opts.declaredIn === undefined
+      ? undefined
+      : { prefix: opts.declaredIn || undefined, rootScoped: !opts.declaredIn };
   return runWithRequestContext(reqCtx, () => {
     const reverse = opts.routeMap
-      ? createReverseFunction(opts.routeMap, opts.routeName, opts.params ?? {})
+      ? scopeReverse(
+          createReverseFunction(
+            opts.routeMap,
+            opts.routeName,
+            opts.params ?? {},
+          ),
+          reverseScope,
+        )
       : ((() => {
           throw new Error(
             "ctx.reverse() requires the `routeMap` option in runLoader(). " +
@@ -289,7 +309,10 @@ function runWithLoaderContext<R>(
           );
         }) as TestLoaderContext["reverse"]);
 
-    const loaderCtx: TestLoaderContext & { _routeName?: string } = {
+    const loaderCtx: TestLoaderContext & {
+      _routeName?: string;
+      _reverseScope?: ReverseScope;
+    } = {
       params: opts.params ?? {},
       routeParams: (opts.params ?? {}) as Record<string, string>,
       request: reqCtx.request,
@@ -346,6 +369,7 @@ function runWithLoaderContext<R>(
       formData: opts.formData,
       reverse: reverse as TestLoaderContext["reverse"],
       _routeName: reqCtx._routeName,
+      _reverseScope: reverseScope,
       rendered:
         opts.rendered !== undefined && opts.rendered !== false
           ? async () => {

package/src/testing/run-middleware.ts

@@ -106,6 +106,13 @@ export interface RunMiddlewareRewrite {
   pathname: string;
   search: string;
   routeName?: string;
+  /**
+   * Present, `true`, only when the rewrite was thrown with
+   * `.disallowMutations()`: production refuses it for a non-GET, non-HEAD
+   * request in global middleware, before the action runs, instead of moving
+   * the mutation to the target.
+   */
+  mutationsDisallowed?: true;
 }
 
 /**
@@ -240,6 +247,9 @@ export async function runMiddleware<TEnv = any>(
         pathname: target.pathname,
         search: target.search,
         ...("name" in error.target && { routeName: error.target.name }),
+        ...(error.mutationsDisallowed && {
+          mutationsDisallowed: true as const,
+        }),
       };
       return new Response(null, {
         status: ctx.res.status,

package/src/testing/run-revalidate.ts

@@ -10,7 +10,10 @@
  * a re-implementation. Pass an array to test a chain in declaration order.
  */
 
-import { evaluateRevalidation } from "../router/revalidation.js";
+import {
+  evaluateRevalidation,
+  toShouldRevalidateFn,
+} from "../router/revalidation.js";
 import { runWithRequestContext } from "../server/request-context.js";
 import type { ResolvedSegment, ShouldRevalidateFn } from "../types.js";
 import {
@@ -81,12 +84,16 @@ export interface RunRevalidateOptions<TEnv = any> {
 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.
+ * Run one revalidate() argument, or a chain in declaration order, the way
+ * the router does for a request: a predicate, or `true` / `false` as
+ * `revalidate()` takes them. 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>[],
+  fn:
+    | ShouldRevalidateFn<any, TEnv>
+    | boolean
+    | readonly (ShouldRevalidateFn<any, TEnv> | boolean)[],
   opts: RunRevalidateOptions<TEnv> = {},
 ): Promise<boolean> {
   const currentUrl = toURL(opts.currentUrl, new URL(DEFAULT_URL));
@@ -124,7 +131,7 @@ export async function runRevalidate<TEnv = any>(
       nextUrl,
       revalidations: fns.map((entry, index) => ({
         name: `runRevalidate#${index}`,
-        fn: entry,
+        fn: toShouldRevalidateFn(entry),
       })),
       routeKey: opts.routeName ?? "",
       context: (opts.context ?? ctx) as RevalidateArgs["context"],