@rangojs/router 0.16.0 → 0.18.0

package/src/ssr/index.tsx

@@ -2,7 +2,11 @@ import React from "react";
 import { createSsrRootComponent, deserializeSsrPayload } from "./ssr-root.js";
 import { injectRSCPayloadEager } from "./inject-rsc-eager.js";
 import { runWithPreinitNonce } from "./preinit-client-references.js";
-import { SHELL_CAPTURE_MAX_WAIT_MS } from "../rsc/shell-capture-constants.js";
+import {
+  POST_QUIESCE_TASK_HOPS,
+  SHELL_CAPTURE_MAX_WAIT_MS,
+} from "../rsc/shell-capture-constants.js";
+import { isThenable } from "../handles/is-thenable.js";
 import type { ErrorPhase } from "../types.js";
 import type { HeadScriptsOption } from "../vite/plugin-types.js";
 
@@ -27,6 +31,7 @@ interface RenderToReadableStreamOptions {
   nonce?: string;
   formState?: unknown;
   progressiveChunkSize?: number;
+  onError?: (error: unknown) => void;
 }
 
 /**
@@ -124,6 +129,13 @@ export interface SSRRenderOptions {
    * prerender pass (host-agnostic bare captures).
    */
   origin?: string;
+
+  /**
+   * Called for each error Fizz reports through its onError: a component that
+   * threw inside a Suspense boundary, which leaves the boundary errored in an
+   * otherwise completed document. React's default console.error is kept.
+   */
+  onError?: (error: unknown) => void;
 }
 
 /**
@@ -229,28 +241,64 @@ export interface SSRDependencies<TEnv = unknown> {
 }
 
 /**
- * Fixed number of macrotask hops between `quiesce` resolving and the abort. These
- * give React's fizz worker turns to flush the settled shell into the prelude and
- * mark still-pending boundaries as POSTPONED (rather than errored) before
- * controller.abort() lands. Not a wall-clock wait.
- *
- * Why 16 and not the original 2: under the REPLAY-ONLY capture model
- * (docs/design/ppr-shell-resume.md), the capture Flight render serializes ring-3
- * cached segments that are ALREADY serialized, so it emits the whole shell payload
- * in the first tick and the gate declares quiesce almost immediately (~a few ms).
- * On the old fresh-execution path the Flight dribbled out as handlers ran, so
- * Flight-quiet effectively meant "the shell has rendered" and 2 hops sufficed.
- *
- * Hops alone are NOT render-readiness: fizz cannot emit even <html> until the
- * payload root settles, which waits on every referenced client-module LOAD —
- * real module-runner I/O in dev (100ms+ cold), which no fixed count of near-
- * zero-cost task hops can buy. captureShellHTML therefore awaits the payload-
- * settled signal (SsrRootOptions.onPayloadSettled, deadline-bounded) between
- * quiesce and these hops; the hops then only flush the settled tree and mark
- * pending boundaries POSTPONED. Still task-based (masked loaders never emit,
- * so more hops never lets a hole settle). Bounded by maxWaitMs end to end.
+ * One set per running capture, collecting the client-reference module loads
+ * requested while it runs (captureClientLoads). The Flight client resolves a
+ * client component used as an element type lazily, so the payload settles
+ * while its module is still loading, and a shell that renders it outside any
+ * Suspense boundary cannot complete until the load does. On the
+ * cloudflare-basic build a cold load (the module, its imports, its CSS
+ * virtual) settled at +890.1ms, after the payload (+873.4ms) and 1ms before
+ * the abort, and uninstrumented builds lost that race (issue #949). The
+ * Flight client asks the loader again for every import row, even for a
+ * module another render is already loading, so a capture sees each load it
+ * needs; one a concurrent render requests meanwhile is collected too and is
+ * the same bounded I/O. The sets are per capture, their contents isolate-wide:
+ * a load that never settles can only hold the captures running when it was
+ * requested, each until its deadline.
+ */
+const activeCaptureClientLoads = new Set<Set<PromiseLike<unknown>>>();
+
+/** The loader wrapper {@link captureClientLoads} last installed. */
+let recordingClientReferenceLoader: ((id: string) => unknown) | undefined;
+
+/**
+ * Start collecting the client-reference loads requested during a capture;
+ * call the returned `stop` when the capture ends. Wraps plugin-rsc's SSR
+ * loader (`globalThis.__vite_rsc_client_require__`, which
+ * `__vite_rsc_require__` reads per call) on the first capture, so an isolate
+ * that never captures keeps the bare loader. Wraps again when another wrapper
+ * replaced this one (the build shell phase bridges hashed ids the same way,
+ * vite/discovery/shell-prerender-phase.ts). Collects nothing without the
+ * loader.
  */
