@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.19

package/src/theme/theme-context.ts

@@ -10,7 +10,7 @@
  */
 
 import { createContext, useContext, type Context } from "react";
-import type { ResolvedThemeConfig, ThemeContextValue } from "./types.js";
+import type { ThemeContextValue } from "./types.js";
 
 /**
  * React context for theme state
@@ -19,33 +19,6 @@ import type { ResolvedThemeConfig, ThemeContextValue } from "./types.js";
 export const ThemeContext: Context<ThemeContextValue | null> =
   createContext<ThemeContextValue | null>(null);
 
-/**
- * SSR module-level state for theme config.
- * Populated by initThemeConfigSync before React renders.
- * Used by MetaTags during SSR to render the theme script.
- */
-let ssrThemeConfig: ResolvedThemeConfig | null = null;
-
-/**
- * Initialize theme config synchronously for SSR.
- * Called before rendering to populate state for MetaTags.
- *
- * @param config - Theme config from router, or null if theme is disabled
- */
-export function initThemeConfigSync(config: ResolvedThemeConfig | null): void {
-  ssrThemeConfig = config;
-}
-
-/**
- * Get theme config for SSR/hydration.
- * Used by MetaTags to render the theme script.
- *
- * @returns Theme config if available, null otherwise
- */
-export function getSSRThemeConfig(): ResolvedThemeConfig | null {
-  return ssrThemeConfig;
-}
-
 /**
  * Get theme context (internal use)
  * Returns null if theme is not enabled

package/src/theme/theme-script.ts

@@ -40,7 +40,8 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
     for (var i = 0; i < cookies.length; i++) {
       var cookie = cookies[i].trim();
       if (cookie.indexOf(storageKey + '=') === 0) {
-        return decodeURIComponent(cookie.substring(storageKey.length + 1));
+        try { return decodeURIComponent(cookie.substring(storageKey.length + 1)); }
+        catch (e) { return cookie.substring(storageKey.length + 1); }
       }
     }
     // Fall back to localStorage

package/src/types/cache-types.ts

@@ -145,6 +145,11 @@ export interface CacheOptions<TEnv = unknown> {
    * Tags for cache invalidation.
    * Can be a static array or a function that returns tags.
    *
+   * Note: Tags are passed through to the store but built-in stores
+   * (MemorySegmentCacheStore, CFCacheStore) do not yet index or
+   * invalidate by tag. Effective tag-based invalidation requires a
+   * custom store implementation with secondary indices.
+   *
    * @example
    * ```typescript
    * // Static tags

package/src/types/error-types.ts

@@ -10,6 +10,7 @@
  * - "rendering": Invoked during SSR rendering errors (ssr/index.tsx, separate callback)
  * - "action": Invoked when server action execution fails (rsc/handler.ts, router.ts)
  * - "revalidation": Invoked when revalidation fails (router.ts, conditional with action)
+ * - "origin": Invoked when cross-origin request validation rejects a request (rsc/handler.ts)
  * - "unknown": Fallback for unclassified errors (not currently invoked)
  */
 export type ErrorPhase =
@@ -21,8 +22,10 @@ export type ErrorPhase =
   | "rendering" // During RSC/SSR rendering (SSR handler uses separate callback)
   | "action" // During server action execution
   | "revalidation" // During revalidation evaluation
+  | "cache" // During "use cache" background operations (stale revalidation, async cache writes)
   | "prerender" // During build-time pre-rendering (Vite closeBundle)
   | "static" // During build-time static handler rendering (Vite closeBundle)
+  | "origin" // During cross-origin request validation (CSRF protection)
   | "unknown"; // Fallback for unclassified errors
 
 /**

package/src/types/global-namespace.ts

@@ -89,3 +89,12 @@ export type DefaultEnv = keyof RSCRouter.Env extends never
 export type DefaultVars = keyof RSCRouter.Vars extends never
   ? Record<string, any>
   : RSCRouter.Vars;
+
+/**
+ * Default route name type for public `routeName` on contexts.
+ * When GeneratedRouteMap is augmented, narrows to the known route names.
+ * Otherwise falls back to `string` for untyped usage.
+ */
+export type DefaultRouteName = keyof RSCRouter.GeneratedRouteMap extends never
+  ? string
+  : keyof RSCRouter.GeneratedRouteMap & string;

package/src/types/handler-context.ts

@@ -10,6 +10,7 @@ import type {
   DefaultEnv,
   DefaultHandlerRouteMap,
   DefaultReverseRouteMap,
+  DefaultRouteName,
   DefaultVars,
 } from "./global-namespace.js";
 import type {
@@ -166,14 +167,12 @@ 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)
  * - 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>) => {
@@ -184,6 +183,7 @@ export type Handler<
  *   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 +202,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;
   /**
@@ -379,12 +381,26 @@ export type HandlerContext<
    * @example
    * ```typescript
    * route("product", (ctx) => {
-   *   ctx.setLocationState([ServerInfo({ data: "value" })]);
+   *   ctx.setLocationState(ServerInfo({ data: "value" }));
+   *   return <ProductPage />;
+   * });
+   * ```
+   */
+  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 />;
    * });
    * ```
    */
-  setLocationState(entries: LocationStateEntry[]): void;
+  routeName?: DefaultRouteName;
   /**
    * Generate URLs from route names.
    *
@@ -420,12 +436,14 @@ export type InternalHandlerContext<
   TEnv = DefaultEnv,
   TSearch extends SearchSchema = {},
 > = HandlerContext<TParams, TEnv, TSearch> & {
-  /** Raw request with all system parameters intact. */
-  _originalRequest: Request;
+  /** 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;
 };
 
 /**
@@ -522,7 +540,11 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
   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")
+  routeName?: DefaultRouteName; // Route name of the navigation target (alias for toRouteName)
+  // Named-route identity for both ends of a navigation transition.
+  // Undefined for unnamed internal routes (those without a `name` option).
+  fromRouteName?: DefaultRouteName; // Route name being navigated away from
+  toRouteName?: DefaultRouteName; // Route name being navigated to
   // Stale cache revalidation (SWR pattern):
   stale?: boolean; // True if this is a stale cache revalidation request
 }) => boolean | { defaultShouldRevalidate: boolean };

package/src/types/loader-types.ts

@@ -40,6 +40,13 @@ 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>;

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/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,5 +1,30 @@
 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).
@@ -71,7 +96,7 @@ 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;

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