@rangojs/router 0.24.4 → 0.25.0

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";
@@ -112,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
@@ -137,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 {
@@ -332,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({
@@ -367,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) }
       : {}),
@@ -377,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) {
@@ -406,6 +435,11 @@ function serializeIntercept(
     targetName: record.targetName,
     loaderIds: Object.freeze(loaderIds),
     hasLoading: record.loading !== undefined,
+    ...serializeLoaderOptions(
+      record.loaders,
+      `intercept ".${record.targetName}"`,
+      options,
+    ),
   });
 }
 
@@ -420,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),
+      ),
     ),
   });
 }
@@ -536,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
@@ -565,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> {
@@ -755,6 +814,26 @@ function materializeRouteItems(
     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
   // flat (no-intercept) shape, or inside the group layout's children callback
@@ -803,24 +882,11 @@ function materializeRouteItems(
             }),
           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
               ? [
@@ -907,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;
 }

package/src/client.rsc.tsx

@@ -36,10 +36,20 @@ export {
 
 export { createLoader } from "./route-definition.js";
 
-export { clientUrls } from "./client-urls/client-urls.js";
+// A module that is not "use client" and declares a component's `.use` can
+// evaluate in the RSC realm too.
+export {
+  clientUrls,
+  loader,
+  loading,
+  revalidate,
+  transition,
+} from "./client-urls/client-urls.js";
 export type {
+  ClientUrlComponent,
   ClientUrlPatterns,
   ClientUrlRouteRecord,
+  ClientUrlUse,
 } from "./client-urls/client-urls.js";
 
 // "use client" hooks the default ./client entry exports. They are client

package/src/client.tsx

@@ -309,10 +309,18 @@ export {
   type UseLoaderOptions,
 } from "./use-loader.js";
 
-export { clientUrls } from "./client-urls/client-urls.js";
+export {
+  clientUrls,
+  loader,
+  loading,
+  revalidate,
+  transition,
+} from "./client-urls/client-urls.js";
 export type {
+  ClientUrlComponent,
   ClientUrlPatterns,
   ClientUrlRouteRecord,
+  ClientUrlUse,
 } from "./client-urls/client-urls.js";
 
 /**

package/src/decode-loader-results.ts

@@ -1,6 +1,11 @@
 import type { ReactNode } from "react";
 import { createElement } from "react";
-import { isLoaderDataResult } from "./types.js";
+import {
+  isLoaderDataResult,
+  type ErrorInfo,
+  type ResolvedSegment,
+} from "./types.js";
+import { isPlaceholder } from "./types/segments.js";
 import { LoaderRedirect } from "./loader-redirect.js";
 
 /**
@@ -15,13 +20,13 @@ import { LoaderRedirect } from "./loader-redirect.js";
  * Only decodeLoaderEntry (the read-site path — client components, so the
  * throw lands in the router-owned boundary; during document SSR, Fizz emits
  * the Suspense fallback and replays the throw at hydration) throws these.
- * decodeLoaderResults runs during the SERVER tree build on forceAwait/action
- * lanes, where a throw would collapse the whole payload — it routes signals
- * through the errorFallback slot instead (same visual: the slot replaces the
- * children under OutletProvider). The document lane's `{ ssr: false }`
- * results take the same non-throwing route (segment-system
- * buildLoaderStreams): they are settled before the tree is built, and the
- * read-site throw would land in the Fizz shell with no boundary to absorb it.
+ * decodeLoaderResults runs during the tree build on settled results, where a
+ * throw would collapse the whole payload — it routes signals through the
+ * errorFallback slot instead (same visual: the slot replaces the children
+ * under OutletProvider). The document lane's `{ ssr: false }` results take
+ * this route (segment-system buildLoaderStreams): they are settled before the
+ * tree is built, and the read-site throw would land in the Fizz shell with no
+ * boundary to absorb it.
  */
 export const LOADER_NOT_FOUND_FALLBACK: unique symbol = Symbol(
   "rango.loaderNotFound",
@@ -65,6 +70,52 @@ function signalFallback(result: any): ReactNode | undefined {
   return undefined;
 }
 
+/**
+ * A failed loader entry's error, rebuilt with the ErrorInfo identity
+ * (name/stack/code/cause) instead of a stripped generic Error.
+ */
+export function loaderResultError(result: { error: ErrorInfo }): Error {
+  const info = result.error;
+  const err = new Error(
+    info.message,
+    info.cause !== undefined ? { cause: info.cause } : undefined,
+  );
+  if (info.name) err.name = info.name;
+  if (info.stack) err.stack = info.stack;
+  if (info.code !== undefined) (err as { code?: string }).code = info.code;
+  return err;
+}
+
+/** A loader that threw: not ok, and not a notFound()/redirect() signal. */
+export function isLoaderError(
+  result: unknown,
+): result is { error: ErrorInfo; fallback: ReactNode | null } {
+  return (
+    isLoaderDataResult(result) &&
+    !result.ok &&
+    !result.notFound &&
+    !result.redirect
+  );
+}
+
+/**
+ * The error of the first loader that threw while it re-ran in an action's
+ * revalidation, for useAction()'s `revalidationError`. The loader itself
+ * throws at its read (segment-system buildLoaderStreams), and the action
+ * resolves. A stale revalidation rejects with it instead and commits nothing
+ * (partial-update.ts). A notFound()/redirect() is a signal, not an error.
+ */
+export async function revalidationErrorOf(
+  segments: ResolvedSegment[] = [],
+): Promise<Error | undefined> {
+  for (const s of segments) {
+    if (s.type !== "loader" || isPlaceholder(s)) continue;
+    const entry = await s.loaderData;
+    if (isLoaderError(entry)) return loaderResultError(entry);
+  }
+  return undefined;
+}
+
 // Shared by segment-system (server) and LoaderResolver (client) so the
 // legacy/ok/error-fallback/throw decode of resolved loader values lives once.
 // Last failing loader wins errorFallback; an error without a fallback throws.
@@ -90,10 +141,9 @@ export function decodeLoaderResults(
     }
 
     // Authority signals take the errorFallback slot (this decode runs during
-    // the server tree build on forceAwait/action lanes — throwing here would
-    // collapse the payload). A signal outranks a plain error fallback and
-    // stops the scan: notFound renders the server-rendered 404 UI, redirect
-    // mounts LoaderRedirect which navigates.
+    // the tree build — throwing here would collapse the payload). A signal
+    // outranks a plain error fallback and stops the scan: notFound renders the
+    // server-rendered 404 UI, redirect mounts LoaderRedirect which navigates.
     const signal = signalFallback(result);
     if (signal !== undefined) {
       return { loaderData, errorFallback: signal };
@@ -108,17 +158,7 @@ export function decodeLoaderResults(
     if (result.fallback != null) {
       errorFallback = result.fallback;
     } else {
-      // No boundary: rethrow preserving the ErrorInfo identity (name/stack/
-      // code/cause) instead of a stripped generic Error.
-      const info = result.error;
-      const err = new Error(
-        info.message,
-        info.cause !== undefined ? { cause: info.cause } : undefined,
-      );
-      if (info.name) err.name = info.name;
-      if (info.stack) err.stack = info.stack;
-      if (info.code !== undefined) (err as { code?: string }).code = info.code;
-      throw err;
+      throw loaderResultError(result);
     }
   }
 
@@ -153,14 +193,7 @@ export function decodeLoaderEntry(result: any): any {
     return result.data;
   }
   throwSignal(result);
-  const info = result.error;
-  const err = new Error(
-    info.message,
-    info.cause !== undefined ? { cause: info.cause } : undefined,
-  );
-  if (info.name) err.name = info.name;
-  if (info.stack) err.stack = info.stack;
-  if (info.code !== undefined) (err as { code?: string }).code = info.code;
+  const err = loaderResultError(result);
   if (result.fallback != null) {
     (err as any)[LOADER_ERROR_FALLBACK] = result.fallback;
   }

package/src/href-client.ts

@@ -274,7 +274,9 @@ declare global {
  * Type-safe href function for client-side use
  *
  * Without mount: identity function, validates absolute paths at compile time.
- * With mount: prepends mount path, for use with useMount() inside include() scopes.
+ * With mount: prepends the mount as given. `useMount()` under a parameterized
+ * include returns its pattern (`/:accountId`), which this does not fill: use
+ * `useHref()` there, which substitutes the mount params.
  *
  * @param path - A valid path matching one of the registered route patterns
  * @param mount - Optional mount prefix from useMount() for include-scoped paths

package/src/index.rsc.ts

@@ -124,6 +124,7 @@ export {
   rewrite,
   type Rewrite,
   type RewriteFunction,
+  type RewriteShell,
 } from "./route-definition/rewrite.js";
 export { RewriteLoopError } from "./errors.js";
 

package/src/index.ts

@@ -134,6 +134,14 @@ function serverOnlyStubError(name: string): Error {
   );
 }
 
+/** A stub whose name `@rangojs/router/client` exports for clientUrls(). */
+function clientUrlsHelperStubError(name: string): Error {
+  return new Error(
+    `${name}() is only available from "@rangojs/router" in a react-server/RSC environment. ` +
+      `In a "use client" module (a clientUrls() component's .use), import ${name}() from "@rangojs/router/client".`,
+  );
+}
+
 /**
  * Error-throwing stub for server-only `urls` function.
  */
@@ -276,7 +284,7 @@ export function middleware(): never {
   throw serverOnlyStubError("middleware");
 }
 export function revalidate(): never {
-  throw serverOnlyStubError("revalidate");
+  throw clientUrlsHelperStubError("revalidate");
 }
 // Cache tag APIs are server-only (real implementations in index.rsc.ts). These
 // stubs keep the named-export shape identical under the default/non-react-server
@@ -291,10 +299,10 @@ export function revalidateTag(): never {
   throw serverOnlyStubError("revalidateTag");
 }
 export function loader(): never {
-  throw serverOnlyStubError("loader");
+  throw clientUrlsHelperStubError("loader");
 }
 export function loading(): never {
-  throw serverOnlyStubError("loading");
+  throw clientUrlsHelperStubError("loading");
 }
 export function parallel(): never {
   throw serverOnlyStubError("parallel");
@@ -309,7 +317,7 @@ export function notFoundBoundary(): never {
   throw serverOnlyStubError("notFoundBoundary");
 }
 export function transition(): never {
-  throw serverOnlyStubError("transition");
+  throw clientUrlsHelperStubError("transition");
 }
 
 // Request context type (safe for client)