@rangojs/router 0.0.0-experimental.dfdb0387 → 0.0.0-experimental.eb0645d3

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

@@ -55,6 +55,9 @@ const hasRoutesInItem = (item: AllUseItems): boolean => {
   if (item.type === "layout" && item.uses) {
     return item.uses.some((child) => hasRoutesInItem(child));
   }
+  if (item.type === "middleware" && item.uses) {
+    return item.uses.some((child) => hasRoutesInItem(child));
+  }
   return false;
 };
 
@@ -353,10 +356,37 @@ const cache: RouteHelpers<any, any>["cache"] = (
   return { name: namespace, type: "cache", uses: result } as CacheItem;
 };
 
-const middleware: RouteHelpers<any, any>["middleware"] = (...fn) => {
+const middleware: RouteHelpers<any, any>["middleware"] = (...args: any[]) => {
+  // Four call forms:
+  //   middleware(fn)                       — single fn, sibling
+  //   middleware(fn, () => [...])          — single fn, wrapping
+  //   middleware([fn1, fn2])              — array, sibling
+  //   middleware([fn1, fn2], () => [...]) — array, wrapping
+  const isArray = Array.isArray(args[0]);
+
+  // Reject the removed variadic form before executing anything.
+  // middleware(fn1, fn2, fn3) — 3+ args, always wrong.
+  // middleware(fn1, fn2) where fn2 is a middleware fn (length >= 1), not a
+  // children callback (length === 0) — legacy two-fn form, reject early.
+  if (
+    args.length > 2 ||
+    (!isArray &&
+      args.length === 2 &&
+      typeof args[1] === "function" &&
+      args[1].length > 0)
+  ) {
+    throw new Error(
+      "middleware() no longer accepts variadic arguments. " +
+        "Use middleware([fn1, fn2, ...]) instead of middleware(fn1, fn2, ...).",
+    );
+  }
+
+  const fns: MiddlewareFn<any>[] = isArray ? args[0] : [args[0]];
+  const children: (() => any[]) | undefined =
+    typeof args[1] === "function" ? args[1] : undefined;
+
   // Prevent "use cache" functions from being used as middleware.
-  // Checked before context validation — this is a static invariant.
-  for (const f of fn) {
+  for (const f of fns) {
     if (isCachedFunction(f)) {
       throw new Error(
         `A "use cache" function cannot be used as middleware. ` +
@@ -367,17 +397,80 @@ const middleware: RouteHelpers<any, any>["middleware"] = (...fn) => {
     }
   }
 
-  const ctx = getContext().getStore();
+  const store = getContext();
+  const ctx = store.getStore();
   if (!ctx) throw new Error("middleware() must be called inside map()");
 
-  // Attach to last entry in stack
-  const parent = ctx.parent;
-  if (!parent || !("middleware" in parent)) {
-    invariant(false, "No parent entry available for middleware()");
+  if (!children) {
+    // Sibling mode: attach to parent entry
+    const parent = ctx.parent;
+    if (!parent || !("middleware" in parent)) {
+      invariant(false, "No parent entry available for middleware()");
+    }
+    const name = `$${store.getNextIndex("middleware")}`;
+    parent.middleware.push(...fns);
+    return { name, type: "middleware" } as MiddlewareItem;
   }
-  const name = `$${getContext().getNextIndex("middleware")}`;
-  parent.middleware.push(...fn);
-  return { name, type: "middleware" } as MiddlewareItem;
+
+  // Wrapping mode: create a transparent layout that carries the middleware
+  const mwIndex = store.getNextIndex("middleware");
+  const namespace = `${ctx.namespace}.${mwIndex}`;
+
+  const urlPrefix = getUrlPrefix();
+  const entry = {
+    id: namespace,
+    shortCode: store.getShortCode("layout"),
+    type: "layout",
+    parent: ctx.parent,
+    handler: RootLayout,
+    loading: undefined,
+    middleware: [...fns],
+    revalidate: [],
+    errorBoundary: [],
+    notFoundBoundary: [],
+    layout: [],
+    parallel: {},
+    intercept: [],
+    loader: [],
+    ...(urlPrefix ? { mountPath: urlPrefix } : {}),
+  } as EntryData;
+
+  // Run children callback. If the second arg was actually a middleware fn
+  // (old variadic form: middleware(mw1, mw2)), this will return a non-array
+  // and the invariant below gives a clear migration error.
+  const rawResult = store.run(namespace, entry, children);
+
+  invariant(
+    Array.isArray(rawResult),
+    "middleware(fn, children) expects the second argument to return an array of use items. " +
+      "To pass multiple middleware, use middleware([fn1, fn2]).",
+  );
+
+  const result = rawResult.flat(3);
+
+  invariant(
+    result.every((item: any) => isValidUseItem(item)),
+    `middleware() children callback must return an array of use items [${namespace}]`,
+  );
+
+  const hasRoutes =
+    result &&
+    Array.isArray(result) &&
+    result.some((item) => item != null && hasRoutesInItem(item));
+
+  if (!hasRoutes) {
+    const parent = ctx.parent;
+    if (parent && "layout" in parent) {
+      entry.parent = null;
+      parent.layout.push(entry);
+    }
+  }
+
+  return {
+    name: namespace,
+    type: "middleware",
+    uses: result,
+  } as MiddlewareItem;
 };
 
 const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
@@ -398,13 +491,25 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
 
   const namespace = `${ctx.namespace}.$${store.getNextIndex("parallel")}`;
 
-  // Unwrap any static handler definitions in parallel slots
+  // Unwrap slot values. A slot value can be:
+  //   - a Handler / ReactNode (legacy form)
+  //   - a Static() definition (build-time only)
+  //   - a slot descriptor `{ handler, use? }` for slot-local overrides
+  // The descriptor's `use` runs after the broadcast `use` for that slot,
+  // so single-assignment items like `loading()` placed there win without
+  // affecting siblings.
   const unwrappedSlots: Record<string, any> = {};
+  const slotLocalUses: Record<string, (() => any[]) | undefined> = {};
   let hasStaticSlot = false;
   const staticSlotIds: Record<string, string> = {};
-  for (const [slotName, slotHandler] of Object.entries(
+  for (const [slotName, rawSlot] of Object.entries(
     slots as Record<string, any>,
   )) {
+    let slotHandler: any = rawSlot;
+    if (isSlotDescriptor(rawSlot)) {
+      slotHandler = rawSlot.handler;
+      slotLocalUses[slotName] = rawSlot.use;
+    }
     if (isStaticHandler(slotHandler)) {
       hasStaticSlot = true;
       unwrappedSlots[slotName] = slotHandler.handler;
@@ -471,13 +576,25 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
           }),
     } 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");
+    // Per-slot merge order (narrowest-scope-wins for single-assignment items
+    // like loading()):
+    //   1. handler.use      — defaults baked into the handler
+    //   2. shared `use`     — broadcast at the parallel() call site
+    //   3. slot-local `use` — per-slot override via `{ handler, use }` descriptor
+    // Items that accumulate (loader, middleware, revalidate, …) compose
+    // across all three layers regardless of order.
+    const rawSlot = (slots as Record<string, any>)[slotName];
+    const slotHandlerForUse = isSlotDescriptor(rawSlot)
+      ? rawSlot.handler
+      : rawSlot;
+    const slotHandlerUse = resolveHandlerUse(slotHandlerForUse);
+    const slotLocalUse = slotLocalUses[slotName];
+    const explicitUse = combineExplicitUses(use, slotLocalUse);
+    const slotMergedUse = mergeHandlerUse(
+      slotHandlerUse,
+      explicitUse,
+      "parallel",
+    );
     if (slotMergedUse) {
       const result = store.run(namespace, slotEntry, slotMergedUse)?.flat(3);
       invariant(
@@ -491,6 +608,28 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
   return { name: namespace, type: "parallel" } as ParallelItem;
 };
 
+function isSlotDescriptor(
+  value: unknown,
+): value is { handler: unknown; use?: () => any[] } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !("__brand" in value) &&
+    "handler" in value &&
+    typeof (value as any).handler !== "undefined"
+  );
+}
+
+function combineExplicitUses(
+  sharedUse: (() => any[]) | undefined,
+  slotLocalUse: (() => any[]) | undefined,
+): (() => any[]) | undefined {
+  if (!sharedUse && !slotLocalUse) return undefined;
+  if (!slotLocalUse) return sharedUse;
+  if (!sharedUse) return slotLocalUse;
+  return () => [...sharedUse(), ...slotLocalUse()];
+}
+
 /**
  * Intercept helper - defines an intercepting route for soft navigation
  */

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

@@ -123,7 +123,7 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   "@main": async (ctx) => <MainContent data={ctx.use(DataLoader)} />,
    * })
    *
-   * // With loaders and loading states
+   * // With loaders and loading states (broadcast to every slot)
    * parallel({
    *   "@analytics": AnalyticsPanel,
    *   "@metrics": MetricsPanel,
@@ -131,12 +131,36 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   loader(DashboardLoader),
    *   loading(<DashboardSkeleton />),
    * ])
+   *
+   * // Per-slot scoped use via slot descriptor — for single-assignment items
+   * // like loading() that should not broadcast to siblings.
+   * parallel({
+   *   "@meta": MetaSlot,
+   *   "@sidebar": {
+   *     handler: SidebarSlot,
+   *     use: () => [loading(<SidebarSkeleton />)],
+   *   },
+   * })
    * ```
    * @param slots - Object with slot names (prefixed with @) mapped to handlers
+   *                or `{ handler, use? }` slot descriptors.
    * @param use - Optional callback for loaders, loading, revalidate, etc.
+   *              Items here apply to every slot in the call (broadcast).
+   *              For per-slot single-assignment items, use the slot descriptor's
+   *              own `use` callback — slot-local items run after the broadcast,
+   *              so they take precedence on `loading()` and other last-write-wins
+   *              fields.
    */
   parallel: <
-    TSlots extends Record<`@${string}`, Handler<any, any, TEnv> | ReactNode>,
+    TSlots extends Record<
+      `@${string}`,
+      | Handler<any, any, TEnv>
+      | ReactNode
+      | {
+          handler: Handler<any, any, TEnv> | ReactNode;
+          use?: () => UseItems<ParallelUseItem>;
+        }
+    >,
   >(
     slots: TSlots,
     use?: () => UseItems<ParallelUseItem>,
@@ -182,21 +206,41 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
     ): InterceptItem;
   };
   /**
-   * Attach middleware to the current route/layout
+   * Attach middleware to the current route/layout, or wrap child segments
+   *
+   * **Sibling mode** — attaches middleware to the parent entry:
    * ```typescript
-   * middleware(async (ctx, next) => {
-   *   const session = await getSession(ctx.request);
-   *   if (!session) return redirect("/login");
-   *   ctx.set("user", session.user);
-   *   next();
-   * })
+   * layout(<DashboardShell />, () => [
+   *   middleware(authMiddleware),
+   *   middleware([authMiddleware, loggingMiddleware]),
+   *   path("/", DashboardPage),
+   * ])
+   * ```
    *
-   * // Chain multiple middleware
-   * middleware(authMiddleware, loggingMiddleware, rateLimitMiddleware)
+   * **Wrapping mode** — scopes middleware to the children only:
+   * ```typescript
+   * middleware(authMiddleware, () => [
+   *   path("/dashboard", DashboardPage),
+   *   path("/settings", SettingsPage),
+   * ])
+   *
+   * middleware([authMiddleware, loggingMiddleware], () => [
+   *   path("/admin", AdminPage),
+   * ])
    * ```
-   * @param fns - One or more middleware functions to execute in order
    */
-  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
    * ```typescript

package/src/route-types.ts

@@ -176,6 +176,13 @@ export type IncludeItem = {
     >;
     /** Root scope flag for dot-local reverse resolution */
     rootScoped?: boolean;
+    /**
+     * Positional include scope token composed from the parent scope plus this
+     * include's sibling index (`${parentScope}I${idx}`). Applied to direct-
+     * descendant shortCodes during lazy evaluation so routes inside the
+     * include cannot collide with siblings declared outside it.
+     */
+    includeScope?: string;
   };
   [IncludeBrand]: void;
 };

package/src/router/handler-context.ts

@@ -18,6 +18,7 @@ import { isInsideCacheScope } from "../server/context.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { PRERENDER_PASSTHROUGH } from "../prerender.js";
+import { encodePathSegment } from "./url-params.js";
 
 /**
  * Strip internal _rsc* query params from a URL.
@@ -174,11 +175,14 @@ export function createReverseFunction(
         /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
         (_, key) => {
           const value = effectiveParams[key];
-          if (value === undefined) {
+          // Empty string is treated as omitted — the trie matcher fills
+          // unmatched optional params with "" (not undefined), so reverse
+          // must collapse those segments instead of leaving empty slots.
+          if (value === undefined || value === "") {
             hadOmittedOptional = true;
             return "";
           }
-          return encodeURIComponent(value);
+          return encodePathSegment(value);
         },
       );
       // Second pass: required params (no trailing ?)
@@ -189,7 +193,7 @@ export function createReverseFunction(
           if (value === undefined) {
             throw new Error(`Missing param "${key}" for route "${name}"`);
           }
-          return encodeURIComponent(value);
+          return encodePathSegment(value);
         },
       );
       // Clean up slashes only when an optional param was actually omitted,

package/src/router/lazy-includes.ts

@@ -125,9 +125,8 @@ export function evaluateLazyEntry<TEnv = any>(
   // Merge captured counters from include() to maintain consistent
   // shortCode indices with sibling entries from pattern extraction
   const lazyCounters: Record<string, number> = {};
-  if (lazyContext && (lazyContext as any).counters) {
-    const captured = (lazyContext as any).counters as Record<string, number>;
-    for (const [key, value] of Object.entries(captured)) {
+  if (lazyContext?.counters) {
+    for (const [key, value] of Object.entries(lazyContext.counters)) {
       lazyCounters[key] = value;
     }
   }
@@ -141,8 +140,9 @@ export function evaluateLazyEntry<TEnv = any>(
       namespace: "lazy",
       parent: getIsolatedLazyParent(lazyContext?.parent as EntryData | null),
       counters: lazyCounters,
-      cacheProfiles: (lazyContext as any)?.cacheProfiles,
-      rootScoped: (lazyContext as any)?.rootScoped,
+      cacheProfiles: lazyContext?.cacheProfiles,
+      rootScoped: lazyContext?.rootScoped,
+      includeScope: lazyContext?.includeScope,
     },
     () => {
       // Run the lazy patterns handler with the original context prefixes

package/src/router/manifest.ts

@@ -126,28 +126,37 @@ export async function loadManifest(
     // were created during pattern extraction.  This prevents shortCode
     // collisions between lazy and non-lazy entries under the same parent
     // (e.g., ArticlesLayout and BlogLayout both under NavLayout).
-    if (lazyContext && (lazyContext as any).counters) {
-      const captured = (lazyContext as any).counters as Record<string, number>;
-      for (const [key, value] of Object.entries(captured)) {
+    if (lazyContext?.counters) {
+      for (const [key, value] of Object.entries(lazyContext.counters)) {
         Store.counters[key] = Math.max(Store.counters[key] ?? 0, value);
       }
     }
 
     // Propagate cache profiles for DSL-time cache("profileName") resolution.
     // Non-lazy entries carry profiles directly; lazy entries carry them
-    // in the captured lazyContext from include() time.
-    const entryProfiles =
-      entry.cacheProfiles ?? (lazyContext as any)?.cacheProfiles;
-    if (entryProfiles) {
-      Store.cacheProfiles = entryProfiles;
-    }
+    // in the captured lazyContext from include() time. Always write
+    // (including clearing to undefined) so a prior lazy build's profile
+    // map cannot leak into a later non-lazy build on the same ALS-backed
+    // Store — which would otherwise let cache("name") resolve a profile
+    // from an unrelated entry.
+    Store.cacheProfiles = entry.cacheProfiles ?? lazyContext?.cacheProfiles;
 
     // Propagate rootScoped from lazyContext so that routes inside
     // nested { name: "sub" } under { name: "" } keep inherited root scope
-    // when the manifest is rebuilt on each request.
-    if (lazyContext && (lazyContext as any).rootScoped !== undefined) {
-      Store.rootScoped = (lazyContext as any).rootScoped;
-    }
+    // when the manifest is rebuilt on each request. Always write
+    // (including clearing to undefined, which makes getRootScoped()
+    // return its true default) so a prior lazy build's scope cannot leak
+    // into a later non-lazy build on the same ALS-backed Store — which
+    // would otherwise mis-register plain routes as non-root-scoped and
+    // break dot-local reverse resolution.
+    Store.rootScoped = lazyContext?.rootScoped;
+
+    // Propagate includeScope from lazyContext so that direct-descendant
+    // shortCodes of this include use the correct scoped counter namespace
+    // on every manifest rebuild. Always write (including clearing to
+    // undefined) so a prior lazy build's scope cannot leak into a later
+    // non-lazy build on the same ALS-backed Store.
+    Store.includeScope = lazyContext?.includeScope;
 
     const handlerExecStart = performance.now();
     const useItems = await getContext().runWithStore(

package/src/router/match-middleware/cache-lookup.ts

@@ -251,6 +251,7 @@ async function* yieldFromStore<TEnv>(
           ctx.url,
           ctx.routeKey,
           ctx.actionContext,
+          ctx.stale || undefined,
         ),
       );
       state.matchedIds = [
@@ -598,7 +599,7 @@ export function withCacheLookup<TEnv>(
         routeKey: ctx.routeKey,
         context: ctx.handlerContext,
         actionContext: ctx.actionContext,
-        stale: cacheResult.shouldRevalidate || undefined,
+        stale: cacheResult.shouldRevalidate || ctx.stale || undefined,
         traceSource: "cache-hit",
       });
 

package/src/router/middleware.ts

@@ -10,6 +10,7 @@
  */
 
 import { contextGet, contextSet } from "../context-var.js";
+import { safeDecodeURIComponent } from "./url-params.js";
 import type {
   CollectedMiddleware,
   MiddlewareCollectableEntry,
@@ -22,6 +23,7 @@ import { _getRequestContext } from "../server/request-context.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { appendMetric, createMetricsStore } from "./metrics.js";
 import { stripInternalParams } from "./handler-context.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.js";
 
 // Re-export types and cookie utilities for backward compatibility
 export type {
@@ -112,7 +114,12 @@ function escapeRegex(str: string): string {
 }
 
 /**
- * Extract params from a pathname using a pattern's regex and param names
+ * Extract params from a pathname using a pattern's regex and param names.
+ *
+ * Values are URL-decoded so apps see the raw string (e.g. "ivo@example.com")
+ * instead of the percent-encoded form ("ivo%40example.com"). This matches the
+ * contract assumed by ctx.reverse (which re-encodes) and aligns with
+ * Express/React Router/Fastify/Koa.
  */
 export function extractParams(
   pathname: string,
@@ -124,7 +131,7 @@ export function extractParams(
 
   const params: Record<string, string> = {};
   for (let i = 0; i < paramNames.length; i++) {
-    params[paramNames[i]] = match[i + 1] || "";
+    params[paramNames[i]] = safeDecodeURIComponent(match[i + 1] || "");
   }
   return params;
 }
@@ -360,6 +367,11 @@ export async function executeMiddleware<TEnv>(
         });
       }
 
+      if (isWebSocketUpgradeResponse(response)) {
+        responseHolder.response = response;
+        return response;
+      }
+
       // Clone response with merged headers (mutable for post-next() modifications)
       responseHolder.response = new Response(response.body, {
         status: response.status,
@@ -451,6 +463,10 @@ export async function executeMiddleware<TEnv>(
     // RequestContext stub headers (from ctx.setCookie) into the
     // returned Response so they are not lost.
     if (result instanceof Response) {
+      if (isWebSocketUpgradeResponse(result)) {
+        responseHolder.response = result;
+        return result;
+      }
       const mergedHeaders = new Headers(result.headers);
       stubResponse.headers.forEach((value, name) => {
         if (name.toLowerCase() === "set-cookie") {
@@ -527,8 +543,11 @@ export async function executeMiddleware<TEnv>(
   // last merge point (e.g. cookies().set() called after await next()).
   // The reqCtx stub may have already been partially merged during finalHandler
   // or early-return paths; only append *new* Set-Cookie entries to avoid dupes.
+  //
+  // Skip for upgrade responses: upgrade headers are semantically immutable and
+  // set-cookie on an upgrade is not meaningful.
   const reqCtx = _getRequestContext();
-  if (reqCtx) {
+  if (reqCtx && !isWebSocketUpgradeResponse(finalResponse)) {
     const stubCookies = reqCtx.res.headers.getSetCookie();
     if (stubCookies.length > 0) {
       const existingCookies = new Set(finalResponse.headers.getSetCookie());