@rangojs/router 0.24.3 → 0.25.0

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

@@ -1,3 +1,4 @@
+import { toShouldRevalidateFn } from "../router/revalidation.js";
 import type { ShouldRevalidateFn } from "../types.js";
 
 /**
@@ -6,7 +7,9 @@ import type { ShouldRevalidateFn } from "../types.js";
  * group's module loads in the RSC realm
  * (vite/plugins/client-urls-revalidate-hoist.ts); materialized loader stubs
  * read it (server-projection.ts). A key hashes the file and the predicate's
- * syntax, so a re-registration under one key is the same predicate.
+ * syntax, so a re-registration under one key is the same predicate. A
+ * hoisted boolean (`revalidate(FLAG)`) is stored as its constant predicate;
+ * any other value is left unregistered for materialization to name.
  *
  * Server-only build output, not router state: no router hook reads it
  * (AGENTS.md Hard rule 8).
@@ -14,9 +17,15 @@ import type { ShouldRevalidateFn } from "../types.js";
 const revalidators = new Map<string, ShouldRevalidateFn<any, any>>();
 
 export function registerClientUrlRevalidators(
-  fns: Readonly<Record<string, ShouldRevalidateFn<any, any>>>,
+  fns: Readonly<Record<string, ShouldRevalidateFn<any, any> | boolean>>,
 ): void {
-  for (const [key, fn] of Object.entries(fns)) revalidators.set(key, fn);
+  for (const [key, fn] of Object.entries(fns)) {
+    if (typeof fn === "function" || typeof fn === "boolean") {
+      revalidators.set(key, toShouldRevalidateFn(fn));
+    } else {
+      revalidators.delete(key);
+    }
+  }
 }
 
 export function getClientUrlRevalidator(

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

@@ -21,6 +21,7 @@ import type {
 import type { PathHelpers } from "../urls/path-helper-types.js";
 import type { AllUseItems } from "../route-types.js";
 import { urls } from "../urls/urls-function.js";
+import { toShouldRevalidateFn } from "../router/revalidation.js";
 import { isHoistedRevalidateRef } from "./hoisted-revalidate.js";
 import { getClientUrlRevalidator } from "./revalidate-registry.js";
 import { setLayoutLoaderCopies } from "./layout-loader-copies.js";
@@ -32,6 +33,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,
@@ -105,11 +113,11 @@ export interface ClientUrlProjectionRoute {
    *  loader(), so a prefetch of the route defers them. Absent (= none) in
    *  projections serialized before the option existed. */
   readonly deferrableLoaderIndices?: readonly number[];
-  /** Per loader (aligned with loaderIds), the keys of its hoisted
-   *  revalidate() predicates in declaration order; materialization attaches
-   *  the registered predicates (revalidate-registry.ts). Absent when no
-   *  loader declares one. */
-  readonly loaderRevalidate?: readonly (readonly string[])[];
+  /** Per loader (aligned with loaderIds), its revalidate() arguments in
+   *  declaration order: a hoisted predicate's key, whose registration
+   *  materialization attaches (revalidate-registry.ts), or a boolean
+   *  literal. Absent when no loader declares one. */
+  readonly loaderRevalidate?: readonly (readonly (string | boolean)[])[];
   /** 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
@@ -130,6 +138,10 @@ export interface ClientUrlProjectionIntercept {
   readonly targetName: string;
   readonly loaderIds: readonly string[];
   readonly hasLoading: boolean;
+  /** As on a route (ClientUrlProjectionRoute.deferrableLoaderIndices). */
+  readonly deferrableLoaderIndices?: readonly number[];
+  /** As on a route (ClientUrlProjectionRoute.loaderRevalidate). */
+  readonly loaderRevalidate?: readonly (readonly (string | boolean)[])[];
 }
 
 export interface ClientUrlProjection {
@@ -325,29 +337,10 @@ function serializeRoute(
     return loader.$$id;
   });
 
