@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

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,10 @@ export interface LazyIncludeContext {
   urlPrefix: string;
   namePrefix: string | undefined;
   parent: unknown; // EntryData - avoid circular import
+  cacheProfiles?: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
 }
 
 /**
@@ -37,6 +41,14 @@ 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> }>
@@ -49,6 +61,12 @@ export interface RouteEntry<TEnv = any> {
    */
   prerenderRouteKeys?: Set<string>;
 
+  /**
+   * Route keys in this entry that use `{ passthrough: true }`.
+   * Used by the non-trie match path to set the `pt` flag.
+   */
+  passthroughRouteKeys?: Set<string>;
+
   // === Lazy evaluation fields ===
 
   /**
@@ -71,4 +89,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

@@ -124,11 +124,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

@@ -4,17 +4,37 @@ import {
   runWithPrefixes,
   getUrlPrefix,
   getNamePrefix,
+  getRootScoped,
 } 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 +111,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 +127,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) {
@@ -136,6 +165,16 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
       ctx.counters[layoutCounterKey]++;
     }
 
+    // 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 +189,8 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
         namePrefix: fullNamePrefix,
         parent: capturedParent,
         counters: capturedCounters,
+        cacheProfiles: ctx.cacheProfiles,
+        rootScoped: capturedRootScoped,
       },
     } 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

@@ -47,6 +47,7 @@ import type {
 } from "./response-types.js";
 import type {
   UnnamedRoute,
+  LocalOnlyInclude,
   PathOptions,
   UrlPatterns,
   IncludeOptions,
@@ -149,7 +150,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,14 +206,24 @@ 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>;
@@ -234,12 +245,19 @@ 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

package/src/urls/path-helper.ts

@@ -6,8 +6,14 @@ import type {
   RouteUseItem,
   UseItems,
 } from "../route-types.js";
-import { getContext, getUrlPrefix, getNamePrefix } from "../server/context";
+import {
+  getContext,
+  getUrlPrefix,
+  getNamePrefix,
+  getRootScoped,
+} from "../server/context";
 import { invariant } from "../errors";
+import { validateUserRouteName } from "../route-name.js";
 import {
   isPrerenderHandler,
   type PrerenderHandlerDefinition,
@@ -16,7 +22,10 @@ import {
   isStaticHandler,
   type StaticHandlerDefinition,
 } from "../static-handler.js";
-import { registerSearchSchema } from "../route-map-builder.js";
+import {
+  registerSearchSchema,
+  registerRouteRootScope,
+} from "../route-map-builder.js";
 import { RESPONSE_TYPE } from "./response-types.js";
 import type { PathOptions } from "./pattern-types.js";
 import type {
@@ -143,6 +152,9 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
     // 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);
 
@@ -222,6 +234,9 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
     // Register route entry with prefixed name
     ctx.manifest.set(routeName, entry);
 
+    // Register root-scope flag for dot-local reverse resolution
+    registerRouteRootScope(routeName, getRootScoped());
+
     // Also store pattern in a separate map for URL generation
     if (ctx.patterns) {
       ctx.patterns.set(routeName, prefixedPattern);

package/src/urls/pattern-types.ts

@@ -15,6 +15,16 @@ import { RESPONSE_TYPE } from "./response-types.js";
  */
 export type UnnamedRoute = "$unnamed";
 
+/**
+ * Sentinel type for include() mounts that stay local to the mounted module.
+ * This keeps child route names out of the parent/global type map while still
+ * allowing the mounted module to use its own local route names internally.
+ *
+ * Branded with a symbol key so it cannot be accidentally produced by user code.
+ */
+declare const LOCAL_ONLY_BRAND: unique symbol;
+export type LocalOnlyInclude = string & { [LOCAL_ONLY_BRAND]: void };
+
 /**
  * Options for path() function
  */
