@rangojs/router 0.12.4 → 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/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.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.4",
+  "version": "0.13.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,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/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,
   });
 }