@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

package/src/types/handler-context.ts

@@ -10,6 +10,7 @@ import type {
   DefaultEnv,
   DefaultHandlerRouteMap,
   DefaultReverseRouteMap,
+  DefaultRouteName,
   DefaultVars,
 } from "./global-namespace.js";
 import type {
@@ -166,24 +167,22 @@ export type Handler<
  *
  * Provides type-safe access to:
  * - Route params (from URL pattern)
- * - Request data (request, searchParams, pathname, url)
+ * - Cleaned route URL (`url`, `searchParams`, `pathname` — no `_rsc*` params)
+ * - Original request (`request` — raw transport URL, headers, method, body)
  * - Platform bindings (env.DB, env.KV, env.SECRETS)
- * - Middleware variables (var.user, var.permissions)
+ * - Middleware variables (`get("user")`, `get("permissions")`)
  * - Getter/setter for variables (get('user'), set('user', ...))
  *
- * **Note:** System parameters (query params starting with `_rsc`) are automatically
- * filtered from `url`, `searchParams`, and `request.url` for cleaner access.
- *
  * @example
  * ```typescript
  * const handler = (ctx: HandlerContext<{ slug: string }, AppEnv>) => {
  *   ctx.params.slug        // Route param (string)
  *   ctx.env.DB             // Binding (D1Database)
- *   ctx.var.user           // Variable (User | undefined)
- *   ctx.get('user')        // Alternative getter
+ *   ctx.get('user')        // Variable (User | undefined)
  *   ctx.set('user', {...}) // Setter
  *   ctx.url                // Clean URL (no _rsc* params)
  *   ctx.searchParams       // Clean params (no _rsc* params)
+ *   ctx.request            // Raw transport request (original URL intact)
  * }
  * ```
  */
@@ -202,13 +201,15 @@ export type HandlerContext<
   readonly _paramCheck?: (params: TParams) => TParams;
   /**
    * True during build-time pre-rendering, false at runtime.
-   * In dev mode, Prerender handlers run live so build is false.
-   * In production passthrough (live fallback), build is also false.
+   * Build-time collection and dev on-demand prerender use `true`.
+   * Live request rendering, including passthrough fallback, uses `false`.
    */
   build: boolean;
   /**
-   * The incoming Request object.
-   * System params (`_rsc*`) are filtered from the URL for cleaner access.
+   * The original incoming Request object (transport URL intact).
+   * Use `ctx.url` / `ctx.searchParams` for application logic — those have
+   * internal `_rsc*` params stripped. `ctx.request` preserves the raw URL
+   * for cases where you need original headers, method, or body.
    */
   request: Request;
   /**
@@ -226,22 +227,25 @@ export type HandlerContext<
    */
   pathname: string;
   /**
-   * The full URL object (with system params filtered).
+   * The full URL object (with internal `_rsc*` params stripped).
+   * Use this for application logic — routing, link generation, display.
    */
   url: URL;
+  /**
+   * The original request URL with all parameters intact, including
+   * internal `_rsc*` transport params. Use `ctx.url` for application
+   * logic — this is only needed for advanced cases like debugging
+   * or custom cache keying.
+   */
+  originalUrl: URL;
   /**
    * Platform bindings (DB, KV, secrets, etc.).
    * Access resources like `ctx.env.DB`, `ctx.env.KV`.
    */
   env: TEnv;
-  /**
-   * Middleware-injected variables.
-   * Access values like `ctx.var.user`, `ctx.var.permissions`.
-   */
-  var: DefaultVars;
   /**
    * Type-safe getter for middleware variables.
-   * Alternative to `ctx.var.key` with better autocomplete.
+   * Preferred way to read middleware-injected variables.
    *
    * @example
    * ```typescript
@@ -262,24 +266,18 @@ export type HandlerContext<
    * ```
    */
   set: {
-    <T>(contextVar: ContextVar<T>, value: T): void;
-  } & (<K extends keyof DefaultVars>(key: K, value: DefaultVars[K]) => void);
-  /**
-   * Stub response for setting headers/cookies.
-   * Headers set here are merged into the final response.
-   *
-   * @example
-   * ```typescript
-   * route("product", (ctx) => {
-   *   ctx.res.headers.set("Cache-Control", "s-maxage=60");
-   *   return <ProductPage />;
-   * });
-   * ```
-   */
-  res: Response;
+    <T>(
+      contextVar: ContextVar<T>,
+      value: T,
+      options?: { cache?: boolean },
+    ): void;
+  } & (<K extends keyof DefaultVars>(
+    key: K,
+    value: DefaultVars[K],
+    options?: { cache?: boolean },
+  ) => void);
   /**
-   * Shorthand for ctx.res.headers - response headers.
-   * Headers set here are merged into the final response.
+   * Response headers. Headers set here are merged into the final response.
    *
    * @example
    * ```typescript
@@ -293,8 +291,15 @@ export type HandlerContext<
   /**
    * Access loader data or push handle data.
    *
+   * Available in route handlers, layout handlers, middleware, server actions,
+   * and server components rendered within the request context.
+   *
    * For loaders: Returns a promise that resolves to the loader data.
    * Loaders are executed in parallel and memoized per request.
+   * Prefer DSL `loader()` + client `useLoader()` over `ctx.use(Loader)` —
+   * DSL loaders are always fresh and cache-safe. Use `ctx.use(Loader)` only
+   * when you need loader data in the handler itself (e.g., to set context
+   * variables or make routing decisions).
    *
    * For handles: Returns a push function to add data for this segment.
    * Handle data accumulates across all matched route segments.
@@ -302,10 +307,11 @@ export type HandlerContext<
    *
    * @example
    * ```typescript
-   * // Loader usage
-   * route("cart", async (ctx) => {
-   *   const cart = await ctx.use(CartLoader);
-   *   return <CartPage cart={cart} />;
+   * // Loader escape hatch — use when handler needs the data directly
+   * route("product", async (ctx) => {
+   *   const { product } = await ctx.use(ProductLoader);
+   *   ctx.set(Product, product); // make available to children
+   *   return <ProductPage />;
    * });
    *
    * // Handle usage - direct value
@@ -379,12 +385,26 @@ export type HandlerContext<
    * @example
    * ```typescript
    * route("product", (ctx) => {
-   *   ctx.setLocationState([ServerInfo({ data: "value" })]);
+   *   ctx.setLocationState(ServerInfo({ data: "value" }));
    *   return <ProductPage />;
    * });
    * ```
    */
