@rangojs/router 0.24.1 → 0.24.2

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

@@ -2,6 +2,13 @@ import type { ClientUrlPatterns } from "./types.js";
 import type { TransitionWhenFn } from "../types/segments.js";
 export interface ClientUrlNavigationIntent {
     readonly routeId: string;
+    /**
+     * The navigation began while an optimistic frame was on screen (a
+     * superseded navigation's): ClientUrlsRoot presents it even when its route
+     * is the committed one, so the committed params' data never comes back on
+     * screen.
+     */
+    readonly fromFrame: boolean;
     /** Destination params from the local trie match (definition-local). */
     readonly params: Readonly<Record<string, string>>;
     /** Absolute destination pathname (mount included) and search ("?..." or ""). */
@@ -39,7 +46,7 @@ export interface ClientUrlNavigationPresentation {
      * gated off), or undefined when nothing was swapped (a same-route
      * navigation decides at the canonical commit).
      */
-    readonly transitionGatedOff: boolean | undefined;
+    readonly transitionGatedOff?: boolean;
     clear(): void;
 }
 export declare function registerClientUrlGroup(definition: ClientUrlPatterns, mount: string, namePrefix: string, setIntent: (intent: ClientUrlNavigationIntent | null) => void, routeId?: string): () => void;

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

@@ -67,6 +67,12 @@ export interface ClientUrlRouteRecord {
      */
     readonly layoutKeys: readonly number[];
     readonly loaders: readonly ClientUrlLoaderRecord[];
+    /**
+     * The leading `loaders` its layout()s declare, the same record objects for
+     * every route under a layout (flattenLayout creates them once): ClientUrlsRoot
+     * keeps a shared one's committed data in the optimistic frame.
+     */
+    readonly layoutLoaders: readonly ClientUrlLoaderRecord[];
     readonly loading: ReactNode | undefined;
     readonly transition: Readonly<ClientTransitionConfig> | undefined;
 }

package/dist/vite/index.js

@@ -5929,7 +5929,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.24.1",
+  version: "0.24.2",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -10900,7 +10900,7 @@ import {
   Fragment as Fragment4,
   Suspense as Suspense3,
   useDeferredValue,
-  useEffect as useEffect17,
+  useLayoutEffect as useLayoutEffect3,
   useMemo as useMemo10,
   useState as useState14
 } from "react";

package/package.json

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

package/skills/client-urls/SKILL.md

@@ -527,7 +527,10 @@ a hard load of the target URL renders the full route.
   `startTransition` when no new segments mount, and the wrapping layout sees
   `useOutlet().pending === true` for the held window; a route-level
   `loading()` does not re-flash there. Across different routes, a `layout()`
-  keeps its instance while the navigation stays under it. `transition()` is not needed for the
+  keeps its instance while the navigation stays under it, and its own
+  `layout()` loaders keep their data on the optimistic frame (a cart count does
+  not suspend); only the destination's loaders and those of layouts it mounts
+  anew wait for the server. `transition()` is not needed for the
   hold; it adds the view-transition animation. Inline `<Suspense>` above each
   `useLoader` read is still the finer-grained tool when different reads on
   one route should wait independently.

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