@@ -70,6 +80,16 @@ export interface UrlPatterns<
  * Options for include()
  */
 export interface IncludeOptions<TNamePrefix extends string = string> {
-  /** Name prefix for all routes in this pattern set */
+  /**
+   * Name prefix for all routes in this pattern set.
+   *
+   * - `{ name: "blog" }` — children become `blog.index`, `blog.detail`, etc.
+   *   Visible in generated route types and resolvable globally via `reverse("blog.index")`.
+   * - `{ name: "" }` — children merge into the parent namespace with no prefix.
+   *   Equivalent to defining the routes inline at the include site.
+   * - Omitted — children live in a private local scope, hidden from the
+   *   generated route map and global reverse resolution. Only dot-local
+   *   reverse (e.g. `reverse(".child")`) works from inside the module.
+   */
   name?: TNamePrefix;
 }

package/src/urls/response-types.ts

@@ -1,6 +1,30 @@
-import type { CookieOptions } from "../router/middleware.js";
 import type { ContextVar } from "../context-var.js";
-import type { DefaultVars } from "../types/global-namespace.js";
+import type { ReverseFunction } from "../reverse.js";
+import type {
+  DefaultReverseRouteMap,
+  DefaultVars,
+} from "../types/global-namespace.js";
+
+/**
+ * Reverse function for response handler contexts.
+ * Global names get autocomplete and param validation from the generated route map.
+ * Local `.name` calls are accepted but not validated (scope unknown at type level).
+ */
+type ResponseReverseFunction = [DefaultReverseRouteMap] extends [
+  Record<string, string>,
+]
+  ? (
+      name: string,
+      params?: Record<string, string>,
+      search?: Record<string, unknown>,
+    ) => string
+  : ReverseFunction<DefaultReverseRouteMap> & {
+      (
+        name: `.${string}`,
+        params?: Record<string, string>,
+        search?: Record<string, unknown>,
+      ): string;
+    };
 
 /**
  * Symbol marking a route as a response route (non-RSC).
@@ -53,8 +77,8 @@ export type TextResponseHandler<
 
 /**
  * Lighter handler context for response routes.
- * No ctx.use() (no loaders). Supports setting response headers and cookies
- * without constructing a full Response object.
+ * No ctx.use() (no loaders). Supports setting response headers via ctx.header().
+ * Use the standalone cookies() function for cookie mutations.
  */
 export interface ResponseHandlerContext<
   TParams = Record<string, string>,
@@ -72,13 +96,11 @@ export interface ResponseHandlerContext<
   url: URL;
   /** The pathname portion of the request URL. */
   pathname: string;
-  reverse: (name: string, params?: Record<string, string>) => string;
+  reverse: ResponseReverseFunction;
   /** Read a variable set by middleware via ctx.set(key, value) or ctx.set(ContextVar, value). */
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;
   } & (<K extends keyof DefaultVars>(key: K) => DefaultVars[K]);
   /** Set a response header. Merged into the auto-wrapped or pass-through Response. */
   header: (name: string, value: string) => void;
-  /** Set a cookie on the response. */
-  setCookie: (name: string, value: string, options?: CookieOptions) => void;
 }

package/src/urls/type-extraction.ts

@@ -6,7 +6,11 @@ import type {
   TypedCacheItem,
   TypedTransitionItem,
 } from "../route-types.js";
-import type { UnnamedRoute, UrlPatterns } from "./pattern-types.js";
+import type {
+  LocalOnlyInclude,
+  UnnamedRoute,
+  UrlPatterns,
+} from "./pattern-types.js";
 
 // ============================================================================
 // Route Type Extraction Utilities
@@ -156,13 +160,15 @@ type ExtractRoutesFromItem<T, D extends number = 40> = [D] extends [never]
           infer TNamePrefix,
           infer TUrlPrefix
         >
-      ? TNamePrefix extends string
-        ? TUrlPrefix extends string
-          ? PrefixRoutes<PrefixPatterns<TRoutes, TUrlPrefix>, TNamePrefix>
-          : PrefixRoutes<TRoutes, TNamePrefix>
-        : TUrlPrefix extends string
-          ? PrefixPatterns<TRoutes, TUrlPrefix>
-          : TRoutes
+      ? TNamePrefix extends LocalOnlyInclude
+        ? {}
+        : TNamePrefix extends string
+          ? TUrlPrefix extends string
+            ? PrefixRoutes<PrefixPatterns<TRoutes, TUrlPrefix>, TNamePrefix>
+            : PrefixRoutes<TRoutes, TNamePrefix>
+          : TUrlPrefix extends string
+            ? PrefixPatterns<TRoutes, TUrlPrefix>
+            : TRoutes
       : // TypedLayoutItem: extract child routes from phantom type
         T extends TypedLayoutItem<infer TChildRoutes>
         ? TChildRoutes
