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

package/src/urls/include-helper.ts

@@ -1,17 +1,22 @@
 import type { AllUseItems, IncludeItem } from "../route-types.js";
 import {
-  getContext,
-  runWithPrefixes,
   getUrlPrefix,
   getNamePrefix,
-  getRootScoped,
+  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");
@@ -27,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[] = [];
@@ -57,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);
@@ -93,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);
@@ -127,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
@@ -149,22 +125,30 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
       });
     }
 
-    // Snapshot parent's counters so lazy manifest generation starts
-    // at the correct index, preventing shortCode collisions with
-    // sibling entries (e.g., BlogLayout and ArticlesLayout under NavLayout).
-    const capturedCounters = { ...ctx.counters };
-
-    // Reserve a layout slot in the parent's counter so sibling lazy includes
-    // produce different shortCode indices for their root layout.
-    // Without this, consecutive include() calls capture identical counters
-    // and their first child layouts get the same shortCode (e.g., both M0L0L0),
-    // causing the client partial-update diff to see no changes on navigation.
+    // Allocate an include-scope token for this include() call. The token is
+    // appended to the parent's shortCode prefix whenever the include's
+    // direct-descendant shortCodes are generated (see getShortCode in
+    // context.ts), partitioning the parent's counter namespace so routes
+    // inside an include cannot collide with siblings declared outside it.
+    //
+    // Scopes compose: a nested include inside an outer include with scope
+    // "I0" allocates against the `${parent.shortCode}I0_include` counter
+    // and produces scope "I0I0", "I0I1", etc.
+    const parentScope = ctx.includeScope ?? "";
+    let includeScope = parentScope;
     if (capturedParent?.shortCode) {
-      const layoutCounterKey = `${capturedParent.shortCode}_layout`;
-      ctx.counters[layoutCounterKey] ??= 0;
-      ctx.counters[layoutCounterKey]++;
+      const includeCounterKey = `${capturedParent.shortCode}${parentScope}_include`;
+      ctx.counters[includeCounterKey] ??= 0;
+      includeScope = `${parentScope}I${ctx.counters[includeCounterKey]++}`;
     }
 
+    // Snapshot parent's counters AFTER allocating the include scope so lazy
+    // manifest generation starts with the same counter state this include
+    // observed — its descendants still get fresh per-scope counters because
+    // they key off `${parent.shortCode}${includeScope}_*` (not shared with
+    // siblings outside the include).
+    const capturedCounters = { ...ctx.counters };
+
     // Compute rootScoped at capture time, mirroring the logic in runWithPrefixes.
     // This ensures lazy evaluation restores the correct scope state.
     const parentRootScoped = ctx.rootScoped;
@@ -175,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,
@@ -191,6 +173,8 @@ 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,

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