-const POST_QUIESCE_TASK_HOPS = 16;
+function captureClientLoads(): {
+  loads: Set<PromiseLike<unknown>>;
+  stop: () => void;
+} {
+  const g = globalThis as {
+    __vite_rsc_client_require__?: (id: string) => unknown;
+  };
+  const load = g.__vite_rsc_client_require__;
+  if (typeof load === "function" && load !== recordingClientReferenceLoader) {
+    recordingClientReferenceLoader = (id) => {
+      const loading = load(id);
+      // plugin-rsc memoizes one promise per id and the Flight client stamps
+      // status "fulfilled" on it once loaded: a warm module is not collected.
+      if (
+        activeCaptureClientLoads.size > 0 &&
+        isThenable(loading) &&
+        (loading as { status?: string }).status !== "fulfilled"
+      ) {
+        for (const loads of activeCaptureClientLoads) loads.add(loading);
+      }
+      return loading;
+    };
+    g.__vite_rsc_client_require__ = recordingClientReferenceLoader;
+  }
+  const loads = new Set<PromiseLike<unknown>>();
+  activeCaptureClientLoads.add(loads);
+  return { loads, stop: () => activeCaptureClientLoads.delete(loads) };
+}
 
 /**
  * Route an SSR error through the deps.onError notification callback with the
@@ -407,6 +455,19 @@ interface ShellCaptureOptions {
    * capture, resume, and browser hydration.
    */
   origin?: string;
+  /**
+   * Called for each component error the prerender reports (an errored
+   * boundary in the prelude), never for the capture's own abort. The caller
+   * refuses to store the shell (issue #915).
+   */
+  onError?: (error: unknown) => void;
+  /**
+   * Called with React's errorInfo for each task still pending when the
+   * capture's own abort froze the prelude; its componentStack is computed
+   * when read. The dev no-shell warning prints the stacks: one of them is what
+   * suspended above <body> (issue #941).
+   */
+  onAbortedTask?: (errorInfo: { componentStack?: string } | undefined) => void;
 }
 
 /**
@@ -437,6 +498,8 @@ interface ShellResumeOptions {
   search?: string;
   /** The HIT request's origin — same host as the capture's (key-scoped). */
   origin?: string;
