@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/src/types/route-config.ts

@@ -7,47 +7,33 @@ export type DocumentProps = {
   children: ReactNode;
 };
 
-/**
- * Parse constraint values into a union type
- * "a|b|c" -> "a" | "b" | "c"
- */
 type ParseConstraint<T extends string> =
   T extends `${infer First}|${infer Rest}` ? First | ParseConstraint<Rest> : T;
 
-/**
- * Extract param info from a param segment
- *
- * Handles:
- * - :param -> { name: "param", optional: false, type: string }
- * - :param? -> { name: "param", optional: true, type: string }
- * - :param(a|b) -> { name: "param", optional: false, type: "a" | "b" }
- * - :param(a|b)? -> { name: "param", optional: true, type: "a" | "b" }
- */
+// Named catch-all (`:name*` / `:name+`) is matched BEFORE the `?`/suffix
+// branches. Its modifier is anchored to the END of the token (no trailing
+// `${string}`) so it is a true suffix and never mis-splits a constraint body
+// such as `id(\d+)`. Both are a required `string`: a matched catch-all always
+// binds a value (possibly ""), so the key is always present.
 type ExtractParamInfo<T extends string> =
-  // Optional + constrained (with optional suffix): :param(a|b)?suffix
   T extends `${infer Name}(${infer Constraint})?${string}`
     ? { name: Name; optional: true; type: ParseConstraint<Constraint> }
-    : // Constrained (with optional suffix): :param(a|b)suffix
-      T extends `${infer Name}(${infer Constraint})${string}`
+    : T extends `${infer Name}(${infer Constraint})${string}`
       ? { name: Name; optional: false; type: ParseConstraint<Constraint> }
-      : // Optional (with optional suffix): :param?suffix
-        T extends `${infer Name}?${string}`
-        ? { name: Name; optional: true; type: string }
-        : // Param with dot-suffix: :param.html
-          T extends `${infer Name}.${string}`
+      : T extends `${infer Name}*`
+        ? { name: Name; optional: false; type: string }
+        : T extends `${infer Name}+`
           ? { name: Name; optional: false; type: string }
-          : // Param with dash-suffix: :param-slug
-            T extends `${infer Name}-${string}`
-            ? { name: Name; optional: false; type: string }
-            : // Param with tilde-suffix: :param~v2
-              T extends `${infer Name}~${string}`
+          : T extends `${infer Name}?${string}`
+            ? { name: Name; optional: true; type: string }
+            : T extends `${infer Name}.${string}`
               ? { name: Name; optional: false; type: string }
-              : // Required: :param (no suffix)
-                { name: T; optional: false; type: string };
+              : T extends `${infer Name}-${string}`
+                ? { name: Name; optional: false; type: string }
+                : T extends `${infer Name}~${string}`
+                  ? { name: Name; optional: false; type: string }
+                  : { name: T; optional: false; type: string };
 
