@rangojs/router 0.13.0 → 0.14.0

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

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

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

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

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

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

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

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

package/dist/vite/index.js

@@ -3746,7 +3746,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.13.0",
+  version: "0.14.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

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

package/skills/client-urls/SKILL.md

@@ -130,7 +130,7 @@ typing work exactly as for server routes (`/typesafety`).
 | `loader()`     | `loader(Def, use?)` or `loader(Def, { ssr: false }, use?)` — see below                                                                                         |
 | `loading()`    | Route-level boundary around the optimistic render; inline `<Suspense>` at read sites keeps the destination's chrome visible while only the reads wait          |
 | `revalidate()` | Valid **inside a loader() use callback only**; runs in the browser                                                                                             |
-| `transition()` | Data-only ViewTransition config — no `when` (that is a server-executed predicate)                                                                              |
+| `transition()` | Data-only ViewTransition animation config — no `when`; same-route navs in a group already hold previous content without it                                     |
 | `intercept()`  | Dot-local named target in the SAME definition; use may contain `loader()`/`loading()`                                                                          |
 
 `include`, `parallel`, `cache`, `middleware`, `errorBoundary`,

package/src/browser/partial-update.ts

@@ -614,7 +614,7 @@ export function createPartialUpdater(
             scroll: scrollPayload,
           });
         });
-      } else if (fullyPrefetched || isSameStructureNav) {
+      } else if (fullyPrefetched || isSameStructureNav || optimisticPresented) {
         // Content-hold commit, two triggers. Fully-prefetched nav: the payload
         // is fully resolved (forceAwait above), so the transition commits
         // synchronously — no fallback flash. Same-structure nav: the re-run
@@ -633,7 +633,10 @@ export function createPartialUpdater(
         // instead of revealing that boundary's fallback; its render happens
         // pre-commit inside the transition, so userland effects cannot run
         // first. Boundaries newly mounted by this nav still reveal their
-        // fallbacks (React shows new boundaries inside transitions).
+        // fallbacks (React shows new boundaries inside transitions). An
+        // optimistic clientUrls() presentation commits here too: the group
+        // segment reconciles in place (clientGroup key), so a read that still
+        // suspends must hold the presented content, not flash a fallback.
         startTransition(() => {
           if (optimisticPresented && addTransitionType) {
             addTransitionType(OPTIMISTIC_COMMIT_TRANSITION_TYPE);

package/src/cache/segment-codec.ts

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

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

@@ -174,13 +174,17 @@ export function ClientUrlsRoot({
     [optimisticRoute, presented],
   );
 
+  // The wrapper chain below is IDENTICAL in the optimistic and the canonical
+  // render (only prop values change): together with the group-keyed segment
+  // (segment-system.tsx, ResolvedSegment.clientGroup) that is what lets the
+  // destination instance survive the canonical commit.
   let content: ReactNode = createElement(route.component, { key: route.id });
-  if (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).
+  if (route.loading !== undefined) {
+    // loading() is the route-level boundary for group routes (segment-system
+    // places no LoaderBoundary around them); presence mirrors the
+    // projection's hasLoading (loading("") is still a configured fallback).
     content = createElement(Suspense, {
-      fallback: optimisticRoute.loading,
+      fallback: route.loading,
       children: content,
     });
   }
@@ -195,19 +199,15 @@ 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;
+  return createElement(OutletProvider, {
+    content: null,
+    loaderStreams: optimistic?.streams,
+    pending,
+    children: createElement(OptimisticLocationContext.Provider, {
+      value: optimistic?.location ?? null,
+      children: content,
+    }),
+  });
 }
 
 export function ClientUrlsLoading({

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

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

package/src/route-content-wrapper.tsx

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

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

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

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

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

package/src/segment-system.tsx

@@ -350,6 +350,13 @@ export async function renderSegments(
       `Expected layout, route, error, or notFound segment, got ${node.segment.type}`,
     );
     const { component, id, params, loading } = node.segment;
+    // clientUrls() group routes: ONE React key and ONE wrapper shape per group
+    // mount (no LoaderBoundary/RouteContentWrapper — ClientUrlsRoot renders
+    // loading() itself), so an in-group navigation reconciles the mounted
+    // ClientUrlsRoot: the optimistic destination keeps its instance across the
+    // commit and same-route param navs hold instead of remounting. The
+    // server-side loading value still drives PPR masking and SSR.
+    const clientGroup = node.segment.clientGroup;
     const segNodeStart = segDebug ? performance.now() : 0;
 
     // Param-agnostic keys are opt-in via the transition() DSL (see
@@ -385,7 +392,10 @@ export async function renderSegments(
             .map(([k, v]) => `${k}=${v}`)
             .join(",")
         : "";
-    const key = paramStr ? `${id}-${paramStr}` : id;
+    // Route identity the per-route remount used to provide; group routes key
+    // by the group instead and pass it to the error boundary as its resetKey.
+    const idParamsKey = paramStr ? `${id}-${paramStr}` : id;
+    const key = clientGroup ? `cg:${clientGroup}` : idParamsKey;
 
     const loaderEntries = node.loaders.filter(
       (loader) => loader.loaderId && loader.loaderData !== undefined,
@@ -403,7 +413,7 @@ export async function renderSegments(
     }
 
     let nodeContent: ReactNode = null;
-    if (isRenderableLoading(loading)) {
+    if (!clientGroup && isRenderableLoading(loading)) {
       // forceAwait (popstate, stale-revalidation, fully-prefetched nav) renders a
       // loading() route with the route content ALREADY resolved, so its
       // RouteContentWrapper Suspender does not suspend for a microtask and flash
@@ -499,13 +509,14 @@ export async function renderSegments(
     // escaping to app boundaries. Wrapped UNCONDITIONALLY on loader presence
     // — streams and forceAwait lanes must produce the same tree shape or
     // lane changes remount the subtree (docs/tree-structure.md).
-    if (loaderEntries.length > 0) {
+    if (loaderEntries.length > 0 || clientGroup) {
       nodeContent = createElement(StreamedLoaderErrorBoundary, {
+        resetKey: idParamsKey,
         children: nodeContent,
       });
     }
 
-    if (loading !== undefined && loading !== null) {
+    if (!clientGroup && loading !== undefined && loading !== null) {
       const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
       let boundaryLoaderData: Promise<any[]> | any[] = loaderDataPromise;
       // SPIKE (streaming useLoader): per-loader streams for the boundary's

package/src/server/context.ts

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

package/src/types/segments.ts

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

package/src/urls/path-helper.ts

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

package/src/urls/pattern-types.ts

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