@rangojs/router 0.12.3 → 0.13.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/client-urls/server-projection.d.ts

@@ -54,6 +54,14 @@ export interface ClientUrlProjection {
 export declare function serializeClientUrlPatterns(patterns: ClientUrlPatterns): ClientUrlProjection;
 export declare function isClientUrlPatterns(value: unknown): value is ClientUrlPatterns;
 export declare function isClientUrlReference(value: unknown): value is ClientUrlReference;
+/**
+ * A clientUrls() definition object or, on the server, its client reference.
+ * Run this BEFORE any duck-typing of the value (`typeof === "function"`,
+ * `.handler` reads): a client reference is a callable Proxy that throws on
+ * unknown property reads, so a later shape check would either invoke it as a
+ * thunk or surface React's "cannot dot into a client module" error.
+ */
+export declare function isClientUrlSource(value: unknown): value is ClientUrlDefinitionSource;
 export declare function setClientUrlProjection(reference: string | ClientUrlReference, projection: ClientUrlProjection): void;
 export declare function getClientUrlProjection(reference: string | ClientUrlReference): ClientUrlProjection | undefined;
 export declare function clearClientUrlProjections(): void;

package/dist/types/urls/include-provider.d.ts

@@ -1,12 +1,16 @@
 import type { UrlPatterns } from "./pattern-types.js";
+import type { ClientUrlPatterns } from "../client-urls/types.js";
 /**
  * What an async `include()` provider may resolve to: a `urls()` value directly,
  * or a module namespace whose `default` export is a `urls()` value (the shape
  * produced by `() => import("./routes")` when the route module does
- * `export default urls(...)`).
+ * `export default urls(...)`). A `clientUrls()` module resolves the same way
+ * (`() => import("./shop.client")`); on the server its `default` is the client
+ * reference, adapted exactly as the eager `include(prefix, clientUrlsDefault)`
+ * form.
  */
-export type IncludeModule<TEnv = any> = UrlPatterns<TEnv> | {
-    default: UrlPatterns<TEnv>;
+export type IncludeModule<TEnv = any> = UrlPatterns<TEnv> | ClientUrlPatterns | {
+    default: UrlPatterns<TEnv> | ClientUrlPatterns;
 };
 /**
  * An async/lazy include provider: a thunk returning a `urls()` value (or a
@@ -22,6 +26,7 @@ export type IncludeProvider<TEnv = any> = () => IncludeModule<TEnv> | Promise<In
 export declare function isIncludeProvider(value: unknown): value is IncludeProvider;
 /**
  * Normalize an async provider's resolved value to a `UrlPatterns`. Accepts a
- * `urls()` value directly or a module whose `default` export is one.
+ * `urls()`/`clientUrls()` value directly or a module whose `default` export is
+ * one.
  */
 export declare function resolveIncludeModule<TEnv = any>(mod: IncludeModule<TEnv>, id?: string): UrlPatterns<TEnv>;

package/dist/types/urls/path-helper-types.d.ts

@@ -40,10 +40,12 @@ export type TextResponsePathFn<TEnv> = <const TPattern extends string, const TNa
 /**
  * What an async include() provider resolves to. Route types (`TRoutes`) are
  * inferred from the resolved `urls()` value so `href()` and named routes stay
- * type-safe through a code-split module (`() => import("./routes")`).
+ * type-safe through a code-split module (`() => import("./routes")`). A
+ * clientUrls() module's default export types as ClientUrlPatterns, so
+ * `() => import("./shop.client")` infers the group's names the same way.
  */
-type IncludeResolved<TEnv, TRoutes extends Record<string, any>, TResponses extends Record<string, unknown>> = UrlPatterns<TEnv, TRoutes, TResponses> | {
-    default: UrlPatterns<TEnv, TRoutes, TResponses>;
+type IncludeResolved<TEnv, TRoutes extends Record<string, any>, TResponses extends Record<string, unknown>> = UrlPatterns<TEnv, TRoutes, TResponses> | ClientUrlPatterns<TRoutes> | {
+    default: UrlPatterns<TEnv, TRoutes, TResponses> | ClientUrlPatterns<TRoutes>;
 };
 /** include() argument: an eager `urls()` value or an async provider thunk. */
 export type IncludeArg<TEnv, TRoutes extends Record<string, any>, TResponses extends Record<string, unknown>> = UrlPatterns<TEnv, TRoutes, TResponses> | ClientUrlPatterns<TRoutes> | (() => IncludeResolved<TEnv, TRoutes, TResponses> | Promise<IncludeResolved<TEnv, TRoutes, TResponses>>);

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.3",
+  version: "0.13.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.3",
+  "version": "0.13.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -201,8 +201,8 @@
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "esbuild": "^0.28.1",
     "happy-dom": "^20.10.1",
     "jiti": "^2.7.0",

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
@@ -112,6 +113,10 @@ import shopUrls from "./shop.client.js";
 include("/shop", shopUrls, { name: "shop" });
 ```
 
+The async form works without a server wrapper module too:
+`include("/shop", () => import("./shop.client.js"), { name: "shop" })` — same
+behavior, no startup win, uniform with code-split server groups.
+
 Route names compose through the include (`shop.index`, `shop.product`) and
 flow into the generated route map, so `href`/`reverse` and `Handler<"...">`
 typing work exactly as for server routes (`/typesafety`).
@@ -123,7 +128,7 @@ 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)                                                                              |
 | `intercept()`  | Dot-local named target in the SAME definition; use may contain `loader()`/`loading()`                                                                          |

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,
@@ -622,6 +635,9 @@ export function createPartialUpdater(
         // first. Boundaries newly mounted by this nav still reveal their
         // fallbacks (React shows new boundaries inside transitions).
         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/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,61 @@ 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],
+  );
+
+  let content: ReactNode = createElement(route.component, { key: route.id });
+  if (optimisticRoute && optimisticRoute.loading !== undefined) {
+    // loading() is the route-level boundary around the optimistic render;
+    // presence mirrors the projection's hasLoading (a falsy-but-valid node
+    // like loading("") is still a configured fallback).
+    content = createElement(Suspense, {
+      fallback: optimisticRoute.loading,
+      children: content,
+    });
+  }
 
   for (let index = route.layouts.length - 1; index >= 0; index--) {
     const layoutKey = `${route.id}-layout-${index}`;
@@ -154,6 +195,18 @@ export function ClientUrlsRoot({
     });
   }
 
+  if (optimistic) {
+    content = createElement(OutletProvider, {
+      content: null,
+      loaderStreams: optimistic.streams,
+      pending,
+      children: createElement(OptimisticLocationContext.Provider, {
+        value: optimistic.location,
+        children: content,
+      }),
+    });
+  }
+
   return content;
 }
 

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

@@ -359,6 +359,19 @@ export function isClientUrlReference(
   }
 }
 
+/**
+ * A clientUrls() definition object or, on the server, its client reference.
+ * Run this BEFORE any duck-typing of the value (`typeof === "function"`,
+ * `.handler` reads): a client reference is a callable Proxy that throws on
+ * unknown property reads, so a later shape check would either invoke it as a
+ * thunk or surface React's "cannot dot into a client module" error.
+ */
+export function isClientUrlSource(
+  value: unknown,
+): value is ClientUrlDefinitionSource {
+  return isClientUrlPatterns(value) || isClientUrlReference(value);
+}
+
 /**
  * Strip vite's HMR timestamp query from a module id. After an HMR update of
  * a clientUrls module, the RSC graph re-imports it under

package/src/router.ts

@@ -3,10 +3,7 @@ import { createCacheScope } from "./cache/cache-scope.js";
 import { resolveCacheProfiles } from "./cache/profile-registry.js";
 import { isCachedFunction } from "./cache/taint.js";
 import { assertClientComponent } from "./component-utils.js";
-import {
-  isClientUrlPatterns,
-  isClientUrlReference,
-} from "./client-urls/server-projection.js";
+import { isClientUrlSource } from "./client-urls/server-projection.js";
 import type { ClientUrlPatterns } from "./client-urls/types.js";
 import { DefaultDocument } from "./components/DefaultDocument.js";
 import type { SerializedManifest } from "./debug.js";
@@ -784,10 +781,7 @@ export function createRouter<TEnv = any>(
       // same lazy include materialization, so no ordering, one-definition, or
       // deferral rules exist. Prefixing, wrapping RSC layouts, and middleware
       // scope still come from mounting through include() in urls() yourself.
-      if (
-        isClientUrlPatterns(patternsOrBuilder) ||
-        isClientUrlReference(patternsOrBuilder)
-      ) {
+      if (isClientUrlSource(patternsOrBuilder)) {
         const clientSource = patternsOrBuilder as ClientUrlPatterns;
         patternsOrBuilder = urls(({ include }) => [
           include("/", clientSource, { name: "" }),

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,
   });
 }

package/src/urls/include-helper.ts

@@ -13,8 +13,7 @@ import type { IncludeProvider } from "./include-provider.js";
 import type { IncludeFn } from "./path-helper-types.js";
 import {
   clientUrlIncludePatterns,
-  isClientUrlPatterns,
-  isClientUrlReference,
+  isClientUrlSource,
 } from "../client-urls/server-projection.js";
 import type { ClientUrlPatterns } from "../client-urls/types.js";
 
@@ -77,14 +76,11 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
   ): IncludeItem => {
     const { ctx } = requireDslContext("include() must be called inside urls()");
 
-    // clientUrls() sources mount through include() like any urls() module.
-    // Detect them FIRST: a client REFERENCE is a callable proxy, so the
-    // downstream provider check (`typeof === "function"`) would otherwise
-    // invoke it as an async include thunk. The substituted handler defers
-    // materialization to evaluation time, when the discovery-installed
-    // projection is available; the include machinery then applies URL and
-    // route-name prefixes exactly as for server modules.
-    if (isClientUrlPatterns(patterns) || isClientUrlReference(patterns)) {
+    // clientUrls() sources mount like any urls() module: the adapter defers
+    // materialization to evaluation time (projection installed by then) and
+    // the include machinery applies URL/name prefixes as for server modules.
+    // Ordering: see isClientUrlSource.
+    if (isClientUrlSource(patterns)) {
       patterns = clientUrlIncludePatterns(patterns) as UrlPatterns<TEnv>;
     }
 

package/src/urls/include-provider.ts

@@ -1,14 +1,23 @@
 import type { UrlPatterns } from "./pattern-types.js";
+import type { ClientUrlPatterns } from "../client-urls/types.js";
+import {
+  clientUrlIncludePatterns,
+  isClientUrlSource,
+} from "../client-urls/server-projection.js";
 
 /**
  * What an async `include()` provider may resolve to: a `urls()` value directly,
  * or a module namespace whose `default` export is a `urls()` value (the shape
  * produced by `() => import("./routes")` when the route module does
- * `export default urls(...)`).
+ * `export default urls(...)`). A `clientUrls()` module resolves the same way
+ * (`() => import("./shop.client")`); on the server its `default` is the client
+ * reference, adapted exactly as the eager `include(prefix, clientUrlsDefault)`
+ * form.
  */
 export type IncludeModule<TEnv = any> =
   | UrlPatterns<TEnv>
-  | { default: UrlPatterns<TEnv> };
+  | ClientUrlPatterns
+  | { default: UrlPatterns<TEnv> | ClientUrlPatterns };
 
 /**
  * An async/lazy include provider: a thunk returning a `urls()` value (or a
@@ -36,9 +45,19 @@ function isUrlPatterns(value: unknown): value is UrlPatterns {
   );
 }
 
+/**
+ * A `urls()` value as is; a `clientUrls()` source through the same adapter the
+ * eager include() path applies (ordering: see isClientUrlSource).
+ */
+function toUrlPatterns(value: unknown): UrlPatterns | undefined {
+  if (isClientUrlSource(value)) return clientUrlIncludePatterns(value);
+  return isUrlPatterns(value) ? value : undefined;
+}
+
 /**
  * Normalize an async provider's resolved value to a `UrlPatterns`. Accepts a
- * `urls()` value directly or a module whose `default` export is one.
+ * `urls()`/`clientUrls()` value directly or a module whose `default` export is
+ * one.
  */
 export function resolveIncludeModule<TEnv = any>(
   mod: IncludeModule<TEnv>,
@@ -53,8 +72,8 @@ export function resolveIncludeModule<TEnv = any>(
   // 404s with a misleading error). A bare `() => urls(...)` provider (no
   // module) has no `default`, so it still resolves via the mod-as-value branch.
   const def = (mod as { default?: unknown })?.default;
-  if (isUrlPatterns(def)) return def as UrlPatterns<TEnv>;
-  if (isUrlPatterns(mod)) return mod as UrlPatterns<TEnv>;
+  const resolved = toUrlPatterns(def) ?? toUrlPatterns(mod);
+  if (resolved) return resolved as UrlPatterns<TEnv>;
   // The common failure is a module namespace whose `default` is missing or not a
   // urls() value (e.g. only named exports); `typeof` alone says "object" and
   // hides that, so name the keys present. "provider" (not "async provider") —
@@ -65,7 +84,7 @@ export function resolveIncludeModule<TEnv = any>(
       : typeof mod;
   throw new Error(
     `[@rangojs/router] include() provider${id ? ` for "${id}"` : ""} must ` +
-      `resolve to a urls() value — either returned directly or as the module's ` +
-      `\`default\` export (e.g. \`export default urls(...)\`). Got ${got}.`,
+      `resolve to a urls() or clientUrls() value — either returned directly or ` +
+      `as the module's \`default\` export (e.g. \`export default urls(...)\`). Got ${got}.`,
   );
 }

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

@@ -160,7 +160,9 @@ export type TextResponsePathFn<TEnv> = <
 /**
  * What an async include() provider resolves to. Route types (`TRoutes`) are
  * inferred from the resolved `urls()` value so `href()` and named routes stay
- * type-safe through a code-split module (`() => import("./routes")`).
+ * type-safe through a code-split module (`() => import("./routes")`). A
+ * clientUrls() module's default export types as ClientUrlPatterns, so
+ * `() => import("./shop.client")` infers the group's names the same way.
  */
 type IncludeResolved<
   TEnv,
@@ -168,7 +170,12 @@ type IncludeResolved<
   TResponses extends Record<string, unknown>,
 > =
   | UrlPatterns<TEnv, TRoutes, TResponses>
-  | { default: UrlPatterns<TEnv, TRoutes, TResponses> };
+  | ClientUrlPatterns<TRoutes>
+  | {
+      default:
+        | UrlPatterns<TEnv, TRoutes, TResponses>
+        | ClientUrlPatterns<TRoutes>;
+    };
 
 /** include() argument: an eager `urls()` value or an async provider thunk. */
 export type IncludeArg<