@@ -5,7 +5,7 @@ import {
   Fragment,
   Suspense,
   useDeferredValue,
-  useEffect,
+  useLayoutEffect,
   useMemo,
   useState,
   type ReactNode,
@@ -17,10 +17,7 @@ import {
   registerClientUrlGroup,
   type ClientUrlNavigationIntent,
 } from "./navigation.js";
-import {
-  OptimisticLocationContext,
-  type OptimisticLocation,
-} from "./optimistic-location.js";
+import { OptimisticLocationContext } from "./optimistic-location.js";
 import type {
   ClientUrlInterceptRecord,
   ClientUrlPatterns,
@@ -124,11 +121,6 @@ export function ClientUrlsRoot({
   // same way client href()/useMount resolve include-relative URLs.
   const mount = useMount();
   const [intent, setIntent] = useState<ClientUrlNavigationIntent | null>(null);
-  useEffect(
-    () =>
-      registerClientUrlGroup(definition, mount, namePrefix, setIntent, routeId),
-    [definition, mount, namePrefix, routeId],
-  );
 
   // Optimistic destination (design: docs/design/client-urls-optimistic-destination.md).
   // `intent` is set urgently at navigation start so `pending` flips at once
@@ -137,46 +129,58 @@ export function ClientUrlsRoot({
   // 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. A navigation its
-  // transition({ when }) gated off at the swap presents urgently: no hold,
-  // no view transition, the destination's loading() streams.
+  // from the committed page never swap: held data + transition() own that
+  // case; one that began on an optimistic frame does (fromFrame). A
+  // navigation its transition({ when }) gated off at the swap presents
+  // urgently: no hold, no view transition, the destination's loading()
+  // streams.
   const pending = intent !== null;
   const deferred = useDeferredValue(intent);
   const presented = intent?.transitionGatedOff ? intent : deferred;
   const optimisticRoute =
-    presented && presented.routeId !== routeId
+    presented && (presented.routeId !== routeId || presented.fromFrame)
       ? findRoute(definition, presented.routeId)
       : null;
   const route = optimisticRoute ?? findRoute(definition, routeId);
 
+  // At commit, so a navigation reads what is on screen (no routeId while a
+  // frame is): React renders transition lanes one at a time, so the render
+  // that presents the next intent may still lack the canonical commit of the
+  // one it supersedes.
+  useLayoutEffect(
+    () =>
+      registerClientUrlGroup(
+        definition,
+        mount,
+        namePrefix,
+        setIntent,
+        optimisticRoute ? undefined : routeId,
+      ),
+    [definition, mount, namePrefix, routeId, optimisticRoute],
+  );
+
   // 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>(
+  // found in `loaderStreams`, so a read suspends instead of throwing "not
+  // found in context"; the canonical commit brings the real data. Skips the
+  // committed route's layout() records: flattenLayout creates them once per
+  // layout, so one the destination holds too is a layout both keep mounted
+  // (#1124), reading committed data. Route-own loaders always wait, also on
+  // a return to the committed route (fromFrame).
+  const loaderStreams = useMemo(
     () =>
-      optimisticRoute && presented
-        ? {
-            streams: Object.fromEntries(
-              optimisticRoute.loaders.map((record) => [
-                record.loader.$$id,
-                PENDING_FOREVER,
-              ]),
-            ),
-            location: {
-              params: presented.params,
-              pathname: presented.pathname,
-              search: presented.search,
-              state: presented.state,
-            },
-          }
-        : null,
-    [optimisticRoute, presented],
+      optimisticRoute
+        ? Object.fromEntries(
+            optimisticRoute.loaders
+              .filter(
+                (record) =>
+                  !findRoute(definition, routeId).layoutLoaders.includes(
+                    record,
+                  ),
+              )
+              .map((record) => [record.loader.$$id, PENDING_FOREVER]),
+          )
+        : undefined,
+    [optimisticRoute, definition, routeId],
   );
 
   // The wrapper chain below is IDENTICAL in the optimistic and the canonical
@@ -206,10 +210,11 @@ export function ClientUrlsRoot({
 
   return createElement(OutletProvider, {
     content: null,
-    loaderStreams: optimistic?.streams,
+    loaderStreams,
     pending,
     children: createElement(OptimisticLocationContext.Provider, {
-      value: optimistic?.location ?? null,
+      // The intent carries every OptimisticLocation field.
+      value: optimisticRoute ? presented : null,
       children: content,
     }),
   });

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

@@ -566,6 +566,9 @@ function createHelpers(): ClientUrlHelpers {
   });
 }
 
+// A layout()'s loader records are created once here and shared by every
+// route under it (ClientUrlRouteRecord.layoutLoaders); ClientUrlsRoot relies
+// on that identity (client-root.tsx).
 function applyConfig(
   context: FlattenContext,
   items: readonly InternalItem[],
@@ -619,6 +622,7 @@ function addPathRecord(
       layouts: Object.freeze([...routeContext.layouts]),
       layoutKeys: Object.freeze([...routeContext.layoutKeys]),
       loaders: Object.freeze([...routeContext.loaders]),
+      layoutLoaders: context.loaders,
       loading: routeContext.loading,
       transition: transitionItem
         ? Object.freeze({ ...transitionItem.config })

package/src/client-urls/navigation.ts

@@ -6,6 +6,13 @@ import type { TransitionWhenFn } from "../types/segments.js";
 
 export interface ClientUrlNavigationIntent {
   readonly routeId: string;
+  /**
+   * The navigation began while an optimistic frame was on screen (a
+   * superseded navigation's): ClientUrlsRoot presents it even when its route
+   * is the committed one, so the committed params' data never comes back on
+   * screen.
+   */
+  readonly fromFrame: boolean;
   /** Destination params from the local trie match (definition-local). */
   readonly params: Readonly<Record<string, string>>;
   /** Absolute destination pathname (mount included) and search ("?..." or ""). */
@@ -43,10 +50,13 @@ interface ActiveClientUrlGroup {
   readonly mount: string;
   /** include() route-name prefix ("" at root) for canonical name composition. */
   readonly namePrefix: string;
-  /** The group route on screen (ClientUrlsRoot's committed routeId). */
+  /**
+   * The group route on screen (ClientUrlsRoot's committed routeId), undefined
+   * while an optimistic frame is. Registered at commit.
+   */
   readonly routeId: string | undefined;
   readonly setIntent: (intent: ClientUrlNavigationIntent | null) => void;
-  intent: ClientUrlNavigationIntent | null;
+  intent?: ClientUrlNavigationIntent | null;
 }
 
 /**
@@ -74,7 +84,7 @@ export interface ClientUrlNavigationPresentation {
    * gated off), or undefined when nothing was swapped (a same-route
    * navigation decides at the canonical commit).
    */
-  readonly transitionGatedOff: boolean | undefined;
+  readonly transitionGatedOff?: boolean;
   clear(): void;
 }
 
@@ -110,7 +120,6 @@ export function registerClientUrlGroup(
     namePrefix,
     routeId,
     setIntent,
-    intent: null,
   };
   activeGroup = group;
 
@@ -151,9 +160,10 @@ export function beginClientUrlNavigation(
 
   const state = buildState?.();
 
-  // A same-route intent never swaps (ClientUrlsRoot), so transition({ when })
-  // decides at the canonical commit; a cross-route one decides here, at the
-  // navigation's first presentation.
+  // A same-route intent from the committed page never swaps (ClientUrlsRoot),
+  // so transition({ when }) decides at the canonical commit; one that swaps
+  // decides here, at the navigation's first presentation. While a frame is on
+  // screen, group.routeId is undefined and every intent swaps.
   let transitionGatedOff: boolean | undefined;
   if (decideTransition && match.routeKey !== group.routeId) {
     const originLocal = stripMountPrefix(window.location.pathname, group.mount);
@@ -171,6 +181,10 @@ export function beginClientUrlNavigation(
 
   const intent: ClientUrlNavigationIntent = {
     routeId: match.routeKey,
+    // From what React committed, not group.intent: a superseded intent is
+    // cleared when its canonical commit is handed over, before React renders
+    // it, and its frame is still on screen until then.
+    fromFrame: !group.routeId,
     params: match.params,
     pathname: targetUrl.pathname,
     search: targetUrl.search,
@@ -192,16 +206,10 @@ export function beginClientUrlNavigation(
     // updates land in order, so this changes nothing there.
     startTransition(() => group.setIntent(null));
   };
-  signal.addEventListener("abort", clear, { once: true });
+  // An abort after clear() finds another intent or none and does nothing.
+  signal.addEventListener("abort", clear);
 
-  return {
-    routeId: match.routeKey,
-    transitionGatedOff,
-    clear() {
-      signal.removeEventListener("abort", clear);
-      clear();
-    },
-  };
+  return { ...intent, clear };
 }
 
 export function clearClientUrlNavigationRegistry(): void {

package/src/client-urls/types.ts

@@ -114,6 +114,12 @@ export interface ClientUrlRouteRecord {
    */
   readonly layoutKeys: readonly number[];
   readonly loaders: readonly ClientUrlLoaderRecord[];
+  /**
+   * The leading `loaders` its layout()s declare, the same record objects for
+   * every route under a layout (flattenLayout creates them once): ClientUrlsRoot
+   * keeps a shared one's committed data in the optimistic frame.
+   */
+  readonly layoutLoaders: readonly ClientUrlLoaderRecord[];
   readonly loading: ReactNode | undefined;
   readonly transition: Readonly<ClientTransitionConfig> | undefined;
 }