+  /** Called for each component error the resumed holes report. */
+  onError?: (error: unknown) => void;
 }
 
 /**
@@ -601,7 +664,14 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
     rscStream: ReadableStream<Uint8Array>,
     options?: SSRRenderOptions,
   ): Promise<ReadableStream<Uint8Array>> {
-    const { nonce, formState, streamMode, search, origin } = options ?? {};
+    const {
+      nonce,
+      formState,
+      streamMode,
+      search,
+      origin,
+      onError: onRenderError,
+    } = options ?? {};
 
     try {
       // Tee the stream:
@@ -659,6 +729,13 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
           formState,
           nonce,
           ...(progressiveChunkSize !== undefined && { progressiveChunkSize }),
+          ...(onRenderError && {
+            onError: (error: unknown) => {
+              onRenderError(error);
+              // What React's default onError does (it only logs).
+              console.error(error);
+            },
+          }),
         }),
       );
 
@@ -731,12 +808,13 @@ export function createShellCaptureHandler<TEnv = unknown>(
     const deadline = (await isDebuggerAttached())
       ? { promise: new Promise<void>(() => {}), cancel: () => {} }
       : createCancelableTimeout(maxWaitMs);
+    const clientLoads = captureClientLoads();
     try {
       // No nonce (nonce'd requests never reach capture); no formState.
-      // payloadSettled: fires when the Flight payload root settles — i.e.
-      // every client-module load the payload references completed and fizz
-      // can actually emit the tree. The abort below gates on it (bounded by
-      // the same deadline): Flight byte-quiet alone is NOT render-readiness.
+      // payloadSettled: fires when the Flight payload root settles and fizz
+      // can emit the tree. The abort below gates on it and on the
+      // client-reference loads in flight in the isolate (bounded by the same
+      // deadline): Flight byte-quiet alone is NOT render-readiness.
       let settlePayload!: () => void;
       const payloadSettled = new Promise<void>((resolve) => {
         settlePayload = resolve;
@@ -793,10 +871,12 @@ export function createShellCaptureHandler<TEnv = unknown>(
         // render errors are NOT our sentinel and still surface through
         // deps.onError, the same channel renderHTML uses. See
         // docs/design/ppr-shell-resume.md.
-        onError: (error: unknown) => {
+        onError: (error: unknown, errorInfo?: { componentStack?: string }) => {
           if (error === abortReason) {
+            opts.onAbortedTask?.(errorInfo);
             return;
           }
+          opts.onError?.(error);
           reportRenderError(onError, error);
         },
       });
@@ -815,25 +895,34 @@ export function createShellCaptureHandler<TEnv = unknown>(
       // shell that never goes quiet (a root postpone / hung handle).
       await Promise.race([opts.quiesce, deadline.promise]);
       // Then wait for fizz RENDER-READINESS, bounded by the same deadline:
-      // the payload root settles only after every client-module load the
-      // payload references completed (real module-runner I/O in dev; 100ms+
-      // on a cold graph). Flight byte-quiet does NOT imply this — a fully
+      // the payload root settles, then the client-reference module loads the
+      // capture started settle — a client component used as an element type
+      // resolves lazily, after the payload (real module-runner I/O in dev;
+      // 100ms+ on a cold graph). Flight byte-quiet does NOT imply this — a fully
       // REPLAYED (prerendered) route's Flight stream finishes in ~1-3ms and
       // an abort taken on quiet-plus-task-hops alone landed BEFORE fizz could
       // emit <html>, freezing a zero-byte prelude: the eternal-MISS shape
       // this route class showed on every cold graph (dev cold boots, GH
       // runners) while ordinary routes — whose live handler execution keeps
-      // Flight noisy long enough — never hit it. Masked-loader holes do not
-      // block payload settlement (they postpone below the root), so this
-      // await costs a genuinely hole-y shell nothing; a payload that NEVER
-      // settles (hung handles) degrades at the deadline exactly as before.
-      // A prerender that SETTLES first (early success or a hard rejection)
-      // ends the wait immediately — fizz is already done either way.
+      // Flight noisy long enough — never hit it. Holes the payload carries
+      // block neither wait (masked live loaders and loader-nested promises postpone
+      // below the root and load no module; the Flight input stays frozen),
+      // so this await costs a genuinely hole-y shell nothing; a payload that
+      // NEVER settles (hung handles) degrades at the deadline exactly as
+      // before. A prerender that SETTLES first (early success or a hard
+      // rejection) ends the wait immediately — fizz is already done either
+      // way.
       const prerenderSettled = prerenderPromise.then(
         () => {},
         () => {},
       );
-      await Promise.race([payloadSettled, prerenderSettled, deadline.promise]);
+      // The capture's loads all started when their import rows were parsed,
+      // before the Flight input froze.
+      await Promise.race([
+        payloadSettled.then(() => Promise.allSettled(clientLoads.loads)),
+        prerenderSettled,
+        deadline.promise,
+      ]);
       // Fixed task hops before the abort: give React's fizz worker turns to flush
       // the now-complete shell and mark the still-pending boundaries as POSTPONED
       // rather than errored. Deterministic (the byte set is already frozen and
@@ -877,11 +966,10 @@ export function createShellCaptureHandler<TEnv = unknown>(
 
       // Sanity gate: a prelude with no `<body` is the no-shell failure mode.
       // Return null and store nothing; the request falls back to axis 1 and a
-      // later request re-captures. The dominant real-world cause is a loader
-      // route WITHOUT a route-level loading() boundary: renderSegments' loading-
-      // less branch awaits loader data at TREE-BUILD, so the masked loader pins
-      // the whole tree above <body> (root postpone). Root-postponing layouts and
-      // hung handles degrade the same way. shell-capture.ts logs a once-per-key
+      // later request re-captures. The dominant real-world cause is a masked
+      // live-loader read with no boundary above it (lane rule: see
+      // resolveLoaderData, loader-cache.ts), which root-postpones above
+      // <body>. Root-postponing layouts and hung handles degrade the same way. shell-capture.ts logs a once-per-key
       // warning so the eternal-MISS shape is diagnosable.
       if (!new TextDecoder().decode(prelude).includes("<body")) {
         return null;
@@ -893,6 +981,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
       };
     } finally {
       deadline.cancel();
+      clientLoads.stop();
     }
   };
 }
@@ -982,7 +1071,10 @@ export function createShellResumeHandler<TEnv = unknown>(
           // resumed stream and need the per-request nonce.
           const resumed = await runWithPreinitNonce(nonce, () =>
             resume(<SsrRoot />, JSON.parse(postponed), {
-              onError: (error) => reportRenderError(onError, error),
+              onError: (error) => {
+                opts.onError?.(error);
+                reportRenderError(onError, error);
+              },
               nonce,
             }),
           );

package/src/ssr/ssr-root.tsx

@@ -189,14 +189,15 @@ export interface SsrRootOptions {
   nonce?: string;
   /**
    * Fires once when the Flight payload root settles (resolve OR reject) — the
-   * signal that every client-module load the payload references completed and
-   * fizz can start emitting the tree. The capture pass gates its abort on
-   * this: a fully REPLAYED (prerendered) route's Flight stream goes
-   * byte-quiet in ~1-3ms, but fizz cannot render even <html> until the
-   * module loads finish (real module-runner I/O in dev; 100ms+ on a cold
-   * graph), so an abort gated on Flight quiet alone fires first and freezes
-   * a zero-byte prelude. Masked-loader holes do NOT block this signal —
-   * they postpone below the root.
+   * signal that fizz can start emitting the tree. A client component used as
+   * an element type resolves lazily, so its module load can still be in
+   * flight (captureShellHTML waits for those separately, issue #949). The
+   * capture pass gates its abort on this: a fully REPLAYED (prerendered)
+   * route's Flight stream goes byte-quiet in ~1-3ms, but fizz cannot render
+   * even <html> until the module loads finish (real module-runner I/O in dev;
+   * 100ms+ on a cold graph), so an abort gated on Flight quiet alone fires
+   * first and freezes a zero-byte prelude. Masked-loader holes do NOT block
+   * this signal — they postpone below the root.
    */
   onPayloadSettled?: () => void;
   /**

package/src/static-handler.ts

@@ -21,11 +21,14 @@
  * ```ts
  * export const DocsNav = Static((ctx) => <Nav docs={readDocsSync()} />);
  * export const DocShell = Static((ctx) => <Shell />);
+ * // Prerender/Static must be exported consts; an inline call inside path()
+ * // gets no build-injected $$id and throws.
+ * export const DocPage = Prerender(getParams, DocPageHandler);
  *
  * urls(({ path, layout }) => [
  *   layout(DocsNav, () => [
  *     path("/getting-started", DocShell, { name: "doc.gs" }),
- *     path("/:slug", Prerender(getParams, DocPageHandler)),
+ *     path("/:slug", DocPage),
  *   ]),
  * ]);
  * ```

package/src/testing/flight-runtime.d.ts

@@ -19,6 +19,9 @@ declare module "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge" {
     options?: { onError?: (error: unknown) => string | void },
   ): ReadableStream<Uint8Array>;
 
+  /** Server-side temporary-reference set (a WeakMap). */
+  export function createTemporaryReferenceSet(): unknown;
+
   /**
    * Tag a value as a client reference. Mutates `impl` in place (defining
    * `$$typeof`/`$$id`/`$$async`) and returns it, so a server tree that imports
@@ -55,3 +58,21 @@ declare module "@vitejs/plugin-rsc/core/browser" {
     load: (id: string) => unknown;
   }): void;
 }
+
+/**
+ * The vendored react-server-dom CLIENT build the RSC environment decodes with
+ * (plugin-rsc `react/rsc/client`). The plugin-rsc stub runs the "use cache"
+ * codec on it under the react-server condition.
+ */
+declare module "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge" {
+  export function createFromReadableStream<T = unknown>(
+    stream: ReadableStream<Uint8Array>,
+    options?: object,
+  ): Promise<T>;
+  export function encodeReply(
+    value: unknown,
+    options?: object,
+  ): Promise<string | FormData>;
+  /** Client-side temporary-reference set (a Map). */
+  export function createTemporaryReferenceSet(): unknown;
+}

