@rangojs/router 0.0.0-experimental.7dc955ec → 0.0.0-experimental.80

package/src/server/loader-registry.ts

@@ -44,20 +44,21 @@ export function setLoaderImports(
 export async function getLoaderLazy(
   id: string,
 ): Promise<LoaderRegistryEntry | undefined> {
-  // Check if already cached in main registry
-  const existing = loaderRegistry.get(id);
-  if (existing) {
-    return existing;
-  }
-
-  // Check the fetchable loader registry (populated by createLoader)
+  // Always check fetchableLoaderRegistry first — it's the source of truth.
+  // createLoader() updates it during module re-evaluation (HMR), so checking
+  // here ensures we pick up the fresh function after a loader file change.
   const fetchable = getFetchableLoader(id);
   if (fetchable) {
-    // Cache in main registry for future requests
     loaderRegistry.set(id, fetchable);
     return fetchable;
   }
 
+  // Fall back to local cache (populated by previous lazy imports in production)
+  const existing = loaderRegistry.get(id);
+  if (existing) {
+    return existing;
+  }
+
   // Try to lazy load from the import map (production mode)
   if (lazyLoaderImports && lazyLoaderImports.size > 0) {
     const lazyImport = lazyLoaderImports.get(id);

package/src/server/request-context.ts

@@ -24,12 +24,16 @@ import {
   type ContextVar,
   contextGet,
   contextSet,
-  isContextVar,
   isNonCacheable,
 } from "../context-var.js";
-import { createHandleStore, type HandleStore } from "./handle-store.js";
+import {
+  createHandleStore,
+  buildHandleSnapshot,
+  type HandleStore,
+  type HandleData,
+} from "./handle-store.js";
 import { isHandle } from "../handle.js";
-import { track, RSCRouterContext, type MetricsStore } from "./context.js";
+import { track, type MetricsStore } from "./context.js";
 import { getFetchableLoader } from "./fetchable-loader-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
@@ -70,8 +74,8 @@ export interface RequestContext<
   pathname: string;
   /** URL search params (with internal `_rsc*` params stripped, same as `url.searchParams`) */
   searchParams: URLSearchParams;
-  /** Variables set by middleware (same as ctx.var) */
-  var: Record<string, any>;
+  /** @internal Shared variable backing store for ctx.get()/ctx.set(). */
+  _variables: Record<string, any>;
   /** Get a variable set by middleware */
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;
@@ -272,6 +276,54 @@ export interface RequestContext<
   /** @internal Previous route key (from the navigation source), used for revalidation */
   _prevRouteKey?: string;
 
+  /**
+   * @internal Render barrier for experimental `rendered()` API.
+   * Resolves when all non-loader segments have settled and handle data
+   * is available. Used by DSL loaders that call `ctx.rendered()`.
+   */
+  _renderBarrier: Promise<void>;
+
+  /**
+   * @internal Resolve the render barrier. Accepts resolved segments, filters
+   * out loaders, and captures non-loader segment IDs as the handle ordering.
+   * Called after segment resolution (fresh) or handle replay (cache/prerender).
+   */
+  _resolveRenderBarrier: (
+    segments: Array<{ type: string; id: string }>,
+  ) => void;
+
+  /**
+   * @internal Segment order at barrier resolution time, used by loader
+   * ctx.use(handle) to collect handle data in correct order.
+   */
+  _renderBarrierSegmentOrder?: string[];
+
+  /**
+   * @internal Set to true when the matched entry tree contains any `loading()`
+   * entries (streaming). Used by rendered() to fail fast.
+   */
+  _treeHasStreaming?: boolean;
+
+  /**
+   * @internal Loader IDs that have called rendered() and are waiting for the
+   * barrier. Used to detect deadlocks when a handler tries to await the same
+   * loader via ctx.use(Loader).
+   */
+  _renderBarrierWaiters?: Set<string>;
+
+  /**
+   * @internal Loader IDs that handlers have started awaiting via ctx.use().
+   * Used for bidirectional deadlock detection: if a loader later calls
+   * rendered() and a handler already awaits it, we can detect the deadlock.
+   */
+  _handlerLoaderDeps?: Set<string>;
+
+  /**
+   * @internal Cached HandleData snapshot built at barrier resolution time.
+   * Avoids rebuilding the snapshot on every loader ctx.use(handle) call.
+   */
+  _renderBarrierHandleSnapshot?: HandleData;
+
   /** @internal Per-request error dedup set for onError reporting */
   _reportedErrors: WeakSet<object>;
 
@@ -288,6 +340,15 @@ export interface RequestContext<
 
   /** @internal Request-scoped performance metrics store */
   _metricsStore?: MetricsStore;
+
+  /** @internal Router basename for this request (used by redirect()) */
+  _basename?: string;
+
+  /**
+   * @internal RouteSnapshot from classifyRequest, reused by match/matchPartial
+   * to avoid a second resolveRoute call. Cleared on HMR invalidation.
+   */
+  _classifiedRoute?: import("../router/route-snapshot.js").RouteSnapshot;
 }
 
 /**
@@ -314,10 +375,20 @@ export type PublicRequestContext<
   | "_routeName"
   | "_prevRouteKey"
   | "_reportedErrors"
+  | "_renderBarrier"
+  | "_resolveRenderBarrier"
+  | "_renderBarrierSegmentOrder"
+  | "_treeHasStreaming"
+  | "_renderBarrierWaiters"
+  | "_handlerLoaderDeps"
+  | "_renderBarrierHandleSnapshot"
   | "_reportBackgroundError"
   | "_debugPerformance"
   | "_metricsStore"
+  | "_basename"
   | "_setStatus"
+  | "_variables"
+  | "_classifiedRoute"
   | "res"
 >;
 
@@ -592,7 +663,7 @@ export function createRequestContext<TEnv>(
     originalUrl: new URL(request.url),
     pathname: url.pathname,
     searchParams: cleanUrl.searchParams,
-    var: variables,
+    _variables: variables,
     get: ((keyOrVar: any) => {
       if (isNonCacheable(variables, keyOrVar) && isInsideCacheScope()) {
         throw new Error(
@@ -739,9 +810,58 @@ export function createRequestContext<TEnv>(
     _reportedErrors: new WeakSet<object>(),
     _metricsStore: undefined,
 
+    // Render barrier: deferred promise resolved after non-loader segments settle.
+    _renderBarrier: null as any, // set below
+    _resolveRenderBarrier: null as any, // set below
+    _renderBarrierSegmentOrder: undefined,
+
     reverse: createReverseFunction(getGlobalRouteMap(), undefined, {}),
   };
 
+  // Lazy render barrier: only allocate the Promise when a loader actually
+  // calls rendered(). Requests that don't use rendered() pay zero cost.
+  let barrierResolved = false;
+  let resolveBarrier: (() => void) | undefined;
+  ctx._renderBarrier = null as any; // lazy — created on first access
+  ctx._resolveRenderBarrier = (
+    segments: Array<{ type: string; id: string }>,
+  ) => {
+    if (barrierResolved) return;
+    barrierResolved = true;
+    const segOrder = segments
+      .filter((s) => s.type !== "loader")
+      .map((s) => s.id);
+    ctx._renderBarrierSegmentOrder = segOrder;
+    // Build and cache handle snapshot so loader ctx.use(handle) calls
+    // don't rebuild it on every invocation.
+    ctx._renderBarrierHandleSnapshot = buildHandleSnapshot(
+      handleStore,
+      segOrder,
+    );
+    ctx._renderBarrierWaiters = undefined;
+    ctx._handlerLoaderDeps = undefined;
+    if (resolveBarrier) resolveBarrier();
+  };
+  Object.defineProperty(ctx, "_renderBarrier", {
+    get() {
+      // Barrier already resolved (cache/prerender hit) or first lazy access.
+      // Either way, replace the getter with a concrete value to avoid
+      // repeated Promise.resolve() allocations on subsequent reads.
+      const p = barrierResolved
+        ? Promise.resolve()
+        : new Promise<void>((resolve) => {
+            resolveBarrier = resolve;
+          });
+      Object.defineProperty(ctx, "_renderBarrier", {
+        value: p,
+        writable: false,
+        configurable: false,
+      });
+      return p;
+    },
+    configurable: true,
+  });
+
   // Now create use() with access to ctx
   ctx.use = createUseFunction({
     handleStore,
@@ -924,14 +1044,13 @@ export function createUseFunction<TEnv>(
       pathname: ctx.pathname,
       url: ctx.url,
       env: ctx.env as any,
-      var: ctx.var as any,
       get: ctx.get as any,
-      use: <TDep, TDepParams = any>(
+      use: (<TDep, TDepParams = any>(
         dep: LoaderDefinition<TDep, TDepParams>,
       ): Promise<TDep> => {
         // Recursive call - will start dep loader if not already started
         return ctx.use(dep);
-      },
+      }) as LoaderContext["use"],
       method: "GET",
       body: undefined,
       reverse: createReverseFunction(
@@ -940,6 +1059,12 @@ export function createUseFunction<TEnv>(
         ctx.params as Record<string, string>,
         ctx._routeName ? isRouteRootScoped(ctx._routeName) : undefined,
       ),
+      rendered: () => {
+        throw new Error(
+          `ctx.rendered() is only available in DSL loaders (registered via loader() in urls()). ` +
+            `It cannot be used from request-context loaders or server actions.`,
+        );
+      },
     };
 
     const doneLoader = track(`loader:${loader.$$id}`, 2);

package/src/ssr/index.tsx

@@ -129,6 +129,7 @@ interface RscPayload {
     matched?: string[];
     pathname?: string;
     params?: Record<string, string>;
+    basename?: string;
     themeConfig?: ResolvedThemeConfig | null;
     initialTheme?: Theme;
     version?: string;
@@ -261,6 +262,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       function SsrRoot() {
         payload ??= createFromReadableStream<RscPayload>(rscStream1);
         const resolved = React.use(payload);
+
         const themeConfig = resolved.metadata?.themeConfig ?? null;
         const pathname = resolved.metadata?.pathname ?? "/";
 
@@ -286,6 +288,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
           navigate: async () => {},
           refresh: async () => {},
           version: resolved.metadata?.version,
+          basename: resolved.metadata?.basename,
         };
 
         // Build content tree from segments.

package/src/static-handler.ts

@@ -32,11 +32,21 @@
  */
 import type { ReactNode } from "react";
 import type { Handler } from "./types.js";
-import type { PrerenderOptions, StaticBuildContext } from "./prerender.js";
+import type { StaticBuildContext } from "./prerender.js";
+import type { UseItems, HandlerUseItem } from "./route-types.js";
 import { isCachedFunction } from "./cache/taint.js";
 
 // -- Types ------------------------------------------------------------------
 
+export interface StaticHandlerOptions {
+  /**
+   * Keep handler in server bundle for live fallback (default: false).
+   * false: handler replaced with stub, source-only APIs excluded from bundle.
+   * true: handler stays in bundle, renders live at request time.
+   */
+  passthrough?: boolean;
+}
+
 export interface StaticHandlerDefinition<
   TParams extends Record<string, any> = any,
 > {
@@ -46,14 +56,16 @@ export interface StaticHandlerDefinition<
   /** In dev mode, the actual handler function that layout/path/parallel can call. */
   handler: Handler<TParams>;
   /** Static handler options (passthrough support). */
-  options?: PrerenderOptions;
+  options?: StaticHandlerOptions;
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<HandlerUseItem>;
 }
 
 // -- Function ---------------------------------------------------------------
 
 export function Static<TParams extends Record<string, any> = {}>(
   handler: (ctx: StaticBuildContext) => ReactNode | Promise<ReactNode>,
-  options?: PrerenderOptions,
+  options?: StaticHandlerOptions,
   __injectedId?: string,
 ): StaticHandlerDefinition<TParams>;
 
@@ -61,7 +73,7 @@ export function Static<TParams extends Record<string, any> = {}>(
 
 export function Static<TParams extends Record<string, any>>(
   handler: Function,
-  optionsOrId?: PrerenderOptions | string,
+  optionsOrId?: StaticHandlerOptions | string,
   maybeId?: string,
 ): StaticHandlerDefinition<TParams> {
   if (isCachedFunction(handler)) {
@@ -72,13 +84,13 @@ export function Static<TParams extends Record<string, any>>(
     );
   }
 
-  let options: PrerenderOptions | undefined;
+  let options: StaticHandlerOptions | undefined;
   let id: string;
 
   if (typeof optionsOrId === "string") {
     id = optionsOrId;
   } else {
-    options = optionsOrId as PrerenderOptions | undefined;
+    options = optionsOrId as StaticHandlerOptions | undefined;
     id = maybeId ?? "";
   }
 

package/src/types/cache-types.ts

@@ -5,8 +5,8 @@
  * during cache key generation (before middleware runs).
  *
  * Note: While the full RequestContext is passed, middleware-set variables
- * (ctx.var, ctx.get()) may not be populated yet since cache lookup
- * happens before middleware execution.
+ * read via `ctx.get()` may not be populated yet since cache lookup happens
+ * before middleware execution.
  */
 export type { RequestContext as CacheContext } from "../server/request-context.js";
 
@@ -101,7 +101,7 @@ export interface CacheOptions<TEnv = unknown> {
    * Return false to skip cache for this request (always fetch fresh).
    *
    * Has access to full RequestContext including env, request, params, cookies, etc.
-   * Note: Middleware-set variables (ctx.var) may not be populated yet.
+   * Note: Middleware-set variables read via `ctx.get()` may not be populated yet.
    *
    * @example
    * ```typescript
@@ -123,7 +123,7 @@ export interface CacheOptions<TEnv = unknown> {
    * Bypasses default key generation AND store's keyGenerator.
    *
    * Has access to full RequestContext including env, request, params, cookies, etc.
-   * Note: Middleware-set variables (ctx.var) may not be populated yet.
+   * Note: Middleware-set variables read via `ctx.get()` may not be populated yet.
    *
    * @example
    * ```typescript

package/src/types/handler-context.ts

@@ -19,6 +19,7 @@ import type {
   ResolvedRouteMap,
 } from "./route-config.js";
 import type { LoaderDefinition } from "./loader-types.js";
+import type { UseItems, HandlerUseItem } from "../route-types.js";
 
 // Re-export MiddlewareFn for internal/advanced use
 export type { MiddlewareFn } from "../router/middleware.js";
@@ -135,7 +136,7 @@ export type Handler<
     | Record<string, any> = {},
   TRouteMap extends {} = DefaultHandlerRouteMap,
   TEnv = DefaultEnv,
-> = (
+> = ((
   ctx: HandlerContext<
     T extends `.${infer Local}`
       ? Local extends keyof TRouteMap
@@ -160,7 +161,10 @@ export type Handler<
       : ExtractSearchFromEntry<DefaultHandlerRouteMap, T>,
     TRouteMap extends DefaultHandlerRouteMap ? never : TRouteMap
   >,
-) => ReactNode | Promise<ReactNode> | Response | Promise<Response>;
+) => ReactNode | Promise<ReactNode> | Response | Promise<Response>) & {
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<HandlerUseItem>;
+};
 
 /**
  * Context passed to handlers (Hono-inspired type-safe context)
@@ -170,7 +174,7 @@ export type Handler<
  * - 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', ...))
  *
  * @example
@@ -178,8 +182,7 @@ export type Handler<
  * 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)
@@ -206,6 +209,12 @@ export type HandlerContext<
    * Live request rendering, including passthrough fallback, uses `false`.
    */
   build: boolean;
+  /**
+   * True when running in Vite dev mode, false during production build or
+   * live request rendering. Use this to branch on runtime mode without
+   * changing build semantics (e.g., skip expensive operations in dev).
+   */
+  dev: boolean;
   /**
    * The original incoming Request object (transport URL intact).
    * Use `ctx.url` / `ctx.searchParams` for application logic — those have
@@ -244,14 +253,9 @@ export type HandlerContext<
    * 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
@@ -277,9 +281,9 @@ export type HandlerContext<
       value: T,
       options?: { cache?: boolean },
     ): void;
-  } & ((
-    key: keyof DefaultVars,
-    value: DefaultVars[keyof DefaultVars],
+  } & (<K extends keyof DefaultVars>(
+    key: K,
+    value: DefaultVars[K],
     options?: { cache?: boolean },
   ) => void);
   /**
@@ -301,8 +305,11 @@ export type HandlerContext<
    * 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 — calling
-   * `ctx.use(SameLoader)` multiple times returns the same promise.
+   * 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.
@@ -310,10 +317,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
@@ -444,6 +452,8 @@ export type InternalHandlerContext<
 > = HandlerContext<TParams, TEnv, TSearch> & {
   /** @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. */

package/src/types/loader-types.ts

@@ -1,4 +1,5 @@
 import type { ContextVar } from "../context-var.js";
+import type { Handle } from "../handle.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 import type { ScopedReverseFunction } from "../reverse.js";
 import type { SearchSchema, ResolveSearchSchema } from "../search-params.js";
@@ -53,16 +54,42 @@ export type LoaderContext<
   pathname: string;
   url: URL;
   env: TEnv;
-  var: DefaultVars;
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;
   } & (<K extends keyof DefaultVars>(key: K) => DefaultVars[K]);
   /**
-   * Access another loader's data (returns promise since loaders run in parallel)
+   * Access another loader's data, or read handle data after rendered().
+   *
+   * For loaders: returns a promise (loaders run in parallel).
+   * For handles: returns collected data (only after `await ctx.rendered()`).
    */
-  use: <T, TLoaderParams = any>(
-    loader: LoaderDefinition<T, TLoaderParams>,
-  ) => Promise<T>;
+  use: {
+    <T, TLoaderParams = any>(
+      loader: LoaderDefinition<T, TLoaderParams>,
+    ): Promise<T>;
+    <TData, TAccumulated = TData[]>(
+      handle: Handle<TData, TAccumulated>,
+    ): TAccumulated;
+  };
+  /**
+   * **Experimental.** Wait for all non-loader segments to settle.
+   *
+   * After the returned promise resolves, handle data is available via
+   * `ctx.use(handle)`. Only supported in DSL loaders on non-streaming
+   * trees (no `loading()`). Throws if called from a handler-invoked
+   * loader or when the tree uses streaming.
+   *
+   * @example
+   * ```typescript
+   * const PricesLoader = createLoader(async (ctx) => {
+   *   "use server";
+   *   await ctx.rendered();
+   *   const products = ctx.use(Products); // reads handle data
+   *   return pricing.getLive(products.map(p => p.id));
+   * });
+   * ```
+   */
+  rendered: () => Promise<void>;
   /**
    * HTTP method (GET, POST, PUT, PATCH, DELETE)
    * Available when loader is called via load({ method: "POST", ... })
@@ -166,11 +193,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-entry.ts

@@ -8,10 +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;
 }
 
 /**
@@ -69,7 +80,7 @@ export interface RouteEntry<TEnv = any> {
   prerenderRouteKeys?: Set<string>;
 
   /**
-   * Route keys in this entry that use `{ passthrough: true }`.
+   * 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>;

package/src/types/segments.ts

@@ -50,12 +50,12 @@ 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
-  parallelLoaderSources?: any[]; // Internal: preserves stable aggregate promise across renders
   // Error-specific fields
   error?: ErrorInfo; // For error segments: the error information
   // NotFound-specific fields

package/src/urls/include-helper.ts

@@ -4,7 +4,6 @@ import {
   runWithPrefixes,
   getUrlPrefix,
   getNamePrefix,
-  getRootScoped,
 } from "../server/context";
 import {
   INTERNAL_INCLUDE_SCOPE_PREFIX,
@@ -149,22 +148,32 @@ 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;
@@ -191,6 +200,7 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
         counters: capturedCounters,
         cacheProfiles: ctx.cacheProfiles,
         rootScoped: capturedRootScoped,
+        includeScope,
       },
     } as IncludeItem;
   };