-  const loaderRevalidate = route.loaders.map(({ loader, revalidate }) =>
-    revalidate.flatMap((entry) => {
-      if (isHoistedRevalidateRef(entry)) return [entry.$$rangoRevalidate];
-      if (options.hoisted) {
-        throw new Error(
-          `clientUrls() revalidate() on loader "${loader.$$id}" of route ` +
-            `"${route.pattern}" was not hoisted to the server: call the ` +
-            "builder's revalidate() helper with an inline function or an " +
-            "imported predicate.",
-        );
-      }
-      return [];
-    }),
-  );
-
   const awaitedLoaderIndices = indicesWhere(
     route.loaders,
     ({ ssr }) => ssr === false,
   );
-  const deferrableLoaderIndices = indicesWhere(
-    route.loaders,
-    ({ prefetch }) => prefetch === false,
-  );
 
   const transition = serializeTransition(route);
   return Object.freeze({
@@ -360,6 +353,55 @@ function serializeRoute(
     ...(awaitedLoaderIndices.length > 0
       ? { awaitedLoaderIndices: Object.freeze(awaitedLoaderIndices) }
       : {}),
+    ...serializeLoaderOptions(
+      route.loaders,
+      `route "${route.pattern}"`,
+      options,
+    ),
+    ...(layoutLoaders.length > 0
+      ? { layoutLoaders: Object.freeze(layoutLoaders) }
+      : {}),
+    ...(transition ? { transition } : {}),
+    ...(typeof route.transition?.when === "function"
+      ? { transitionWhen: true as const }
+      : {}),
+  });
+}
+
+/**
+ * The loader options a route and an intercept project alike: the `prefetch:
+ * false` indices and each loader's revalidate() keys and boolean literals.
+ * Under `options.hoisted` a predicate the build left in place fails loudly.
+ */
+function serializeLoaderOptions(
+  loaders: readonly ClientUrlLoaderRecord[],
+  owner: string,
+  options: SerializeClientUrlPatternsOptions,
+): Pick<
+  ClientUrlProjectionRoute,
+  "deferrableLoaderIndices" | "loaderRevalidate"
+> {
+  const loaderRevalidate = loaders.map(({ loader, revalidate }) =>
+    revalidate.flatMap((entry): (string | boolean)[] => {
+      if (isHoistedRevalidateRef(entry)) return [entry.$$rangoRevalidate];
+      if (typeof entry === "boolean") return [entry];
+      if (options.hoisted) {
+        throw new Error(
+          `clientUrls() revalidate() on loader "${loader.$$id}" of ${owner} ` +
+            "was not hoisted to the server: call revalidate() (the builder's " +
+            'helper, or the one "@rangojs/router/client" exports for a ' +
+            "component's .use) with an inline function, an imported " +
+            "predicate or a boolean.",
+        );
+      }
+      return [];
+    }),
+  );
+  const deferrableLoaderIndices = indicesWhere(
+    loaders,
+    ({ prefetch }) => prefetch === false,
+  );
+  return {
     ...(deferrableLoaderIndices.length > 0
       ? { deferrableLoaderIndices: Object.freeze(deferrableLoaderIndices) }
       : {}),
@@ -370,19 +412,13 @@ function serializeRoute(
           ),
         }
       : {}),
-    ...(layoutLoaders.length > 0
-      ? { layoutLoaders: Object.freeze(layoutLoaders) }
-      : {}),
-    ...(transition ? { transition } : {}),
-    ...(typeof route.transition?.when === "function"
-      ? { transitionWhen: true as const }
-      : {}),
-  });
+  };
 }
 
 function serializeIntercept(
   record: ClientUrlInterceptRecord,
   index: number,
+  options: SerializeClientUrlPatternsOptions,
 ): ClientUrlProjectionIntercept {
   const loaderIds = record.loaders.map(({ loader }, loaderIndex) => {
     if (typeof loader.$$id !== "string" || loader.$$id.length === 0) {
@@ -399,6 +435,11 @@ function serializeIntercept(
     targetName: record.targetName,
     loaderIds: Object.freeze(loaderIds),
     hasLoading: record.loading !== undefined,
+    ...serializeLoaderOptions(
+      record.loaders,
+      `intercept ".${record.targetName}"`,
+      options,
+    ),
   });
 }
 
@@ -413,7 +454,9 @@ export function serializeClientUrlPatterns(
       patterns.routes.map((route) => serializeRoute(route, options, ordinals)),
     ),
     intercepts: Object.freeze(
-      (patterns.intercepts ?? []).map(serializeIntercept),
+      (patterns.intercepts ?? []).map((record, index) =>
+        serializeIntercept(record, index, options),
+      ),
     ),
   });
 }
