@rangojs/router 0.12.4 → 0.14.0

package/dist/types/browser/optimistic-commit.d.ts

@@ -0,0 +1,12 @@
+import type { ViewTransitionClass } from "../types/segments.js";
+/**
+ * Transition type added to the canonical commit of a navigation that already
+ * presented an optimistic clientUrls() destination (client-urls/client-root.tsx).
+ * The optimistic swap ran in a transition lane and got the route's configured
+ * <ViewTransition> animation; the commit then replaces the branch with the
+ * destination's own segment — identical pixels — so every router-placed
+ * boundary maps this type to "none" (withOptimisticCommitNone) and the user
+ * perceives one animated navigation, not two.
+ */
+export declare const OPTIMISTIC_COMMIT_TRANSITION_TYPE = "rango-optimistic-commit";
+export declare function withOptimisticCommitNone(value: ViewTransitionClass | undefined): ViewTransitionClass;

package/dist/types/browser/partial-update.d.ts

@@ -43,6 +43,13 @@ export type UpdateMode = {
     targetCacheHandleData?: Record<string, Record<string, unknown[]>>;
     /** Source URL for intercept restore (popstate cache miss) */
     interceptSourceUrl?: string;
+    /**
+     * The bridge already presented an optimistic clientUrls() destination
+     * for this navigation: transition-lane commits add
+     * OPTIMISTIC_COMMIT_TRANSITION_TYPE so router <ViewTransition>
+     * boundaries do not animate the identical repaint.
+     */
+    optimisticPresented?: boolean;
 } | {
     type: "leave-intercept";
     interceptSourceUrl?: string;

package/dist/types/browser/react/use-params.d.ts

@@ -2,7 +2,9 @@
  * Hook to access the current route params.
  *
  * Returns the merged route params from the matched route.
- * Updates when navigation completes, not during pending navigation.
+ * Updates when navigation completes, not during pending navigation — except
+ * inside an optimistically rendered clientUrls() destination, where it
+ * reports THAT route's params (see OptimisticLocationContext).
  *
  * @example
  * ```tsx

package/dist/types/browser/react/use-pathname.d.ts

@@ -2,7 +2,9 @@
  * Hook to access the current pathname.
  *
  * Returns the committed pathname string (excludes search params and hash).
- * Updates when navigation completes, not during pending navigation.
+ * Updates when navigation completes, not during pending navigation — except
+ * inside an optimistically rendered clientUrls() destination, where it
+ * reports THAT route's pathname (see OptimisticLocationContext).
  *
  * @example
  * ```tsx

package/dist/types/client-urls/navigation.d.ts

@@ -1,6 +1,11 @@
 import type { ClientUrlPatterns } from "./types.js";
 export interface ClientUrlNavigationIntent {
     readonly routeId: string;
+    /** Destination params from the local trie match (definition-local). */
+    readonly params: Readonly<Record<string, string>>;
+    /** Absolute destination pathname (mount included) and search ("?..." or ""). */
+    readonly pathname: string;
+    readonly search: string;
 }
 export declare function setActiveInterceptTargets(targets: readonly string[] | undefined): void;
 export interface ClientUrlNavigationPresentation {

package/dist/types/client-urls/optimistic-location.d.ts

@@ -0,0 +1,17 @@
+import { type Context } from "react";
+/**
+ * Route identity of an optimistically rendered clientUrls() destination:
+ * the values the local trie match produced for the URL the user navigated
+ * to. Provided by ClientUrlsRoot around the optimistic branch ONLY, so
+ * useParams / usePathname / useSearchParams inside that branch describe the
+ * route being rendered while the same hooks in chrome outside it keep the
+ * committed location until the canonical response commits (or redirects, in
+ * which case the branch — and these values — are discarded).
+ */
+export interface OptimisticLocation {
+    readonly params: Readonly<Record<string, string>>;
+    readonly pathname: string;
+    /** Search string including the leading "?" (or ""). */
+    readonly search: string;
+}
+export declare const OptimisticLocationContext: Context<OptimisticLocation | null>;

package/dist/types/route-content-wrapper.d.ts

@@ -23,15 +23,35 @@ import type { ResolvedSegment } from "./types.js";
  */
 export declare class StreamedLoaderErrorBoundary extends Component<{
     children: ReactNode;
+    resetKey?: string;
 }, {
     error: unknown;
+    resetKey?: string;
 }> {
     state: {
         error: unknown;
+        resetKey?: string;
     };
     static getDerivedStateFromError(error: unknown): {
         error: unknown;
     };
+    /**
+     * A caught marker (redirect, notFound, error fallback) belongs to ONE route
+     * + params. Group-keyed segments (ResolvedSegment.clientGroup) keep this
+     * instance alive across in-group navigations, so the error must clear when
+     * the route or params change — otherwise a redirect caught for /legacy
+     * keeps rendering LoaderRedirect for /state. `resetKey` is the segment's
+     * id-params identity, the cadence the per-route remount used to provide.
+     */
+    static getDerivedStateFromProps(props: {
+        resetKey?: string;
+    }, state: {
+        error: unknown;
+        resetKey?: string;
+    }): {
+        error: unknown;
+        resetKey?: string;
+    } | null;
     render(): ReactNode;
 }
 /**

package/dist/types/server/context.d.ts

@@ -48,6 +48,8 @@ export type EntryPropCommon = {
     cache?: EntryCacheConfig;
     /** URL prefix from include() scope, used for MountContext on client */
     mountPath?: string;
+    /** clientUrls() group key (PathOptions.clientGroup); route entries only. */
+    clientGroup?: string;
 };
 /**
  * Attachments resolved by walking the parent chain, not owned by the entry:

package/dist/types/types/segments.d.ts

@@ -163,6 +163,9 @@ export interface ResolvedSegment {
     error?: ErrorInfo;
     notFoundInfo?: NotFoundInfo;
     mountPath?: string;
+    /** clientUrls() group key (the include mount), shared by every route
+     *  segment of one group; see the group-route branch in segment-system.tsx. */
+    clientGroup?: string;
     /**
      * @internal Server-side marker: true when the segment's handler actually ran
      * this request (not skipped via the revalidate cache path). Used by

package/dist/types/urls/pattern-types.d.ts

@@ -102,6 +102,9 @@ export interface PathOptions<TName extends string = string, TSearch extends Sear
     trailingSlash?: TrailingSlashMode;
     /** Response type marker (set by path.json(), etc.) */
     [RESPONSE_TYPE]?: string;
+    /** @internal clientUrls() group key stamped by server-projection.ts; see
+     *  ResolvedSegment.clientGroup. */
+    clientGroup?: string;
 }
 /**
  * Result of urls() - contains the route definitions

package/dist/vite/index.js

@@ -3746,7 +3746,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.12.4",
+  version: "0.14.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -8057,6 +8057,10 @@ import {
 // src/browser/react/use-pathname.ts
 import { useContext as useContext6, useState as useState3, useEffect as useEffect4, useRef as useRef3 } from "react";
 
+// src/client-urls/optimistic-location.ts
+import { createContext as createContext4 } from "react";
+var OptimisticLocationContext = createContext4(null);
+
 // src/browser/react/use-search-params.ts
 import {
   useCallback as useCallback2,
@@ -8072,8 +8076,8 @@ import { useContext as useContext8, useState as useState5, useEffect as useEffec
 var EMPTY_PARAMS = Object.freeze({});
 
 // src/browser/react/nonce-context.ts
-import { createContext as createContext4, useContext as useContext9 } from "react";
-var NonceContext = createContext4(void 0);
+import { createContext as createContext5, useContext as useContext9 } from "react";
+var NonceContext = createContext5(void 0);
 
 // src/browser/react/use-action.ts
 import {
@@ -8112,8 +8116,8 @@ import {
 } from "react";
 
 // src/theme/theme-context.ts
-import { createContext as createContext5, useContext as useContext12 } from "react";
-var ThemeContext = createContext5(null);
+import { createContext as createContext6, useContext as useContext12 } from "react";
+var ThemeContext = createContext6(null);
 
 // src/theme/constants.ts
 var THEME_COOKIE = {
@@ -8155,7 +8159,7 @@ import {
 
 // src/browser/react/use-link-status.ts
 import {
-  createContext as createContext6,
+  createContext as createContext7,
   useContext as useContext13,
   useState as useState11,
   useEffect as useEffect11,
@@ -8163,7 +8167,7 @@ import {
   useOptimistic as useOptimistic3,
   startTransition as startTransition4
 } from "react";
-var LinkContext = createContext6(
+var LinkContext = createContext7(
   null
 );
 
@@ -8988,7 +8992,10 @@ init_redirect_origin();
 import {
   createElement as createElement4,
   Fragment as Fragment4,
+  Suspense as Suspense3,
+  useDeferredValue,
   useEffect as useEffect16,
+  useMemo as useMemo9,
   useState as useState15
 } from "react";
 
@@ -8997,6 +9004,8 @@ import { startTransition as startTransition6 } from "react";
 
 // src/client-urls/client-root.tsx
 import { jsx as jsx11, jsxs as jsxs4 } from "react/jsx-runtime";
+var PENDING_FOREVER = new Promise(() => {
+});
 
 // src/client-urls/server-projection.ts
 var SEARCH_SCHEMA_VALUES = /* @__PURE__ */ new Set([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.12.4",
+  "version": "0.14.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/client-urls/SKILL.md

@@ -17,8 +17,9 @@ latency. `clientUrls()` makes that shape unrepresentable.
 This is the fastest-transition shape Rango has, and the natural fit for
 dashboard / admin / settings-style apps — high navigation frequency inside one
 layout, mostly tab/param/filter switches. Three things compound: the
-definition also matches in the browser, so a soft navigation presents
-optimistic pending UI immediately (`useOutlet().pending`) with no server
+definition also matches in the browser, so a soft navigation renders the
+destination component immediately (loader reads suspend into `loading()` or
+an inline `<Suspense>`; `useOutlet().pending` flips for chrome) with no server
 round-trip to start; browser-run `revalidate()` predicates HOLD data across
 navigations that don't invalidate it (a tab switch re-runs nothing — only the
 decision crosses the wire); and any read that does refresh streams behind its
@@ -127,9 +128,9 @@ typing work exactly as for server routes (`/typesafety`).
 | `path()`       | Options are `name`, `search`, `trailingSlash`, `ppr` (shell caching — see /ppr skill; loader routes need `loading()` or capture refuses); no response variants |
 | `layout()`     | Must contain at least one `path()`                                                                                                                             |
 | `loader()`     | `loader(Def, use?)` or `loader(Def, { ssr: false }, use?)` — see below                                                                                         |
-| `loading()`    | Route/layout-level pending UI; inline `<Suspense>` at read sites is usually better                                                                             |
+| `loading()`    | Route-level boundary around the optimistic render; inline `<Suspense>` at read sites keeps the destination's chrome visible while only the reads wait          |
 | `revalidate()` | Valid **inside a loader() use callback only**; runs in the browser                                                                                             |
-| `transition()` | Data-only ViewTransition config — no `when` (that is a server-executed predicate)                                                                              |
+| `transition()` | Data-only ViewTransition animation config — no `when`; same-route navs in a group already hold previous content without it                                     |
 | `intercept()`  | Dot-local named target in the SAME definition; use may contain `loader()`/`loading()`                                                                          |
 
 `include`, `parallel`, `cache`, `middleware`, `errorBoundary`,

package/src/browser/navigation-bridge.ts

@@ -365,15 +365,18 @@ export function createNavigationBridge(
             scroll: options?.scroll,
             state: resolvedState,
           }),
