@rangojs/router 0.0.0-experimental.61 → 0.0.0-experimental.63

package/src/prerender.ts

@@ -36,6 +36,7 @@ import type { Handle } from "./handle.js";
 import type { ContextVar } from "./context-var.js";
 import type { ReverseFunction } from "./reverse.js";
 import type { DefaultReverseRouteMap } from "./types/global-namespace.js";
+import type { UseItems, HandlerUseItem } from "./route-types.js";
 import { isCachedFunction } from "./cache/taint.js";
 
 // -- Named route resolution types -------------------------------------------
@@ -105,13 +106,6 @@ type ResolvePrerenderParams<
 // -- Types ------------------------------------------------------------------
 
 export interface PrerenderOptions {
-  /**
-   * Keep handler in server bundle for live fallback (default: false).
-   * false: handler replaced with stub, source-only APIs excluded from bundle.
-   * true: handler stays in bundle, unknown params render live at request time.
-   */
-  passthrough?: boolean;
-
   /**
    * Maximum number of param sets to render in parallel (default: 1).
    * Only applies to dynamic Prerender handlers with getParams().
@@ -131,8 +125,8 @@ export interface PrerenderOptions {
 
 /**
  * Context passed to Prerender() handlers at build time.
- * Has a synthetic URL from getParams, params, and pathname.
- * No request, env, headers, cookies.
+ * Has a synthetic URL from getParams, params, pathname, and optionally env.
+ * No request, headers, cookies.
  */
 export interface BuildContext<TParams> {
   /** Params extracted from the route pattern (populated from getParams). */
@@ -141,6 +135,23 @@ export interface BuildContext<TParams> {
   /** True during build-time pre-rendering, false during passthrough live render. */
   build: true;
 
+  /**
+   * True when running in Vite dev mode (on-demand prerender), false during
+   * production `vite build`. Use this to branch on runtime mode without
+   * changing build semantics.
+   */
+  dev: boolean;
+
+  /**
+   * Build-time environment bindings (KV, D1, etc.) supplied by the Vite plugin.
+   * Only available when `buildEnv` is configured in rango() options.
+   * Throws with a clear error if not configured.
+   *
+   * This is NOT the live request env — it is shared across all prerender
+   * invocations for the build.
+   */
+  env: DefaultEnv;
+
   /** Read a variable set by getParams or a parent handler. */
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;
@@ -173,8 +184,8 @@ export interface BuildContext<TParams> {
 
   /**
    * Signal that this param set should not produce a local prerender artifact.
-   * At runtime the handler runs live instead. Only valid on routes declared
-   * with `{ passthrough: true }`.
+   * At runtime the live handler runs instead. Only valid on routes wrapped
+   * with `Passthrough()`.
    */
   passthrough: () => PrerenderPassthroughResult;
 }
@@ -187,6 +198,17 @@ export interface StaticBuildContext {
   /** Always true for Static handlers at build time. */
   build: true;
 
+  /**
+   * True when running in Vite dev mode, false during production build.
+   */
+  dev: boolean;
+
+  /**
+   * Build-time environment bindings supplied by the Vite plugin.
+   * Only available when `buildEnv` is configured in rango() options.
+   */
+  env: DefaultEnv;
+
   /** Read a variable (available for type consistency with BuildContext). */
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;
@@ -214,6 +236,17 @@ export interface GetParamsContext {
   /** Always true during build-time getParams execution. */
   build: true;
 
+  /**
+   * True when running in Vite dev mode, false during production build.
+   */
+  dev: boolean;
+
+  /**
+   * Build-time environment bindings supplied by the Vite plugin.
+   * Only available when `buildEnv` is configured in rango() options.
+   */
+  env: DefaultEnv;
+
   /** Set a variable that will be available to each handler invocation via ctx.get(). */
   set: {
     <T>(contextVar: ContextVar<T>, value: T): void;
@@ -224,23 +257,6 @@ export interface GetParamsContext {
   reverse: BuildReverseFunction;
 }
 
-/**
- * Context type for passthrough Prerender handlers.
- *
- * When `passthrough: true`, the handler runs both at build time and at request
- * time. The context is a full `HandlerContext` with `build: boolean`:
- * - `ctx.build === true`: build-time, env/request/res throw at runtime
- * - `ctx.build === false`: live request, full context available
- *
- * For `passthrough: false` (default), handlers receive `BuildContext` only.
- */
-export type PrerenderPassthroughContext<
-  TParams = {},
-  TEnv = DefaultEnv,
-> = HandlerContext<TParams, TEnv> & {
-  passthrough: () => PrerenderPassthroughResult;
-};
-
 export interface PrerenderHandlerDefinition<
   TParams extends Record<string, any> = any,
 > {
@@ -253,6 +269,8 @@ export interface PrerenderHandlerDefinition<
   getParams?: (ctx: GetParamsContext) => Promise<TParams[]> | TParams[];
   /** Pre-render options. */
   options?: PrerenderOptions;
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<HandlerUseItem>;
 }
 
 // -- Overloads --------------------------------------------------------------
@@ -263,7 +281,7 @@ export interface PrerenderHandlerDefinition<
 // Explicit params work as before:
 //   Prerender<{ slug: string }> → params = { slug: string }
 
-// Overload 1: Static handler, no passthrough (build-time only)
+// Overload 1: Static handler (build-time only)
 export function Prerender<
   T extends
     | keyof DefaultPrerenderRouteMap
@@ -273,34 +291,15 @@ export function Prerender<
 >(
   handler: (
     ctx: BuildContext<ResolvePrerenderParams<T, TRouteMap>>,
-  ) => ReactNode | Promise<ReactNode>,
-  options?: PrerenderOptions & { passthrough?: false },
-  __injectedId?: string,
-): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
-
-// Overload 2: Static handler, passthrough (build + live — full HandlerContext)
-export function Prerender<
-  T extends
-    | keyof DefaultPrerenderRouteMap
-    | `.${keyof TRouteMap & string}`
-    | Record<string, any> = {},
-  TRouteMap extends {} = DefaultPrerenderRouteMap,
-  TEnv = DefaultEnv,
->(
-  handler: (
-    ctx: PrerenderPassthroughContext<
-      ResolvePrerenderParams<T, TRouteMap>,
-      TEnv
-    >,
   ) =>
     | ReactNode
     | PrerenderPassthroughResult
     | Promise<ReactNode | PrerenderPassthroughResult>,
-  options: PrerenderOptions & { passthrough: true },
+  options?: PrerenderOptions,
   __injectedId?: string,
 ): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
 
-// Overload 3: Dynamic handler, no passthrough (build-time only)
+// Overload 2: Dynamic handler (build-time only)
 export function Prerender<
   T extends
     | keyof DefaultPrerenderRouteMap
@@ -315,35 +314,11 @@ export function Prerender<
     | ResolvePrerenderParams<T, TRouteMap>[],
   handler: (
     ctx: BuildContext<ResolvePrerenderParams<T, TRouteMap>>,
-  ) => ReactNode | Promise<ReactNode>,
-  options?: PrerenderOptions & { passthrough?: false },
-  __injectedId?: string,
-): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
-
-// Overload 4: Dynamic handler, passthrough (build + live — full HandlerContext)
-export function Prerender<
-  T extends
-    | keyof DefaultPrerenderRouteMap
-    | `.${keyof TRouteMap & string}`
-    | Record<string, any>,
-  TRouteMap extends {} = DefaultPrerenderRouteMap,
-  TEnv = DefaultEnv,
->(
-  getParams: (
-    ctx: GetParamsContext,
-  ) =>
-    | Promise<ResolvePrerenderParams<T, TRouteMap>[]>
-    | ResolvePrerenderParams<T, TRouteMap>[],
-  handler: (
-    ctx: PrerenderPassthroughContext<
-      ResolvePrerenderParams<T, TRouteMap>,
-      TEnv
-    >,
   ) =>
     | ReactNode
     | PrerenderPassthroughResult
     | Promise<ReactNode | PrerenderPassthroughResult>,
-  options: PrerenderOptions & { passthrough: true },
+  options?: PrerenderOptions,
   __injectedId?: string,
 ): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
 
@@ -422,7 +397,7 @@ export function Prerender<TParams extends Record<string, any>>(
 /**
  * Sentinel returned by `ctx.passthrough()` to signal that a specific param set
  * should not produce a local prerender artifact. The build skips writing the
- * entry; at runtime the handler runs live (requires `{ passthrough: true }`).
+ * entry; at runtime the Passthrough live handler runs instead.
  */
 export const PRERENDER_PASSTHROUGH: Readonly<{
   __brand: "prerenderPassthrough";
@@ -446,7 +421,7 @@ export function isPrerenderPassthrough(
   );
 }
 
-// -- Type guard -------------------------------------------------------------
+// -- Type guards ------------------------------------------------------------
 
 /**
  * Type guard to check if a value is a PrerenderHandlerDefinition.
@@ -461,3 +436,89 @@ export function isPrerenderHandler(
     (value as { __brand: unknown }).__brand === "prerenderHandler"
   );
 }
+
+// -- Passthrough wrapper ----------------------------------------------------
+
+/**
+ * A prerender route with a live fallback handler for unknown params at runtime.
+ *
+ * Wraps a `Prerender(...)` definition with a separate handler that runs at
+ * request time for params not covered by `getParams()`.
+ *
+ * - Build time: `prerenderDef` provides getParams + build handler.
+ * - Runtime: `liveHandler` runs for unknown params with full HandlerContext.
+ *
+ * @example
+ * ```ts
+ * const BlogPrerender = Prerender(
+ *   async () => [{ slug: "getting-started" }, { slug: "api-reference" }],
+ *   async (ctx) => <BlogPost slug={ctx.params.slug} />,
+ * );
+ *
+ * // In route definition:
+ * path("/blog/:slug", Passthrough(BlogPrerender, async (ctx) => {
+ *   const post = await ctx.env.DB.get(ctx.params.slug);
+ *   return <BlogPost slug={ctx.params.slug} post={post} />;
+ * }))
+ * ```
+ */
+export interface PassthroughHandlerDefinition<
+  TParams extends Record<string, any> = any,
+  TEnv = DefaultEnv,
+> {
+  readonly __brand: "passthroughHandler";
+  /** The underlying prerender definition (build-time rendering). */
+  prerenderDef: PrerenderHandlerDefinition<TParams>;
+  /** Live handler for runtime fallback on unknown params. */
+  liveHandler: (
+    ctx: HandlerContext<TParams, TEnv>,
+  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>;
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<HandlerUseItem>;
+}
+
+export function Passthrough<
+  TParams extends Record<string, any>,
+  TEnv = DefaultEnv,
+>(
+  prerenderDef: PrerenderHandlerDefinition<TParams>,
+  liveHandler: (
+    ctx: HandlerContext<TParams, TEnv>,
+  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>,
+): PassthroughHandlerDefinition<TParams, TEnv>;
+
+// Implementation
+export function Passthrough<
+  TParams extends Record<string, any>,
+  TEnv = DefaultEnv,
+>(
+  prerenderDef: PrerenderHandlerDefinition<TParams>,
+  liveHandler: (
+    ctx: HandlerContext<TParams, TEnv>,
+  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>,
+): PassthroughHandlerDefinition<TParams, TEnv> {
+  if (!isPrerenderHandler(prerenderDef)) {
+    throw new Error(
+      "[rsc-router] Passthrough: first argument must be a Prerender() definition.",
+    );
+  }
+  return {
+    __brand: "passthroughHandler" as const,
+    prerenderDef,
+    liveHandler,
+  };
+}
+
+/**
+ * Type guard to check if a value is a PassthroughHandlerDefinition.
+ */
+export function isPassthroughHandler(
+  value: unknown,
+): value is PassthroughHandlerDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__brand" in value &&
+    (value as { __brand: unknown }).__brand === "passthroughHandler"
+  );
+}

package/src/reverse.ts

@@ -332,7 +332,9 @@ export function createReverse<TRoutes extends Record<string, string>>(
       // Clean up slashes only when an optional param was actually omitted,
       // so intentional trailing-slash patterns like "/blog/" are preserved.
       if (hadOmittedOptional) {
+        const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
         result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
+        if (hadTrailingSlash && !result.endsWith("/")) result += "/";
       }
     }
 

package/src/route-definition/dsl-helpers.ts

@@ -37,6 +37,7 @@ import type {
   UseItems,
 } from "../route-types.js";
 import type { RouteHelpers } from "./helpers-types.js";
+import { resolveHandlerUse, mergeHandlerUse } from "./resolve-handler-use.js";
 
 /**
  * Check if an item contains routes (directly or inside nested structures like cache).
@@ -447,15 +448,6 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
       : {}),
   } satisfies EntryData;
 
-  // Run use callback if provided to collect loaders, revalidate, loading
-  if (use && typeof use === "function") {
-    const result = store.run(namespace, entry, use)?.flat(3);
-    invariant(
-      Array.isArray(result) && result.every((item) => isValidUseItem(item)),
-      `parallel() use() callback must return an array of use items [${namespace}]`,
-    );
-  }
-
   for (const slotName of slotNames) {
     const slotEntry = {
       ...entry,
@@ -478,6 +470,22 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
             staticHandlerIds: undefined,
           }),
     } satisfies EntryData;
+
+    // Per-slot: handler.use defaults first, then explicit use second.
+    // This matches the "defaults first, overrides second" rule used by
+    // path(), layout(), and intercept(). Each slot's handler.use is
+    // scoped to its own entry (no cross-slot bleed).
+    const slotHandler = (slots as Record<string, any>)[slotName];
+    const slotHandlerUse = resolveHandlerUse(slotHandler);
+    const slotMergedUse = mergeHandlerUse(slotHandlerUse, use, "parallel");
+    if (slotMergedUse) {
+      const result = store.run(namespace, slotEntry, slotMergedUse)?.flat(3);
+      invariant(
+        Array.isArray(result) && result.every((item) => isValidUseItem(item)),
+        `parallel() use() callback must return an array of use items [${namespace}]`,
+      );
+    }
+
     ctx.parent.parallel[slotName] = slotEntry;
   }
   return { name: namespace, type: "parallel" } as ParallelItem;
@@ -527,8 +535,12 @@ const intercept = (
     when: [], // Selector conditions for conditional interception
   };
 
-  // Run use callback if provided to collect loaders, revalidate, middleware, etc.
-  if (use && typeof use === "function") {
+  // Merge handler.use defaults with explicit use
+  const handlerUseFn = resolveHandlerUse(handler);
+  const mergedUse = mergeHandlerUse(handlerUseFn, use, "intercept");
+
+  // Run merged use callback to collect loaders, revalidate, middleware, etc.
+  if (mergedUse) {
     // Create a temporary parent context for the use() callback
     // so that middleware, loader, revalidate attach to the intercept entry
     const originalParent = ctx.parent;
@@ -555,7 +567,7 @@ const intercept = (
     };
     ctx.parent = tempParent as EntryData;
 
-    const result = use()?.flat(3);
+    const result = mergedUse()?.flat(3);
 
     // Restore original parent
     ctx.parent = originalParent;
@@ -752,7 +764,7 @@ const routeFn: RouteHelpers<any, any>["route"] = (name, handler, use) => {
     shortCode: store.getShortCode("route"),
     type: "route",
     parent: ctx.parent,
-    handler,
+    handler: handler as unknown as Handler<any, any, any>,
     loading: undefined, // Allow loading() to attach loading state
     middleware: [],
     revalidate: [],
@@ -771,9 +783,12 @@ const routeFn: RouteHelpers<any, any>["route"] = (name, handler, use) => {
   );
   /* Register route entry */
   ctx.manifest.set(name, entry);
+  /* Merge handler.use defaults with explicit use */
+  const handlerUseFn = resolveHandlerUse(handler);
+  const mergedUse = mergeHandlerUse(handlerUseFn, use, "route");
   /* Run use and attach handlers */
-  if (use && typeof use === "function") {
-    const result = store.run(namespace, entry, use)?.flat(3);
+  if (mergedUse) {
+    const result = store.run(namespace, entry, mergedUse)?.flat(3);
     invariant(
       Array.isArray(result) && result.every((item) => isValidUseItem(item)),
       `route() use() callback must return an array of use items [${namespace}]`,
@@ -834,10 +849,14 @@ const layout: RouteHelpers<any, any>["layout"] = (handler, use) => {
     (handler as any).$$routePrefix = ctx.namePrefix;
   }
 
-  // Run use callback if provided
+  // Merge handler.use defaults with explicit use
+  const handlerUseFn = resolveHandlerUse(handler);
+  const mergedUse = mergeHandlerUse(handlerUseFn, use, "layout");
+
+  // Run merged use callback if present
   let result: AllUseItems[] | undefined;
-  if (use && typeof use === "function") {
-    result = store.run(namespace, entry, use)?.flat(3);
+  if (mergedUse) {
+    result = store.run(namespace, entry, mergedUse)?.flat(3);
 
     invariant(
       Array.isArray(result) && result.every((item) => isValidUseItem(item)),

package/src/route-definition/index.ts

@@ -45,6 +45,9 @@ export {
   type RouteHandlers,
 } from "./helper-factories.js";
 
+// Handler use resolver
+export { resolveHandlerUse } from "./resolve-handler-use.js";
+
 // Redirect
 export { redirect } from "./redirect.js";
 

package/src/route-definition/resolve-handler-use.ts

@@ -0,0 +1,149 @@
+import type { AllUseItems } from "../route-types.js";
+import { isPrerenderHandler, isPassthroughHandler } from "../prerender.js";
+import { isStaticHandler } from "../static-handler.js";
+
+/**
+ * Extract the .use callback from any handler shape.
+ *
+ * Checks definition brands first (objects with __brand), then plain functions.
+ * ReactNode handlers return undefined (no .use possible).
+ */
+export function resolveHandlerUse(handler: unknown): (() => any[]) | undefined {
+  if (handler == null) return undefined;
+
+  // Check branded definitions first — they're objects but also have typeof "object"
+  if (isPassthroughHandler(handler)) {
+    return (handler as any).use;
+  }
+  if (isPrerenderHandler(handler)) {
+    return (handler as any).use;
+  }
+  if (isStaticHandler(handler)) {
+    return (handler as any).use;
+  }
+  // Plain handler function
+  if (typeof handler === "function") {
+    return (handler as any).use;
+  }
+  // ReactNode or other — no .use
+  return undefined;
+}
+
+/**
+ * Allowed item types per mount site.
+ * Mirrors the RouteUseItem / ParallelUseItem / InterceptUseItem / LayoutUseItem unions
+ * from route-types.ts for runtime validation.
+ */
+const MOUNT_SITE_ALLOWED_TYPES: Record<string, Set<string>> = {
+  path: new Set([
+    "layout",
+    "parallel",
+    "intercept",
+    "middleware",
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "cache",
+    "transition",
+  ]),
+  // Response routes (path.json, path.text, etc.) — mirrors ResponseRouteUseItem
+  response: new Set(["middleware", "cache"]),
+  route: new Set([
+    "layout",
+    "parallel",
+    "intercept",
+    "middleware",
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "cache",
+    "transition",
+  ]),
+  // layout allows AllUseItems — no validation needed, but included for completeness
+  layout: new Set([
+    "layout",
+    "route",
+    "middleware",
+    "revalidate",
+    "parallel",
+    "intercept",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "cache",
+    "transition",
+    "include",
+  ]),
+  parallel: new Set([
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "transition",
+  ]),
+  intercept: new Set([
+    "middleware",
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "layout",
+    "route",
+    "when",
+    "transition",
+  ]),
+};
+
+/**
+ * Validate that items from handler.use() are valid for the given mount site.
+ * Throws a descriptive error if any item is not allowed.
+ */
+export function validateHandlerUseItems(
+  items: AllUseItems[],
+  mountSite: string,
+): void {
+  const allowed = MOUNT_SITE_ALLOWED_TYPES[mountSite];
+  if (!allowed) return;
+  for (const item of items) {
+    if (item == null) continue;
+    if (!allowed.has((item as any).type)) {
+      throw new Error(
+        `handler.use() returned ${(item as any).type}() which is not valid inside ${mountSite}(). ` +
+          `Allowed types: ${[...allowed].join(", ")}.`,
+      );
+    }
+  }
+}
+
+/**
+ * Create a merged use callback from handler.use and explicit use.
+ * handler.use items come first (defaults), explicit items second (overrides).
+ * Returns undefined if both are absent.
+ */
+export function mergeHandlerUse(
+  handlerUse: (() => any[]) | undefined,
+  explicitUse: (() => any[]) | undefined,
+  mountSite: string,
+): (() => any[]) | undefined {
+  if (!handlerUse && !explicitUse) return undefined;
+  if (!handlerUse) return explicitUse;
+  if (!explicitUse) {
+    return () => {
+      const items = handlerUse().flat(3);
+      validateHandlerUseItems(items, mountSite);
+      return items;
+    };
+  }
+  return () => {
+    const hItems = handlerUse().flat(3);
+    validateHandlerUseItems(hItems, mountSite);
+    return [...hItems, ...explicitUse()];
+  };
+}

package/src/route-types.ts

@@ -257,3 +257,14 @@ export type LoaderUseItem = RevalidateItem | CacheItem;
  * runtime via .flat(3).
  */
 export type UseItems<T> = (T | readonly T[])[];
+
+/**
+ * Union of all items that handler.use() may return.
+ * A handler doesn't know its mount site at definition time, so the type
+ * is intentionally broad — validation happens per-mount-site at runtime.
+ */
+export type HandlerUseItem =
+  | RouteUseItem
+  | LayoutUseItem
+  | ParallelUseItem
+  | InterceptUseItem;