@rangojs/router 0.27.0 → 0.29.0

package/src/testing/e2e/page-helpers.ts

@@ -4,6 +4,7 @@
 
 import type { ConsoleMessage, Expect, Locator, Page } from "@playwright/test";
 import { PREFETCH_HEADER } from "../../prefetch-markers.js";
+import { WIRE } from "../../wire-params.js";
 
 // ============================================================================
 //  Standalone helpers (need only a page/locator)
@@ -177,8 +178,7 @@ export function isPrefetchRequest(req: {
 
 // Module-level matcher + handler so blockPrefetch/unblockPrefetch share
 // stable references — Playwright's unroute matches by identity.
-const rscPartialUrl = (url: URL): boolean =>
-  url.searchParams.has("_rsc_partial");
+const rscPartialUrl = (url: URL): boolean => url.searchParams.has(WIRE.partial);
 async function abortPrefetchRoute(
   route: import("@playwright/test").Route,
 ): Promise<void> {

package/src/testing/render-route.tsx

@@ -26,24 +26,30 @@
  *   - 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
+ *     the commit, which React holds with it. 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.
+ *     not modeled). navigate(url, { streamUntil }) gives the navigation a
+ *     response stream that stays open past the commit (isStreaming).
+ *     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".
- *     Back/forward, action and optimistic clientUrls() swap decisions are
- *     e2e territory.
+ *     useRouter().replace kind "replace", refresh() kind "revalidate", and a
+ *     back/forward that restores a page kind "pop". Action and optimistic
+ *     clientUrls() swap decisions are e2e territory.
  *   - Location state reaches readers the way it does in production:
  *     NavigationProvider holds the committed entry's state next to the
  *     payload, so a navigation whose loader the test holds keeps the entry
  *     being left on screen with its own state. A `popstate` event is a
- *     back/forward onto the entry history.state holds; the tree has one
- *     location, so no page is restored with it. A server action's state, a
+ *     back/forward onto the entry history.state holds. When it is the
+ *     mounted entry or one a navigate() wrote, history still holds the state
+ *     written there, and another page is on screen, its page is restored
+ *     from the history cache, with the handle values it had, as production's
+ *     restore is; otherwise the tree keeps its location. A stale entry's
+ *     revalidation, a restore that fetches, a server action's state, a
  *     redirect's and an intercept's are e2e territory.
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
@@ -61,6 +67,7 @@
 import { decideTransitionGatedOff } from "../browser/transition-when.js";
 import {
   StrictMode,
+  startTransition,
   useEffect,
   type ReactNode,
   type ComponentType,
@@ -78,10 +85,12 @@ import {
   shouldStartViewTransition,
 } from "../browser/partial-update.js";
 import type {
+  HandleData,
   NavigateOptions,
   NavigateOptionsInternal,
   NavigationStore,
   NavigationBridge,
+  NavigationUpdate,
   UpdateSubscriber,
 } from "../browser/types.js";
 import type {
@@ -101,6 +110,7 @@ import type {
   TransitionWhenKind,
 } from "../types.js";
 import {
+  setCurrentHistoryStateListener,
   setLocationStateVersion,
   type LocationStateDefinition,
 } from "../browser/react/location-state-shared.js";
@@ -447,11 +457,40 @@ export interface TestRouterHandle {
    * `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.
+   *
+   * `options.streamUntil` gives the navigation a response stream, as a real
+   * response has: it opens in a task after the call, before the commit (the
+   * response arrives, and `useNavigation().pendingUrl` clears), and stays open
+   * until the promise settles (a page that streams a tail past its commit:
+   * `isStreaming` reads true until then). Without it the navigation has no
+   * stream. A navigation that a newer one or a back/forward aborts before its
+   * response arrives opens none and commits nothing; one aborted after its
+   * response arrived stops counting as streaming at the abort, as in
+   * production, where its response streams on and is ignored.
+   *
+   * @example
+   * const tail = deferred();
+   * await router.navigate("/products/2", { streamUntil: tail.promise });
+   * // useNavigation(): idle, isStreaming true
+   * await act(async () => tail.resolve());
+   * // useNavigation(): idle, isStreaming false
+   *
+   * A navigation started while React holds a page goes inside
+   * `await act(async () => ...)`. Its first update makes React retry the held
+   * page, which suspends again; a synchronous act() scope drops that retry
+   * and React renders no later update of the same priority.
+   *
+   * @example
+   * await act(async () => {
+   *   await router.navigate("/products/3", { transition: false });
+   * });
    */
   navigate(
     url: string,
     options?: Pick<RenderRouteOptions, "loaders" | "handles"> &
-      Pick<NavigateOptions, "state" | "replace" | "transition">,
+      Pick<NavigateOptions, "state" | "replace" | "transition"> & {
+        streamUntil?: Promise<unknown>;
+      },
   ): Promise<void>;
   /**
    * Re-render the current location, as router.refresh() does: a spec's
@@ -821,7 +860,49 @@ export async function renderRoute(
     history?: Pick<NavigateOptionsInternal, "state" | "replace" | "transition">;
     kind?: TransitionWhenKind;
     transition?: boolean;
+    streamUntil?: Promise<unknown>;
   };
+
+  // The page each history entry shows, by the entry's `idx` stamp (the
+  // seeded entry has none: 0), so a back/forward can restore it as
+  // production restores a history-cache entry. `state` is the entry's
+  // history state as the router last wrote it: an entry the test wrote over
+  // it (no `idx` reads as 0) is not that page. `handleData` is the page's
+  // pushes, taken when it is left.
+  interface EntryPage {
+    url: URL;
+    segments: ResolvedSegment[];
+    params: Record<string, string>;
+    state: unknown;
+    handleData?: HandleData;
+  }
+  const entries = new Map<number, EntryPage>();
+  const entryIndex = (): number => {
+    const idx = (window.history.state as { idx?: unknown } | null)?.idx;
+    return typeof idx === "number" ? idx : 0;
+  };
+  let entryOnScreen = entryIndex();
+  entries.set(entryOnScreen, {
+    url,
+    segments: initialSegments,
+    params: initialMatch.params,
+    state: window.history.state,
+  });
+  // A write the router makes to the entry history is on (a flash read,
+  // Def.write() or delete()) stays that entry's state, as production's
+  // per-entry memory follows it (navigation-store.ts). A test's own
+  // history.replaceState() does not.
+  setCurrentHistoryStateListener(() => {
+    store.rememberDisplayedEntry();
+    const written = entries.get(entryIndex());
+    if (written) written.state = window.history.state;
+  });
+  /** The page being left keeps its pushes for a back/forward onto it. */
+  const leaveEntry = (): void => {
+    const left = entries.get(entryOnScreen);
+    if (left) left.handleData = eventController.getHandleState().data;
+  };
+  let popGeneration = 0;
   // 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
@@ -837,6 +918,29 @@ export async function renderRoute(
     // takes it, and no act() of the caller's can overlap it.
     act(() => eventController.flushRouteState());
     try {
+      const streamUntil = navOptions?.streamUntil;
+      if (streamUntil) {
+        // The response arrives a task after the request, ahead of the
+        // commit (navigation-transaction.ts: the stream opens with it).
+        await act(async () => {
+          await new Promise((resolve) => setTimeout(resolve, 0));
+        });
+        if (handle.signal.aborted) return;
+        const stream = handle.startStreaming();
+        act(() => eventController.flushRouteState());
+        // A navigation that is left stops counting as streaming at the abort
+        // (partial-update.ts endStream); the abort's notification goes out
+        // with the newer navigation's.
+        handle.signal.addEventListener("abort", () => stream.end(), {
+          once: true,
+        });
+        const end = (): void =>
+          act(() => {
+            stream.end();
+            eventController.flushRouteState();
+          });
+        void streamUntil.then(end, end);
+      }
       await commitNavigation(handle, target, navOptions);
     } finally {
       // Back to idle when the commit never came (a render that threw).
@@ -922,6 +1026,7 @@ export async function renderRoute(
     // 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;
+    leaveEntry();
     handle.complete(nextUrl);
     eventController.setParams(match.params);
     store.setCurrentUrl(nextUrl.href);
@@ -934,6 +1039,13 @@ export async function renderRoute(
       );
       eventController.commitLocationState(historyState);
     }
+    entryOnScreen = entryIndex();
+    entries.set(entryOnScreen, {
+      url: nextUrl,
+      segments,
+      params: match.params,
+      state: window.history.state,
+    });
     const emit: UpdateSubscriber = (update) => store.emitUpdate(update);
     await act(async () => {
       // As production's emitters name their cause (suspense-audit.ts I6).
@@ -961,17 +1073,90 @@ export async function renderRoute(
     return navigate(current.pathname + current.search, { kind: "revalidate" });
   };
 
+  // A back/forward onto the mounted entry or one a navigation wrote, whose
+  // page is not the one on screen: its page is restored from the entry, as production's
+  // history-cache restore does (navigation-bridge.ts handlePopstate). Not
+  // modeled: a stale entry's revalidation and a restore that has to fetch.
+  const restoreEntry = async (index: number, page: EntryPage) => {
+    const generation = ++popGeneration;
+    eventController.abortNavigation();
+    const historyState = window.history.state;
+    // transition({ when }) decides the restore (kind "pop") against the
+    // entry being left.
+    const gatedOff = decideTransitionGatedOff(page.segments, () => ({
+      kind: "pop",
+      from: {
+        url: eventController.getLocation().href,
+        params: eventController.getParams(),
+        routeName: leaf.name,
+        state: entries.get(entryOnScreen)?.state ?? null,
+      },
+      to: {
+        url: page.url,
+        params: page.params,
+        routeName: leaf.name,
+        state: historyState,
+      },
+    }));
+    const root = await renderSegments(page.segments, {
+      forceAwait: true,
+      outletPending: options.outletPending,
+      transitionGatedOff: gatedOff,
+    });
+    // A later back/forward owns the screen.
+    if (generation !== popGeneration) return;
+    leaveEntry();
+    entryOnScreen = index;
+    store.setCurrentUrl(page.url.href);
+    store.setSegmentIds(page.segments.map((s) => s.id));
+    const update: NavigationUpdate = {
+      root,
+      metadata: {
+        ...makeMetadata(page.url.pathname, page.segments, page.params),
+        isPartial: true,
+        cachedHandleData: page.handleData,
+      },
+    };
+    await act(async () => {
+      // The restored entry's location and params, set where its tree is
+      // handed over, so the hooks take them in that batch.
+      eventController.setLocation(page.url);
+      eventController.setParams(page.params);
+      eventController.commitLocationState(historyState);
+      auditTreeCause("popstate");
+      if (!shouldStartViewTransition(page.segments, gatedOff)) {
+        store.emitUpdate(update);
+      } else {
+        startTransition(() => {
+          store.emitUpdate({ ...update, inTransition: true });
+        });
+      }
+    });
+  };
+
   let prefetchRoot: HTMLElement | undefined;
   const bridge: NavigationBridge = {
     navigate: (target, navigateOptions) =>
       navigate(target, { history: navigateOptions ?? {} }),
     refresh: () => refresh(),
-    // Back/forward onto the entry history.state holds. The tree has one
-    // location, so nothing is restored: a treeless commit of that entry, as
-    // production's traversal that keeps every segment
-    // (navigation-transaction.ts commit). Flushed, not left to the notify
-    // timer: the dispatching test's act() has returned by then.
+    // Back/forward onto the entry history.state holds. Its page is restored
+    // when the mount or a navigation wrote the entry, history still holds that
+    // state and another page is on screen (restoreEntry). Otherwise the tree
+    // keeps its location: a treeless commit of that entry, as production's
+    // traversal that keeps every segment (navigation-transaction.ts commit).
+    // Flushed, not left to the notify timer: the dispatching test's act()
+    // has returned by then.
     handlePopstate: async () => {
+      const index = entryIndex();
+      const page = entries.get(index);
+      if (
+        page &&
+        index !== entryOnScreen &&
+        page.state === window.history.state
+      ) {
+        await restoreEntry(index, page);
+        return;
+      }
       eventController.commitLocationState(window.history.state, true);
       eventController.flushRouteState();
     },
@@ -1091,6 +1276,7 @@ export async function renderRoute(
         loaders: navOptions?.loaders,
         handles: navOptions?.handles,
         transition: navOptions?.transition,
+        streamUntil: navOptions?.streamUntil,
         history:
           navOptions?.state !== undefined || navOptions?.replace
             ? navOptions

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

@@ -53,16 +53,16 @@ import type { ExecutionContext } from "../types/request-scope.js";
 import type { HandlerCacheConfig, SSRModule } from "../rsc/types.js";
 import type { createRSCHandler } from "../rsc/handler.js";
 import { setDefaultSSRModuleLoaderForTests } from "../rsc/ssr-module-loader.js";
+import {
+  createPrerenderStore,
+  prerenderManifestEntries,
+} from "../prerender/store.js";
 import {
   POST_QUIESCE_TASK_HOPS,
   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,
-  STALE_PARAM,
-} from "../prefetch-markers.js";
+import { 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";
@@ -76,6 +76,7 @@ import {
   type PprReplayStatus,
   type ShellStatus,
 } from "./shell-status.js";
+import { writePartialParams } from "../browser/wire-protocol.js";
 
 /** Options for {@link serveShellRequest}. */
 export interface ServeShellRequestOptions<TEnv = any> {
@@ -114,7 +115,13 @@ export interface ServeShellRequestOptions<TEnv = any> {
    * and segments take an action's revalidation defaults; it renders live, as
    * an action does, so neither the route cache nor the document cache answers
    * or stores it, and a `ppr` route's `replayStatus` is
-   * `{ outcome: "BYPASS", reason: "stale" }`.
+   * `{ outcome: "BYPASS", reason: "stale" }`. `boundary` names the error
+   * segment of a thrown action's boundary the page at `from` shows
+   * (`_rsc_boundary`), as the follow-up an earlier action owes that page
+   * sends it, with `stale: true` and no `segments`: the response renders
+   * every segment above the boundary and nothing at or below it, claims the
+   * boundary in `matched` and sends no segment for it. The server reads it
+   * only beside `stale`.
    */
   partial?:
     | true
@@ -126,6 +133,7 @@ export interface ServeShellRequestOptions<TEnv = any> {
         fill?: boolean;
         interceptSource?: string;
         stale?: boolean;
+        boundary?: string;
       };
   /**
    * POST this form as a submit before hydration: the no-JS request the
@@ -485,29 +493,14 @@ async function servePrerenderArtifacts(
     const { hashParams } = await import("../prerender/param-hash.js");
     baked.add(pathname);
     if (result && !result.passthrough) {
-      const key = `${result.routeName}/${hashParams(result.params)}`;
-      payloads.set(
-        key,
-        JSON.stringify({ segments: result.segments, handles: result.handles }),
-      );
-      // The intercept variant, keyed and shaped as the build writes it
-      // (vite/discovery/prerender-collection.ts).
-      if (result.interceptSegments?.length) {
-        payloads.set(
-          `${key}/i`,
-          JSON.stringify({
-            segments: [...result.segments, ...result.interceptSegments],
-            handles: result.interceptHandles ?? "",
-          }),
-        );
+      const paramHash = hashParams(result.params);
+      for (const [key, value] of prerenderManifestEntries(result, paramHash)) {
+        payloads.set(key, value);
       }
     }
   }
-  const [{ createPrerenderStore }, { setPrerenderStoreForTests }] =
-    await Promise.all([
-      import("../prerender/store.js"),
-      import("../router/match-middleware/cache-lookup.js"),
-    ]);
+  const { setPrerenderStoreForTests } =
+    await import("../router/match-middleware/cache-lookup.js");
   const previousLoader = globalThis.__loadPrerenderManifestModule;
   globalThis.__loadPrerenderManifestModule = async () => ({
     default: Object.fromEntries([...payloads.keys()].map((key) => [key, key])),
@@ -585,12 +578,12 @@ async function buildActionRequest(
   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(","));
-  if (action.rewriteTarget) {
-    target.searchParams.set("_rsc_rt", action.rewriteTarget);
-  }
+  const target = writePartialParams(new URL(url), {
+    action: action.id,
+    segmentIds: action.segments ?? [],
+    emptySegments: "send",
+    rewriteTarget: 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);
@@ -640,20 +633,23 @@ async function buildRequest(
     fill = false,
     interceptSource,
     stale = false,
+    boundary,
   } = partial === true ? {} : partial;
   if (stale && prefetch) {
     throw new Error(
       "serveShellRequest: partial.stale cannot be combined with partial.prefetch",
     );
   }
-  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, stale) and
-  // browser/prefetch/fetch.ts (prefetch).
-  if (fill) target.searchParams.set(FILL_PARAM, "1");
-  if (stale) target.searchParams.set(STALE_PARAM, "true");
+  // As the browser writes them: browser/navigation-client.ts, and
+  // browser/prefetch/fetch.ts for the prefetch header.
+  const target = writePartialParams(new URL(url), {
+    segmentIds: segments,
+    emptySegments: "send",
+    stale,
+    boundary,
+    rewriteTarget,
+    fill,
+  });
   if (prefetch && !headers.has(PREFETCH_HEADER)) {
     headers.set(PREFETCH_HEADER, "1");
   }

package/src/types/cache-types.ts

@@ -137,9 +137,12 @@ export interface CacheOptions<TEnv = unknown> {
   ) => boolean;
 
   /**
-   * Custom cache key function - FULL OVERRIDE.
-   * Bypasses default key generation AND store's keyGenerator. The result is
-   * stored namespaced (`key:` plus its URI encoding), so no value it returns
+   * Custom cache key function. Replaces the URL part of the default key
+   * (host, path, params, search) AND bypasses the store's keyGenerator. The
+   * request kind stays: a document request, a navigation and each intercept
+   * navigation keep their own record under one result, so the result decides
+   * which requests of one kind share a record. It is stored namespaced
+   * (`key:` plus its URI encoding, then the kind), so no value it returns
    * names another route's record; a nested cache() keys its records within
    * this partition.
    *

package/src/types/error-types.ts

@@ -81,11 +81,38 @@ export interface OnErrorContext<TEnv = any> {
   actionId?: string;
   /** Environment/bindings (platform context) */
   env?: TEnv;
-  /** Duration from request start to error (milliseconds) */
+  /**
+   * Duration from request start to error (milliseconds). For a `background`
+   * error it counts from the start of the request that started the work, so
+   * it includes that response and any wait before the work ran.
+   */
   duration?: number;
-  /** Whether this is a partial/navigation request */
+  /**
+   * Whether this is a partial/navigation request, on an error the segment
+   * walk catches (a handler that throws, a streamed `loading()` handler that
+   * rejects, a DSL loader that rejects): `true` for a navigation, unset for a
+   * document. A `cache()` record's refresh or proactive write reports the
+   * request that started it; a PPR shell capture renders a document. The
+   * `routing` phase reports `false`.
+   */
   isPartial?: boolean;
-  /** Whether an error boundary caught the error */
+  /**
+   * `true` when the error came from work whose output goes to a cache and
+   * never to the response of the request that started it: a stale `cache()`
+   * record's refresh, the write of a navigation that kept a layout mounted, a
+   * stale document cache entry's re-run, a PPR shell capture, or a stale
+   * `"use cache"` function's or cached loader's refresh, the work's own
+   * failure included. `request` and `url` are the starting request's (a
+   * shell capture's handler errors name the page it captures). A
+   * `router.prerender()` warm's own render is its request's: unset, while a
+   * shell capture it makes is `true`. Unset for every other error.
+   */
+  background?: boolean;
+  /**
+   * Whether an error boundary caught the error and its fallback reached the
+   * response. `false` on a `background` error: the failed render is never
+   * stored, so no visitor sees the fallback.
+   */
   handledByBoundary?: boolean;
   /** Stack trace (if available) */
   stack?: string;

package/src/types/handler-context.ts

@@ -462,7 +462,7 @@ export type InternalHandlerContext<
   _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
+   * (readPrerenderSource, cache-lookup.ts); gateOnDemandProducer reads it. On
    * this context, not the request's: withCacheLookup documents that the
    * request ALS can be lost mid-pipeline on workerd.
    */
@@ -510,6 +510,17 @@ export type InternalHandlerContext<
    * request is a fill. See router/segment-resolution/prefetch-deferral.ts.
    */
   _prefetchDeferral?: import("../router/segment-resolution/prefetch-deferral.js").PrefetchDeferral;
+  /**
+   * @internal DSL loaders registered and not started, by `$$id`: a prefetch
+   * deferred them, or a pass that skips loaders (`skipLoaders`) did not run
+   * them. A reader's ctx.use() starts one through its registration
+   * (registerDeferredLoader, startDeferredLoader in
+   * router/segment-resolution/prefetch-deferral.ts).
+   */
+  _deferredLoaders?: Map<
+    string,
+    import("../router/segment-resolution/prefetch-deferral.js").DeferredLoader
+  >;
   /**
    * @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

package/src/types/segments.ts

@@ -165,7 +165,7 @@ export interface ResolvedSegment {
   loaderData?: any; // For loaders: the resolved data from loader execution
   /**
    * True when this loader was awaited before first flush
-   * (loader(Def, { ssr: false })). Stamped by resolveLoaders (fresh.ts) on
+   * (loader(Def, { ssr: false })). Stamped by resolveOwnerLoaders on
    * document AND shell-capture renders — capture bakes flagged loaders and
    * awaits the same lane. Feeds segment-system's settled-value delivery and
    * the dev SSR suspension warning (ssr-suspension-warning.ts).