@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.25dbaac3

package/src/types/request-scope.ts

@@ -0,0 +1,126 @@
+/**
+ * RequestScope: the fields every user-facing context shares.
+ *
+ * A handler, middleware, loader, response handler, and the ALS-bound
+ * RequestContext are all different phases of the same request, and they
+ * all carry the same set of request-scoped capabilities: the raw Request,
+ * the parsed URL pair (`url` is cleaned of internal `_rsc*` params,
+ * `originalUrl` retains them), pathname/searchParams, platform bindings
+ * (`env`), and two escape hatches for work that outlives the response
+ * (`waitUntil`) or needs the raw Cloudflare runtime object
+ * (`executionContext`).
+ *
+ * Each public context type intersects `RequestScope<TEnv>` with its own
+ * phase-specific fields (e.g. `params`/`reverse` on HandlerContext,
+ * `headers`/`header()` on MiddlewareContext). That keeps platform surface
+ * in one place and lets the next runtime escape hatch we need land in
+ * one file instead of four.
+ */
+
+import type { DefaultEnv } from "./global-namespace.js";
+
+/**
+ * Minimal subset of Cloudflare Workers' ExecutionContext that the router
+ * uses. Defined locally so the package does not depend on
+ * `@cloudflare/workers-types`. Consumers that want the full type can cast.
+ *
+ * On non-Cloudflare runtimes (Node, dev server, tests), this is undefined
+ * — portable apps should prefer `ctx.waitUntil(...)`, which degrades
+ * gracefully. `ctx.executionContext` is the escape hatch for libraries
+ * (MCP, Durable Object routing, etc.) that type their arguments as the
+ * raw ExecutionContext.
+ */
+export interface ExecutionContext {
+  waitUntil(promise: Promise<any>): void;
+  passThroughOnException(): void;
+}
+
+/**
+ * Fallback `waitUntil` body used when no Cloudflare `ExecutionContext`
+ * is available (Node, dev, tests). Runs the work fire-and-forget and
+ * logs errors so they don't silently swallow.
+ *
+ * Exported so every `waitUntil` call site degrades identically instead
+ * of inventing its own fallback policy.
+ */
+export function fireAndForgetWaitUntil(fn: () => Promise<void>): void {
+  fn().catch((err) =>
+    console.error("[waitUntil] Background task failed:", err),
+  );
+}
+
+/**
+ * Fields present on every user-facing request context.
+ *
+ * @template TEnv - Platform bindings type (Cloudflare env, etc.).
+ */
+export interface RequestScope<TEnv = DefaultEnv> {
+  /**
+   * The original incoming Request object (transport URL intact).
+   * Use `url` / `searchParams` for application logic — those have
+   * internal `_rsc*` params stripped. `request` preserves the raw URL
+   * when you need original headers, method, or body.
+   */
+  request: Request;
+
+  /**
+   * The request URL with internal `_rsc*` transport params stripped.
+   * Use this for routing, link generation, and display.
+   */
+  url: URL;
+
+  /**
+   * The original request URL with all parameters intact, including
+   * internal `_rsc*` transport params. Use `url` for application logic
+   * — this is only needed for advanced cases like debugging or custom
+   * cache keying.
+   */
+  originalUrl: URL;
+
+  /** URL pathname (same as `url.pathname`). */
+  pathname: string;
+
+  /**
+   * Query parameters from the URL (system params like `_rsc*` are
+   * filtered). Always a standard `URLSearchParams` instance.
+   */
+  searchParams: URLSearchParams;
+
+  /**
+   * Platform bindings (DB, KV, secrets, etc.). On Cloudflare Workers
+   * these are the `env` object passed to the Worker's `fetch()` handler.
+   */
+  env: TEnv;
+
+  /**
+   * Schedule work to run after the response is sent.
+   * On Cloudflare Workers, delegates to `executionContext.waitUntil()`.
+   * On Node / dev / tests, runs as fire-and-forget with error logging.
+   *
+   * @example
+   * ```typescript
+   * ctx.waitUntil(async () => {
+   *   await cacheStore.set(key, data, ttl);
+   * });
+   * ```
+   */
+  waitUntil(fn: () => Promise<void>): void;
+
+  /**
+   * Raw Cloudflare Workers `ExecutionContext`, when running on a
+   * Cloudflare-compatible runtime. Undefined elsewhere.
+   *
+   * Escape hatch for libraries that type their arguments as
+   * `ExecutionContext` (MCP `fetch`, `routeAgentRequest`, etc.).
+   * For the common "do work after the response" case, prefer
+   * `ctx.waitUntil(...)` — it is platform-neutral.
+   *
+   * @example
+   * ```typescript
+   * path.any("/mcp", (ctx) =>
+   *   emailMcp.fetch(ctx.request, ctx.env, ctx.executionContext!),
+   * );
+   * ```
+   */
+  executionContext?: ExecutionContext;
+}

