@rangojs/router 0.0.0-experimental.35 → 0.0.0-experimental.358c376d

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

@@ -5,6 +5,7 @@ import type {
   Handler,
   HandlerContext,
   LoaderDefinition,
+  LoaderOptions,
   MiddlewareFn,
   NotFoundBoundaryHandler,
   PartialCacheOptions,
@@ -28,7 +29,6 @@ import type {
   ParallelUseItem,
   InterceptUseItem,
   LoaderUseItem,
-  WhenItem,
   TypedCacheItem,
   TransitionItem,
   TypedTransitionItem,
@@ -37,9 +37,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 +58,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 +74,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 +117,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 +157,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 +196,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 +271,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 +303,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
@@ -270,17 +345,26 @@ export type PathHelpers<TEnv> = {
   revalidate: (fn: ShouldRevalidateFn<any, TEnv>) => RevalidateItem;
 
   /**
-   * Attach a data loader to the current route/layout
+   * Attach a data loader to the current route/layout.
+   *
+   * Pass `{ stream: "navigation" }` to await this loader before first flush
+   * on DOCUMENT requests (see {@link LoaderOptions}) — the opt-in for loaders
+   * whose data, handle pushes, or thrown notFound()/redirect() must be in the
+   * SSR'd HTML. Per-loader: a dynamic sibling keeps streaming.
    */
   loader: <TData>(
     loaderDef: LoaderDefinition<TData>,
+    optionsOrUse?: LoaderOptions | (() => LoaderUseItem[]),
     use?: () => LoaderUseItem[],
   ) => LoaderItem;
 
   /**
    * 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 +380,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 +388,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;

package/src/urls/path-helper.ts

@@ -1,21 +1,18 @@
 import type { ReactNode } from "react";
 import type { Handler } from "../types.js";
-import type {
-  AllUseItems,
-  RouteItem,
-  RouteUseItem,
-  UseItems,
-} from "../route-types.js";
+import type { RouteItem, RouteUseItem, UseItems } from "../route-types.js";
 import {
-  getContext,
   getUrlPrefix,
   getNamePrefix,
   getRootScoped,
+  requireDslContext,
+  stampStaticDefScope,
 } from "../server/context";
-import { invariant } from "../errors";
+import { invariant, DataNotFoundError } from "../errors";
 import { validateUserRouteName } from "../route-name.js";
 import {
   isPrerenderHandler,
+  isPassthroughHandler,
   type PrerenderHandlerDefinition,
 } from "../prerender.js";
 import {
@@ -34,40 +31,15 @@ import type {
   JsonResponsePathFn,
   TextResponsePathFn,
 } from "./path-helper-types.js";
+import {
+  resolveHandlerUse,
+  mergeHandlerUse,
+} from "../route-definition/resolve-handler-use.js";
+import {
+  emptySegmentBase,
+  runAndValidateUseItems,
+} from "../route-definition/dsl-helpers.js";
 
-/**
- * Check if a value is a valid use item
- */
-const isValidUseItem = (item: any): item is AllUseItems | undefined | null => {
-  return (
-    typeof item === "undefined" ||
-    item === null ||
-    (item &&
-      typeof item === "object" &&
-      "type" in item &&
-      [
-        "layout",
-        "route",
-        "middleware",
-        "revalidate",
-        "parallel",
-        "intercept",
-        "loader",
-        "loading",
-        "errorBoundary",
-        "notFoundBoundary",
-        "when",
-        "cache",
-        "transition",
-        "include",
-      ].includes(item.type))
-  );
-};
-
-/**
- * Apply URL prefix to a pattern
- * Handles edge cases like "/" patterns and double slashes
- */
 function applyUrlPrefix(prefix: string, pattern: string): string {
   if (!prefix) return pattern;
   if (pattern === "/") return prefix;
@@ -77,29 +49,17 @@ function applyUrlPrefix(prefix: string, pattern: string): string {
   return prefix + pattern;
 }
 
-/**
- * Apply name prefix to a route name
- */
 function applyNamePrefix(prefix: string | undefined, name: string): string {
   if (!prefix) return name;
   return `${prefix}.${name}`;
 }
 
-/**
- * Resolve response type from path options (set by path.json(), path.text(), etc.)
- */
 function resolveResponseType(
   options: PathOptions | undefined,
 ): string | undefined {
   return options?.[RESPONSE_TYPE];
 }
 
-/**
- * Create path() helper
- *
- * The path() function is the key new feature - it combines URL pattern
- * with handler at the definition site.
- */
 export function createPathHelper<TEnv>(): PathFn<TEnv> {
   return ((
     pattern: string,
@@ -107,17 +67,15 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
     optionsOrUse?: PathOptions | (() => UseItems<RouteUseItem>),
     maybeUse?: () => UseItems<RouteUseItem>,
   ): RouteItem => {
-    const store = getContext();
-    const ctx = store.getStore();
-    if (!ctx) throw new Error("path() must be called inside urls()");
+    const { store, ctx } = requireDslContext(
+      "path() must be called inside urls()",
+    );
 
     invariant(
       !ctx.parent || ctx.parent.type !== "parallel",
       "path() cannot be used inside parallel()",
     );
 
-    // Walk the parent chain to prevent path() nested under another path(),
-    // even when separated by intermediate layouts (e.g. path(layout(path())))
     {
       let ancestor = ctx.parent;
       while (ancestor) {
@@ -129,7 +87,6 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       }
     }
 
-    // Determine options and use based on argument types
     let options: PathOptions | undefined;
     let use: (() => UseItems<RouteUseItem>) | undefined;
 
@@ -142,73 +99,74 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       use = maybeUse;
     }
 
-    // Get prefixes from context (set by include())
+    const handlerUseFn = resolveHandlerUse(handler);
+    const mountSite = resolveResponseType(options) ? "response" : "path";
+    const mergedUse = mergeHandlerUse(handlerUseFn, use, mountSite);
+
     const urlPrefix = getUrlPrefix();
     const namePrefix = getNamePrefix();
 
-    // Apply URL prefix to pattern
     const prefixedPattern = applyUrlPrefix(urlPrefix, pattern);
 
-    // Generate route name - use provided name or generate from pattern
     const localName =
       options?.name || `$path_${pattern.replace(/[/:*?]/g, "_")}`;
     if (options?.name) {
       validateUserRouteName(options.name);
     }
-    // Apply name prefix if set (from include())
     const routeName = applyNamePrefix(namePrefix, localName);
 
     const namespace = `${ctx.namespace}.${store.getNextIndex("route")}.${routeName}`;
 
-    // Per-request pruning: skip registration for routes that won't be rendered.
-    // forRoute is set by loadManifest() to the matched route name. During
-    // evaluateLazyEntry() (route matching), forRoute is unset so all routes
-    // register normally. We still increment counters to keep shortCodes stable
-    // across different routes (needed for segment reconciliation on navigation).
-    //
-    // include() does not need its own forRoute pruning. include() creates lazy
-    // entries that defer handler execution until route matching. When the lazy
-    // handler eventually runs inside loadManifest(), this path() check already
-    // covers all routes defined inside the include.
     if (ctx.forRoute && routeName !== ctx.forRoute) {
       store.getShortCode("route");
       return { type: "route" } as RouteItem;
     }
 
-    // Ensure handler is always a function (wrap ReactNode or extract from prerender/static def)
     const wrappedHandler: Handler<any, any, TEnv> =
       typeof handler === "function"
         ? (handler as Handler<any, any, TEnv>)
-        : isPrerenderHandler(handler)
-          ? (handler.handler as Handler<any, any, TEnv>)
-          : isStaticHandler(handler)
-            ? (handler.handler as Handler<any, any, TEnv>)
-            : () => handler;
+        : isPassthroughHandler(handler)
+          ? typeof handler.prerenderDef.handler === "function"
+            ? (handler.prerenderDef.handler as Handler<any, any, TEnv>)
+            : () => {
+                throw new DataNotFoundError(
+                  "No prerender data found for this route",
+                );
+              }
+          : isPrerenderHandler(handler)
+            ? typeof handler.handler === "function"
+              ? (handler.handler as Handler<any, any, TEnv>)
+              : () => {
+                  throw new DataNotFoundError(
+                    "No prerender data found for this route",
+                  );
+                }
+            : isStaticHandler(handler)
+              ? (handler.handler as Handler<any, any, TEnv>)
+              : () => handler;
 
     const entry = {
+      ...emptySegmentBase(),
       id: namespace,
       shortCode: store.getShortCode("route"),
       type: "route" as const,
       parent: ctx.parent,
       handler: wrappedHandler,
-      // Store the PREFIXED pattern for route matching
       pattern: prefixedPattern,
-      loading: undefined,
-      middleware: [],
-      revalidate: [],
-      errorBoundary: [],
-      notFoundBoundary: [],
-      layout: [],
-      parallel: [],
-      intercept: [],
-      loader: [],
       ...(urlPrefix ? { mountPath: urlPrefix } : {}),
-      ...(isPrerenderHandler(handler)
+      ...(isPassthroughHandler(handler)
         ? {
             isPrerender: true as const,
-            prerenderDef: handler as PrerenderHandlerDefinition,
+            prerenderDef: handler.prerenderDef as PrerenderHandlerDefinition,
+            isPassthrough: true as const,
+            liveHandler: handler.liveHandler as Handler<any, any, TEnv>,
           }
-        : {}),
+        : isPrerenderHandler(handler)
+          ? {
+              isPrerender: true as const,
+              prerenderDef: handler as PrerenderHandlerDefinition,
+            }
+          : {}),
       ...(isStaticHandler(handler)
         ? {
             isStaticPrerender: true as const,
@@ -218,31 +176,33 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       ...(resolveResponseType(options)
         ? { responseType: resolveResponseType(options) }
         : {}),
+      // PPR shell-caching opt-in (document-level). Stored raw; the integrated
+      // serve path normalizes it via resolvePprConfig (rsc/shell-serve.ts).
+      ...(options?.ppr !== undefined && options.ppr !== false
+        ? { ppr: options.ppr }
+        : {}),
     };
 
-    // Capture namespace prefix on static handler for build-time reverse() resolution
-    if (isStaticHandler(handler) && handler.$$id && ctx.namePrefix) {
-      (handler as any).$$routePrefix = ctx.namePrefix;
+    if (isStaticHandler(handler) && handler.$$id) {
+      if (ctx.namePrefix) {
+        (handler as any).$$routePrefix = ctx.namePrefix;
+      }
+      stampStaticDefScope(handler, routeName);
     }
 
-    // Check for duplicate route names (TypeScript should catch this, but runtime check too)
     invariant(
       ctx.manifest.get(routeName) === undefined,
       `Duplicate route name: ${routeName} at ${namespace}`,
     );
 
-    // Register route entry with prefixed name
     ctx.manifest.set(routeName, entry);
 
-    // Register root-scope flag for dot-local reverse resolution
-    registerRouteRootScope(routeName, getRootScoped());
+    registerRouteRootScope(routeName, getRootScoped(), ctx.routerId);
 
-    // Also store pattern in a separate map for URL generation
     if (ctx.patterns) {
       ctx.patterns.set(routeName, prefixedPattern);
     }
 
-    // Store pattern grouped by URL prefix for separate entry creation
     if (ctx.patternsByPrefix) {
       const urlPrefix = getUrlPrefix() || "";
       if (!ctx.patternsByPrefix.has(urlPrefix)) {
@@ -251,25 +211,25 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       ctx.patternsByPrefix.get(urlPrefix)!.set(routeName, prefixedPattern);
     }
 
-    // Store trailing slash config if specified
     if (options?.trailingSlash && ctx.trailingSlash) {
       ctx.trailingSlash.set(routeName, options.trailingSlash);
     }
 
-    // Store search schema if specified
     if (options?.search) {
       if (ctx.searchSchemas) {
         ctx.searchSchemas.set(routeName, options.search);
       }
-      registerSearchSchema(routeName, options.search);
+      registerSearchSchema(routeName, options.search, ctx.routerId);
     }
 
-    // Run use callback if provided
-    if (use && typeof use === "function") {
-      const result = store.run(namespace, entry, use)?.flat(3);
-      invariant(
-        Array.isArray(result) && result.every((item) => isValidUseItem(item)),
-        `path() use() callback must return an array of use items [${namespace}]`,
+    if (mergedUse) {
+      const result = runAndValidateUseItems(
+        store,
+        namespace,
+        entry,
+        mergedUse,
+        "path",
+        "use",
       );
       return { name: namespace, type: "route", uses: result } as RouteItem;
     }
@@ -278,10 +238,6 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
   }) as PathFn<TEnv>;
 }
 
-/**
- * Attach response type tag methods (.json, .text, .html, .xml, .md, .image, .stream, .any) to a path helper.
- * Each tag wraps the original path() call with the RESPONSE_TYPE option set.
- */
 export function attachPathResponseTags<TEnv>(
   pathFn: PathFn<TEnv>,
 ): PathFn<TEnv> & {
@@ -303,7 +259,6 @@ export function attachPathResponseTags<TEnv>(
     ) => {
       let options: PathOptions;
       let use: (() => any[]) | undefined;
-
       if (typeof optionsOrUse === "function") {
         options = { [RESPONSE_TYPE]: responseType };
         use = optionsOrUse;