@@ -529,28 +572,48 @@ export function clearClientUrlProjections(): void {
   clientUrlProjections.clear();
 }
 
+/** The projected loaders of a route or an intercept. */
+interface ProjectedLoaders {
+  readonly projected: Pick<
+    ClientUrlProjectionRoute,
+    | "loaderIds"
+    | "loaderRevalidate"
+    | "awaitedLoaderIndices"
+    | "deferrableLoaderIndices"
+  >;
+  /** Names the owner in an error: `route "/a"`, `intercept ".b"`. */
+  readonly label: string;
+  /** The owner's loader records in a definition object. */
+  readonly inline: (
+    patterns: ClientUrlPatterns,
+  ) => readonly ClientUrlLoaderRecord[] | undefined;
+}
+
 /**
- * The revalidate() predicates of one materialized loader. A definition
- * object (unit tests, the testing primitives) carries its functions. A
- * client reference resolves the projection's content keys in the registry
- * the group's hoisted module filled when it loaded; a key with no
- * registration fails loudly here, at materialization, never at a request.
+ * The revalidate() predicates of one materialized loader, a boolean as its
+ * constant predicate. A definition object (unit tests, the testing
+ * primitives) carries its functions. A client reference resolves the
+ * projection's content keys in the registry the group's hoisted module
+ * filled when it loaded; a key with no registration fails loudly here, at
+ * materialization, never at a request.
  */
 function loaderRevalidators(
   reference: ClientUrlDefinitionSource,
-  route: ClientUrlProjectionRoute,
+  { projected, label, inline }: ProjectedLoaders,
   loaderIndex: number,
 ): ShouldRevalidateFn<any, any>[] {
   const fromRegistry = (key: string): ShouldRevalidateFn<any, any> => {
     if (!getClientUrlRevalidator(key)) {
       const id = isClientUrlReference(reference) ? reference.$$id : "(inline)";
       throw new Error(
-        `clientUrls() revalidate() on loader "${route.loaderIds[loaderIndex]}" ` +
-          `of route "${route.pattern}" in "${id}" has no server ` +
+        `clientUrls() revalidate() on loader "${projected.loaderIds[loaderIndex]}" ` +
+          `of ${label} in "${id}" has no server ` +
           `registration (key "${key}"). The rango Vite plugin registers ` +
           "hoisted predicates when the group's module loads in the RSC " +
-          "environment; a transform that changed the predicate's syntax " +
-          "in one environment only also causes this.",
+          "environment, with those of the modules route discovery found " +
+          "its keys in (a component's .use). An argument that evaluated to " +
+          "neither a function nor a boolean there, or a transform that " +
+          "changed its syntax in one environment only, causes this.",
       );
     }
     // Looked up per call: a dev re-evaluation of the hoisted module
@@ -558,14 +621,17 @@ function loaderRevalidators(
     return (args) => getClientUrlRevalidator(key)!(args);
   };
   if (isClientUrlPatterns(reference)) {
-    const record = reference.routes.find(({ id }) => id === route.id);
-    return (record?.loaders[loaderIndex]?.revalidate ?? []).map((entry) =>
+    return (inline(reference)?.[loaderIndex]?.revalidate ?? []).map((entry) =>
       isHoistedRevalidateRef(entry)
         ? fromRegistry(entry.$$rangoRevalidate)
-        : entry,
+        : toShouldRevalidateFn(entry),
     );
   }
-  return (route.loaderRevalidate?.[loaderIndex] ?? []).map(fromRegistry);
+  return (projected.loaderRevalidate?.[loaderIndex] ?? []).map((entry) =>
+    toShouldRevalidateFn(
+      typeof entry === "boolean" ? entry : fromRegistry(entry),
+    ),
+  );
 }
 
 function createLoaderStub(id: string): LoaderDefinition<unknown> {
@@ -607,6 +673,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 +787,52 @@ 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 } : {};
+  };
+
+  // The loader() items of a route's or an intercept's projected loaders: each
+  // stub with its `ssr: false` and `prefetch: false` flags and its
+  // revalidate() predicates.
+  const materializeLoaders = (owner: ProjectedLoaders) =>
+    owner.projected.loaderIds.map((id, loaderIndex) => {
+      const revalidators = loaderRevalidators(reference, owner, loaderIndex);
+      return loader(
+        createLoaderStub(id),
+        {
+          ...(owner.projected.awaitedLoaderIndices?.includes(loaderIndex) && {
+            ssr: false,
+          }),
+          ...(owner.projected.deferrableLoaderIndices?.includes(
+            loaderIndex,
+          ) && { prefetch: false }),
+        },
+        () => revalidators.map((fn) => revalidate(fn)),
+      );
+    });
 
   // 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,27 +878,15 @@ function materializeRouteItems(
               definition: reference as ClientUrlPatterns,
               routeId: route.id,
               namePrefix,
+              ...foreignProp(),
             }),
           materializedPathOptions(route, clientGroup),
           recordingCopies(routeIndex, () => [
-            ...route.loaderIds.map((id, loaderIndex) => {
-              const revalidators = loaderRevalidators(
-                reference,
-                route,
-                loaderIndex,
-              );
-              return loader(
-                createLoaderStub(id),
-                {
-                  ...(route.awaitedLoaderIndices?.includes(loaderIndex) && {
-                    ssr: false,
-                  }),
-                  ...(route.deferrableLoaderIndices?.includes(loaderIndex) && {
-                    prefetch: false,
-                  }),
-                },
-                () => revalidators.map((fn) => revalidate(fn)),
-              );
+            ...materializeLoaders({
+              projected: route,
+              label: `route "${route.pattern}"`,
+              inline: (patterns) =>
+                patterns.routes.find(({ id }) => id === route.id)?.loaders,
             }),
             ...(route.hasLoading
               ? [
@@ -744,15 +938,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(
@@ -767,7 +973,12 @@ function materializeRouteItems(
             }),
           { when: isInGroupOrigin },
           () => [
-            ...record.loaderIds.map((id) => loader(createLoaderStub(id))),
+            ...materializeLoaders({
+              projected: record,
+              label: `intercept ".${record.targetName}"`,
+              inline: (patterns) =>
+                patterns.intercepts?.[interceptIndex]?.loaders,
+            }),
             ...(record.hasLoading
               ? [
                   loading(

package/src/client-urls/types.ts

@@ -28,6 +28,18 @@ export type ClientUrlItems = readonly ClientUrlItemInput[];
 
 export type ClientUrlUse = () => ClientUrlItems;
 
+/**
+ * A component path(), layout() or intercept() mounts. Its optional `use`
+ * carries its own items, as a server handler's `.use` does, built with the
+ * helpers `@rangojs/router/client` exports: they come before the mount
+ * site's explicit items (an explicit loading() or transition() wins, loaders
+ * accumulate). A page component may carry loader(), loading() and
+ * transition(); a layout or intercept component loader() and loading().
+ */
+export type ClientUrlComponent = ComponentType & {
+  readonly use?: ClientUrlUse;
+};
+
 export type ClientPathOptions<
   TName extends string = string,
   TSearch extends SearchSchema = SearchSchema,
@@ -42,13 +54,13 @@ export type ClientPathFn = <
   const TSearch extends SearchSchema = {},
 >(
   pattern: TPattern,
-  component: ComponentType,
+  component: ClientUrlComponent,
   optionsOrUse?: ClientPathOptions<TName, TSearch> | ClientUrlUse,
   use?: ClientUrlUse,
 ) => ClientUrlItem & TypedRouteItem<TName, TPattern, unknown, TSearch>;
 
 export type ClientLayoutFn = <const TItems extends ClientUrlItems>(
-  component: ComponentType,
+  component: ClientUrlComponent,
   children: () => TItems,
 ) => ClientUrlItem & TypedLayoutItem<ExtractRoutes<TItems>>;
 
@@ -57,11 +69,13 @@ export interface ClientUrlLoaderRecord {
   /**
    * Per-loader revalidate() predicates, run on the server; empty = the
    * router's defaults. Under the rango Vite plugin the browser and SSR copies
-   * hold the marker the build left in place of each hoisted predicate.
+   * hold the marker the build left in place of each hoisted predicate; a
+   * boolean literal stays in place.
    */
   readonly revalidate: readonly (
     | ShouldRevalidateFn<any, DefaultEnv>
     | HoistedRevalidateRef
+    | boolean
   )[];
   /**
    * loader(Def, { ssr: false }): document renders await this loader before
@@ -71,11 +85,10 @@ export interface ClientUrlLoaderRecord {
    */
   readonly ssr?: false;
   /**
-   * loader(Def, { prefetch: false }): a prefetch of the route defers this
-   * loader and the click that adopts it runs it in its fill request (see
-   * {@link LoaderOptions}). Projected onto the materialized stub. Inside
-   * intercept() it is not recorded: intercept loaders ignore the flag, as in
-   * urls().
+   * loader(Def, { prefetch: false }): a prefetch of the route, or of an
+   * intercept's target from its source, defers this loader and the click
+   * that adopts it runs it in its fill request (see {@link LoaderOptions}).
+   * Projected onto the materialized stub.
    */
   readonly prefetch?: false;
 }
@@ -126,7 +139,7 @@ export interface ClientUrlRouteRecord {
 
 /**
  * A restricted intercept declared inside clientUrls(). Compared to the server
- * intercept() there is no `when` selector, no middleware, and the target must
+ * intercept() there is no `when` selector, and the target must
  * be a dot-local NAMED route in the same definition — every field is
  * JSON-projectable, which is what makes the declaration legal in a
  * "use client" module. `targetName` is stored bare (no leading dot).
@@ -160,8 +173,8 @@ export interface ClientUrlHelpers {
    * the destination at once, commits the adopted prefetch with the other
    * loaders' data, and runs only the flagged loaders in its one fill
    * request. A `layout()` loader with the flag is flagged on every route
-   * below it. Inside intercept() the flag is accepted and ignored, as in
-   * urls().
+   * below it. Inside intercept() it defers the loader in a prefetch of the
+   * intercept from its source, as in urls().
    */
   readonly loader: <TData>(
     definition: LoaderDefinition<TData>,
@@ -176,10 +189,11 @@ export interface ClientUrlHelpers {
    * names, ...): the build moves it out of this "use client" module. It may
    * reference imports and globals only; a binding of this module, `this`,
    * `import()`, a browser global, an `async` function or an import from a
-   * "use client" module fails the build with its file and line.
+   * "use client" module fails the build with its file and line. A boolean
+   * is shorthand for `() => true` / `() => false`.
    */
   readonly revalidate: (
-    fn: ShouldRevalidateFn<any, DefaultEnv>,
+    fn: ShouldRevalidateFn<any, DefaultEnv> | boolean,
   ) => ClientUrlItem;
   /**
    * Declare an intercept for a named route in THIS definition. The target is
@@ -190,7 +204,7 @@ export interface ClientUrlHelpers {
   readonly intercept: (
     slotName: `@${string}`,
     targetName: `.${string}`,
-    component: ComponentType,
+    component: ClientUrlComponent,
     use?: ClientUrlUse,
   ) => ClientUrlItem;
   /**
@@ -198,7 +212,8 @@ export interface ClientUrlHelpers {
    * holds previous content instead of re-streaming the loading() fallback,
    * and on experimental React the config's ViewTransition classes apply.
    * Data-only — no `when` gate (server-executed; declare it in the server
-   * tree). Valid inside a path() use callback only.
+   * tree). Valid inside a path() use callback, or a page component's
+   * `.use`.
    */
   readonly transition: (config: ClientTransitionConfig) => ClientUrlItem;
 }
@@ -215,5 +230,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;
 }