package/src/types/route-config.ts

@@ -7,24 +7,6 @@ export type DocumentProps = {
   children: ReactNode;
 };
 
-/**
- * @deprecated RouterEnv is no longer needed. Pass bindings directly as TEnv
- * to createRouter<TEnv>() and declare RSCRouter.Vars for variables.
- *
- * Migration:
- *   // Before:
- *   type AppEnv = RouterEnv<AppBindings, AppVariables>;
- *   createRouter<AppEnv>();
- *
- *   // After:
- *   createRouter<AppBindings>();
- *   declare global { namespace RSCRouter { interface Vars extends AppVariables {} } }
- */
-export interface RouterEnv<TBindings = {}, TVariables = {}> {
-  Bindings: TBindings;
-  Variables: TVariables;
-}
-
 /**
  * Parse constraint values into a union type
  * "a|b|c" -> "a" | "b" | "c"
@@ -42,17 +24,26 @@ type ParseConstraint<T extends string> =
  * - :param(a|b)? -> { name: "param", optional: true, type: "a" | "b" }
  */
 type ExtractParamInfo<T extends string> =
-  // Optional + constrained: :param(a|b)?
-  T extends `${infer Name}(${infer Constraint})?`
+  // Optional + constrained (with optional suffix): :param(a|b)?suffix
+  T extends `${infer Name}(${infer Constraint})?${string}`
     ? { name: Name; optional: true; type: ParseConstraint<Constraint> }
-    : // Constrained only: :param(a|b)
-      T extends `${infer Name}(${infer Constraint})`
+    : // Constrained (with optional suffix): :param(a|b)suffix
+      T extends `${infer Name}(${infer Constraint})${string}`
       ? { name: Name; optional: false; type: ParseConstraint<Constraint> }
-      : // Optional only: :param?
-        T extends `${infer Name}?`
+      : // Optional (with optional suffix): :param?suffix
+        T extends `${infer Name}?${string}`
         ? { name: Name; optional: true; type: string }
