@rangojs/router 0.24.2 → 0.24.4

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

@@ -25,12 +25,15 @@ export declare function ClientUrlsInterceptLoading({ definition, interceptIndex,
     definition: ClientUrlPatterns;
     interceptIndex: number;
 }): ReactNode;
-export declare function ClientUrlsRoot({ definition, routeId, namePrefix, }: {
+export declare function ClientUrlsRoot({ definition, routeId, namePrefix, foreign, }: {
     definition: ClientUrlPatterns;
     routeId: string;
     /** include() route-name prefix, injected at materialization for canonical
      *  name composition (intercept-target coordination). */
     namePrefix?: string;
+    /** The server's routes that compete with the group's for a URL
+     *  (competingPatterns in server-projection.ts). */
+    foreign?: readonly string[];
 }): ReactNode;
 export declare function ClientUrlsLoading({ definition, routeId, }: {
     definition: ClientUrlPatterns;

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

@@ -1,5 +1,27 @@
+import { type TrieNode } from "../router/route-trie-builder.js";
 import type { ClientUrlBuilder, ClientUrlPatterns } from "./types.js";
 import type { ExtractRoutes } from "../urls/type-extraction.js";
 import type { ClientUrlItems } from "./types.js";
 export declare function clientUrls<const TItems extends ClientUrlItems>(builder: ClientUrlBuilder<TItems>): ClientUrlPatterns<ExtractRoutes<TItems>>;
+/**
+ * The router's trie over a group's routes, each pattern joined to the
+ * include() mount PATTERN (`/:locale?`, `/:accountId/:projectId`): an
+ * absolute pathname matches with the mount's params bound next to the
+ * route's, by the server's own precedence (an optional mount param expands
+ * like any other). Comparing the pathname with the mount as a literal prefix
+ * never matched a parameterized mount.
+ *
+ * `foreign` are the server's routes outside the group that compete with its
+ * routes for a URL (competingPatterns in server-projection.ts): a `/:slug`
+ * route under `/:locale?` matches a root `/login` too. Each is a leaf keyed by
+ * its own pattern, inserted last so an exact tie goes to it; a match on one is
+ * not the group's.
+ */
+export declare function buildClientUrlsTrie(routes: readonly {
+    readonly id: string;
+    readonly pattern: string;
+    readonly options?: {
+        readonly trailingSlash?: string;
+    };
+}[], mount: string, foreign?: readonly string[]): TrieNode;
 export type { ClientTransitionConfig, ClientUrlBuilder, ClientUrlHelpers, ClientUrlInterceptRecord, ClientUrlItem, ClientUrlItemInput, ClientUrlItems, ClientLayoutFn, ClientPathOptions, ClientUrlLoaderRecord, ClientPathFn, ClientUrlPatterns, ClientUrlRouteRecord, ClientUrlUse, } from "./types.js";

package/dist/types/client-urls/layout-loader-copies.d.ts

@@ -0,0 +1,11 @@
+import type { EntryData } from "../server/context.js";
+import type { LoaderDefinition } from "../types.js";
+export declare function setLayoutLoaderCopies(stub: LoaderDefinition<any>, ids: readonly string[]): void;
+/** True for the materialized stub of a clientUrls() layout() loader copy. */
+export declare function isLayoutLoaderCopy(stub: LoaderDefinition<any>): boolean;
+/**
+ * `held` with the id of each of `route`'s layout() loader copies whose
+ * loader the page holds under another route of the layout; `held` itself
+ * when there is none.
+ */
+export declare function withLayoutLoaderCopies(held: ReadonlySet<string>, route: EntryData): ReadonlySet<string>;

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

@@ -9,7 +9,10 @@ export interface ClientUrlNavigationIntent {
      * screen.
      */
     readonly fromFrame: boolean;
-    /** Destination params from the local trie match (definition-local). */
+    /**
+     * Destination params: the route's and its include() mount's, the params
+     * useParams() reads after the commit.
+     */
     readonly params: Readonly<Record<string, string>>;
     /** Absolute destination pathname (mount included) and search ("?..." or ""). */
     readonly pathname: string;
@@ -24,17 +27,12 @@ export interface ClientUrlNavigationIntent {
 }
 /** What the bridge needs to decide transition({ when }) at the swap. */
 export interface ClientUrlDestination {
-    /** Definition-local params of the destination match. */
+    /** Destination params, the include() mount's included. */
     readonly params: Readonly<Record<string, string>>;
     /** Canonical route name (include prefix applied); undefined when unnamed. */
     readonly routeName: string | undefined;
     /** The destination route's own `when`, from its "use client" definition. */
     readonly when: TransitionWhenFn | undefined;
-    /**
-     * Param names the ORIGIN route matched inside the group: the committed
-     * params minus these are the mount's (include prefix) params.
-     */
-    readonly originLocalParamNames: readonly string[];
     /** `history.state` the navigation will push (ClientUrlNavigationIntent.state). */
     readonly state: unknown;
 }
@@ -49,7 +47,7 @@ export interface ClientUrlNavigationPresentation {
     readonly transitionGatedOff?: boolean;
     clear(): void;
 }
-export declare function registerClientUrlGroup(definition: ClientUrlPatterns, mount: string, namePrefix: string, setIntent: (intent: ClientUrlNavigationIntent | null) => void, routeId?: string): () => void;
+export declare function registerClientUrlGroup(definition: ClientUrlPatterns, mount: string, namePrefix: string, setIntent: (intent: ClientUrlNavigationIntent | null) => void, routeId?: string, foreign?: readonly string[]): () => void;
 export declare function beginClientUrlNavigation(targetUrl: URL, signal: AbortSignal, 
 /** Builds the entry state; called only when the group presents the target. */
 buildState?: () => unknown, decideTransition?: (destination: ClientUrlDestination) => boolean): ClientUrlNavigationPresentation | null;

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

@@ -1,6 +1,7 @@
 import type { SearchSchemaValue } from "../search-params.js";
 import type { TrailingSlashMode } from "../types.js";
 import type { PartialPrerenderProps, UrlPatterns } from "../urls/pattern-types.js";
+import type { TrieNode } from "../router/route-trie-builder.js";
 import type { ClientTransitionConfig, ClientUrlPatterns } from "./types.js";
 export interface ClientUrlReference {
     readonly $$typeof: symbol;
@@ -42,6 +43,11 @@ export interface ClientUrlProjectionRoute {
      *  the registered predicates (revalidate-registry.ts). Absent when no
      *  loader declares one. */
     readonly loaderRevalidate?: readonly (readonly string[])[];
+    /** One per leading loader its layout()s declare
+     *  (ClientUrlRouteRecord.layoutLoaders): the record's ordinal in the
+     *  definition. Two routes whose loader at an index carries the same ordinal
+     *  hold one layout() loader (layout-loader-copies.ts). Absent when none. */
+    readonly layoutLoaders?: readonly number[];
     /** Data-only transition config (never `when`); absent in projections
      *  serialized before transition support. */
     readonly transition?: Readonly<ClientTransitionConfig>;
@@ -96,6 +102,16 @@ export declare function isClientUrlSource(value: unknown): value is ClientUrlDef
 export declare function setClientUrlProjection(reference: string | ClientUrlReference, projection: ClientUrlProjection): void;
 export declare function getClientUrlProjection(reference: string | ClientUrlReference): ClientUrlProjection | undefined;
 export declare function clearClientUrlProjections(): void;
+/**
+ * The patterns of the router's routes, outside the group, that a URL of the
+ * group matches too: the trie walked in step with the group's (its patterns
+ * joined to the mount), static against static, a param against either, a
+ * catch-all against everything below. Constraints are not compared, so the
+ * list may hold a route no URL of the group reaches: the client trie, which
+ * gets the patterns as they are, never lets one win a URL it does not match.
+ * `own` are the group's route keys in the router's trie.
+ */
+export declare function competingPatterns(router: TrieNode, group: TrieNode, own: ReadonlySet<string>): string[];
 export declare function materializeClientUrlPatterns(reference: ClientUrlDefinitionSource, projection: ClientUrlProjection): UrlPatterns;
 /**
  * Adapt a clientUrls() source for `include()` mounting inside the canonical

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

@@ -149,6 +149,11 @@ export interface ClientUrlPatterns<TRoutes extends Record<string, any> = Record<
     readonly intercepts: readonly ClientUrlInterceptRecord[];
     readonly [CLIENT_URL_PATTERNS_BRAND]: void;
     readonly _routes?: TRoutes;
-    match(pathname: string): TrieMatchResult | null;
+    /**
+     * Match an absolute pathname against the routes joined to `mount`, the
+     * include() mount pattern (default "/"); params include the mount's. A
+     * `foreign` pattern that wins is a match whose routeKey is that pattern.
+     */
+    match(pathname: string, mount?: string, foreign?: readonly string[]): TrieMatchResult | null;
 }
 export {};

package/dist/types/handles/pushed-by.d.ts

@@ -27,5 +27,12 @@ export declare function withSegmentHandles(target: HandleData, source: HandleDat
  * the position of the first value they replace (the end when they replace
  * none). New containers throughout: an object a reader was handed (a history
  * entry's data) is never written to.
+ *
+ * A segment with no values of a handle takes, for each loader `matched`
+ * registers on it that did not run, the values that loader pushed under a
+ * segment the page leaves, a slot excepted: a clientUrls() layout() loader the
+ * server held on a navigation between two routes of the layout
+ * (client-urls/layout-loader-copies.ts), whose pushes the page filed under
+ * the route it leaves.
  */
 export declare function mergePartialHandleData(current: HandleData, incoming: HandleData, segmentOrder: readonly string[], matched: readonly string[], resolvedIds: readonly string[] | undefined): HandleData;

package/dist/types/router/substitute-pattern-params.d.ts

@@ -21,3 +21,19 @@
  * identical across all three call sites.
  */
 export declare function substitutePatternParams(pattern: string, params: Record<string, string | undefined>, routeName: string): string;
+/**
+ * Join an include() mount with a mount-relative pattern. The mount is the
+ * include PATTERN (`/:locale?`), so the result is a pattern too.
+ *
+ * `pattern === "/"` is the index of the local module: under a non-root mount
+ * it collapses, so `/` under `/blog` becomes `/blog`, not `/blog/`. This
+ * matches `ctx.reverse(".index")` and, for a mount without a trailing slash,
+ * the route pattern the server registers (applyUrlPrefix in
+ * urls/path-helper.ts).
+ */
+export declare function joinMount(mount: string, pattern: string): string;
+/**
+ * Whether two matches of an include() mount pattern are in the same instance
+ * of the include: `/en/...` and `/de/...` under `/:locale` are not.
+ */
+export declare function sameMountInstance(mount: string, a: Readonly<Record<string, string>>, b: Readonly<Record<string, string>>): boolean;

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

@@ -353,6 +353,14 @@ interface HelperContext {
     includeScope?: string;
 }
 export declare const RangoContext: AsyncLocalStorage<HelperContext>;
+type ShortCodeType = "layout" | "parallel" | "route" | "loader" | "cache";
+/**
+ * The shortCode the `ahead`-th next `getShortCode(type)` call in this DSL
+ * context returns, without taking it. clientUrls() materialization reads the
+ * code of every group route this way, including the routes an evaluation for
+ * another route skips (client-urls/layout-loader-copies.ts).
+ */
+export declare function peekShortCode(type: ShortCodeType, ahead: number): string;
 export declare const getContext: () => {
     context: AsyncLocalStorage<HelperContext>;
     getStore: () => HelperContext;

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

@@ -1,5 +1,10 @@
 import type { Handler } from "../types.js";
 import type { PathFn, ResponsePathFn, JsonResponsePathFn, TextResponsePathFn } from "./path-helper-types.js";
+/**
+ * The key path() registers a route under: its name, or a `$path_` name built
+ * from its pattern, behind the include's name prefix.
+ */
+export declare function routeKeyOf(namePrefix: string | undefined, pattern: string, name: string | undefined): string;
 /**
  * A retained on-demand producer must never render on a live production
  * request: bundle eviction is skipped for onDemand routes (the producer body

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.2",
+  version: "0.24.4",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -11034,7 +11034,11 @@ function serializeTransition(route2) {
 function indicesWhere(items, pred) {
   return items.flatMap((item, index) => pred(item) ? [index] : []);
 }
-function serializeRoute(route2, options) {
+function serializeRoute(route2, options, ordinals) {
+  const layoutLoaders = route2.layoutLoaders.map((record) => {
+    if (!ordinals.has(record)) ordinals.set(record, ordinals.size);
+    return ordinals.get(record);
+  });
   const loaderIds = route2.loaders.map(({ loader: loader2 }, index) => {
     if (typeof loader2.$$id !== "string" || loader2.$$id.length === 0) {
       throw projectionError(
@@ -11078,6 +11082,7 @@ function serializeRoute(route2, options) {
         loaderRevalidate.map((keys) => Object.freeze(keys))
       )
     } : {},
+    ...layoutLoaders.length > 0 ? { layoutLoaders: Object.freeze(layoutLoaders) } : {},
     ...transition2 ? { transition: transition2 } : {},
     ...typeof route2.transition?.when === "function" ? { transitionWhen: true } : {}
   });
@@ -11099,10 +11104,11 @@ function serializeIntercept(record, index) {
   });
 }
 function serializeClientUrlPatterns(patterns, options = {}) {
+  const ordinals = /* @__PURE__ */ new Map();
   return Object.freeze({
     version: 1,
     routes: Object.freeze(
-      patterns.routes.map((route2) => serializeRoute(route2, options))
+      patterns.routes.map((route2) => serializeRoute(route2, options, ordinals))
     ),
     intercepts: Object.freeze(
       (patterns.intercepts ?? []).map(serializeIntercept)

package/package.json

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

package/skills/client-urls/SKILL.md

@@ -278,6 +278,18 @@ yet (a known gap, left for a follow-up). The build still checks those
 predicates like any other, so one that captures a binding of the `"use client"`
 module fails the build although nothing runs it: import it, or drop it.
 
+A group `layout()` loader revalidates as a server layout's loader does. With no
+`revalidate()` a navigation keeps it, whichever route of the layout it goes to
+and whatever params or search change (a same-route param navigation too), and
+an action re-runs it. Its `revalidate()` decides on every navigation and
+action, with that default as `defaultShouldRevalidate`: a shop layout's
+`loader(CartLoader, () => [revalidate(({ isAction }) => isAction(CartActions))])`
+runs on the document request and then only on cart actions, and the page
+commits without waiting for it. A navigation into the layout runs it. A layout
+loader that reads the route's params needs a rule that re-runs it:
+`revalidate(({ currentParams, nextParams, defaultShouldRevalidate }) =>
+currentParams.slug !== nextParams.slug ? true : defaultShouldRevalidate)`.
+
 Two scars worth copying:
 
 - A blunt `() => false` keeps serving the OLD product on product→product
@@ -455,7 +467,11 @@ makes the first flush, and `ssr: false` guarantees the loader's data does. It
 does not cover the client component's module: the first document a build's
 fresh server renders can still be waiting for it. The dev server matches a
 build here: when the shell is ready, it waits for the client components the
-payload has named and that are still loading, and for nothing else.
+payload has named and that are still loading, and for nothing else. On a
+document with an `ssr: false` loader, a part React finishes a moment after the
+shell, such as a `useActionState` form (React suspends it once to encode its
+action), is in the first flush too: the router gives React up to three more
+turns before it, and none when the document is already complete.
 
 ## `prefetch: false` — keep a loader out of prefetches
 
@@ -477,10 +493,16 @@ too, `useOutlet().pending` ends with that commit, and one follow-up request
 own `<Suspense>` to show the page and that fallback at once; with no boundary
 React holds the page being left until the fill answers, as it would with no
 prefetch. Same rules as on a server route (`/loader` → "`prefetch: false`"):
-only a segment new to the page is deferred, so a same-route click
-(`/product/a` to `/product/b`) prefetches the loader as usual.
-
-- On a `layout()` of the group the flag applies to every route below it.
+the flag skips a loader in a prefetch only when the loader is new to the page.
+A loader already on screen is never deferred: if its revalidation (its
+`revalidate()` or the default) re-runs it, it runs in the prefetch with the
+rest of the destination; otherwise it is held. A same-route click
+(`/product/a` to `/product/b`) is the familiar case.
+
+- A group `layout()` loader is on screen on every route of its layout: a
+  prefetch between two of them defers nothing for it (its `revalidate()`
+  decides, and with no rule it is held), and a prefetch that enters the
+  layout defers it.
 - A flagged `loader()` on a server layout above the group is deferred while
   that layout is new to the page (entering the group from outside).
 - `loading()` in `clientUrls()` takes no options, and a flagged `loading()`
@@ -529,11 +551,22 @@ a hard load of the target URL renders the full route.
   `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
+  not suspend), and in the canonical commit when their `revalidate()` holds
+  them; 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.
+- **Parameterized mounts.** A group under `include("/:locale", ...)`,
+  `include("/:locale?", ...)` or `include("/:accountId/:projectId", ...)`
+  presents at the click like one under a literal mount, and `useParams()` in
+  the destination carries the mount's params. A click that changes a mount
+  param (`/en/...` to `/de/...`) is another instance of the include: no
+  optimistic frame, a plain navigation. The group's intercepts open only from
+  one of its routes in the same mount instance. A URL the server routes
+  elsewhere (a root route that a group `/:slug` under `/:locale?` also
+  matches) never renders as a group route: the server ships the competing
+  routes with the group.
 - **Two parallel loaders with equal latency look "SSR'd" together.** Loaders
   kick off in parallel, so awaiting one (`ssr: false`) gives
   same-or-faster siblings time to settle coincidentally. Do not read "it was

package/skills/loader/SKILL.md

@@ -1128,10 +1128,13 @@ What happens:
 - A **prefetch** of the route does not run the loader and does not read its
   `cache()`; the payload marks it deferred. The rest of the page prefetches as
   usual.
-- Only on a route the browser does not show yet. A loader the page already
-  holds, on a same-route navigation such as `/product/a` to `/product/b`, runs
-  in the prefetch when it revalidates, exactly as without the flag, and the
-  click sends no second request. The rule: a click that adopts a prefetch is
+- Only on a loader new to the page. A loader already on screen is never
+  deferred: if its revalidation (its `revalidate()` or the default) re-runs
+  it, it runs in the prefetch with the rest of the destination, exactly as
+  without the flag, and the click sends no second request; otherwise it is
+  held. The familiar case is a same-route navigation such as `/product/a` to
+  `/product/b`; a `clientUrls()` group `layout()` loader is on screen on every
+  route of its layout the same way. The rule: a click that adopts a prefetch is
   never worse than the same click with no prefetch at all (one exception: a
   click before its prefetch has answered, under "The limits"), and content on
   screen is never swapped for a fallback because of the flag. For the same

package/src/browser/navigation-bridge.ts

@@ -457,20 +457,13 @@ export function createNavigationBridge(
                 ).filter((segment) => segment.clientGroup === undefined),
                 options?.replace ? "replace" : "push",
                 {
-                  to: (from) => {
-                    // Mount (include prefix) params carry over; the origin
-                    // route's own params do not.
-                    const params = { ...from.params };
-                    for (const name of destination.originLocalParamNames) {
-                      delete params[name];
-                    }
-                    return {
-                      url: targetUrl,
-                      params: { ...params, ...destination.params },
-                      routeName: destination.routeName,
-                      state: destination.state,
-                    };
-                  },
+                  // The destination's params include the mount's.
+                  to: () => ({
+                    url: targetUrl,
+                    params: destination.params,
+                    routeName: destination.routeName,
+                    state: destination.state,
+                  }),
                   extra: destination.when,
                 },
               ),

package/src/browser/react/use-reverse.ts

@@ -2,7 +2,10 @@
 
 import { useCallback } from "react";
 import type { LocalReverseFunction } from "../../reverse.js";
-import { substitutePatternParams } from "../../router/substitute-pattern-params.js";
+import {
+  joinMount,
+  substitutePatternParams,
+} from "../../router/substitute-pattern-params.js";
 import { serializeSearchParams } from "../../search-params.js";
 import { useMount } from "./use-mount.js";
 import { useParams } from "./use-params.js";
@@ -15,22 +18,6 @@ function getPattern(entry: RouteEntry | undefined): string | undefined {
   return typeof entry === "string" ? entry : entry.path;
 }
 
-/**
- * Join an include mount prefix with a mount-relative pattern.
- *
- * `pattern === "/"` is the index of the local module — under a non-root
- * mount it must collapse so `/` under `/blog` becomes `/blog`, not
- * `/blog/`. This matches `ctx.reverse(".index")` on the server.
- */
-function joinMount(mount: string, pattern: string): string {
-  if (pattern === "/") {
-    if (mount === "" || mount === "/") return "/";
-    return mount.endsWith("/") ? mount.slice(0, -1) : mount;
-  }
-  const normalizedMount = mount === "/" ? "" : mount.replace(/\/+$/, "");
-  return normalizedMount + pattern;
-}
-
 /**
  * Mount-aware reverse function for a locally-imported `routes` map.
  *

package/src/browser/segment-reconciler.ts

@@ -87,6 +87,19 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
   input.cachedSegments.forEach((s) => cachedSegments.set(s.id, s));
 
   const diffSet = new Set(diff);
+  // A clientUrls() layout() loader the server held on a navigation between
+  // two routes of the layout (client-urls/layout-loader-copies.ts): matched
+  // names it under the destination route, the page holds it under the group
+  // route it leaves. Its copy keeps its data under the new id.
+  const origin = input.cachedSegments.find((s) => s.clientGroup);
+  const destination =
+    origin &&
+    input.serverSegments.find((s) => s.clientGroup === origin.clientGroup);
+  const carried = (id: string) => {
+    const copy =
+      destination && cachedSegments.get(id.replace(destination.id, origin.id));
+    return copy && { ...copy, id };
+  };
   if (IS_BROWSER_DEBUG) {
     debugLog(
       `[reconcile] actor=${actor}, matched=${matched.length}, diff=${diff.length}`,
@@ -102,7 +115,7 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
   const segments = matched
     .map((segId: string) => {
       const fromServer = serverSegments.get(segId);
-      const fromCache = cachedSegments.get(segId);
+      let fromCache = cachedSegments.get(segId);
 
       if (fromServer) {
         const inDiff = diffSet.has(segId);
@@ -179,6 +192,7 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
       }
 
       // Fall back to cached segment (server expects client to already have it)
+      fromCache ??= carried(segId);
       if (!fromCache) {
         if (actor === "action") {
           console.error(`[Browser] MISSING SEGMENT: ${segId} not in cache!`);

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

@@ -108,17 +108,21 @@ export function ClientUrlsRoot({
   definition,
   routeId,
   namePrefix = "",
+  foreign,
 }: {
   definition: ClientUrlPatterns;
   routeId: string;
   /** include() route-name prefix, injected at materialization for canonical
    *  name composition (intercept-target coordination). */
   namePrefix?: string;
+  /** The server's routes that compete with the group's for a URL
+   *  (competingPatterns in server-projection.ts). */
+  foreign?: readonly string[];
 }): ReactNode {
-  // The include() mount prefix this group renders under ("/" at root). The
-  // module trie is built from definition-LOCAL patterns; navigation strips
-  // this prefix before matching (see stripMountPrefix in navigation.ts), the
-  // same way client href()/useMount resolve include-relative URLs.
+  // The include() mount pattern this group renders under ("/" at root).
+  // Navigation matches an absolute pathname against the definition's
+  // patterns joined to it (buildClientUrlsTrie in client-urls.ts), as
+  // useReverse joins it.
   const mount = useMount();
   const [intent, setIntent] = useState<ClientUrlNavigationIntent | null>(null);
 
@@ -155,8 +159,9 @@ export function ClientUrlsRoot({
         namePrefix,
         setIntent,
         optimisticRoute ? undefined : routeId,
+        foreign,
       ),
-    [definition, mount, namePrefix, routeId, optimisticRoute],
+    [definition, mount, namePrefix, routeId, optimisticRoute, foreign],
   );
 
   // Pending entries for the destination's loaders: useLoader use()s a Promise

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

@@ -1,6 +1,7 @@
 import type { ComponentType, ReactNode } from "react";
 import { validateUserRouteName } from "../route-name.js";
-import { buildRouteTrie } from "../router/route-trie-builder.js";
+import { buildRouteTrie, type TrieNode } from "../router/route-trie-builder.js";
+import { joinMount } from "../router/substitute-pattern-params.js";
 import { tryTrieMatch } from "../router/trie-matching.js";
 import type { LoaderDefinition } from "../types.js";
 import { isHoistedRevalidateRef } from "./hoisted-revalidate.js";
@@ -768,28 +769,58 @@ export function clientUrls<const TItems extends ClientUrlItems>(
   collectIntercepts(items, intercepts);
   validateIntercepts(intercepts, routes);
 
-  const routeManifest: Record<string, string> = {};
-  const staticPrefixes: Record<string, string> = {};
-  const trailingSlash: Record<string, string> = {};
-  for (const route of routes) {
-    routeManifest[route.id] = route.pattern;
-    staticPrefixes[route.id] = "";
-    if (route.options?.trailingSlash) {
-      trailingSlash[route.id] = route.options.trailingSlash;
-    }
-  }
-  const trie = buildRouteTrie(routeManifest, staticPrefixes, trailingSlash);
+  const tries = new Map<string, TrieNode>();
 
   return Object.freeze({
     __brand: "client-urls" as const,
     routes: Object.freeze(routes),
     intercepts: Object.freeze(intercepts),
-    match(pathname: string) {
+    match(pathname: string, mount = "/", foreign: readonly string[] = []) {
+      const key = `${mount} ${foreign}`;
+      let trie = tries.get(key);
+      if (!trie) {
+        tries.set(key, (trie = buildClientUrlsTrie(routes, mount, foreign)));
+      }
       return tryTrieMatch(trie, pathname);
     },
   }) as ClientUrlPatterns<ExtractRoutes<TItems>>;
 }
 
+/**
+ * The router's trie over a group's routes, each pattern joined to the
+ * include() mount PATTERN (`/:locale?`, `/:accountId/:projectId`): an
+ * absolute pathname matches with the mount's params bound next to the
+ * route's, by the server's own precedence (an optional mount param expands
+ * like any other). Comparing the pathname with the mount as a literal prefix
+ * never matched a parameterized mount.
+ *
+ * `foreign` are the server's routes outside the group that compete with its
+ * routes for a URL (competingPatterns in server-projection.ts): a `/:slug`
+ * route under `/:locale?` matches a root `/login` too. Each is a leaf keyed by
+ * its own pattern, inserted last so an exact tie goes to it; a match on one is
+ * not the group's.
+ */
+export function buildClientUrlsTrie(
+  routes: readonly {
+    readonly id: string;
+    readonly pattern: string;
+    readonly options?: { readonly trailingSlash?: string };
+  }[],
+  mount: string,
+  foreign: readonly string[] = [],
+): TrieNode {
+  const routeManifest: Record<string, string> = {};
+  const trailingSlash: Record<string, string> = {};
+  for (const route of routes) {
+    routeManifest[route.id] = joinMount(mount, route.pattern);
+    if (route.options?.trailingSlash) {
+      trailingSlash[route.id] = route.options.trailingSlash;
+    }
+  }
+  for (const pattern of foreign) routeManifest[pattern] = pattern;
+  return buildRouteTrie(routeManifest, {}, trailingSlash);
+}
+
 export type {
   ClientTransitionConfig,
   ClientUrlBuilder,

package/src/client-urls/layout-loader-copies.ts

@@ -0,0 +1,56 @@
+import type { EntryData } from "../server/context.js";
+import type { LoaderDefinition } from "../types.js";
+
+/**
+ * A clientUrls() layout()'s loaders are copied into every route record below
+ * it (client-urls.ts applyConfig), and a loader segment's id names its route
+ * (`${routeShortCode}D${index}.${$$id}`). On a navigation between two of the
+ * layout's routes the destination's copy was a segment the client lacked, so
+ * it ran whatever its revalidate() said.
+ *
+ * Materialization (server-projection.ts) records, for each copy, the ids the
+ * same layout() loader has under the group's other routes of that layout. A
+ * request whose page holds one of them holds the destination's copy: the
+ * loader's revalidate() decides, as on a param navigation, and a held copy is
+ * left out of the response. The browser carries the page's copy to the id
+ * `matched` names (browser/segment-reconciler.ts) with its handle pushes
+ * (handles/pushed-by.ts).
+ *
+ * A copy takes a server layout's revalidation default, not its route's: held
+ * on a navigation, params or search changes included, and re-run on an action
+ * (isLayoutLoaderCopy, segment-resolution/revalidation.ts).
+ *
+ * Keyed by the materialized loader stub, created once per evaluation of the
+ * route: the ids depend on the route's shortCode and its siblings'.
+ */
+const copies = new WeakMap<LoaderDefinition<any>, readonly string[]>();
+
+export function setLayoutLoaderCopies(
+  stub: LoaderDefinition<any>,
+  ids: readonly string[],
+): void {
+  copies.set(stub, ids);
+}
+
+/** True for the materialized stub of a clientUrls() layout() loader copy. */
+export function isLayoutLoaderCopy(stub: LoaderDefinition<any>): boolean {
+  return copies.has(stub);
+}
+
+/**
+ * `held` with the id of each of `route`'s layout() loader copies whose
+ * loader the page holds under another route of the layout; `held` itself
+ * when there is none.
+ */
+export function withLayoutLoaderCopies(
+  held: ReadonlySet<string>,
+  route: EntryData,
+): ReadonlySet<string> {
+  let out: Set<string> | undefined;
+  route.loader?.forEach(({ loader }, index) => {
+    if (copies.get(loader)?.some((id) => held.has(id))) {
+      (out ??= new Set(held)).add(`${route.shortCode}D${index}.${loader.$$id}`);
+    }
+  });
+  return out ?? held;
+}