@rangojs/router 0.12.3 → 0.12.4

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

@@ -54,6 +54,14 @@ export interface ClientUrlProjection {
 export declare function serializeClientUrlPatterns(patterns: ClientUrlPatterns): ClientUrlProjection;
 export declare function isClientUrlPatterns(value: unknown): value is ClientUrlPatterns;
 export declare function isClientUrlReference(value: unknown): value is ClientUrlReference;
+/**
+ * A clientUrls() definition object or, on the server, its client reference.
+ * Run this BEFORE any duck-typing of the value (`typeof === "function"`,
+ * `.handler` reads): a client reference is a callable Proxy that throws on
+ * unknown property reads, so a later shape check would either invoke it as a
+ * thunk or surface React's "cannot dot into a client module" error.
+ */
+export declare function isClientUrlSource(value: unknown): value is ClientUrlDefinitionSource;
 export declare function setClientUrlProjection(reference: string | ClientUrlReference, projection: ClientUrlProjection): void;
 export declare function getClientUrlProjection(reference: string | ClientUrlReference): ClientUrlProjection | undefined;
 export declare function clearClientUrlProjections(): void;

package/dist/types/urls/include-provider.d.ts

@@ -1,12 +1,16 @@
 import type { UrlPatterns } from "./pattern-types.js";
+import type { ClientUrlPatterns } from "../client-urls/types.js";
 /**
  * What an async `include()` provider may resolve to: a `urls()` value directly,
  * or a module namespace whose `default` export is a `urls()` value (the shape
  * produced by `() => import("./routes")` when the route module does
- * `export default urls(...)`).
+ * `export default urls(...)`). A `clientUrls()` module resolves the same way
+ * (`() => import("./shop.client")`); on the server its `default` is the client
+ * reference, adapted exactly as the eager `include(prefix, clientUrlsDefault)`
+ * form.
  */
-export type IncludeModule<TEnv = any> = UrlPatterns<TEnv> | {
-    default: UrlPatterns<TEnv>;
+export type IncludeModule<TEnv = any> = UrlPatterns<TEnv> | ClientUrlPatterns | {
+    default: UrlPatterns<TEnv> | ClientUrlPatterns;
 };
 /**
  * An async/lazy include provider: a thunk returning a `urls()` value (or a
@@ -22,6 +26,7 @@ export type IncludeProvider<TEnv = any> = () => IncludeModule<TEnv> | Promise<In
 export declare function isIncludeProvider(value: unknown): value is IncludeProvider;
 /**
  * Normalize an async provider's resolved value to a `UrlPatterns`. Accepts a
- * `urls()` value directly or a module whose `default` export is one.
+ * `urls()`/`clientUrls()` value directly or a module whose `default` export is
+ * one.
  */
 export declare function resolveIncludeModule<TEnv = any>(mod: IncludeModule<TEnv>, id?: string): UrlPatterns<TEnv>;

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

@@ -40,10 +40,12 @@ export type TextResponsePathFn<TEnv> = <const TPattern extends string, const TNa
 /**
  * What an async include() provider resolves to. Route types (`TRoutes`) are
  * inferred from the resolved `urls()` value so `href()` and named routes stay
- * type-safe through a code-split module (`() => import("./routes")`).
+ * type-safe through a code-split module (`() => import("./routes")`). A
+ * clientUrls() module's default export types as ClientUrlPatterns, so
+ * `() => import("./shop.client")` infers the group's names the same way.
  */
-type IncludeResolved<TEnv, TRoutes extends Record<string, any>, TResponses extends Record<string, unknown>> = UrlPatterns<TEnv, TRoutes, TResponses> | {
-    default: UrlPatterns<TEnv, TRoutes, TResponses>;
+type IncludeResolved<TEnv, TRoutes extends Record<string, any>, TResponses extends Record<string, unknown>> = UrlPatterns<TEnv, TRoutes, TResponses> | ClientUrlPatterns<TRoutes> | {
+    default: UrlPatterns<TEnv, TRoutes, TResponses> | ClientUrlPatterns<TRoutes>;
 };
 /** include() argument: an eager `urls()` value or an async provider thunk. */
 export type IncludeArg<TEnv, TRoutes extends Record<string, any>, TResponses extends Record<string, unknown>> = UrlPatterns<TEnv, TRoutes, TResponses> | ClientUrlPatterns<TRoutes> | (() => IncludeResolved<TEnv, TRoutes, TResponses> | Promise<IncludeResolved<TEnv, TRoutes, TResponses>>);

package/dist/vite/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.12.3",
+  "version": "0.12.4",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -201,8 +201,8 @@
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "esbuild": "^0.28.1",
     "happy-dom": "^20.10.1",
     "jiti": "^2.7.0",

package/skills/client-urls/SKILL.md

@@ -112,6 +112,10 @@ import shopUrls from "./shop.client.js";
 include("/shop", shopUrls, { name: "shop" });
 ```
 
+The async form works without a server wrapper module too:
+`include("/shop", () => import("./shop.client.js"), { name: "shop" })` — same
+behavior, no startup win, uniform with code-split server groups.
+
 Route names compose through the include (`shop.index`, `shop.product`) and
 flow into the generated route map, so `href`/`reverse` and `Handler<"...">`
 typing work exactly as for server routes (`/typesafety`).

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

@@ -359,6 +359,19 @@ export function isClientUrlReference(
   }
 }
 
+/**
+ * A clientUrls() definition object or, on the server, its client reference.
+ * Run this BEFORE any duck-typing of the value (`typeof === "function"`,
+ * `.handler` reads): a client reference is a callable Proxy that throws on
+ * unknown property reads, so a later shape check would either invoke it as a
+ * thunk or surface React's "cannot dot into a client module" error.
+ */
+export function isClientUrlSource(
+  value: unknown,
+): value is ClientUrlDefinitionSource {
+  return isClientUrlPatterns(value) || isClientUrlReference(value);
+}
+
 /**
  * Strip vite's HMR timestamp query from a module id. After an HMR update of
  * a clientUrls module, the RSC graph re-imports it under

package/src/router.ts

@@ -3,10 +3,7 @@ import { createCacheScope } from "./cache/cache-scope.js";
 import { resolveCacheProfiles } from "./cache/profile-registry.js";
 import { isCachedFunction } from "./cache/taint.js";
 import { assertClientComponent } from "./component-utils.js";
-import {
-  isClientUrlPatterns,
-  isClientUrlReference,
-} from "./client-urls/server-projection.js";
+import { isClientUrlSource } from "./client-urls/server-projection.js";
 import type { ClientUrlPatterns } from "./client-urls/types.js";
 import { DefaultDocument } from "./components/DefaultDocument.js";
 import type { SerializedManifest } from "./debug.js";
@@ -784,10 +781,7 @@ export function createRouter<TEnv = any>(
       // same lazy include materialization, so no ordering, one-definition, or
       // deferral rules exist. Prefixing, wrapping RSC layouts, and middleware
       // scope still come from mounting through include() in urls() yourself.
-      if (
-        isClientUrlPatterns(patternsOrBuilder) ||
-        isClientUrlReference(patternsOrBuilder)
-      ) {
+      if (isClientUrlSource(patternsOrBuilder)) {
         const clientSource = patternsOrBuilder as ClientUrlPatterns;
         patternsOrBuilder = urls(({ include }) => [
           include("/", clientSource, { name: "" }),

package/src/urls/include-helper.ts

@@ -13,8 +13,7 @@ import type { IncludeProvider } from "./include-provider.js";
 import type { IncludeFn } from "./path-helper-types.js";
 import {
   clientUrlIncludePatterns,
-  isClientUrlPatterns,
-  isClientUrlReference,
+  isClientUrlSource,
 } from "../client-urls/server-projection.js";
 import type { ClientUrlPatterns } from "../client-urls/types.js";
 
@@ -77,14 +76,11 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
   ): IncludeItem => {
     const { ctx } = requireDslContext("include() must be called inside urls()");
 
-    // clientUrls() sources mount through include() like any urls() module.
-    // Detect them FIRST: a client REFERENCE is a callable proxy, so the
-    // downstream provider check (`typeof === "function"`) would otherwise
-    // invoke it as an async include thunk. The substituted handler defers
-    // materialization to evaluation time, when the discovery-installed
-    // projection is available; the include machinery then applies URL and
-    // route-name prefixes exactly as for server modules.
-    if (isClientUrlPatterns(patterns) || isClientUrlReference(patterns)) {
+    // clientUrls() sources mount like any urls() module: the adapter defers
+    // materialization to evaluation time (projection installed by then) and
+    // the include machinery applies URL/name prefixes as for server modules.
+    // Ordering: see isClientUrlSource.
+    if (isClientUrlSource(patterns)) {
       patterns = clientUrlIncludePatterns(patterns) as UrlPatterns<TEnv>;
     }
 

package/src/urls/include-provider.ts

@@ -1,14 +1,23 @@
 import type { UrlPatterns } from "./pattern-types.js";
+import type { ClientUrlPatterns } from "../client-urls/types.js";
+import {
+  clientUrlIncludePatterns,
+  isClientUrlSource,
+} from "../client-urls/server-projection.js";
 
 /**
  * What an async `include()` provider may resolve to: a `urls()` value directly,
  * or a module namespace whose `default` export is a `urls()` value (the shape
  * produced by `() => import("./routes")` when the route module does
- * `export default urls(...)`).
+ * `export default urls(...)`). A `clientUrls()` module resolves the same way
+ * (`() => import("./shop.client")`); on the server its `default` is the client
+ * reference, adapted exactly as the eager `include(prefix, clientUrlsDefault)`
+ * form.
  */
 export type IncludeModule<TEnv = any> =
   | UrlPatterns<TEnv>
-  | { default: UrlPatterns<TEnv> };
+  | ClientUrlPatterns
+  | { default: UrlPatterns<TEnv> | ClientUrlPatterns };
 
 /**
  * An async/lazy include provider: a thunk returning a `urls()` value (or a
@@ -36,9 +45,19 @@ function isUrlPatterns(value: unknown): value is UrlPatterns {
   );
 }
 
+/**
+ * A `urls()` value as is; a `clientUrls()` source through the same adapter the
+ * eager include() path applies (ordering: see isClientUrlSource).
+ */
+function toUrlPatterns(value: unknown): UrlPatterns | undefined {
+  if (isClientUrlSource(value)) return clientUrlIncludePatterns(value);
+  return isUrlPatterns(value) ? value : undefined;
+}
+
 /**
  * Normalize an async provider's resolved value to a `UrlPatterns`. Accepts a
- * `urls()` value directly or a module whose `default` export is one.
+ * `urls()`/`clientUrls()` value directly or a module whose `default` export is
+ * one.
  */
 export function resolveIncludeModule<TEnv = any>(
   mod: IncludeModule<TEnv>,
@@ -53,8 +72,8 @@ export function resolveIncludeModule<TEnv = any>(
   // 404s with a misleading error). A bare `() => urls(...)` provider (no
   // module) has no `default`, so it still resolves via the mod-as-value branch.
   const def = (mod as { default?: unknown })?.default;
-  if (isUrlPatterns(def)) return def as UrlPatterns<TEnv>;
-  if (isUrlPatterns(mod)) return mod as UrlPatterns<TEnv>;
+  const resolved = toUrlPatterns(def) ?? toUrlPatterns(mod);
+  if (resolved) return resolved as UrlPatterns<TEnv>;
   // The common failure is a module namespace whose `default` is missing or not a
   // urls() value (e.g. only named exports); `typeof` alone says "object" and
   // hides that, so name the keys present. "provider" (not "async provider") —
@@ -65,7 +84,7 @@ export function resolveIncludeModule<TEnv = any>(
       : typeof mod;
   throw new Error(
     `[@rangojs/router] include() provider${id ? ` for "${id}"` : ""} must ` +
-      `resolve to a urls() value — either returned directly or as the module's ` +
-      `\`default\` export (e.g. \`export default urls(...)\`). Got ${got}.`,
+      `resolve to a urls() or clientUrls() value — either returned directly or ` +
+      `as the module's \`default\` export (e.g. \`export default urls(...)\`). Got ${got}.`,
   );
 }

package/src/urls/path-helper-types.ts

@@ -160,7 +160,9 @@ export type TextResponsePathFn<TEnv> = <
 /**
  * What an async include() provider resolves to. Route types (`TRoutes`) are
  * inferred from the resolved `urls()` value so `href()` and named routes stay
- * type-safe through a code-split module (`() => import("./routes")`).
+ * type-safe through a code-split module (`() => import("./routes")`). A
+ * clientUrls() module's default export types as ClientUrlPatterns, so
+ * `() => import("./shop.client")` infers the group's names the same way.
  */
 type IncludeResolved<
   TEnv,
@@ -168,7 +170,12 @@ type IncludeResolved<
   TResponses extends Record<string, unknown>,
 > =
   | UrlPatterns<TEnv, TRoutes, TResponses>
-  | { default: UrlPatterns<TEnv, TRoutes, TResponses> };
+  | ClientUrlPatterns<TRoutes>
+  | {
+      default:
+        | UrlPatterns<TEnv, TRoutes, TResponses>
+        | ClientUrlPatterns<TRoutes>;
+    };
 
 /** include() argument: an eager `urls()` value or an async provider thunk. */
 export type IncludeArg<