-  setLocationState(entries: LocationStateEntry[]): void;
+  setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
+  /**
+   * The matched route name, if the route has an explicit name.
+   * Undefined for unnamed routes (those without a `name` option in path()).
+   * Includes the namespace prefix from include() (e.g., "blog.post").
+   *
+   * @example
+   * ```typescript
+   * route("product", (ctx) => {
+   *   ctx.routeName // "product"
+   *   return <ProductPage />;
+   * });
+   * ```
+   */
+  routeName?: DefaultRouteName;
   /**
    * Generate URLs from route names.
    *
@@ -420,12 +440,18 @@ export type InternalHandlerContext<
   TEnv = DefaultEnv,
   TSearch extends SearchSchema = {},
 > = HandlerContext<TParams, TEnv, TSearch> & {
-  /** Raw request with all system parameters intact. */
-  _originalRequest: Request;
+  /** @internal Stub response for collecting headers/cookies. */
+  res: Response;
+  /** @internal Shared variable backing store for ctx.get()/ctx.set(). */
+  _variables: Record<string, any>;
+  /** Prerender-only control flow helper, attached when the runtime context supports it. */
+  passthrough?: () => unknown;
   /** Current segment ID for handle data attribution. */
   _currentSegmentId?: string;
   /** Response type tag (json, text, html, etc.) for cache key differentiation. */
   _responseType?: string;
+  /** Route name for cache key scoping (prevents cross-route collisions). */
+  _routeName?: string;
 };
 
 /**
@@ -505,26 +531,112 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * })
  * ```
  */
+/**
+ * Revalidation function called during client-side navigation to decide whether
+ * a segment (layout, route, parallel slot, or loader) should be re-rendered.
+ *
+ * Return `true` to re-render, `false` to skip (keep client's current version),
+ * or `{ defaultShouldRevalidate: boolean }` to override the default for
+ * downstream segments.
+ *
+ * @example
+ * ```ts
+ * // Re-render only when a cart action happened or browser signals staleness
+ * revalidate(({ actionId, stale }) =>
+ *   actionId?.includes("cart") || stale || false
+ * )
+ *
+ * // Always re-render when params change (default behavior made explicit)
+ * revalidate(({ defaultShouldRevalidate }) => defaultShouldRevalidate)
+ * ```
+ */
 export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
+  /** Route params from the page being navigated away from. */
   currentParams: TParams;
+  /** Full URL of the page being navigated away from. */
   currentUrl: URL;
+  /** Route params for the navigation target. */
   nextParams: TParams;
+  /** Full URL of the navigation target. */
   nextUrl: URL;
+  /**
+   * The router's default revalidation decision for this segment.
+   * `true` when params changed or the segment is new to the client.
+   * Return this when you want default behavior plus your own conditions.
+   */
   defaultShouldRevalidate: boolean;
+  /** Full handler context — access to `ctx.use()`, `ctx.env`, `ctx.params`, etc. */
   context: HandlerContext<TParams, TEnv>;
-  // Segment metadata (which segment is being evaluated):
+
+  // ── Segment metadata (which segment is being evaluated) ──────────────
+
+  /** The type of segment being revalidated. */
   segmentType: "layout" | "route" | "parallel";
