@rangojs/router 0.0.0-experimental.9c9afef3 → 0.0.0-experimental.a014d2b7

package/src/router/loader-resolution.ts

@@ -5,8 +5,8 @@
  */
 
 import type { ReactNode } from "react";
-import { track } from "../server/context";
 import type { EntryData } from "../server/context";
+import { observePhase, PHASES } from "./instrument.js";
 import { contextGet } from "../context-var.js";
 import type {
   ResolvedSegment,
@@ -19,11 +19,17 @@ import type {
   ErrorBoundaryFallbackProps,
   ErrorInfo,
 } from "../types";
-import type { LoaderRevalidationResult, ActionContext } from "./types";
-import { isHandle, type Handle } from "../handle.js";
-import type { HandleStore } from "../server/handle-store.js";
+import { isHandle, collectHandleData, type Handle } from "../handle.js";
+import { withDefer } from "../defer.js";
+import { buildHandleSnapshot } from "../server/handle-store.js";
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
 import { _getRequestContext } from "../server/request-context.js";
+import {
+  isInsideLoaderScope,
+  runInsideLoaderBodyScope,
+  isInsidePushCallbackScope,
+  runInsidePushCallbackScope,
+} from "../server/context.js";
 import { debugLog } from "./logging.js";
 
 /**
@@ -65,7 +71,9 @@ export function wrapLoaderWithErrorHandling<T>(
   ) => ErrorInfo,
   onError?: LoaderErrorCallback,
 ): Promise<LoaderDataResult<T>> {
-  // Extract loader name from segmentId (format: "M1L0D0.loaderName")
+  // Extract the trailing token from segmentId (format: "<shortCode>D<i>.<loaderId>").
+  // The token is the loader's $$id (hash#export in prod, pathfrag#export in dev),
+  // not a clean display name.
   const loaderName = segmentId.split(".").pop() || "unknown";
 
   return Promise.resolve(promise)
@@ -101,16 +109,40 @@ export function wrapLoaderWithErrorHandling<T>(
         };
       }
 
-      // Render fallback on server
+      // Render fallback on server. The user ErrorBoundaryHandler may throw
+      // synchronously; if it does we must NOT let that rejection escape — the
+      // wrapped LoaderDataResult promise is contracted to never reject (see
+      // segment-resolution/fresh.ts `await Promise.all(...wrapped)`), and a
+      // rejection here would collapse the whole entry and discard healthy
+      // sibling loader data. On a fallback-render throw, fall back to the
+      // no-boundary result (fallback: null) so the client throws the ORIGINAL
+      // error, and the wrapped promise still resolves to a LoaderDataResult.
       let renderedFallback: ReactNode;
-      if (typeof fallback === "function") {
-        // ErrorBoundaryHandler - call with error info
-        const props: ErrorBoundaryFallbackProps = {
+      try {
+        if (typeof fallback === "function") {
+          // ErrorBoundaryHandler - call with error info
+          const props: ErrorBoundaryFallbackProps = {
+            error: errorInfo,
+          };
+          renderedFallback = fallback(props);
+        } else {
+          renderedFallback = fallback;
+        }
+      } catch (fallbackError) {
+        debugLog("loader", "error boundary fallback render threw", {
+          segmentId,
+          message: errorInfo.message,
+          fallbackError:
+            fallbackError instanceof Error
+              ? fallbackError.message
+              : String(fallbackError),
+        });
+        return {
+          __loaderResult: true,
+          ok: false,
           error: errorInfo,
+          fallback: null,
         };
-        renderedFallback = fallback(props);
-      } else {
-        renderedFallback = fallback;
       }
 
       debugLog("loader", "loader error wrapped with boundary fallback", {
@@ -242,6 +274,16 @@ function createLoaderExecutor<TEnv>(
     pendingLoaders.add(loader.$$id);
 
     const currentLoaderId = loader.$$id;
+    const variables = (ctx as InternalHandlerContext<any, TEnv>)._variables;
+
+    // Capture whether this loader is being started from a DSL loader scope
+    // (runInsideLoaderScope in fresh.ts). Handler-invoked loaders are NOT
+    // inside loader scope. This determines whether rendered() is allowed.
+    const isDslLoader = isInsideLoaderScope();
+
+    let renderedResolved = false;
+    let renderedPromise: Promise<void> | null = null;
+
     // Loader functions are always fresh (never cached), so they get an
     // unguarded get that bypasses non-cacheable read guards. This applies
     // to ALL loaders — DSL and handler-called — because the loader
@@ -255,26 +297,138 @@ function createLoaderExecutor<TEnv>(
       search: (ctx as any).search,
       pathname: ctx.pathname,
       url: ctx.url,
+      originalUrl: ctx.originalUrl,
       env: ctx.env,
-      var: ctx.var,
-      get: ((keyOrVar: any) => contextGet(ctx.var, keyOrVar)) as typeof ctx.get,
-      use: <TDep, TDepParams = any>(
-        dep: LoaderDefinition<TDep, TDepParams>,
-      ): Promise<TDep> => {
-        return useLoader(dep, currentLoaderId);
-      },
+      waitUntil: ctx.waitUntil.bind(ctx),
+      executionContext: ctx.executionContext,
+      get: ((keyOrVar: any) =>
+        contextGet(variables, keyOrVar)) as typeof ctx.get,
+      use: ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
+        if (isHandle(item)) {
+          if (!renderedResolved) {
+            throw new Error(
+              `ctx.use(handle) in a loader requires "await ctx.rendered()" first. ` +
+                `Handle "${item.$$id}" cannot be read until the render tree has settled.`,
+            );
+          }
+          const reqCtx = reqCtxRef ?? _getRequestContext();
+          if (!reqCtx) {
+            throw new Error(
+              `ctx.use(handle) failed: request context not available.`,
+            );
+          }
+          const segmentOrder = reqCtx._renderBarrierSegmentOrder ?? [];
+          // The complete snapshot is cached at barrier resolution for
+          // non-streaming trees, and by rendered() after handleStore.settled for
+          // streaming trees (where the eager snapshot would have been incomplete
+          // because loading() handlers were still in flight). Either way it is
+          // present by the time a loader reads a handle; the fresh build is only
+          // a defensive fallback.
+          const snapshot =
+            reqCtx._renderBarrierHandleSnapshot ??
+            buildHandleSnapshot(reqCtx._handleStore, segmentOrder);
+          return collectHandleData(item, snapshot, segmentOrder);
+        }
+
+        // Loader case
+        return useLoader(item as LoaderDefinition<any, any>, currentLoaderId);
+      }) as LoaderContext["use"],
       method: "GET",
       body: undefined,
       reverse: ctx.reverse as LoaderContext["reverse"],
+      rendered: (): Promise<void> => {
+        // Guard: only DSL loaders may use rendered()
+        if (!isDslLoader) {
+          throw new Error(
+            `ctx.rendered() is only available in DSL loaders (registered via loader() in urls()). ` +
+              `Handler-invoked loaders (ctx.use(Loader) inside a handler) cannot use rendered().`,
+          );
+        }
+
+        const reqCtx = reqCtxRef ?? _getRequestContext();
+
+        if (renderedPromise) return renderedPromise;
+
+        if (!reqCtx) {
+          throw new Error(
+            `ctx.rendered() failed: request context not available.`,
+          );
+        }
+
+        // Bidirectional deadlock check: if a handler already started
+        // awaiting this loader, calling rendered() would deadlock. This is the
+        // real cycle guard (it holds for both streaming and non-streaming): the
+        // handler blocks segment resolution, which blocks the barrier, which
+        // blocks this loader.
+        if (reqCtx._handlerLoaderDeps?.has(currentLoaderId)) {
+          throw new Error(
+            `Deadlock: loader "${currentLoaderId}" called ctx.rendered() but a handler ` +
+              `is already awaiting this loader via ctx.use(). The handler blocks ` +
+              `segment resolution, which blocks the barrier, which blocks this loader. ` +
+              `Move the data dependency to a loader-to-loader pattern instead.`,
+          );
+        }
+
+        // Register this loader as waiting for the barrier so that
+        // setupLoaderAccess can detect deadlocks when a handler
+        // tries to await the same loader via ctx.use().
+        if (!reqCtx._renderBarrierWaiters) {
+          reqCtx._renderBarrierWaiters = new Set();
+        }
+        reqCtx._renderBarrierWaiters.add(currentLoaderId);
+
+        // Streaming trees (loading()): the barrier resolves once the segment
+        // tree is resolved, but loading() handlers stream behind Suspense and
+        // their handle pushes are still in flight then. Their async execution
+        // IS tracked in the handle store (trackHandler -> store.track), so after
+        // the barrier we seal (no further handlers register once the tree is
+        // resolved) and wait for settled — every tracked handler, streaming
+        // included, has finished pushing. The loader's own segment streams in
+        // after, so this does not block the shell; the deadlock guard above
+        // keeps a handler from depending on this loader.
+        const streaming = reqCtx._treeHasStreaming === true;
+        renderedPromise = reqCtx._renderBarrier.then(async () => {
+          if (streaming) {
+            reqCtx._handleStore.seal();
+            await reqCtx._handleStore.settled;
+            // The eager snapshot was intentionally left unbuilt for streaming
+            // (it would have been incomplete). Build the complete one once, now
+            // that the store has settled, so every ctx.use(handle) reads the
+            // cached snapshot instead of rebuilding it per call.
+            reqCtx._renderBarrierHandleSnapshot ??= buildHandleSnapshot(
+              reqCtx._handleStore,
+              reqCtx._renderBarrierSegmentOrder ?? [],
+            );
+          }
+          renderedResolved = true;
+        });
+        return renderedPromise;
+      },
     };
 
-    const doneLoader = track(`loader:${loader.$$id}`, 2);
-    const promise = Promise.resolve(
-      loaderFn(loaderCtx as LoaderContext<any, TEnv>),
-    ).finally(() => {
-      pendingLoaders.delete(loader.$$id);
-      doneLoader();
-    });
+    // Meter this loader once via observePhase (loader:<id> perf metric +
+    // rango.loader span); loaderFn runs inside the span callback so its KV/D1/
+    // fetch spans nest under it. This is one of the observePhase loader funnels —
+    // see instrument.ts for the single-metering contract.
+    //
+    // Run the loader body inside loader scope so request-scoped reads
+    // (cookies()/headers() and non-cacheable ctx.get) are exempt from the
+    // cache-purity guards: loaders always run fresh, so their reads never leak
+    // into a cached segment. DSL loaders are already wrapped by fresh.ts; this
+    // also covers handler-invoked loaders (ctx.use(Loader) from a handler),
+    // which otherwise execute in the caller's cache scope and would wrongly
+    // throw. rendered() gating uses the captured isDslLoader (above), so this
+    // does not grant rendered() to handler-invoked loaders. Uses a body-only
+    // scope, so isInsideLoaderScope() / barrier / deadlock gating is unchanged.
+    const promise = observePhase(PHASES.loader(loader.$$id), () =>
+      Promise.resolve(
+        runInsideLoaderBodyScope(() =>
+          loaderFn(loaderCtx as LoaderContext<any, TEnv>),
+        ),
+      ).finally(() => {
+        pendingLoaders.delete(loader.$$id);
+      }),
+    );
 
     loaderPromises.set(loader.$$id, promise);
     return promise;
@@ -296,12 +450,13 @@ export function setupLoaderAccess<TEnv>(
   ctx: HandlerContext<any, TEnv>,
   loaderPromises: Map<string, Promise<any>>,
 ): void {
-  // Eagerly capture the HandleStore at setup time (before pipeline async ops).
-  // In workerd/Cloudflare, dynamic imports and fetch() in the match pipeline
-  // can disrupt AsyncLocalStorage, causing getRequestContext() to return
-  // undefined when handlers later call ctx.use(handle). Capturing early
-  // ensures the store reference survives ALS disruption.
-  const handleStoreRef = _getRequestContext()?._handleStore;
+  // Eagerly capture the request context and HandleStore at setup time
+  // (before pipeline async ops). In workerd/Cloudflare, dynamic imports and
+  // fetch() in the match pipeline can disrupt AsyncLocalStorage, causing
+  // getRequestContext() to return undefined when handlers later call
+  // ctx.use(handle). Capturing early ensures references survive ALS disruption.
+  const reqCtxRef = _getRequestContext();
+  const handleStoreRef = reqCtxRef?._handleStore;
 
   const useLoader = createLoaderExecutor(ctx, loaderPromises);
 
@@ -319,21 +474,72 @@ export function setupLoaderAccess<TEnv>(
         );
       }
 
-      return (
-        dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>),
-      ) => {
-        if (!store) return;
-
-        const valueOrPromise =
-          typeof dataOrFn === "function"
-            ? (dataOrFn as () => Promise<unknown>)()
-            : dataOrFn;
+      return withDefer(
+        (dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>)) => {
+          if (!store) return;
+
+          if (typeof dataOrFn === "function") {
+            // Run the callback inside the push-callback scope so ctx.use(loader)
+            // calls it makes — including after its own awaits, for an async
+            // callback — are not registered as handler-to-loader deps and do not
+            // trip the deadlock guard. A pushed promise value is not tracked by
+            // handleStore.settled and does not block segment resolution, so it
+            // cannot form a rendered() deadlock. The ALS scope (not a plain
+            // boolean) is what survives the callback's awaits.
+            const result = runInsidePushCallbackScope(() =>
+              (dataOrFn as () => Promise<unknown>)(),
+            );
+            store.push(handle.$$id, segmentId, result);
+            return;
+          }
+
+          store.push(handle.$$id, segmentId, dataOrFn);
+        },
+      );
+    }
 
-        store.push(handle.$$id, segmentId, valueOrPromise);
-      };
+    // Deadlock guard and handler-to-loader dependency tracking.
+    // Skip when inside a DSL loader scope (resolveLoaderData also calls
+    // ctx.use() but that's DSL-to-DSL, not handler-to-loader) or when
+    // inside a handle push callback (push callbacks don't block segment
+    // resolution so they can't cause rendered() deadlocks). The push-callback
+    // check is an ALS scope so it also exempts an ASYNC callback's continuation
+    // after its first await — relevant on streaming trees, where the guard
+    // state now stays live until handleStore.settled.
+    const loader = item as LoaderDefinition<any, any>;
+    if (!isInsideLoaderScope() && !isInsidePushCallbackScope()) {
+      const reqCtx = reqCtxRef ?? _getRequestContext();
+      if (reqCtx) {
+        // Direction 1: handler awaits loader that already called rendered()
+        if (
+          loaderPromises.has(loader.$$id) &&
+          reqCtx._renderBarrierWaiters?.has(loader.$$id)
+        ) {
+          throw new Error(
+            `Deadlock: handler is awaiting loader "${loader.$$id}" which called ctx.rendered(). ` +
+              `The loader is waiting for segment resolution, but the handler blocks resolution. ` +
+              `Move the data dependency to a loader-to-loader pattern instead.`,
+          );
+        }
+        // Direction 2: track dep so rendered() can detect the deadlock if the
+        // loader calls it later. Skip once the guard window is CLOSED — for a
+        // non-streaming tree that is when the barrier resolves (rendered()
+        // resolves immediately), and for a streaming tree it is when
+        // handleStore.settled completes (rendered() keeps waiting until then, so
+        // a loading() handler resuming after the barrier can still form a
+        // cycle). Using the explicit guard-closed flag rather than
+        // _renderBarrierSegmentOrder keeps tracking live across the streaming
+        // settle wait. (Handle push callbacks are already excluded above via
+        // isInsidePushCallbackScope(), so they cannot produce false positives
+        // here.)
+        if (!reqCtx._renderBarrierGuardClosed) {
+          if (!reqCtx._handlerLoaderDeps) reqCtx._handlerLoaderDeps = new Set();
+          reqCtx._handlerLoaderDeps.add(loader.$$id);
+        }
+      }
     }
 
-    return useLoader(item as LoaderDefinition<any, any>, null);
+    return useLoader(loader, null);
   }) as typeof ctx.use;
 }
 
@@ -360,18 +566,21 @@ export function setupBuildUse<TEnv>(ctx: HandlerContext<any, TEnv>): void {
         );
       }
 
-      return (
-        dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>),
-      ) => {
-        if (!store) return;
+      // Wrap with withDefer so ctx.use(Handle).defer(...) works on the build /
+      // prerender path, matching production setupLoaderAccess. Without it a
+      // prerender handler calling .defer() throws "defer is not a function".
+      return withDefer(
+        (dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>)) => {
+          if (!store) return;
 
-        const valueOrPromise =
-          typeof dataOrFn === "function"
-            ? (dataOrFn as () => Promise<unknown>)()
-            : dataOrFn;
+          const valueOrPromise =
+            typeof dataOrFn === "function"
+              ? (dataOrFn as () => Promise<unknown>)()
+              : dataOrFn;
 
-        store.push(handle.$$id, segmentId, valueOrPromise);
-      };
+          store.push(handle.$$id, segmentId, valueOrPromise);
+        },
+      );
     }
 
     // Loader case: not available during pre-rendering
@@ -399,8 +608,11 @@ export function setupLoaderAccessSilent<TEnv>(
 
   ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
     if (isHandle(item)) {
-      // Silent mode - return a no-op so handle data is not pushed during caching
-      return (_dataOrFn: unknown) => {};
+      // Silent mode - return a no-op so handle data is not pushed during caching.
+      // Wrap with withDefer so ctx.use(Handle).defer(...) still resolves to a
+      // callable resolver (also a no-op here), matching production's push shape
+      // instead of throwing "defer is not a function".
+      return withDefer((_dataOrFn: unknown) => {});
     }
 
     return useLoader(item as LoaderDefinition<any, any>, null);

package/src/router/logging.ts

@@ -1,8 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 
-// -- Revalidation trace types --
-
 export interface RevalidationTraceEntry {
   segmentId: string;
   segmentType: string;
@@ -36,8 +34,6 @@ export interface RevalidationTrace {
   entries: RevalidationTraceEntry[];
 }
 
-// -- Log context --
-
 interface RouterLogContext {
   requestId: string;
   transactionId: string;
@@ -195,8 +191,6 @@ export function debugWarn(
   console.warn(`${prefix} ${message}`);
 }
 
-// -- Revalidation trace helpers --
-
 export function isTraceActive(): boolean {
   if (!INTERNAL_RANGO_DEBUG) return false;
   const ctx = routerLogContext.getStore();

package/src/router/manifest.ts

@@ -1,9 +1,3 @@
-/**
- * Router Manifest Loading
- *
- * Handles lazy loading and validation of route manifests.
- */
-
 import { invariant, RouteNotFoundError } from "../errors";
 import { createRouteHelpers } from "../route-definition";
 import {
@@ -14,6 +8,7 @@ import {
   type MetricsStore,
 } from "../server/context";
 import MapRootLayout from "../server/root-layout";
+import { joinPrefix } from "./pattern-matching.js";
 import type { RouteEntry } from "../types";
 import type { UrlPatterns } from "../urls";
 import { VERSION } from "@rangojs/router:version";
@@ -23,20 +18,19 @@ import { VERSION } from "@rangojs/router:version";
 // stable references), so the resulting EntryData tree can be safely cached and reused
 // across requests within the same isolate.
 //
-// Cache is keyed by (VERSION, mountIndex, routeKey, isSSR). VERSION comes from the
+// Cache is keyed by (VERSION, routerId, mountIndex, routeKey, isSSR). routeKey is
+// REQUIRED in the key: loadManifest() runs the handler with forRoute=routeKey, and
+// path-helper.ts prunes (skips registering) every route except forRoute, so the
+// resulting Store.manifest is pruned to the requested route — NOT the full include.
+// Dropping routeKey would make a sibling route miss and overwrite this entry with its
+// own pruned manifest, so alternating sibling requests would thrash (re-run the
+// handler every time). Running the include handler once per isolate instead of once
+// per route is possible but needs an unpruned manifest cache with prune-on-read — see
+// LP1 in docs/internal/matching-and-lazy-discovery.md. VERSION comes from the
 // @rangojs/router:version virtual module which Vite invalidates on RSC module HMR.
 // When VERSION changes, this module re-evaluates and the cache is recreated empty.
-// Including VERSION in the key is additional defense against stale entries.
 const manifestModuleCache = new Map<string, Map<string, EntryData>>();
 
-/**
- * Load manifest from route entry with AsyncLocalStorage context
- * Handles lazy imports, unwrapping, and validation
- *
- * Results are cached at module level after first execution. Subsequent calls
- * for the same (routeKey, isSSR) within the same isolate return cached data
- * without re-executing the DSL handler.
- */
 /**
  * Clear the module-level manifest cache.
  * Called on HMR to ensure stale handler references are discarded.
@@ -65,9 +59,11 @@ export async function loadManifest(
 
   const mountIndex = entry.mountIndex;
 
-  // Check module-level cache (persists across requests within same isolate)
+  // Check module-level cache (persists across requests within same isolate).
   // Include routerId so multi-router setups (host routing) don't share cached
   // EntryData across routers with overlapping mountIndex + routeKey combinations.
+  // routeKey is in the key because loadManifest() builds a manifest pruned to
+  // forRoute=routeKey (see path-helper.ts) — see the cache comment above.
   const cacheKey = `${VERSION}:${entry.routerId ?? ""}:${mountIndex ?? ""}:${routeKey}:${isSSR ? 1 : 0}`;
   const cached = manifestModuleCache.get(cacheKey);
   if (cached) {
@@ -88,20 +84,15 @@ export async function loadManifest(
   const storeSetupStart = performance.now();
   const Store = getContext().getOrCreateStore(routeKey);
 
-  // Set mount index in store for unique shortCode prefixes
   Store.mountIndex = mountIndex;
-
-  // Set isSSR flag so loading() can check if we're in SSR
   Store.isSSR = isSSR;
 
-  // Attach metrics store to context if provided
   if (metricsStore) {
     Store.metrics = metricsStore;
   }
 
   pushMetric?.("manifest:store-setup", storeSetupStart);
 
-  // Clear manifest before rebuilding to prevent stale entry mutations
   const clearStart = performance.now();
   Store.manifest.clear();
   pushMetric?.("manifest:clear", clearStart);
@@ -126,28 +117,37 @@ export async function loadManifest(
     // were created during pattern extraction.  This prevents shortCode
     // collisions between lazy and non-lazy entries under the same parent
     // (e.g., ArticlesLayout and BlogLayout both under NavLayout).
-    if (lazyContext && (lazyContext as any).counters) {
-      const captured = (lazyContext as any).counters as Record<string, number>;
-      for (const [key, value] of Object.entries(captured)) {
+    if (lazyContext?.counters) {
+      for (const [key, value] of Object.entries(lazyContext.counters)) {
         Store.counters[key] = Math.max(Store.counters[key] ?? 0, value);
       }
     }
 
     // Propagate cache profiles for DSL-time cache("profileName") resolution.
     // Non-lazy entries carry profiles directly; lazy entries carry them
-    // in the captured lazyContext from include() time.
-    const entryProfiles =
-      entry.cacheProfiles ?? (lazyContext as any)?.cacheProfiles;
-    if (entryProfiles) {
-      Store.cacheProfiles = entryProfiles;
-    }
+    // in the captured lazyContext from include() time. Always write
+    // (including clearing to undefined) so a prior lazy build's profile
+    // map cannot leak into a later non-lazy build on the same ALS-backed
+    // Store — which would otherwise let cache("name") resolve a profile
+    // from an unrelated entry.
+    Store.cacheProfiles = entry.cacheProfiles ?? lazyContext?.cacheProfiles;
 
     // Propagate rootScoped from lazyContext so that routes inside
     // nested { name: "sub" } under { name: "" } keep inherited root scope
-    // when the manifest is rebuilt on each request.
-    if (lazyContext && (lazyContext as any).rootScoped !== undefined) {
-      Store.rootScoped = (lazyContext as any).rootScoped;
-    }
+    // when the manifest is rebuilt on each request. Always write
+    // (including clearing to undefined, which makes getRootScoped()
+    // return its true default) so a prior lazy build's scope cannot leak
+    // into a later non-lazy build on the same ALS-backed Store — which
+    // would otherwise mis-register plain routes as non-root-scoped and
+    // break dot-local reverse resolution.
+    Store.rootScoped = lazyContext?.rootScoped;
+
+    // Propagate includeScope from lazyContext so that direct-descendant
+    // shortCodes of this include use the correct scoped counter namespace
+    // on every manifest rebuild. Always write (including clearing to
+    // undefined) so a prior lazy build's scope cannot leak into a later
+    // non-lazy build on the same ALS-backed Store.
+    Store.includeScope = lazyContext?.includeScope;
 
     const handlerExecStart = performance.now();
     const useItems = await getContext().runWithStore(
@@ -167,7 +167,10 @@ export async function loadManifest(
         if (entry.lazy && entry.lazyPatterns) {
           const lazyPatterns = entry.lazyPatterns as UrlPatterns<any>;
           const includePrefix = (entry as any)._lazyPrefix || "";
-          const fullPrefix = (lazyContext?.urlPrefix || "") + includePrefix;
+          // Slash-collapsing join so a trailing-slash parent prefix does not
+          // bake a double slash into the registered route patterns (must match
+          // the same join in evaluateLazyEntry / the build-time runWithPrefixes).
+          const fullPrefix = joinPrefix(lazyContext?.urlPrefix, includePrefix);
 
           if (fullPrefix || lazyContext?.namePrefix) {
             return runWithPrefixes(fullPrefix, lazyContext?.namePrefix, () =>
@@ -177,20 +180,16 @@ export async function loadManifest(
           return lazyPatterns.handler();
         }
 
-        // Wrap handler execution in root layout so routes get correct parent
-        // This ensures all routes are registered with the layout as their parent
         let promiseResult: Promise<any> | null = null;
         const wrappedItems = helpers.layout(MapRootLayout, () => {
           const result = entry.handler();
           if (result instanceof Promise) {
-            // Lazy handler detected - capture promise for async handling
             promiseResult = result;
-            return []; // Return empty, we'll discard this wrapped result
+            return [];
           }
           return result;
         });
 
-        // Handle lazy (Promise-based) handlers
         if (promiseResult !== null) {
           const load = await (promiseResult as Promise<any>);
           if (
@@ -224,7 +223,6 @@ export async function loadManifest(
           );
         }
 
-        // Inline handler - routes were registered with correct parent inside layout
         return [wrappedItems].flat(3);
       },
     );