-/**
- * Build param object from info
- */
 type ParamFromInfo<Info> = Info extends {
   name: infer N extends string;
   optional: true;
@@ -62,10 +48,6 @@ type ParamFromInfo<Info> = Info extends {
     ? { [K in N]: V }
     : never;
 
-/**
- * Merge two param objects preserving optionality
- * Uses Pick to preserve the modifiers from source types
- */
 type MergeParams<A, B> = Pick<A, keyof A> & Pick<B, keyof B> extends infer O
   ? { [K in keyof O]: O[K] }
   : never;
@@ -78,12 +60,15 @@ type MergeParams<A, B> = Pick<A, keyof A> & Pick<B, keyof B> extends infer O
  * - Optional params: /:locale? -> { locale?: string }
  * - Constrained params: /:locale(en|gb) -> { locale: "en" | "gb" }
  * - Optional + constrained: /:locale(en|gb)? -> { locale?: "en" | "gb" }
+ * - Named catch-all: /:path+ (one-or-more), /:slug* (zero-or-more) -> string
  *
  * @example
  * ExtractParams<"/products/:id"> // { id: string }
  * ExtractParams<"/:locale?/blog/:slug"> // { locale?: string; slug: string }
  * ExtractParams<"/:locale(en|gb)/blog"> // { locale: "en" | "gb" }
  * ExtractParams<"/:locale(en|gb)?/blog/:slug"> // { locale?: "en" | "gb"; slug: string }
+ * ExtractParams<"/docs/:slug*"> // { slug: string }
+ * ExtractParams<"/shop/:path+"> // { path: string }
  */
 export type ExtractParams<
   T extends string,
@@ -109,17 +94,11 @@ export type ExtractParams<
  */
 export type TrailingSlashMode = "never" | "always" | "ignore";
 
-/**
- * Route configuration object (alternative to string path)
- */
 export type RouteConfig = {
   path: string;
   trailingSlash?: TrailingSlashMode;
 };
 
-/**
- * Route definition options (global defaults)
- */
 export type RouteDefinitionOptions = {
   trailingSlash?: TrailingSlashMode;
 };
@@ -128,11 +107,6 @@ export type RouteDefinition = {
   [key: string]: string | RouteConfig | RouteDefinition;
 };
 
-/**
- * Recursively flatten nested routes with depth limit to prevent infinite recursion
- * Transforms: { products: { detail: "/product/:slug" } } => { "products.detail": "/product/:slug" }
- * Also handles RouteConfig objects: { api: { path: "/api" } } => { "api": "/api" }
- */
 type FlattenRoutes<
   T extends RouteDefinition,
   Prefix extends string = "",
@@ -153,18 +127,12 @@ type FlattenRoutes<
             : never;
     }[keyof T];
 
-/**
- * Union to intersection helper
- */
 type UnionToIntersection<U> = (
   U extends unknown ? (k: U) => void : never
 ) extends (k: infer I) => void
   ? I
   : never;
 
-/**
- * Resolved route map - flattened route definitions with full paths
- */
 export type ResolvedRouteMap<T extends RouteDefinition> = UnionToIntersection<
   FlattenRoutes<T>
 >;

package/src/types/route-entry.ts

@@ -1,9 +1,6 @@
 import type { AllUseItems } from "../route-types.js";
 import type { TrailingSlashMode, ResolvedRouteMap } from "./route-config.js";
 
-/**
- * Context captured for lazy include evaluation
- */
 export interface LazyIncludeContext {
   urlPrefix: string;
   namePrefix: string | undefined;
@@ -16,6 +13,9 @@ export interface LazyIncludeContext {
   >;
   /** Root scope flag for dot-local reverse resolution */
   rootScoped?: boolean;
+  /** Owning router id; scopes search-schema/root-scope registration during
+   *  lazy include evaluation (route-map-builder.ts registries) */
+  routerId?: string;
   /**
    * Positional include scope token composed from the parent scope plus this
    * include's sibling index (`${parentScope}I${idx}`). Applied to direct-
@@ -25,9 +25,6 @@ export interface LazyIncludeContext {
   includeScope?: string;
 }
 
-/**
- * Internal route entry stored in router
- */
 export interface RouteEntry<TEnv = any> {
   prefix: string;
   /**

package/src/types/segments.ts

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import type { ErrorInfo, NotFoundInfo } from "./boundaries.js";
+import type { RevalidateParams, HandlerContext } from "./handler-context.js";
 
 /**
  * CSS class(es) for a ViewTransition phase.
@@ -8,9 +9,106 @@ import type { ErrorInfo, NotFoundInfo } from "./boundaries.js";
  */
 export type ViewTransitionClass = Record<string, string> | string;
 
+/**
+ * The context a transition({ when }) predicate receives.
+ *
+ * It mirrors the {@link ShouldRevalidateFn} args a `revalidate()` predicate
+ * gets — the same navigation/action metadata — so the two read the same shape,
+ * plus `get`/`env` for request-context reads. There is no full `HandlerContext`
+ * here: the gate runs at the RSC-payload layer with the request context, not a
+ * handler context, so handler-only sugar (`search`/`build`/`dev`/`headers`) is
+ * absent by design. On ordinary routes, `get` can read what handlers or
+ * middleware set via `ctx.set(...)`. On `ppr` routes the gate runs before route
+ * handlers, so only middleware-established values are available.
+ *
+ * Field availability (all source fields are optional — never fabricated):
+ * - `currentUrl` / `currentParams` / `fromRouteName` (the navigation SOURCE) are
+ *   populated on soft navigations and action-success revalidations. They are
+ *   undefined on an initial full document load and on action-error / no-JS error
+ *   paths that skip the navigation snapshot — there is no prior page to name.
+ * - `nextUrl` / `nextParams` / `get` / `env` / `method` are always present;
+ *   `toRouteName` is present only when the target route is named (undefined for
+ *   unnamed/auto-generated routes, like `fromRouteName`).
+ * - `actionId` / `actionUrl` / `actionResult` / `formData` are populated only
+ *   when a server action triggered the render; `method` is "POST" then, "GET"
+ *   otherwise. On no-JS (progressive-enhancement) action paths `actionId` may be
+ *   undefined when React cannot surface the action's stable id: the success
+ *   re-render still sets `actionUrl`/`formData` for a recognized action, but the
+ *   error-boundary re-render exposes `actionUrl` only when `actionId` resolved.
+ *   Malformed form bodies that fail before action detection expose no action
+ *   fields. Treat `actionId` as "the action, if known", not as "was this an
+ *   action".
+ *
+ * PREFETCH / CACHE CAVEAT (read this before gating on the source): the gate runs
+ * server-side during resolution. A PREFETCHED navigation renders at prefetch
+ * time, so `currentUrl`/`currentParams`/`fromRouteName` reflect the page the
+ * prefetch fired from, NOT necessarily the page the user actually navigates from
+ * — the decision is baked into the stored Flight payload and replayed verbatim.
+ * A non-PPR `cache()`/prerender hit replays the stored transition with the
+ * predicate NOT re-run. A `ppr` route instead evaluates the predicate before
+ * handlers on every match, including cache, prerender, and PPR replay. Prefetch
+ * still freezes the server decision into its Flight payload. If the gate must
+ * reflect the exact click-time source, source-scope the prefetch
+ * (`<Link prefetchKey=":source">`).
+ */
+export type TransitionWhenContext<
+  TParams = Record<string, string>,
+  TEnv = unknown,
+> = Partial<
+  Pick<
+    RevalidateParams<TParams, TEnv>,
+    "currentUrl" | "currentParams" | "fromRouteName"
+  >
+> &
+  Pick<
+    RevalidateParams<TParams, TEnv>,
+    | "nextUrl"
+    | "nextParams"
+    | "toRouteName"
+    | "actionId"
+    | "actionUrl"
+    | "actionResult"
+    | "formData"
+    | "method"
+  > &
+  Pick<HandlerContext<any, TEnv>, "get" | "env">;
+
+/**
+ * Predicate that gates whether a transition() applies for the current request.
+ *
+ * Evaluated server-side outside any cache scope. On ordinary routes it runs
+ * AFTER the route's handler, so `get(...)` can read handler/middleware state. A
+ * route with `ppr` automatically hoists it before route handlers and reevaluates
+ * it on every cache/prerender/PPR replay; there `get(...)` can read middleware
+ * state, but not values set by route handlers. Return false to drop this
+ * segment's transition for the request; return true to apply it. The
+ * context ({@link TransitionWhenContext}) carries the same navigation/action
+ * metadata a `revalidate()` predicate sees plus `get`/`env`. If it throws, the
+ * error is reported to the router's onError (phase "rendering") and the
+ * transition is dropped (the navigation does not hold).
+ *
+ * Distinct from intercept()'s `when` config selector, which runs at MATCH time
+ * over `{ from, to, params, segments, … }`.
+ *
+ * Scope: dropping a transition removes only THIS segment's contribution to the
+ * navigation's hold. The startTransition hold is navigation-wide — it engages if
+ * any matched segment still has a transition — so `when: false` makes the
+ * navigation stream its loading fallback only when no other matched segment
+ * keeps a transition (the common case: a single transition on the route).
+ *
+ * On non-PPR routes it runs only during fresh resolution. On PPR routes it runs
+ * before handlers for every match, including runtime cache, build-time
+ * prerender, and PPR segment replay. A prefetched navigation still freezes the
+ * result to prefetch time; see {@link TransitionWhenContext}.
+ */
+export type TransitionWhenFn = (ctx: TransitionWhenContext) => boolean;
+
 /**
  * Configuration for React's <ViewTransition> component.
- * Maps directly to ViewTransitionProps (minus children/ref/callbacks).
+ *
+ * The phase fields (enter/exit/update/share/default/name) map directly to
+ * ViewTransitionProps (minus children/ref/callbacks). The `viewTransition`
+ * field is router-specific and is stripped before the config reaches React.
  */
 export interface TransitionConfig {
   enter?: ViewTransitionClass;
@@ -19,19 +117,35 @@ export interface TransitionConfig {
   share?: ViewTransitionClass;
   default?: ViewTransitionClass;
   name?: string;
+  /**
+   * Whether the router wraps this segment's content in its own
+   * <ViewTransition> boundary.
+   *
+   * - "auto" (default): the router places the boundary, producing the
+   *   router-owned cross-fade described by the phase fields above.
+   * - false: the router places no boundary. The navigation commit is still
+   *   driven through startTransition (so loaders hold instead of flashing a
+   *   skeleton, and consumer-placed <ViewTransition> elements still animate),
+   *   but the router contributes no cross-fade of its own.
+   *
+   * When unset, inherits the createRouter({ viewTransition }) default.
+   */
+  viewTransition?: "auto" | false;
+  /**
+   * Optional server-side predicate that gates this transition per request. When
+   * present and it returns false, the router drops this segment's transition for
+   * the request, so the navigation streams its loading fallback instead of
+   * holding. PPR routes evaluate it before route handlers and on every replay;
+   * other routes evaluate it after handlers on fresh resolution. The predicate
+   * is server-only and never serialized to the client; only its resolved effect
+   * crosses. See {@link TransitionWhenFn}.
+   */
+  when?: TransitionWhenFn;
 }
 
 /**
  * Resolved segment with component
  *
- * Segment types:
- * - layout: Wraps child content via <Outlet />
- * - route: The leaf content for a URL
- * - parallel: Named slots rendered via <ParallelOutlet name="@slot" />
- * - loader: Data segment (no visual rendering, carries loaderData)
- * - error: Error fallback segment (replaces failed segment with error UI)
- * - notFound: Not found fallback segment (replaces segment when data not found)
- *
  * @internal This type is an implementation detail and may change without notice.
  */
 export interface ResolvedSegment {
@@ -62,13 +176,16 @@ export interface ResolvedSegment {
   notFoundInfo?: NotFoundInfo; // For notFound segments: the not found information
   // Mount path from include() scope, used for MountContext.Provider wrapping
   mountPath?: string;
+  /**
+   * @internal Server-side marker: true when the segment's handler actually ran
+   * this request (not skipped via the revalidate cache path). Used by
+   * match-result.ts to populate `MatchResult.resolvedIds` for client-side
+   * handle-bucket cleanup. Stripped from the wire payload before serialization
+   * — never reaches the client.
+   */
+  _handlerRan?: boolean;
 }
 
-/**
- * Segment metadata (without component)
- *
- * @internal This type is an implementation detail and may change without notice.
- */
 export interface SegmentMetadata {
   id: string;
   type: "layout" | "route" | "parallel" | "loader" | "error" | "notFound";
@@ -116,6 +233,15 @@ export interface MatchResult {
   segments: ResolvedSegment[];
   matched: string[];
   diff: string[];
+  /**
+   * Every segment id whose handler actually ran on the server this request,
+   * including ones with `component === null` that get filtered out of
+   * `segments`/`diff` to avoid wasted bytes. Drives the client's handle-
+   * cleanup pass — a slot that re-resolves and pushes nothing must clear
+   * its previous handle bucket, but `diff` doesn't carry it because the
+   * segment payload doesn't either. A superset of `diff`.
+   */
+  resolvedIds: string[];
   /**
    * Merged route params from all matched segments
    * Available for use by the handler after route matching
@@ -132,6 +258,13 @@ export interface MatchResult {
    * Slots are used for intercepting routes during soft navigation
    */
   slots?: Record<string, SlotState>;
+  /**
+   * Intercept TARGET route names reachable when this location is a navigation
+   * origin (chain walk of the matched entry, when-conditionals included).
+   * Shipped in payload metadata so the browser-local clientUrls matcher can
+   * decline its optimistic presentation for targets an intercept would claim.
+   */
+  interceptTargets?: string[];
   /**
    * Redirect URL for trailing slash normalization.
    * When set, the RSC handler should return a 308 redirect to this URL

package/src/urls/include-helper.ts

@@ -1,16 +1,22 @@
 import type { AllUseItems, IncludeItem } from "../route-types.js";
 import {
-  getContext,
-  runWithPrefixes,
   getUrlPrefix,
   getNamePrefix,
+  requireDslContext,
 } from "../server/context";
 import {
   INTERNAL_INCLUDE_SCOPE_PREFIX,
   validateUserRouteName,
 } from "../route-name.js";
 import type { UrlPatterns, IncludeOptions } from "./pattern-types.js";
+import type { IncludeProvider } from "./include-provider.js";
 import type { IncludeFn } from "./path-helper-types.js";
+import {
+  clientUrlIncludePatterns,
+  isClientUrlPatterns,
+  isClientUrlReference,
+} from "../client-urls/server-projection.js";
+import type { ClientUrlPatterns } from "../client-urls/types.js";
 
 function hasExplicitNameOption(options: IncludeOptions | undefined): boolean {
   return !!options && Object.prototype.hasOwnProperty.call(options, "name");
@@ -26,28 +32,10 @@ function allocateInternalIncludeScopeId(
 }
 
 /**
- * Process an IncludeItem by executing its nested patterns with prefixes
- * This expands the include into actual route registrations
- */
-function processIncludeItem(item: IncludeItem): AllUseItems[] {
-  const { prefix, patterns } = item;
-  const namePrefix =
-    (item as IncludeItem & { _lazyContext?: { namePrefix?: string } })
-      ._lazyContext?.namePrefix ?? item.options?.name;
-
-  // Execute the nested patterns' handler with URL and name prefixes
-  // The urlPrefix being set tells nested urls() to skip RootLayout wrapping
-  return runWithPrefixes(prefix, namePrefix, () => {
-    // Call the nested patterns' handler - this registers routes with prefixed patterns/names
-    return (patterns as UrlPatterns).handler();
-  });
-}
-
-/**
- * Recursively process items, expanding any IncludeItems
- * Returns items with IncludeItems expanded into actual route items
+ * Recursively walk items, recursing into layout children.
  *
- * Lazy includes are kept as-is (not expanded) for the router to handle later.
+ * All includes are lazy and kept as-is; the router expands them on the first
+ * matching request.
  */
 export function processItems(items: readonly AllUseItems[]): AllUseItems[] {
   const result: AllUseItems[] = [];
@@ -56,28 +44,8 @@ export function processItems(items: readonly AllUseItems[]): AllUseItems[] {
     if (!item) continue;
 
     if (item.type === "include") {
-      const includeItem = item as IncludeItem & {
-        _expanded?: AllUseItems[];
-        lazy?: boolean;
-      };
-
-      // Lazy includes are NOT expanded here - kept for router to handle
-      if (includeItem.lazy) {
-        result.push(item);
-        continue;
-      }
-
-      // Eager includes are already expanded during include() call
-      if (includeItem._expanded) {
-        // Items were expanded immediately - just process them recursively
-        result.push(...processItems(includeItem._expanded));
-      } else {
-        // Fallback for legacy include items without _expanded
-        const expanded = processIncludeItem(item as IncludeItem);
-        result.push(...processItems(expanded));
-      }
+      result.push(item);
     } else if (item.type === "layout" && (item as any).uses) {
-      // Process nested items in layout
       const layoutItem = item as any;
       layoutItem.uses = processItems(layoutItem.uses);
       result.push(layoutItem);
@@ -92,23 +60,33 @@ export function processItems(items: readonly AllUseItems[]): AllUseItems[] {
 /**
  * Create include() helper for composing URL patterns
  *
- * By default, include() IMMEDIATELY expands the nested patterns. This ensures
- * that routes from included patterns inherit the correct parent context
- * (the layout they're included in).
- *
- * With `lazy: true`, patterns are NOT expanded at definition time. Instead,
- * they're evaluated on first request that matches the prefix. This improves
- * cold start time for apps with many routes.
+ * All includes are lazy: the nested patterns are NOT expanded at definition
+ * time. Instead they are evaluated on the first request that matches the
+ * prefix, which improves cold start time for apps with many routes.
  */
 export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
   return (
     prefix: string,
-    patterns: UrlPatterns<TEnv>,
+    // A `urls()` value (eager), an async provider thunk
+    // (`() => import("./routes")`) whose evaluation is deferred to the first
+    // request matching `prefix`, or a clientUrls() definition (object or
+    // client reference). Providers are stored unevaluated and resolved by the
+    // runtime lazy-include expansion / build-time discovery.
+    patterns: UrlPatterns<TEnv> | IncludeProvider<TEnv> | ClientUrlPatterns,
     options?: IncludeOptions,
   ): IncludeItem => {
-    const store = getContext();
-    const ctx = store.getStore();
-    if (!ctx) throw new Error("include() must be called inside urls()");
+    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)) {
+      patterns = clientUrlIncludePatterns(patterns) as UrlPatterns<TEnv>;
+    }
 
     const explicitName = options?.name;
     const hasExplicitName = hasExplicitNameOption(options);
@@ -126,10 +104,9 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
         ? capturedUrlPrefix + prefix.slice(1)
         : capturedUrlPrefix + prefix
       : prefix;
-    const internalScope = !hasExplicitName
-      ? allocateInternalIncludeScopeId(ctx.counters)
-      : undefined;
-    const nextSegment = hasExplicitName ? explicitName : internalScope;
+    const nextSegment = hasExplicitName
+      ? explicitName
+      : allocateInternalIncludeScopeId(ctx.counters);
     const fullNamePrefix =
       nextSegment !== undefined && nextSegment !== ""
         ? capturedNamePrefix
@@ -162,9 +139,7 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
     if (capturedParent?.shortCode) {
       const includeCounterKey = `${capturedParent.shortCode}${parentScope}_include`;
       ctx.counters[includeCounterKey] ??= 0;
-      const includeIdx = ctx.counters[includeCounterKey];
-      ctx.counters[includeCounterKey] = includeIdx + 1;
-      includeScope = `${parentScope}I${includeIdx}`;
+      includeScope = `${parentScope}I${ctx.counters[includeCounterKey]++}`;
     }
 
     // Snapshot parent's counters AFTER allocating the include scope so lazy
@@ -184,8 +159,6 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
           ? (parentRootScoped ?? false)
           : parentRootScoped;
 
-    // All includes are lazy - patterns are evaluated on first matching request
-    // This improves cold start time significantly for large route sets
     return {
       type: "include",
       name,
@@ -200,6 +173,7 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
         counters: capturedCounters,
         cacheProfiles: ctx.cacheProfiles,
         rootScoped: capturedRootScoped,
+        routerId: ctx.routerId,
         includeScope,
       },
     } as IncludeItem;

package/src/urls/include-provider.ts

@@ -0,0 +1,71 @@
+import type { UrlPatterns } from "./pattern-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 type IncludeModule<TEnv = any> =
+  | UrlPatterns<TEnv>
+  | { default: UrlPatterns<TEnv> };
+
+/**
+ * An async/lazy include provider: a thunk returning a `urls()` value (or a
+ * Promise of one). The thunk is stored unevaluated by `include()` and called
+ * once, on the first request that matches the prefix — so the route module and
+ * its (code-split) subtree are not evaluated at startup.
+ *
+ * Forward-compatible: `() => import("./routes")` today (async, separate chunk);
+ * `() => m.routes` with native `import defer` later (sync, deferred eval).
+ */
+export type IncludeProvider<TEnv = any> = () =>
+  | IncludeModule<TEnv>
+  | Promise<IncludeModule<TEnv>>;
+
+/** True when the include() argument is a provider thunk rather than a value. */
+export function isIncludeProvider(value: unknown): value is IncludeProvider {
+  // A `urls()` value is a (branded) object; a provider is a function.
+  return typeof value === "function";
+}
+
+/** A `urls()` value is an object exposing a synchronous `handler()`. */
+function isUrlPatterns(value: unknown): value is UrlPatterns {
+  return (
+    !!value && typeof (value as { handler?: unknown }).handler === "function"
+  );
+}
+
+/**
+ * Normalize an async provider's resolved value to a `UrlPatterns`. Accepts a
+ * `urls()` value directly or a module whose `default` export is one.
+ */
+export function resolveIncludeModule<TEnv = any>(
+  mod: IncludeModule<TEnv>,
+  id?: string,
+): UrlPatterns<TEnv> {
+  // Prefer an explicit `default` export (the `export default urls(...)`
+  // convention) BEFORE duck-typing the namespace. isUrlPatterns() keys on a
+  // `.handler` function, but a routes module can legitimately carry a NAMED
+  // `export function handler(...)` alongside its `export default urls(...)`;
+  // checking the namespace first would then misidentify the whole module as the
+  // urls() value and invoke the user's helper as the DSL handler (the group
+  // 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>;
+  // 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") —
+  // synchronous providers are supported (see IncludeProvider).
+  const got =
+    mod && typeof mod === "object"
+      ? `a module with keys [${Object.keys(mod).join(", ") || "none"}] but no valid \`default\``
+      : 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}.`,
+  );
+}

package/src/urls/index.ts

@@ -1,4 +1,3 @@
-// Response types and symbols
 export {
   RESPONSE_TYPE,
   type ResponseHandler,
@@ -8,28 +7,22 @@ export {
   type ResponseHandlerContext,
 } from "./response-types.js";
 
-// Pattern types
 export type {
   UnnamedRoute,
   LocalOnlyInclude,
   PathOptions,
-  PathDefinition,
+  PartialPrerenderProps,
   UrlPatterns,
   IncludeOptions,
 } from "./pattern-types.js";
 
-// Type extraction utilities
 export type {
   ExtractRoutes,
   ExtractResponses,
-  ExtractRouteNames,
-  ExtractPathParams,
-  ResponseError,
-  ResponseEnvelope,
+  ProblemDetails,
   RouteResponse,
 } from "./type-extraction.js";
 
-// Path helper types
 export type {
   PathFn,
   ResponsePathFn,
@@ -39,10 +32,8 @@ export type {
   PathHelpers,
 } from "./path-helper-types.js";
 
-// Main entry point
 export { urls } from "./urls-function.js";
 
-// Re-exports from route-types
 export type {
   AllUseItems,
   IncludeItem,