@rangojs/router 0.24.0 → 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

@@ -58,7 +58,21 @@ export interface ClientUrlRouteRecord {
     readonly options: Readonly<ClientPathOptions> | undefined;
     readonly component: ComponentType;
     readonly layouts: readonly ComponentType[];
+    /**
+     * One per entry in `layouts`: the layout() item's ordinal among its sibling
+     * layout()s, its React key. Routes under the same layout() share it, so
+     * ClientUrlsRoot keeps that layout's instance across them (#1124). Keys only
+     * need to be unique among siblings: a differing parent layout remounts the
+     * whole subtree anyway.
+     */
+    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.0",
+  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.0",
+  "version": "0.24.2",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/client-urls/SKILL.md

@@ -526,7 +526,11 @@ a hard load of the target URL renders the full route.
   reconciles instead of remounting. The canonical commit runs in a
   `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. `transition()` is not needed for the
+  `loading()` does not re-flash there. Across different routes, a `layout()`
+  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
@@ -194,22 +198,23 @@ export function ClientUrlsRoot({
     });
   }
 
+  // Keyed per layout() item, not per route (#1124).
   for (let index = route.layouts.length - 1; index >= 0; index--) {
-    const layoutKey = `${route.id}-layout-${index}`;
     content = createElement(OutletProvider, {
-      key: layoutKey,
+      key: route.layoutKeys[index],
       content,
       pending,
-      children: createElement(route.layouts[index], { key: layoutKey }),
+      children: createElement(route.layouts[index]),
     });
   }
 
   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

@@ -154,12 +154,14 @@ interface LoadingItem extends ItemBase {
 
 interface FlattenContext {
   readonly layouts: readonly ComponentType[];
+  readonly layoutKeys: readonly number[];
   readonly loaders: readonly ClientUrlLoaderRecord[];
   readonly loading: ReactNode | undefined;
 }
 
 const EMPTY_CONTEXT: FlattenContext = {
   layouts: [],
+  layoutKeys: [],
   loaders: [],
   loading: undefined,
 };
@@ -564,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[],
@@ -588,6 +593,7 @@ function applyConfig(
 
   return {
     layouts: context.layouts,
+    layoutKeys: context.layoutKeys,
     loaders,
     loading,
   };
@@ -614,7 +620,9 @@ function addPathRecord(
       options,
       component: item.component,
       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 })
@@ -625,6 +633,7 @@ function addPathRecord(
 
 function flattenLayout(
   item: LayoutItem,
+  ordinal: number,
   context: FlattenContext,
   routes: ClientUrlRouteRecord[],
 ): void {
@@ -633,6 +642,7 @@ function flattenLayout(
     {
       ...context,
       layouts: [...context.layouts, item.component],
+      layoutKeys: [...context.layoutKeys, ordinal],
     },
     item.children,
   );
@@ -650,11 +660,12 @@ function flattenRoutes(
   context: FlattenContext,
   routes: ClientUrlRouteRecord[],
 ): void {
+  let layoutOrdinal = 0;
   for (const item of items) {
     if (item.type === "path") {
       addPathRecord(item, context, routes);
     } else if (item.type === "layout") {
-      flattenLayout(item, context, routes);
+      flattenLayout(item, layoutOrdinal++, context, routes);
     }
   }
 }

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

@@ -105,7 +105,21 @@ export interface ClientUrlRouteRecord {
   readonly options: Readonly<ClientPathOptions> | undefined;
   readonly component: ComponentType;
   readonly layouts: readonly ComponentType[];
+  /**
+   * One per entry in `layouts`: the layout() item's ordinal among its sibling
+   * layout()s, its React key. Routes under the same layout() share it, so
+   * ClientUrlsRoot keeps that layout's instance across them (#1124). Keys only
+   * need to be unique among siblings: a differing parent layout remounts the
+   * whole subtree anyway.
+   */
+  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;
 }