@@ -239,13 +245,15 @@ type ExtractResponsesFromItem<T, D extends number = 40> = [D] extends [never]
         : { [K in TName]: TData }
       : {}
     : T extends TypedIncludeItem<any, infer TNamePrefix, any, infer TResponses>
-      ? TNamePrefix extends string
-        ? TResponses extends Record<string, unknown>
-          ? PrefixKeys<TResponses, TNamePrefix>
-          : {}
-        : TResponses extends Record<string, unknown>
-          ? TResponses
-          : {}
+      ? TNamePrefix extends LocalOnlyInclude
+        ? {}
+        : TNamePrefix extends string
+          ? TResponses extends Record<string, unknown>
+            ? PrefixKeys<TResponses, TNamePrefix>
+            : {}
+          : TResponses extends Record<string, unknown>
+            ? TResponses
+            : {}
       : T extends TypedLayoutItem<any, infer TChildResponses>
         ? TChildResponses extends Record<string, unknown>
           ? TChildResponses

package/src/use-loader.tsx

@@ -88,6 +88,7 @@ function useLoaderInternal<T>(
   const [fetchedData, setFetchedData] = useState<T | undefined>(undefined);
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
+  const requestIdRef = useRef(0);
 
   // Track context data changes to reset fetched data on navigation
   const prevContextDataRef = useRef(contextData);
@@ -105,12 +106,23 @@ function useLoaderInternal<T>(
 
   const throwOnError = options?.throwOnError ?? true;
 
+  // Refs for values used inside load() that should NOT cause callback identity
+  // churn. loader.$$id can change if a reusable component receives a different
+  // loader without remounting; data changes on every navigation. Refs keep the
+  // callback stable while always reading the latest values.
+  const loaderIdRef = useRef(loader.$$id);
+  loaderIdRef.current = loader.$$id;
+  const dataRef = useRef(data);
+  dataRef.current = data;
+
   // Load function for fetching data via the ?_rsc_loader endpoint.
   // Supports GET (data fetching) and POST/PUT/PATCH/DELETE (mutations).
   const load = useCallback(
     async (loadOptions?: LoadOptions): Promise<T> => {
+      const requestId = ++requestIdRef.current;
+      const loaderId = loaderIdRef.current;
       // Verify the loader has $$id
-      if (!loader.$$id) {
+      if (!loaderId) {
         throw new Error(
           `Loader is missing $$id. Make sure the exposeLoaderId Vite plugin is enabled.`,
         );
@@ -120,8 +132,8 @@ function useLoaderInternal<T>(
       setError(null);
 
       try {
-        const url = new URL(window.location.pathname, window.location.origin);
-        url.searchParams.set("_rsc_loader", loader.$$id);
+        const url = new URL(window.location.href);
+        url.searchParams.set("_rsc_loader", loaderId);
 
         const method = loadOptions?.method ?? "GET";
         const isBodyMethod = method !== "GET";
@@ -202,19 +214,25 @@ function useLoaderInternal<T>(
         }
 
         const result = payload.loaderResult;
-        setFetchedData(result);
+        if (requestId === requestIdRef.current) {
+          setFetchedData(result);
+        }
         return result;
       } catch (e) {
         const err = e instanceof Error ? e : new Error(String(e));
-        setError(err);
+        if (requestId === requestIdRef.current) {
+          setError(err);
+        }
         if (throwOnError) {
           throw err;
         }
-        // When throwOnError is false, return the current data (previous successful
-        // value or undefined). Caller should check error state for error handling.
-        return data as T;
+        // When throwOnError is false, return the latest data snapshot (previous
+        // successful value or undefined). Caller should check error state.
+        return dataRef.current as T;
       } finally {
-        setIsLoading(false);
+        if (requestId === requestIdRef.current) {
+          setIsLoading(false);
+        }
       }
     },
     [throwOnError],