@rangojs/router 0.24.3 → 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/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;
@@ -101,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/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/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.3",
+  version: "0.24.4",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

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

package/skills/client-urls/SKILL.md

@@ -557,6 +557,16 @@ a hard load of the target URL renders the full route.
   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/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/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/navigation.ts

@@ -1,6 +1,7 @@
 "use client";
 
 import { startTransition } from "react";
+import { sameMountInstance } from "../router/substitute-pattern-params.js";
 import type { ClientUrlPatterns } from "./types.js";
 import type { TransitionWhenFn } from "../types/segments.js";
 
@@ -13,7 +14,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;
@@ -29,27 +33,27 @@ 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;
 }
 
 interface ActiveClientUrlGroup {
   readonly definition: ClientUrlPatterns;
-  /** include() mount prefix the group is rendered under ("/" at root). */
+  /**
+   * include() mount the group is rendered under ("/" at root): the PATTERN
+   * (`/:locale?`), as useMount() returns it.
+   */
   readonly mount: string;
   /** include() route-name prefix ("" at root) for canonical name composition. */
   readonly namePrefix: string;
+  /** The server's routes that compete with the group's (ClientUrlsRoot). */
+  readonly foreign: readonly string[] | undefined;
   /**
    * The group route on screen (ClientUrlsRoot's committed routeId), undefined
    * while an optimistic frame is. Registered at commit.
@@ -90,34 +94,19 @@ export interface ClientUrlNavigationPresentation {
 
 let activeGroup: ActiveClientUrlGroup | null = null;
 
-/**
- * Strip the include mount prefix from an absolute pathname, yielding the
- * definition-local pathname the module trie was built from. Returns null when
- * the pathname lies outside the mount — the navigation then targets a server
- * route and gets no optimistic presentation. Mirrors joinMount() in
- * use-reverse.ts: the bare mount maps to the module index "/".
- */
-function stripMountPrefix(pathname: string, mount: string): string | null {
-  if (mount === "" || mount === "/") return pathname;
-  const normalized = mount.endsWith("/") ? mount.slice(0, -1) : mount;
-  if (pathname === normalized) return "/";
-  if (pathname.startsWith(`${normalized}/`)) {
-    return pathname.slice(normalized.length);
-  }
-  return null;
-}
-
 export function registerClientUrlGroup(
   definition: ClientUrlPatterns,
   mount: string,
   namePrefix: string,
   setIntent: (intent: ClientUrlNavigationIntent | null) => void,
   routeId?: string,
+  foreign?: readonly string[],
 ): () => void {
   const group: ActiveClientUrlGroup = {
     definition,
     mount,
     namePrefix,
+    foreign,
     routeId,
     setIntent,
   };
@@ -138,20 +127,42 @@ export function beginClientUrlNavigation(
   const group = activeGroup;
   if (!group) return null;
 
-  const localPathname = stripMountPrefix(targetUrl.pathname, group.mount);
-  if (localPathname === null) return null;
-
-  const match = group.definition.match(localPathname);
+  // Not one of the group's routes under its mount pattern, or a server route
+  // that wins the URL (a foreign leaf): no optimistic presentation.
+  const match = group.definition.match(
+    targetUrl.pathname,
+    group.mount,
+    group.foreign,
+  );
   if (!match || match.redirectTo) return null;
+  const record = group.definition.routes.find(
+    (candidate) => candidate.id === match.routeKey,
+  );
+  if (!record) return null;
+  // Other mount params (`/en/...` to `/de/...`) are another instance of the
+  // group: a frame would render the destination inside the old instance's
+  // chrome (the server's layouts above the group, still the old locale's).
+  // Such a click leaves the group: a plain navigation. History still holds the
+  // committed entry while a frame is on screen, so it is the origin.
+  if (group.mount.includes(":")) {
+    const origin = group.definition.match(
+      window.location.pathname,
+      group.mount,
+      group.foreign,
+    );
+    if (
+      !origin ||
+      !sameMountInstance(group.mount, origin.params, match.params)
+    ) {
+      return null;
+    }
+  }
 
   // Decline when an intercept would claim this target: compose the matched
   // record's canonical route name (include namePrefix + local name) and check
   // it against the current location's intercept target set. Unnamed records
   // cannot be intercept targets (intercepts target route NAMES).
-  const record = group.definition.routes.find(
-    (candidate) => candidate.id === match.routeKey,
-  );
-  const canonicalName = record?.name
+  const canonicalName = record.name
     ? group.namePrefix
       ? `${group.namePrefix}.${record.name}`
       : record.name
@@ -166,15 +177,11 @@ export function beginClientUrlNavigation(
   // 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);
-    const originMatch =
-      originLocal === null ? null : group.definition.match(originLocal);
-    const when = record?.transition?.when;
+    const when = record.transition?.when;
     transitionGatedOff = decideTransition({
       params: match.params,
       routeName: canonicalName,
       when: typeof when === "function" ? when : undefined,
-      originLocalParamNames: Object.keys(originMatch?.params ?? {}),
       state,
     });
   }

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

@@ -32,6 +32,13 @@ import {
   ClientUrlsRoot,
 } from "./client-root.js";
 import { createClientUrlsWhenRef } from "../transition-when-ref.js";
+import type { TrieLeaf, TrieNode } from "../router/route-trie-builder.js";
+import { tryTrieMatch } from "../router/trie-matching.js";
+import { sameMountInstance } from "../router/substitute-pattern-params.js";
+import { getRouterTrie } from "../route-map-builder.js";
+import { _getRequestContext } from "../server/request-context.js";
+import { routeKeyOf } from "../urls/path-helper.js";
+import { buildClientUrlsTrie } from "./client-urls.js";
 import type {
   ClientTransitionConfig,
   ClientUrlInterceptRecord,
@@ -607,6 +614,100 @@ function materializedPathOptions(
   };
 }
 
+/** A param segment on a walked path; the leaf's `pa` names it. */
+const PARAM = "\0";
+
+/**
+ * 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 function competingPatterns(
+  router: TrieNode,
+  group: TrieNode,
+  own: ReadonlySet<string>,
+): string[] {
+  const found = new Set<string>();
+  const add = (leaf: TrieLeaf, path: readonly string[], tail = ""): void => {
+    if (own.has(leaf.n)) return;
+    let index = 0;
+    const pattern = path.map((piece) => {
+      if (piece[0] !== PARAM) return piece;
+      const name = leaf.pa?.[index++] ?? `p${index}`;
+      const allowed = leaf.cv?.[name];
+      return `/:${name}${allowed ? `(${allowed.join("|")})` : ""}${piece.slice(1)}`;
+    });
+    found.add(pattern.join("") + tail || "/");
+  };
+  const catchAll = (node: TrieNode, path: readonly string[]): void => {
+    const leaf = node.w!;
+    add(
+      leaf,
+      path,
+      leaf.pn === "*" ? "/*" : `/:${leaf.pn}${leaf.w1 ? "+" : "*"}`,
+    );
+  };
+  const everything = (node: TrieNode, path: readonly string[]): void => {
+    if (node.r) add(node.r, path);
+    if (node.w) catchAll(node, path);
+    for (const [key, child] of Object.entries(node.s ?? {})) {
+      everything(child, [...path, `/${key}`]);
+    }
+    if (node.p) everything(node.p.c, [...path, PARAM]);
+    for (const [suffix, child] of Object.entries(node.xp ?? {})) {
+      everything(child.c, [...path, PARAM + suffix]);
+    }
+  };
+  // Every child of the group's node that a segment `matches` lets through.
+  const groupSteps = (
+    node: TrieNode,
+    matches: (key: string) => boolean,
+  ): TrieNode[] => [
+    ...Object.entries(node.s ?? {}).flatMap(([key, child]) =>
+      matches(key) ? [child] : [],
+    ),
+    ...(node.p ? [node.p.c] : []),
+    ...Object.values(node.xp ?? {}).map((child) => child.c),
+  ];
+  const walk = (g: TrieNode, r: TrieNode, path: readonly string[]): void => {
+    if (g.w) return everything(r, path);
+    if (r.r && g.r) add(r.r, path);
+    if (r.w && (g.r || g.s || g.p || g.xp)) catchAll(r, path);
+    for (const [key, child] of Object.entries(r.s ?? {})) {
+      const next = [...path, `/${key}`];
+      if (g.s?.[key]) walk(g.s[key], child, next);
+      if (g.p) walk(g.p.c, child, next);
+      for (const [suffix, gx] of Object.entries(g.xp ?? {})) {
+        if (key.endsWith(suffix)) walk(gx.c, child, next);
+      }
+    }
+    if (r.p) {
+      for (const step of groupSteps(g, () => true)) {
+        walk(step, r.p.c, [...path, PARAM]);
+      }
+    }
+    for (const [suffix, child] of Object.entries(r.xp ?? {})) {
+      for (const step of groupSteps(g, (key) => key.endsWith(suffix))) {
+        walk(step, child.c, [...path, PARAM + suffix]);
+      }
+    }
+  };
+  walk(group, router, []);
+  return [...found];
+}
+
+/** competingPatterns per router trie, per group (name prefix and mount). */
+const COMPETING = new WeakMap<TrieNode, Map<string, readonly string[]>>();
+
+function currentRouterTrie(): TrieNode | undefined {
+  const routerId = _getRequestContext()?._routerId;
+  return routerId ? getRouterTrie(routerId) : undefined;
+}
+
 function materializeRouteItems(
   reference: ClientUrlDefinitionSource,
   projection: ClientUrlProjection,
@@ -627,6 +728,32 @@ function materializeRouteItems(
   // 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() || "/";
+  // The group's routes as the router's trie names them.
+  const own = new Set(
+    projection.routes.map((route) =>
+      routeKeyOf(namePrefix, route.pattern, route.name ?? undefined),
+    ),
+  );
+  // ClientUrlsRoot's `foreign`: the router's routes that compete with the
+  // group's for a URL, so the browser presents only what the server routes
+  // here (a `/:slug` route under `/:locale?` would claim a root `/login`).
+  const foreignProp = (): { foreign?: readonly string[] } => {
+    const router = currentRouterTrie();
+    if (!router) return {};
+    let byGroup = COMPETING.get(router);
+    if (!byGroup) COMPETING.set(router, (byGroup = new Map()));
+    const key = `${namePrefix} ${clientGroup}`;
+    let foreign = byGroup.get(key);
+    if (!foreign) {
+      foreign = competingPatterns(
+        router,
+        buildClientUrlsTrie(projection.routes, clientGroup),
+        own,
+      );
+      byGroup.set(key, foreign);
+    }
+    return foreign.length ? { foreign } : {};
+  };
 
   // 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
@@ -672,6 +799,7 @@ function materializeRouteItems(
               definition: reference as ClientUrlPatterns,
               routeId: route.id,
               namePrefix,
+              ...foreignProp(),
             }),
           materializedPathOptions(route, clientGroup),
           recordingCopies(routeIndex, () => [
@@ -744,15 +872,27 @@ function materializeRouteItems(
   //    out-of-group origin the slot's host layout is not in the rendered
   //    tree, so the modal would silently vanish. The declaration contract is
   //    module-local, so materialization synthesizes the origin check the DSL
-  //    deliberately does not expose: activate only when the origin pathname
-  //    is inside this include's mount. This is server-generated code — no
-  //    function crosses the "use client" projection boundary.
-  const mount = getUrlPrefix() || "/";
-  const isInGroupOrigin = ({ from }: InterceptSelectorContext): boolean =>
-    mount === "/"
-      ? true
-      : from.url.pathname === mount ||
-        from.url.pathname.startsWith(`${mount}/`);
+  //    deliberately does not expose: activate only when the origin is one of
+  //    this group's routes, in the target's mount instance. The router
+  //    matched the origin already: its route name, or for an unnamed one its
+  //    key in the router's trie, says whether it is the group's (a URL
+  //    prefix cannot: a `/:locale?` mount prefixes every path), and its
+  //    params whether another locale is another instance, a full page
+  //    (beginClientUrlNavigation in navigation.ts leaves the group for it
+  //    too). This is server-generated code — no function crosses the
+  //    "use client" projection boundary.
+  const isInGroupOrigin = ({ from, to }: InterceptSelectorContext): boolean => {
+    if (clientGroup === "/") return true;
+    const router = currentRouterTrie();
+    const key =
+      from.routeName ??
+      (router && tryTrieMatch(router, from.url.pathname)?.routeKey);
+    return (
+      !!key &&
+      own.has(key) &&
+      sameMountInstance(clientGroup, from.params, to.params)
+    );
+  };
   const slotNames = [...new Set(intercepts.map((record) => record.slotName))];
   const buildInterceptItems = (): AllUseItems[] =>
     intercepts.map(

package/src/client-urls/types.ts

@@ -215,5 +215,14 @@ export interface ClientUrlPatterns<
   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;
 }

package/src/router/substitute-pattern-params.ts

@@ -73,3 +73,37 @@ export function substitutePatternParams(
   if (hasTrailingSlash && !result.endsWith("/")) result += "/";
   return result;
 }
+
+/**
+ * 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 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;
+}
+
+/**
+ * Whether two matches of an include() mount pattern are in the same instance
+ * of the include: `/en/...` and `/de/...` under `/:locale` are not.
+ */
+export function sameMountInstance(
+  mount: string,
+  a: Readonly<Record<string, string>>,
+  b: Readonly<Record<string, string>>,
+): boolean {
+  return (
+    substitutePatternParams(mount, a, mount) ===
+    substitutePatternParams(mount, b, mount)
+  );
+}

package/src/urls/path-helper.ts

@@ -54,6 +54,21 @@ function applyNamePrefix(prefix: string | undefined, name: string): string {
   return `${prefix}.${name}`;
 }
 
+/**
+ * The key path() registers a route under: its name, or a `$path_` name built
+ * from its pattern, behind the include's name prefix.
+ */
+export function routeKeyOf(
+  namePrefix: string | undefined,
+  pattern: string,
+  name: string | undefined,
+): string {
+  return applyNamePrefix(
+    namePrefix,
+    name || `$path_${pattern.replace(/[/:*?]/g, "_")}`,
+  );
+}
+
 function resolveResponseType(
   options: PathOptions | undefined,
 ): string | undefined {
@@ -143,12 +158,10 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
 
     const prefixedPattern = applyUrlPrefix(urlPrefix, pattern);
 
-    const localName =
-      options?.name || `$path_${pattern.replace(/[/:*?]/g, "_")}`;
     if (options?.name) {
       validateUserRouteName(options.name);
     }
-    const routeName = applyNamePrefix(namePrefix, localName);
+    const routeName = routeKeyOf(namePrefix, pattern, options?.name);
 
     const namespace = `${ctx.namespace}.${store.getNextIndex("route")}.${routeName}`;