package/src/testing/flight.entry.ts

@@ -18,6 +18,11 @@
  * element tree, so you can assert typed prop fidelity across the client boundary
  * (a `Date` comes back a `Date`) and detect inlined-vs-island. Serialize +
  * deserialize only — no hydration/interaction (that is the e2e tier).
+ *
+ * `serveShellRequest` serves one request through the router's production
+ * handler, so a `ppr` route's MISS runs the real shell capture and a later
+ * request is a real HIT; only the HTML step is stubbed. `resetShellTestState`
+ * clears the per-isolate PPR state between tests.
  */
 
 export {
@@ -50,3 +55,12 @@ export type {
   RenderHandlerResult,
   StateCookieSeed,
 } from "./render-handler.js";
+
+export {
+  serveShellRequest,
+  resetShellTestState,
+} from "./serve-shell-request.js";
+export type {
+  ServeShellRequestOptions,
+  ServeShellRequestResult,
+} from "./serve-shell-request.js";

package/src/testing/generated-routes.ts

@@ -158,10 +158,10 @@ export async function diffGeneratedRoutes(
  *
  * @example
  * ```ts
- * import generated from "./router.named-routes.gen";
+ * import { NamedRoutes } from "./router.named-routes.gen";
  * import { router } from "./router";
  *
- * await assertGeneratedRoutesMatch(router, generated);
+ * await assertGeneratedRoutesMatch(router, NamedRoutes);
  * ```
  */
 export async function assertGeneratedRoutesMatch(

package/src/testing/internal/context.ts

@@ -347,7 +347,7 @@ export function buildRunSnapshot<TEnv>(
  *
  * @example
  * ```ts
- * const { result, cookies, response, thrown } = await runInRequestContext(
+ * const { cookies, headers, response, thrown } = await runInRequestContext(
  *   () => loginAction(input), // sets a session cookie, then `throw redirect("/app")`
  *   {
  *     env,

package/src/testing/internal/flight-client-globals.ts

@@ -7,9 +7,11 @@
  * (@vitejs/plugin-rsc `core/plugin.js`). That transform does NOT run in a bare
  * Vitest process, so the vendored client's free `__webpack_require__` /
  * `__webpack_chunk_load__` references would be undefined. We provide minimal
- * shims: `__webpack_require__` routes to the loader installed via
- * `setRequireModule`, and `__webpack_chunk_load__` is a no-op (renderServerTree
- * serializes with empty `chunks`, so no chunk fetch ever happens).
+ * shims: `__webpack_require__` forwards to `__vite_rsc_require__` (the build's
+ * rename), which plugin-rsc's `setRequireModule` installs (core/browser from
+ * renderServerTree, core/rsc from the plugin-rsc stub), and
+ * `__webpack_chunk_load__` is a no-op (the test manifests use empty `chunks`,
+ * so no chunk fetch ever happens).
  *
  * MUST be imported (for side effect) BEFORE `@vitejs/plugin-rsc/react/browser`,
  * which is why flight-tree.ts lists it first.
@@ -17,11 +19,11 @@
 const g = globalThis as unknown as {
   __webpack_require__?: ((id: string) => unknown) & { u?: unknown };
   __webpack_chunk_load__?: (chunkId: string) => Promise<unknown>;
-  __vite_rsc_client_require__?: (id: string) => unknown;
+  __vite_rsc_require__?: (id: string) => unknown;
 };
 
 if (!g.__webpack_require__) {
-  g.__webpack_require__ = (id: string) => g.__vite_rsc_client_require__!(id);
+  g.__webpack_require__ = (id: string) => g.__vite_rsc_require__!(id);
 }
 if (!g.__webpack_chunk_load__) {
   g.__webpack_chunk_load__ = async () => {};

package/src/testing/render-route.tsx

@@ -23,10 +23,13 @@
  *     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() commits synchronously, so it 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).
+ *   - 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).
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
  * useRouter, usePathname, useSearchParams, Outlet/useOutlet nesting and seeded
@@ -48,7 +51,15 @@ import {
 } from "../browser/navigation-store.js";
 import { createEventController } from "../browser/event-controller.js";
 import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
-import type { NavigationStore, NavigationBridge } from "../browser/types.js";
+import {
+  commitInTransition,
+  shouldStartViewTransition,
+} from "../browser/partial-update.js";
+import type {
+  NavigationStore,
+  NavigationBridge,
+  UpdateSubscriber,
+} from "../browser/types.js";
 import type { EventController } from "../browser/event-controller.js";
 import type { ResolvedSegment, RscMetadata } from "../browser/types.js";
 import { NavigationProvider } from "../browser/react/NavigationProvider.js";
@@ -57,7 +68,7 @@ import {
   buildParamsFromMatch,
 } from "../router/pattern-matching.js";
 import { normalizeBasename } from "../router/basename.js";
-import type { LoaderDefinition } from "../types.js";
+import type { LoaderDefinition, TransitionConfig } from "../types.js";
 import type { LocationStateDefinition } from "../browser/react/location-state-shared.js";
 import type { Handle } from "../handle.js";
 import type { ThemeConfig } from "../theme/types.js";
@@ -130,6 +141,14 @@ export interface RenderRouteSpec {
   loaderIds?: string[];
   /** Optional route name (informational; not used for matching). */
   name?: string;
+  /**
+   * The `transition()` config this node declares (`{}` for a bare
+   * `transition()`), attached to its segment as the DSL does. Puts the chain in
+   * a transition scope: param-agnostic keys (segment-system.tsx) and a held
+   * navigate() commit, so a pending loader seed passed to
+   * `router.navigate(url, { loaders })` pins `useLoader().isLoading`.
+   */
+  transition?: TransitionConfig;
 }
 
 /**
@@ -303,8 +322,26 @@ export interface TestRouterHandle {
    * updates params + location, and re-renders the segment tree. This is a
    * client-only navigation: no server fetch occurs, so only the components in
    * `routes` can be reached.
+   *
+   * `options.loaders` seeds loader data for THIS navigation, merged over the
+   * render-time seeds (the data a real navigation's response would carry). A
+   * 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.
+   *
+   * @example
+   * await router.navigate("/products/2", { loaders: [[ProductLoader, next]] });
+   * // reader: isLoading true, old data
+   * await act(async () => resolve({ name: "Product 2" }));
+   * // reader: isLoading false, new data
    */
-  navigate(url: string): Promise<void>;
+  navigate(
+    url: string,
+    options?: Pick<RenderRouteOptions, "loaders">,
+  ): Promise<void>;
   /** The current committed pathname. */
   pathname(): string;
   /** The current committed params. */
@@ -413,6 +450,7 @@ function buildSegments(
       belongsToRoute: true,
     };
     if (mount) node.mountPath = mount;
+    if (spec.transition) node.transition = spec.transition;
     if (isLeaf && spec.layout) {
       const Layout = spec.layout;
       node.layout = <Layout />;
@@ -464,10 +502,17 @@ export async function renderRoute(
   const initialUrl = requestUrl ?? staticPrefix(leaf.path) ?? "/";
   const url = new URL(initialUrl, TEST_ORIGIN);
 
-  const loaderData: Record<string, unknown> = { ...(options.loaderData ?? {}) };
-  for (const [loader, data] of options.loaders ?? []) {
-    loaderData[ensureSyntheticId(loader as object, "$$id")] = data;
-  }
+  const seedLoaders = (
+    base: Record<string, unknown>,
+    loaders: RenderRouteOptions["loaders"],
+  ): Record<string, unknown> => {
+    const out = { ...base };
+    for (const [loader, data] of loaders ?? []) {
+      out[ensureSyntheticId(loader as object, "$$id")] = data;
+    }
+    return out;
+  };
+  const loaderData = seedLoaders(options.loaderData ?? {}, options.loaders);
 
   if (typeof window !== "undefined") {
     const stateObj: Record<string, unknown> = {};
@@ -550,25 +595,33 @@ export async function renderRoute(
   );
 
   let warnedNavLifecycle = false;
-  const navigate = async (target: string): Promise<void> => {
-    // renderRoute commits navigations synchronously (no server fetch, no Flight
-    // stream), so it never drives the navigation lifecycle. The transition 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, not silent.
+  const navigate = async (
+    target: string,
+    navOptions?: Pick<RenderRouteOptions, "loaders">,
+  ): Promise<void> => {
+    // 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 commit synchronously and 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.",
+        "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(routes, match.params, loaderData, mount);
+    const segments = buildSegments(
+      routes,
+      match.params,
+      seedLoaders(loaderData, navOptions?.loaders),
+      mount,
+    );
     const metadata = makeMetadata(nextUrl.pathname, segments, match.params);
     const root = await renderSegments(segments, {
       outletPending: options.outletPending,
@@ -577,8 +630,16 @@ export async function renderRoute(
     eventController.setParams(match.params);
     store.setCurrentUrl(nextUrl.href);
     store.setSegmentIds(segments.map((s) => s.id));
+    const emit: UpdateSubscriber = (update) => store.emitUpdate(update);
     await act(async () => {
-      store.emitUpdate({ root, metadata });
+      // Production's transition() lane (browser/partial-update.ts). Its
+      // same-structure / fully-prefetched / optimistic hold lanes are not
+      // modeled: without transition() the commit stays urgent.
+      if (shouldStartViewTransition(segments)) {
+        commitInTransition(emit, segments, { root, metadata }, ["navigation"]);
+      } else {
+        emit({ root, metadata });
+      }
     });
   };