-        : // Required: :param
-          { name: T; optional: false; type: string };
+        : // Param with dot-suffix: :param.html
+          T extends `${infer Name}.${string}`
+          ? { 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}`
+              ? { name: Name; optional: false; type: string }
+              : // Required: :param (no suffix)
+                { name: T; optional: false; type: string };
 
 /**
  * Build param object from info

package/src/types/route-entry.ts

@@ -8,6 +8,21 @@ export interface LazyIncludeContext {
   urlPrefix: string;
   namePrefix: string | undefined;
   parent: unknown; // EntryData - avoid circular import
+  /** Counter snapshot from pattern extraction for consistent shortCode indices */
+  counters?: Record<string, number>;
+  cacheProfiles?: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
+  /** 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;
 }
 
 /**
@@ -37,18 +52,39 @@ export interface RouteEntry<TEnv = any> {
    * If not specified for a route, defaults to pattern-based detection
    */
   trailingSlash?: Record<string, TrailingSlashMode>;
+  /**
+   * Supported handler shapes:
+   *   - sync: () => Array<AllUseItems>
+   *   - lazy import: () => Promise<{ default: () => Array<AllUseItems> }>
+   *   - lazy function: () => Promise<() => Array<AllUseItems>>
+   *
+   * Direct Promise<Array> is NOT supported and rejected at runtime.
+   */
   handler: () =>
     | Array<AllUseItems>
     | Promise<{ default: () => Array<AllUseItems> }>
     | Promise<() => Array<AllUseItems>>;
   mountIndex: number;
 
+  /**
+   * Router ID that owns this entry. Used to namespace the manifest cache
+   * so multi-router setups (host routing) don't share cached EntryData
+   * across routers with overlapping mountIndex + routeKey combinations.
+   */
+  routerId?: string;
+
   /**
    * Route keys in this entry that have pre-render handlers.
    * Used by the non-trie match path to set the `pr` flag.
    */
   prerenderRouteKeys?: Set<string>;
 
+  /**
+   * Route keys in this entry that are wrapped with `Passthrough()`.
+   * Used by the non-trie match path to set the `pt` flag.
+   */
+  passthroughRouteKeys?: Set<string>;
+
   // === Lazy evaluation fields ===
 
   /**
@@ -71,4 +107,14 @@ export interface RouteEntry<TEnv = any> {
    * For lazy entries: whether patterns have been evaluated
    */
   lazyEvaluated?: boolean;
+
+  /**
+   * Cache profiles for DSL-time cache("profileName") resolution.
+   * Set on all entries (lazy and non-lazy) so loadManifest() can
+   * propagate them into the HelperContext Store.
+   */
+  cacheProfiles?: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
 }

package/src/types/segments.ts

@@ -50,7 +50,9 @@ export interface ResolvedSegment {
   parallelName?: string; // For parallels: the parallel group name (used to match with revalidations)
   // Loader-specific fields
   loaderId?: string; // For loaders: the loader $$id identifier
+  _inherited?: boolean; // For inherited loaders: dedup marker for buildMatchResult
   loaderData?: any; // For loaders: the resolved data from loader execution
+  parallelLoading?: ReactNode; // For parallel-owned loaders: the parallel's loading fallback
   // Intercept loader fields (for streaming loader data in parallel segments)
   loaderDataPromise?: Promise<any[]> | any[]; // Loader data promise or resolved array
   loaderIds?: string[]; // IDs ($$id) of loaders for this segment
@@ -60,6 +62,14 @@ 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;
 }
 
 /**
@@ -114,6 +124,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
@@ -124,11 +143,6 @@ export interface MatchResult {
    * Used by ctx.reverse() for local name resolution.
    */
   routeName?: string;
-  /**
-   * Server-Timing header value (only present when debugPerformance is enabled)
-   * Can be added to response headers for DevTools integration
-   */
-  serverTiming?: string;
   /**
    * State of named slots for this route match
    * Key is slot name (e.g., "@modal"), value is slot state

package/src/urls/include-helper.ts

@@ -5,16 +5,35 @@ import {
   getUrlPrefix,
   getNamePrefix,
 } from "../server/context";
+import {
+  INTERNAL_INCLUDE_SCOPE_PREFIX,
+  validateUserRouteName,
+} from "../route-name.js";
 import type { UrlPatterns, IncludeOptions } from "./pattern-types.js";
 import type { IncludeFn } from "./path-helper-types.js";
 
+function hasExplicitNameOption(options: IncludeOptions | undefined): boolean {
+  return !!options && Object.prototype.hasOwnProperty.call(options, "name");
+}
+
+function allocateInternalIncludeScopeId(
+  counters: Record<string, number>,
+): string {
+  const key = "__include_scope__";
+  const index = counters[key] ?? 0;
+  counters[key] = index + 1;
+  return `${INTERNAL_INCLUDE_SCOPE_PREFIX}${index}`;
+}
+
 /**
  * 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, options } = item;
-  const namePrefix = options?.name;
+  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
@@ -91,7 +110,11 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
     const ctx = store.getStore();
     if (!ctx) throw new Error("include() must be called inside urls()");
 
-    const namePrefix = options?.name;
+    const explicitName = options?.name;
+    const hasExplicitName = hasExplicitNameOption(options);
+    if (hasExplicitName && explicitName) {
+      validateUserRouteName(explicitName);
+    }
     const name = `$include_${prefix.replace(/[/:*?]/g, "_")}`;
 
     // Capture context for deferred evaluation
@@ -103,11 +126,16 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
         ? capturedUrlPrefix + prefix.slice(1)
         : capturedUrlPrefix + prefix
       : prefix;
-    const fullNamePrefix = namePrefix
-      ? capturedNamePrefix
-        ? `${capturedNamePrefix}.${namePrefix}`
-        : namePrefix
-      : capturedNamePrefix;
+    const internalScope = !hasExplicitName
+      ? allocateInternalIncludeScopeId(ctx.counters)
+      : undefined;
+    const nextSegment = hasExplicitName ? explicitName : internalScope;
+    const fullNamePrefix =
+      nextSegment !== undefined && nextSegment !== ""
+        ? capturedNamePrefix
+          ? `${capturedNamePrefix}.${nextSegment}`
+          : nextSegment
+        : capturedNamePrefix;
 
     // Track this include for build-time manifest generation
     if (ctx.trackedIncludes) {
@@ -120,22 +148,42 @@ 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;
+      const includeIdx = ctx.counters[includeCounterKey];
+      ctx.counters[includeCounterKey] = includeIdx + 1;
+      includeScope = `${parentScope}I${includeIdx}`;
     }
 
+    // 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;
+    const capturedRootScoped =
+      nextSegment === ""
+        ? (parentRootScoped ?? true)
+        : nextSegment !== undefined
+          ? (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 {
@@ -150,6 +198,9 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
         namePrefix: fullNamePrefix,
         parent: capturedParent,
         counters: capturedCounters,
+        cacheProfiles: ctx.cacheProfiles,
+        rootScoped: capturedRootScoped,
+        includeScope,
       },
     } as IncludeItem;
   };

package/src/urls/index.ts

@@ -11,6 +11,7 @@ export {
 // Pattern types
 export type {
   UnnamedRoute,
+  LocalOnlyInclude,
   PathOptions,
   PathDefinition,
   UrlPatterns,

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

@@ -37,7 +37,10 @@ import type {
   UseItems,
 } from "../route-types.js";
 import type { SearchSchema } from "../search-params.js";
-import type { PrerenderHandlerDefinition } from "../prerender.js";
+import type {
+  PrerenderHandlerDefinition,
+  PassthroughHandlerDefinition,
+} from "../prerender.js";
 import type { StaticHandlerDefinition } from "../static-handler.js";
 import type { InterceptWhenFn } from "../server/context";
 import type {
@@ -47,6 +50,7 @@ import type {
 } from "./response-types.js";
 import type {
   UnnamedRoute,
+  LocalOnlyInclude,
   PathOptions,
   UrlPatterns,
   IncludeOptions,
@@ -69,6 +73,7 @@ export type PathFn<TEnv> = <
         ctx: HandlerContext<TParams, TEnv, TSearch>,
       ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>)
     | PrerenderHandlerDefinition<TParams>
+    | PassthroughHandlerDefinition<TParams, TEnv>
     | StaticHandlerDefinition<TParams>,
   optionsOrUse?: PathOptions<TName, TSearch> | (() => UseItems<RouteUseItem>),
   use?: () => UseItems<RouteUseItem>,
@@ -149,7 +154,7 @@ export type TextResponsePathFn<TEnv> = <
 export type IncludeFn<TEnv> = <
   TRoutes extends Record<string, any>,
   const TUrlPrefix extends string,
-  const TNamePrefix extends string = never,
+  const TNamePrefix extends string = LocalOnlyInclude,
   TResponses extends Record<string, unknown> = Record<string, unknown>,
 >(
   prefix: TUrlPrefix,
@@ -205,25 +210,50 @@ export type PathHelpers<TEnv> = {
   };
 
   /**
-   * Include nested URL patterns with optional name prefix
+   * Include nested URL patterns under a URL prefix.
    *
-   * ```typescript
-   * // Without name - routes keep local names
-   * include("/blog", blogPatterns)
+   * The `name` option controls how child route names appear in the
+   * global route map and generated types:
    *