@@ -28,7 +28,6 @@ import type {
   ParallelUseItem,
   InterceptUseItem,
   LoaderUseItem,
-  WhenItem,
   TypedCacheItem,
   TransitionItem,
   TypedTransitionItem,
@@ -37,9 +36,14 @@ import type {
   UseItems,
 } from "../route-types.js";
 import type { SearchSchema } from "../search-params.js";
-import type { PrerenderHandlerDefinition } from "../prerender.js";
-import type { StaticHandlerDefinition } from "../static-handler.js";
-import type { InterceptWhenFn } from "../server/context";
+import type {
+  PrerenderHandlerDefinition,
+  PassthroughHandlerDefinition,
+} from "../prerender.js";
+import type {
+  StaticHandlerDefinition,
+  StaticHandlerRef,
+} from "../static-handler.js";
 import type {
   ResponseHandler,
   ResponseHandlerContext,
@@ -53,6 +57,7 @@ import type {
   IncludeOptions,
 } from "./pattern-types.js";
 import type { ExtractRoutes, ExtractResponses } from "./type-extraction.js";
+import type { ClientUrlPatterns } from "../client-urls/types.js";
 
 /**
  * Base path function signature for defining routes with URL patterns.
@@ -68,8 +73,9 @@ export type PathFn<TEnv> = <
     | ReactNode
     | ((
         ctx: HandlerContext<TParams, TEnv, TSearch>,
-      ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>)
+      ) => ReactNode | Response | Promise<ReactNode | Response>)
     | PrerenderHandlerDefinition<TParams>
+    | PassthroughHandlerDefinition<TParams, TEnv>
     | StaticHandlerDefinition<TParams>,
   optionsOrUse?: PathOptions<TName, TSearch> | (() => UseItems<RouteUseItem>),
   use?: () => UseItems<RouteUseItem>,
@@ -110,6 +116,12 @@ export type ResponsePathFn<TEnv> = <
  * Path function for JSON response routes (path.json()).
  * Handler can return plain JSON-serializable values or Response.
  * TData is inferred from the handler's return type (excluding Response/Promise wrappers).
+ *
+ * Note: a nested Promise in the return (a forgotten await) is caught at runtime
+ * by response-route-handler.ts (it throws instead of silently emitting `{}`). A
+ * compile-time JsonValue constraint was evaluated and rejected — it breaks
+ * interface-typed returns (interfaces lack the index signature JsonValue
+ * requires) and preserves literal types in the inferred response shape.
  */
 export type JsonResponsePathFn<TEnv> = <
   const TPattern extends string,
@@ -144,6 +156,35 @@ export type TextResponsePathFn<TEnv> = <
   use?: () => UseItems<ResponseRouteUseItem>,
 ) => TypedRouteItem<TName, TPattern, string, TSearch>;
 
+/**
+ * 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 IncludeResolved<
+  TEnv,
+  TRoutes extends Record<string, any>,
+  TResponses extends Record<string, unknown>,
+> =
+  | UrlPatterns<TEnv, TRoutes, TResponses>
+  | { default: UrlPatterns<TEnv, TRoutes, TResponses> };
+
+/** 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>
+  // clientUrls() definitions mount through include() like any urls() module;
+  // on the server the runtime value is the module's client reference, but the
+  // TypeScript type of that default export IS ClientUrlPatterns, so route
+  // names flow into NamedRoutes through the same TRoutes inference.
+  | ClientUrlPatterns<TRoutes>
+  | (() =>
+      | IncludeResolved<TEnv, TRoutes, TResponses>
+      | Promise<IncludeResolved<TEnv, TRoutes, TResponses>>);
+
 /**
  * Base include function signature.
  */
@@ -154,7 +195,7 @@ export type IncludeFn<TEnv> = <
   TResponses extends Record<string, unknown> = Record<string, unknown>,
 >(
   prefix: TUrlPrefix,
-  patterns: UrlPatterns<TEnv, TRoutes, TResponses>,
+  patterns: IncludeArg<TEnv, TRoutes, TResponses>,
   options?: IncludeOptions<TNamePrefix>,
 ) => TypedIncludeItem<TRoutes, TNamePrefix, TUrlPrefix, TResponses>;
 
@@ -229,15 +270,31 @@ export type PathHelpers<TEnv> = {
   include: IncludeFn<TEnv>;
 
   /**
-   * Define parallel routes that render simultaneously in named slots
+   * Define parallel routes that render simultaneously in named slots.
+   *
+   * A slot value can be a Handler / ReactNode / StaticHandlerDefinition
+   * (legacy form, broadcast use applies to every slot) or a slot descriptor
+   * `{ handler, use? }` whose `use` is scoped to that slot only. Per-slot
+   * merge order is `handler.use` → shared `use` → slot-local `use`, with
+   * narrowest scope winning for last-write-wins items like `loading()`.
+   *
+   * Not generic over the slots record: an inferred type parameter makes the
+   * object literal an inference site, which suppresses contextual typing of
+   * arrow slot handlers (`(ctx) => ...` was implicit any). Static() values use
+   * an opaque handler-less reference here so their own `.handler` cannot
+   * contribute a second call signature or expose internal fields in completion.
    */
-  parallel: <
-    TSlots extends Record<
+  parallel: (
+    slots: Record<
       `@${string}`,
-      Handler<any, any, TEnv> | ReactNode | StaticHandlerDefinition
+      | Handler<any, any, TEnv>
+      | ReactNode
+      | StaticHandlerRef
+      | {
+          handler: Handler<any, any, TEnv> | ReactNode | StaticHandlerRef;
+          use?: () => ParallelUseItem[];
+        }
     >,
-  >(
-    slots: TSlots,
     use?: () => ParallelUseItem[],
   ) => ParallelItem;
 
@@ -245,24 +302,41 @@ export type PathHelpers<TEnv> = {
    * Define an intercepting route for soft navigation
    * Note: routeName must match a named path() in this urlpatterns
    */
-  intercept: keyof RSCRouter.GeneratedRouteMap extends never
+  intercept: keyof Rango.GeneratedRouteMap extends never
     ? (
         slotName: `@${string}`,
         routeName: string,
         handler: ReactNode | Handler<any, any, TEnv>,
+        config?:
+          | import("../server/context.js").InterceptConfig<TEnv>
+          | (() => InterceptUseItem[]),
         use?: () => InterceptUseItem[],
       ) => InterceptItem
     : (
         slotName: `@${string}`,
-        routeName: (keyof RSCRouter.GeneratedRouteMap & string) | `.${string}`,
+        routeName: (keyof Rango.GeneratedRouteMap & string) | `.${string}`,
         handler: ReactNode | Handler<any, any, TEnv>,
+        config?:
+          | import("../server/context.js").InterceptConfig<TEnv>
+          | (() => InterceptUseItem[]),
         use?: () => InterceptUseItem[],
       ) => InterceptItem;
 
   /**
-   * Attach middleware to the current route/layout
+   * Attach middleware to the current route/layout, or wrap child segments
    */
-  middleware: (...fns: MiddlewareFn<TEnv>[]) => MiddlewareItem;
+  middleware: {
+    (fn: MiddlewareFn<TEnv>): MiddlewareItem;
+    (
+      fn: MiddlewareFn<TEnv>,
+      children: () => UseItems<LayoutUseItem>,
+    ): MiddlewareItem;
+    (fns: MiddlewareFn<TEnv>[]): MiddlewareItem;
+    (
+      fns: MiddlewareFn<TEnv>[],
+      children: () => UseItems<LayoutUseItem>,
+    ): MiddlewareItem;
+  };
 
   /**
    * Control when a segment should revalidate during navigation
@@ -280,7 +354,10 @@ export type PathHelpers<TEnv> = {
   /**
    * Attach a loading component to the current route/layout
    */
-  loading: (component: ReactNode, options?: { ssr?: boolean }) => LoadingItem;
+  loading: (
+    component: ReactNode | (() => ReactNode),
+    options?: { ssr?: boolean },
+  ) => LoadingItem;
 
   /**
    * Attach an error boundary to catch errors in this segment
@@ -296,11 +373,6 @@ export type PathHelpers<TEnv> = {
     fallback: ReactNode | NotFoundBoundaryHandler,
   ) => NotFoundBoundaryItem;
 
-  /**
-   * Define a condition for when an intercept should activate
-   */
-  when: (fn: InterceptWhenFn) => WhenItem;
-
   /**
    * Define cache configuration for segments
    */
@@ -309,15 +381,28 @@ export type PathHelpers<TEnv> = {
     <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
       children: () => TChildren,
     ): TypedCacheItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
-    (options: PartialCacheOptions | false): TypedCacheItem<{}, {}>;
+    (options: PartialCacheOptions<TEnv> | false): TypedCacheItem<{}, {}>;
     <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
-      options: PartialCacheOptions | false,
+      options: PartialCacheOptions<TEnv> | false,
       use: () => TChildren,
     ): TypedCacheItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
   };
 
   /**
-   * Attach a ViewTransition boundary to the current segment or a group of routes
+   * Opt a route (or group of routes) into transition-driven navigation.
+   *
+   * Two independent layers: (1) startTransition, on all React versions, holds
+   * the previous content across a same-route nav (no skeleton flash) and is the
+   * precondition for any view transition; (2) on experimental React, an
+   * additional `<ViewTransition>` boundary cross-fades/morphs the swap. Pass
+   * `{ viewTransition: false }` to keep #1 without the router boundary. A view
+   * transition cannot fire without a startTransition. See
+   * skills/view-transitions for the startTransition x ViewTransition matrix.
+   *
+   * Pass `when: (ctx) => boolean` to gate the transition per request. It normally
+   * runs after the route handler; `ppr` routes automatically run it before route
+   * handlers and on every replay, where `ctx.get(...)` sees middleware state but
+   * not handler-set values.
    */
   transition: {
     (): TransitionItem;