-  layoutName?: string; // Layout name (e.g., "root", "shop", "auth") - only for layouts
-  slotName?: string; // Slot name (e.g., "@sidebar", "@modal") - only for parallels
-  // Action context (populated when revalidation triggered by server action):
-  actionId?: string; // Action identifier (e.g., "src/actions.ts#addToCart")
-  actionUrl?: URL; // URL where action was executed
-  actionResult?: any; // Return value from action execution
-  formData?: FormData; // FormData from action request
-  method?: string; // Request method: 'GET' for navigation, 'POST' for actions
-  routeName?: string; // Route name where action was executed (e.g., "products.detail")
-  // Stale cache revalidation (SWR pattern):
-  stale?: boolean; // True if this is a stale cache revalidation request
+  /** Layout name (e.g., `"root"`, `"shop"`, `"auth"`). Only set for layout segments. */
+  layoutName?: string;
+  /** Slot name (e.g., `"@sidebar"`, `"@modal"`). Only set for parallel segments. */
+  slotName?: string;
+
+  // ── Action context (populated when revalidation is triggered by a server action) ──
+
+  /**
+   * Identifier of the server action that triggered revalidation.
+   * `undefined` during normal navigation (no action involved).
+   *
+   * Format: `"src/<path>#<exportName>"` — the file path is the source path
+   * relative to the project root, followed by `#` and the exported function name.
+   *
+   * This is stable and can be used for path-based matching to revalidate
+   * when any action in a module or directory fires:
+   *
+   * @example
+   * ```ts
+   * // Match a specific action
+   * revalidate(({ actionId }) => actionId === "src/actions/cart.ts#addToCart")
+   *
+   * // Match any action in the cart module
+   * revalidate(({ actionId }) => actionId?.includes("cart") ?? false)
+   *
+   * // Match any action under src/apps/store/actions/
+   * revalidate(({ actionId }) => actionId?.startsWith("src/apps/store/actions/") ?? false)
+   * ```
+   */
+  actionId?: string;
+  /** URL where the action was executed (the page the user was on when they triggered the action). */
+  actionUrl?: URL;
+  /** Return value from the action execution. Can be used to conditionally revalidate based on the action's outcome. */
+  actionResult?: any;
+  /** FormData from the action request body. Only set for form-based actions (not inline `"use server"` actions). */
+  formData?: FormData;
+  /** HTTP method: `"GET"` for navigation, `"POST"` for server actions. */
+  method?: string;
+
+  // ── Route identity ───────────────────────────────────────────────────
+
+  /** Route name of the navigation target. Alias for `toRouteName`. */
+  routeName?: DefaultRouteName;
+  /**
+   * Route name being navigated away from.
+   * `undefined` for unnamed internal routes (those without a `name` option).
+   */
+  fromRouteName?: DefaultRouteName;
+  /**
+   * Route name being navigated to.
+   * `undefined` for unnamed internal routes (those without a `name` option).
+   */
+  toRouteName?: DefaultRouteName;
+
+  // ── Staleness signal ─────────────────────────────────────────────────
+
+  /**
+   * `true` when the browser signals that data may be stale — typically because
+   * a server action was executed in this or another tab (`_rsc_stale` header).
+   *
+   * This is NOT segment cache staleness (loaders are never segment-cached).
+   * Use this to decide whether loader data should be re-fetched after an
+   * action that may have mutated backend state.
+   */
+  stale?: boolean;
 }) => boolean | { defaultShouldRevalidate: boolean };
 
 // MiddlewareFn is imported from "../router/middleware.js" and re-exported

package/src/types/loader-types.ts

@@ -40,13 +40,19 @@ export type LoaderContext<
   TSearch extends SearchSchema = {},
 > = {
   params: TParams;
+  /**
+   * Route params extracted from the URL pattern match (server-side only).
+   * Unlike `params`, these cannot be overridden by client-provided loader params.
+   * Use this when you need trusted, server-matched route params for auth or
+   * resource scoping.
+   */
+  routeParams: Record<string, string>;
   request: Request;
   searchParams: URLSearchParams;
   search: {} extends TSearch ? {} : ResolveSearchSchema<TSearch>;
   pathname: string;
   url: URL;
   env: TEnv;
-  var: DefaultVars;
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;
   } & (<K extends keyof DefaultVars>(key: K) => DefaultVars[K]);
@@ -159,11 +165,11 @@ export type LoadOptions =
  *   return await db.products.findBySlug(slug);
  * });
  *
- * // Server usage
- * const cart = ctx.use(CartLoader);
+ * // Client usage (preferred — cache-safe, always fresh)
+ * const { data } = useLoader(CartLoader);
  *
- * // Client usage (fn is stripped, only name remains)
- * const cart = useLoader(CartLoader);
+ * // Server escape hatch (handler needs data directly)
+ * const cart = await ctx.use(CartLoader);
  * ```
  */
 export type LoaderDefinition<

package/src/types/route-config.ts

@@ -24,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,18 +41,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 use `{ passthrough: true }`.
+   * Used by the non-trie match path to set the `pt` flag.
+   */
+  passthroughRouteKeys?: Set<string>;
+
   // === Lazy evaluation fields ===
 
   /**
@@ -71,4 +96,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

@@ -51,9 +51,11 @@ export interface ResolvedSegment {
   // Loader-specific fields
   loaderId?: string; // For loaders: the loader $$id identifier
   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
+  parallelLoaderSources?: any[]; // Internal: preserves stable aggregate promise across renders
   // Error-specific fields
   error?: ErrorInfo; // For error segments: the error information
   // NotFound-specific fields
@@ -124,11 +126,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,