-   * // With name - routes are prefixed (e.g., "index" -> "blog.index")
+   * ```typescript
+   * // Named — children become "blog.index", "blog.post", etc.
+   * // Visible in generated types and globally reversible.
    * include("/blog", blogPatterns, { name: "blog" })
+   *
+   * // Flattened — children merge into the parent namespace as-is.
+   * // Equivalent to defining those routes inline at the include site.
+   * include("/blog", blogPatterns, { name: "" })
+   *
+   * // Local-only (default) — children are scoped privately.
+   * // Hidden from generated types and global reverse resolution.
+   * // Only dot-local reverse (reverse(".child")) works inside.
+   * include("/blog", blogPatterns)
    * ```
    */
   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()`.
    */
   parallel: <
     TSlots extends Record<
       `@${string}`,
-      Handler<any, any, TEnv> | ReactNode | StaticHandlerDefinition
+      | Handler<any, any, TEnv>
+      | ReactNode
+      | StaticHandlerDefinition
+      | {
+          handler:
+            | Handler<any, any, TEnv>
+            | ReactNode
+            | StaticHandlerDefinition;
+          use?: () => ParallelUseItem[];
+        }
     >,
   >(
     slots: TSlots,
@@ -234,17 +264,35 @@ export type PathHelpers<TEnv> = {
    * Define an intercepting route for soft navigation
    * Note: routeName must match a named path() in this urlpatterns
    */
-  intercept: (
-    slotName: `@${string}`,
-    routeName: string,
-    handler: ReactNode | Handler<any, any, TEnv>,
-    use?: () => InterceptUseItem[],
-  ) => InterceptItem;
+  intercept: keyof RSCRouter.GeneratedRouteMap extends never
+    ? (
+        slotName: `@${string}`,
+        routeName: string,
+        handler: ReactNode | Handler<any, any, TEnv>,
+        use?: () => InterceptUseItem[],
+      ) => InterceptItem
+    : (
+        slotName: `@${string}`,
+        routeName: (keyof RSCRouter.GeneratedRouteMap & string) | `.${string}`,
+        handler: ReactNode | Handler<any, any, TEnv>,
+        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
@@ -262,7 +310,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