-          hasUsableCache
-            ? {
+          isLeavingIntercept
+            ? { type: "leave-intercept" as const }
+            : {
                 type: "navigate" as const,
-                targetCacheSegments: cachedSegments,
-                targetCacheHandleData: cachedHandleData,
-              }
-            : isLeavingIntercept
-              ? { type: "leave-intercept" as const }
-              : undefined,
+                ...(hasUsableCache
+                  ? {
+                      targetCacheSegments: cachedSegments,
+                      targetCacheHandleData: cachedHandleData,
+                    }
+                  : {}),
+                optimisticPresented: clientUrlPresentation !== null,
+              },
         );
       } catch (error) {
         // Server-side redirect with location state: the current transaction's

package/src/browser/optimistic-commit.ts

@@ -0,0 +1,32 @@
+import type { ViewTransitionClass } from "../types/segments.js";
+
+/**
+ * Transition type added to the canonical commit of a navigation that already
+ * presented an optimistic clientUrls() destination (client-urls/client-root.tsx).
+ * The optimistic swap ran in a transition lane and got the route's configured
+ * <ViewTransition> animation; the commit then replaces the branch with the
+ * destination's own segment — identical pixels — so every router-placed
+ * boundary maps this type to "none" (withOptimisticCommitNone) and the user
+ * perceives one animated navigation, not two.
+ */
+export const OPTIMISTIC_COMMIT_TRANSITION_TYPE = "rango-optimistic-commit";
+
+/**
+ * Merge the "none" mapping for the optimistic-commit type into a
+ * <ViewTransition> class prop. A string class becomes the `default` entry of
+ * a map; an absent prop yields the shared type-only map (React falls back to
+ * the boundary's `default` prop for other types).
+ */
+const NONE_ONLY: ViewTransitionClass = Object.freeze({
+  [OPTIMISTIC_COMMIT_TRANSITION_TYPE]: "none",
+});
+
+export function withOptimisticCommitNone(
+  value: ViewTransitionClass | undefined,
+): ViewTransitionClass {
+  if (value === undefined) return NONE_ONLY;
+  if (typeof value === "string") {
+    return { default: value, [OPTIMISTIC_COMMIT_TRANSITION_TYPE]: "none" };
+  }
+  return { ...value, [OPTIMISTIC_COMMIT_TRANSITION_TYPE]: "none" };
+}

package/src/browser/partial-update.ts

@@ -30,6 +30,7 @@ import {
   validateExternalRedirect,
 } from "./validate-redirect-origin.js";
 import type { NavigationUpdate } from "./types.js";
+import { OPTIMISTIC_COMMIT_TRANSITION_TYPE } from "./optimistic-commit.js";
 import {
   collectClientRevalidationDecisions,
   setActiveInterceptTargets,
@@ -98,6 +99,13 @@ export type UpdateMode =
       targetCacheHandleData?: Record<string, Record<string, unknown[]>>;
       /** Source URL for intercept restore (popstate cache miss) */
       interceptSourceUrl?: string;
+      /**
+       * The bridge already presented an optimistic clientUrls() destination
+       * for this navigation: transition-lane commits add
+       * OPTIMISTIC_COMMIT_TRANSITION_TYPE so router <ViewTransition>
+       * boundaries do not animate the identical repaint.
+       */
+      optimisticPresented?: boolean;
     }
   | { type: "leave-intercept"; interceptSourceUrl?: string }
   | { type: "stale-revalidation"; interceptSourceUrl?: string }
@@ -555,6 +563,8 @@ export function createPartialUpdater(
       debugLog("[partial-update] updating document");
 
       const hasTransition = shouldStartViewTransition(reconciled.segments);
+      const optimisticPresented =
+        mode.type === "navigate" && mode.optimisticPresented === true;
       // [VT-DIAG] Gated behind INTERNAL_RANGO_DEBUG. Reports which reconciled
       // segment still carries a transition after the server-side when-gate, and
       // whether the commit will be held in a startTransition. If `withTransition`
@@ -594,6 +604,9 @@ export function createPartialUpdater(
         startTransition(() => {
           if (addTransitionType) {
             addTransitionType("navigation");
+            if (optimisticPresented) {
+              addTransitionType(OPTIMISTIC_COMMIT_TRANSITION_TYPE);
+            }
           }
           onUpdate({
             root: newTree,
@@ -601,7 +614,7 @@ export function createPartialUpdater(
             scroll: scrollPayload,
           });
         });
-      } else if (fullyPrefetched || isSameStructureNav) {
+      } else if (fullyPrefetched || isSameStructureNav || optimisticPresented) {
         // Content-hold commit, two triggers. Fully-prefetched nav: the payload
         // is fully resolved (forceAwait above), so the transition commits
         // synchronously — no fallback flash. Same-structure nav: the re-run
@@ -620,8 +633,14 @@ export function createPartialUpdater(
         // instead of revealing that boundary's fallback; its render happens
         // pre-commit inside the transition, so userland effects cannot run
         // first. Boundaries newly mounted by this nav still reveal their
-        // fallbacks (React shows new boundaries inside transitions).
+        // fallbacks (React shows new boundaries inside transitions). An
+        // optimistic clientUrls() presentation commits here too: the group
+        // segment reconciles in place (clientGroup key), so a read that still
+        // suspends must hold the presented content, not flash a fallback.
         startTransition(() => {
+          if (optimisticPresented && addTransitionType) {
+            addTransitionType(OPTIMISTIC_COMMIT_TRANSITION_TYPE);
+          }
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,

package/src/browser/react/use-params.ts

@@ -3,6 +3,7 @@
 import { useContext, useState, useEffect, useRef } from "react";
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.js";
+import { OptimisticLocationContext } from "../../client-urls/optimistic-location.js";
 
 const EMPTY_PARAMS: Record<string, string> = Object.freeze({});
 
@@ -10,7 +11,9 @@ const EMPTY_PARAMS: Record<string, string> = Object.freeze({});
  * Hook to access the current route params.
  *
  * Returns the merged route params from the matched route.
- * Updates when navigation completes, not during pending navigation.
+ * Updates when navigation completes, not during pending navigation — except
+ * inside an optimistically rendered clientUrls() destination, where it
+ * reports THAT route's params (see OptimisticLocationContext).
  *
  * @example
  * ```tsx
@@ -43,6 +46,7 @@ export function useParams<T>(
   selector?: (params: Record<string, string | undefined>) => T,
 ): T | Record<string, string | undefined> {
   const ctx = useContext(NavigationStoreContext);
+  const optimistic = useContext(OptimisticLocationContext);
 
   const [value, setValue] = useState<T | Record<string, string>>(() => {
     const params = ctx ? ctx.eventController.getParams() : EMPTY_PARAMS;
@@ -71,5 +75,8 @@ export function useParams<T>(
     return ctx.eventController.subscribe(update);
   }, []);
 
+  if (optimistic) {
+    return selector ? selector(optimistic.params) : optimistic.params;
+  }
   return value;
 }

package/src/browser/react/use-pathname.ts

@@ -2,12 +2,15 @@
 
 import { useContext, useState, useEffect, useRef } from "react";
 import { NavigationStoreContext } from "./context.js";
+import { OptimisticLocationContext } from "../../client-urls/optimistic-location.js";
 
 /**
  * Hook to access the current pathname.
  *
  * Returns the committed pathname string (excludes search params and hash).
- * Updates when navigation completes, not during pending navigation.
+ * Updates when navigation completes, not during pending navigation — except
+ * inside an optimistically rendered clientUrls() destination, where it
+ * reports THAT route's pathname (see OptimisticLocationContext).
  *
  * @example
  * ```tsx
@@ -17,6 +20,7 @@ import { NavigationStoreContext } from "./context.js";
  */
 export function usePathname(): string {
   const ctx = useContext(NavigationStoreContext);
+  const optimistic = useContext(OptimisticLocationContext);
 
   const [pathname, setPathname] = useState<string>(() => {
     if (!ctx) {
@@ -43,5 +47,5 @@ export function usePathname(): string {
     return ctx.eventController.subscribe(update);
   }, []);
 
-  return pathname;
+  return optimistic ? optimistic.pathname : pathname;
 }

package/src/browser/react/use-search-params.ts

@@ -10,6 +10,7 @@ import {
 } from "react";
 import { NavigationStoreContext } from "./context.js";
 import type { ReadonlyURLSearchParams } from "../types.js";
+import { OptimisticLocationContext } from "../../client-urls/optimistic-location.js";
 
 /**
  * Accepted shapes for the setter: a full replacement for the search string.
@@ -110,6 +111,7 @@ function normalizeInit(init: SearchParamsInit): URLSearchParams {
  */
 export function useSearchParams(): [ReadonlyURLSearchParams, SetSearchParams] {
   const ctx = useContext(NavigationStoreContext);
+  const optimistic = useContext(OptimisticLocationContext);
 
   // Seed from the store location on BOTH sides (mirrors usePathname): the
   // SSR store carries the live request's search, the browser store carries
@@ -167,8 +169,17 @@ export function useSearchParams(): [ReadonlyURLSearchParams, SetSearchParams] {
     });
   }, []);
 
+  // Inside an optimistically rendered clientUrls() destination the read side
+  // is THAT route's search (see OptimisticLocationContext); the setter keeps
+  // navigating from the committed location.
+  const optimisticSearch = optimistic?.search;
   return useMemo(
-    () => [searchParams, setSearchParams],
-    [searchParams, setSearchParams],
+    () => [
+      optimisticSearch === undefined
+        ? searchParams
+        : new URLSearchParams(optimisticSearch),
+      setSearchParams,
+    ],
+    [searchParams, setSearchParams, optimisticSearch],
   );
 }

package/src/cache/segment-codec.ts

@@ -215,6 +215,7 @@ export async function serializeSegments(
           loaderIds: segment.loaderIds,
           transition: segment.transition,
           mountPath: segment.mountPath,
+          clientGroup: segment.clientGroup,
         },
       };
     }),

package/src/client-urls/client-root.tsx

@@ -3,7 +3,10 @@
 import {
   createElement,
   Fragment,
+  Suspense,
+  useDeferredValue,
   useEffect,
+  useMemo,
   useState,
   type ReactNode,
 } from "react";
@@ -14,12 +17,18 @@ import {
   registerClientUrlGroup,
   type ClientUrlNavigationIntent,
 } from "./navigation.js";
+import {
+  OptimisticLocationContext,
+  type OptimisticLocation,
+} from "./optimistic-location.js";
 import type {
   ClientUrlInterceptRecord,
   ClientUrlPatterns,
   ClientUrlRouteRecord,
 } from "./types.js";
 
+const PENDING_FOREVER: Promise<never> = new Promise<never>(() => {});
+
 function findRoute(
   definition: ClientUrlPatterns,
   routeId: string,
@@ -120,29 +129,65 @@ export function ClientUrlsRoot({
     [definition, mount, namePrefix],
   );
 
-  const pendingRoute =
-    intent && intent.routeId !== routeId
-      ? findRoute(definition, intent.routeId)
-      : null;
-  // Presence must mirror the projection's hasLoading (`loading !== undefined`
-  // in server-projection.ts): a falsy-but-valid node like loading("") is still
-  // a configured destination loading state, not an absent one.
-  const hasPendingLoading =
-    pendingRoute !== null && pendingRoute.loading !== undefined;
-  const route = hasPendingLoading
-    ? pendingRoute
-    : findRoute(definition, routeId);
-  // ANY in-flight group navigation is pending — including same-route navs
-  // (intent.routeId === routeId). For the search-only shape (filters, tabs)
-  // the canonical commit is HELD in a transition (isSameStructureNav in
-  // partial-update.ts) with no content swap to signal progress — this flag
-  // is the only affordance. The urgent setIntent at nav start flips it
-  // immediately; the transition-wrapped clear() entangles with the held
-  // commit, so pending drops exactly when the data lands.
+  // Optimistic destination (design: docs/design/client-urls-optimistic-destination.md).
+  // `intent` is set urgently at navigation start so `pending` flips at once
+  // for chrome; the CONTENT swap keys off the deferred value so it renders in
+  // a transition lane: a destination that suspends with no boundary of its
+  // own keeps the previous content visible (React's transition hold — the
+  // pre-existing contract for routes without loading()), one with loading()
+  // or inline <Suspense> at its reads presents immediately. Same-route intents
+  // never swap: held data + transition() own that case.
   const pending = intent !== null;
-  let content: ReactNode = hasPendingLoading
-    ? pendingRoute.loading
-    : createElement(route.component, { key: route.id });
+  const presented = useDeferredValue(intent);
+  const optimisticRoute =
+    presented && presented.routeId !== routeId
+      ? findRoute(definition, presented.routeId)
+      : null;
+  const route = optimisticRoute ?? findRoute(definition, routeId);
+
+  // Pending entries for the destination's loaders: useLoader use()s a Promise
+  // found in `loaderStreams` (the streaming-loader lane), so a read suspends
+  // instead of throwing "not found in context". Nothing resolves them — the
+  // canonical commit mounts the destination's own segment with real data and
+  // unmounts this branch — so one shared promise serves every loader.
+  // Memoized on the intent: use() needs a stable identity across replays.
+  const optimistic = useMemo<{
+    streams: Record<string, Promise<never>>;
+    location: OptimisticLocation;
+  } | null>(
+    () =>
+      optimisticRoute && presented
+        ? {
+            streams: Object.fromEntries(
+              optimisticRoute.loaders.map((record) => [
+                record.loader.$$id,
+                PENDING_FOREVER,
+              ]),
+            ),
+            location: {
+              params: presented.params,
+              pathname: presented.pathname,
+              search: presented.search,
+            },
+          }
+        : null,
+    [optimisticRoute, presented],
+  );
+
+  // The wrapper chain below is IDENTICAL in the optimistic and the canonical
+  // render (only prop values change): together with the group-keyed segment
+  // (segment-system.tsx, ResolvedSegment.clientGroup) that is what lets the
+  // destination instance survive the canonical commit.
+  let content: ReactNode = createElement(route.component, { key: route.id });
+  if (route.loading !== undefined) {
+    // loading() is the route-level boundary for group routes (segment-system
+    // places no LoaderBoundary around them); presence mirrors the
+    // projection's hasLoading (loading("") is still a configured fallback).
+    content = createElement(Suspense, {
+      fallback: route.loading,
+      children: content,
+    });
+  }
 
   for (let index = route.layouts.length - 1; index >= 0; index--) {
     const layoutKey = `${route.id}-layout-${index}`;
@@ -154,7 +199,15 @@ export function ClientUrlsRoot({
     });
   }
 
-  return content;
+  return createElement(OutletProvider, {
+    content: null,
+    loaderStreams: optimistic?.streams,
+    pending,
+    children: createElement(OptimisticLocationContext.Provider, {
+      value: optimistic?.location ?? null,
+      children: content,
+    }),
+  });
 }
 
 export function ClientUrlsLoading({

package/src/client-urls/navigation.ts

@@ -11,6 +11,11 @@ import type { ClientUrlPatterns } from "./types.js";
 
 export interface ClientUrlNavigationIntent {
   readonly routeId: string;
+  /** Destination params from the local trie match (definition-local). */
+  readonly params: Readonly<Record<string, string>>;
+  /** Absolute destination pathname (mount included) and search ("?..." or ""). */
+  readonly pathname: string;
+  readonly search: string;
 }
 
 interface ActiveClientUrlGroup {
@@ -112,7 +117,12 @@ export function beginClientUrlNavigation(
     if (activeInterceptTargets.has(canonicalName)) return null;
   }
 
-  const intent: ClientUrlNavigationIntent = { routeId: match.routeKey };
+  const intent: ClientUrlNavigationIntent = {
+    routeId: match.routeKey,
+    params: match.params,
+    pathname: targetUrl.pathname,
+    search: targetUrl.search,
+  };
   group.intent = intent;
   group.setIntent(intent);
 

package/src/client-urls/optimistic-location.ts

@@ -0,0 +1,22 @@
+"use client";
+
+import { createContext, type Context } from "react";
+
+/**
+ * Route identity of an optimistically rendered clientUrls() destination:
+ * the values the local trie match produced for the URL the user navigated
+ * to. Provided by ClientUrlsRoot around the optimistic branch ONLY, so
+ * useParams / usePathname / useSearchParams inside that branch describe the
+ * route being rendered while the same hooks in chrome outside it keep the
+ * committed location until the canonical response commits (or redirects, in
+ * which case the branch — and these values — are discarded).
+ */
+export interface OptimisticLocation {
+  readonly params: Readonly<Record<string, string>>;
+  readonly pathname: string;
+  /** Search string including the leading "?" (or ""). */
+  readonly search: string;
+}
+
+export const OptimisticLocationContext: Context<OptimisticLocation | null> =
+  createContext<OptimisticLocation | null>(null);

package/src/client-urls/server-projection.ts

@@ -481,8 +481,12 @@ function createLoaderStub(id: string): LoaderDefinition<unknown> {
   };
 }
 
-function materializedPathOptions(route: ClientUrlProjectionRoute): PathOptions {
+function materializedPathOptions(
+  route: ClientUrlProjectionRoute,
+  clientGroup: string,
+): PathOptions {
   return {
+    clientGroup,
     ...(route.name === null ? {} : { name: route.name }),
     ...(route.options.search ? { search: { ...route.options.search } } : {}),
     ...(route.options.trailingSlash
@@ -517,6 +521,9 @@ function materializeRouteItems(
   // route-name prefix is available here. ClientUrlsRoot needs it to compose
   // canonical names for intercept-target coordination in the browser.
   const namePrefix = getNamePrefix();
+  // One key per group MOUNT (the include's URL prefix): renderSegments keys
+  // every route segment of the group by it (ResolvedSegment.clientGroup).
+  const clientGroup = getUrlPrefix() || "/";
 
   // Helper calls attach to the CURRENT ctx.parent as they execute, so these
   // builders must run where the items belong: at the module top level for the
@@ -533,7 +540,7 @@ function materializeRouteItems(
               routeId: route.id,
               namePrefix,
             }),
-          materializedPathOptions(route),
+          materializedPathOptions(route, clientGroup),
           () => [
             ...route.loaderIds.map((id, loaderIndex) =>
               loader(

package/src/route-content-wrapper.tsx

@@ -32,15 +32,36 @@ import { LoaderRedirect } from "./loader-redirect.js";
  * Errors without any marker rethrow to the app's own boundaries.
  */
 export class StreamedLoaderErrorBoundary extends Component<
-  { children: ReactNode },
-  { error: unknown }
+  { children: ReactNode; resetKey?: string },
+  { error: unknown; resetKey?: string }
 > {
-  state: { error: unknown } = { error: null };
+  state: { error: unknown; resetKey?: string } = {
+    error: null,
+    resetKey: this.props.resetKey,
+  };
 
   static getDerivedStateFromError(error: unknown): { error: unknown } {
     return { error };
   }
 
+  /**
+   * A caught marker (redirect, notFound, error fallback) belongs to ONE route
+   * + params. Group-keyed segments (ResolvedSegment.clientGroup) keep this
+   * instance alive across in-group navigations, so the error must clear when
+   * the route or params change — otherwise a redirect caught for /legacy
+   * keeps rendering LoaderRedirect for /state. `resetKey` is the segment's
+   * id-params identity, the cadence the per-route remount used to provide.
+   */
+  static getDerivedStateFromProps(
+    props: { resetKey?: string },
+    state: { error: unknown; resetKey?: string },
+  ): { error: unknown; resetKey?: string } | null {
+    if (props.resetKey !== state.resetKey) {
+      return { error: null, resetKey: props.resetKey };
+    }
+    return null;
+  }
+
   render(): ReactNode {
     const { error } = this.state;
     if (error !== null && error !== undefined) {

package/src/router/segment-resolution/fresh.ts

@@ -468,6 +468,7 @@ export async function resolveSegment<TEnv>(
       ),
       params,
       belongsToRoute: true,
+      ...(entry.clientGroup ? { clientGroup: entry.clientGroup } : {}),
       ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
     });
   } else {

package/src/router/segment-resolution/revalidation.ts

@@ -907,6 +907,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
     ),
     params,
     belongsToRoute,
+    ...(entry.clientGroup ? { clientGroup: entry.clientGroup } : {}),
     ...(entry.type === "layout" || entry.type === "cache"
       ? { layoutName: entry.id }
       : {}),

package/src/segment-system.tsx

@@ -1,6 +1,7 @@
 import * as React from "react";
 import { createElement, type ReactNode, type ComponentType } from "react";
 import { OutletProvider } from "./outlet-provider.js";
+import { withOptimisticCommitNone } from "./browser/optimistic-commit.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
 import type { ResolvedSegment, RootLayoutProps } from "./types.js";
 import { decodeLoaderResults } from "./decode-loader-results.js";
@@ -145,6 +146,20 @@ function createViewTransitionBoundary(
   const { viewTransition: _viewTransition, ...vtProps } = transition;
   return createElement(ReactViewTransition, {
     ...vtProps,
+    // The commit after an optimistic clientUrls() presentation repaints the
+    // same pixels; it must not animate a second time (browser/optimistic-commit.ts).
+    // `default` always carries the mapping; an unset direction already falls
+    // through to it, so only set directions need their own merge.
+    ...(vtProps.enter !== undefined && {
+      enter: withOptimisticCommitNone(vtProps.enter),
+    }),
+    ...(vtProps.exit !== undefined && {
+      exit: withOptimisticCommitNone(vtProps.exit),
+    }),
+    ...(vtProps.update !== undefined && {
+      update: withOptimisticCommitNone(vtProps.update),
+    }),
+    default: withOptimisticCommitNone(vtProps.default),
     children,
   });
 }
@@ -335,6 +350,13 @@ export async function renderSegments(
       `Expected layout, route, error, or notFound segment, got ${node.segment.type}`,
     );
     const { component, id, params, loading } = node.segment;
+    // clientUrls() group routes: ONE React key and ONE wrapper shape per group
+    // mount (no LoaderBoundary/RouteContentWrapper — ClientUrlsRoot renders
+    // loading() itself), so an in-group navigation reconciles the mounted
+    // ClientUrlsRoot: the optimistic destination keeps its instance across the
+    // commit and same-route param navs hold instead of remounting. The
+    // server-side loading value still drives PPR masking and SSR.
+    const clientGroup = node.segment.clientGroup;
     const segNodeStart = segDebug ? performance.now() : 0;
 
     // Param-agnostic keys are opt-in via the transition() DSL (see
@@ -370,7 +392,10 @@ export async function renderSegments(
             .map(([k, v]) => `${k}=${v}`)
             .join(",")
         : "";
-    const key = paramStr ? `${id}-${paramStr}` : id;
+    // Route identity the per-route remount used to provide; group routes key
+    // by the group instead and pass it to the error boundary as its resetKey.
+    const idParamsKey = paramStr ? `${id}-${paramStr}` : id;
+    const key = clientGroup ? `cg:${clientGroup}` : idParamsKey;
 
     const loaderEntries = node.loaders.filter(
       (loader) => loader.loaderId && loader.loaderData !== undefined,
@@ -388,7 +413,7 @@ export async function renderSegments(
     }
 
     let nodeContent: ReactNode = null;
-    if (isRenderableLoading(loading)) {
+    if (!clientGroup && isRenderableLoading(loading)) {
       // forceAwait (popstate, stale-revalidation, fully-prefetched nav) renders a
       // loading() route with the route content ALREADY resolved, so its
       // RouteContentWrapper Suspender does not suspend for a microtask and flash
@@ -484,13 +509,14 @@ export async function renderSegments(
     // escaping to app boundaries. Wrapped UNCONDITIONALLY on loader presence
     // — streams and forceAwait lanes must produce the same tree shape or
     // lane changes remount the subtree (docs/tree-structure.md).
-    if (loaderEntries.length > 0) {
+    if (loaderEntries.length > 0 || clientGroup) {
       nodeContent = createElement(StreamedLoaderErrorBoundary, {
+        resetKey: idParamsKey,
         children: nodeContent,
       });
     }
 
-    if (loading !== undefined && loading !== null) {
+    if (!clientGroup && loading !== undefined && loading !== null) {
       const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
       let boundaryLoaderData: Promise<any[]> | any[] = loaderDataPromise;
       // SPIKE (streaming useLoader): per-loader streams for the boundary's

package/src/server/context.ts

@@ -69,6 +69,8 @@ export type EntryPropCommon = {
   cache?: EntryCacheConfig;
   /** URL prefix from include() scope, used for MountContext on client */
   mountPath?: string;
+  /** clientUrls() group key (PathOptions.clientGroup); route entries only. */
+  clientGroup?: string;
 };
 
 /**

package/src/types/segments.ts

@@ -193,6 +193,9 @@ export interface ResolvedSegment {
   notFoundInfo?: NotFoundInfo; // For notFound segments: the not found information
   // Mount path from include() scope, used for MountContext.Provider wrapping
   mountPath?: string;
+  /** clientUrls() group key (the include mount), shared by every route
+   *  segment of one group; see the group-route branch in segment-system.tsx. */
+  clientGroup?: string;
   /**
    * @internal Server-side marker: true when the segment's handler actually ran
    * this request (not skipped via the revalidate cache path). Used by

package/src/urls/path-helper.ts

@@ -154,6 +154,7 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       handler: wrappedHandler,
       pattern: prefixedPattern,
       ...(urlPrefix ? { mountPath: urlPrefix } : {}),
+      ...(options?.clientGroup ? { clientGroup: options.clientGroup } : {}),
       ...(isPassthroughHandler(handler)
         ? {
             isPrerender: true as const,

package/src/urls/pattern-types.ts

@@ -112,6 +112,9 @@ export interface PathOptions<
   trailingSlash?: TrailingSlashMode;
   /** Response type marker (set by path.json(), etc.) */
   [RESPONSE_TYPE]?: string;
+  /** @internal clientUrls() group key stamped by server-projection.ts; see
+   *  ResolvedSegment.clientGroup. */
+  clientGroup?: string;
 }
 
 /**