@rangojs/router 0.0.0-experimental.79 → 0.0.0-experimental.7c7e4327

package/src/router/lazy-includes.ts

@@ -1,14 +1,18 @@
 import { registerRouteMap } from "../route-map-builder.js";
-import { extractStaticPrefix } from "./pattern-matching.js";
+import { extractStaticPrefix, joinPrefix } from "./pattern-matching.js";
 import {
-  EntryData,
-  RSCRouterContext,
+  type EntryData,
+  RangoContext,
   runWithPrefixes,
   getIsolatedLazyParent,
 } from "../server/context";
 import type { UrlPatterns } from "../urls.js";
 import type { AllUseItems, IncludeItem } from "../route-types.js";
 import type { ResolvedRouteMap, RouteEntry, TrailingSlashMode } from "../types";
+import {
+  isIncludeProvider,
+  resolveIncludeModule,
+} from "../urls/include-provider.js";
 
 export interface LazyEvalDeps<TEnv = any> {
   routesEntries: RouteEntry<TEnv>[];
@@ -18,9 +22,6 @@ export interface LazyEvalDeps<TEnv = any> {
   routerId?: string;
 }
 
-// Detect lazy includes in handler result and create placeholder entries
-// Lazy includes are IncludeItem with lazy: true and _lazyContext
-// Moved to outer scope so it can be reused by evaluateLazyEntry for nested includes
 export function findLazyIncludes<TEnv = any>(
   items: AllUseItems[],
 ): Array<{
@@ -56,7 +57,6 @@ export function findLazyIncludes<TEnv = any>(
         });
       }
     }
-    // Recursively check nested items (in layouts, etc.)
     if ((item as any).uses && Array.isArray((item as any).uses)) {
       lazyItems.push(...findLazyIncludes((item as any).uses));
     }
@@ -73,19 +73,11 @@ export function findLazyIncludes<TEnv = any>(
 export function evaluateLazyEntry<TEnv = any>(
   entry: RouteEntry<TEnv>,
   deps: LazyEvalDeps<TEnv>,
-): void {
+): void | Promise<void> {
   if (!entry.lazy || entry.lazyEvaluated || !entry.lazyPatterns) {
     return;
   }
 
-  // Check for pre-computed routes from build-time data.
-  // Only leaf nodes (no nested includes) are precomputed, so entries with
-  // nested lazy includes fall through to the handler below.
-  // When multiple entries share the same staticPrefix (e.g., several
-  // include("/", ...) calls), the precomputed data merges all their routes
-  // into one entry. Assigning that merged set to the first matching entry
-  // causes findMatch to pick the wrong handler for routes belonging to a
-  // different include. Skip the shortcut when the prefix is shared.
   const currentPrecomputed = deps.getPrecomputedByPrefix();
   if (currentPrecomputed) {
     const routes = currentPrecomputed.get(entry.staticPrefix);
@@ -99,39 +91,76 @@ export function evaluateLazyEntry<TEnv = any>(
         for (const [name, pattern] of Object.entries(routes)) {
           deps.mergedRouteMap[name] = pattern;
         }
-        registerRouteMap(deps.mergedRouteMap);
+        // Register only this entry's routes (the delta): the full
+        // mergedRouteMap is seeded from the generated manifest at
+        // createRouter() time and already registered there — re-passing it
+        // made this request-path call O(total routes) (issue #666).
+        registerRouteMap(routes);
         return;
       }
     }
   }
 
-  // Mark as evaluated immediately to prevent concurrent evaluation.
-  // JS is single-threaded but handlers.handler() could theoretically yield,
-  // and the while-loop in findMatch retries after evaluation.
-  entry.lazyEvaluated = true;
+  // Async provider (`() => import("./routes")`): the route module is evaluated
+  // off the startup path, on the first request reaching this prefix. Concurrent
+  // first-hits share one in-flight promise so the import + expansion run exactly
+  // once. The eager path below stays fully synchronous (no Promise), so the
+  // per-entry match loop pays no microtask for normal includes.
+  const lazyPatterns = entry.lazyPatterns;
+  if (isIncludeProvider(lazyPatterns)) {
+    const inflight = (entry as { _lazyInflight?: Promise<void> })._lazyInflight;
+    if (inflight) return inflight;
+    const work = (async () => {
+      const resolved = resolveIncludeModule(
+        await lazyPatterns(),
+        entry.staticPrefix,
+      );
+      // Cache the resolved patterns: any later re-entry expands synchronously.
+      entry.lazyPatterns = resolved as unknown as UrlPatterns<TEnv>;
+      runExpansion(entry, deps, resolved as UrlPatterns<TEnv>);
+    })();
+    (entry as { _lazyInflight?: Promise<void> })._lazyInflight = work;
+    const clear = () => {
+      (entry as { _lazyInflight?: Promise<void> })._lazyInflight = undefined;
+    };
+    // On failure, clear the flag (lazyEvaluated stays false) so a later request
+    // can retry the import rather than wedging the route permanently.
+    work.then(clear, clear);
+    return work;
+  }
+
+  runExpansion(entry, deps, lazyPatterns as UrlPatterns<TEnv>);
+}
 
-  const lazyPatterns = entry.lazyPatterns as UrlPatterns<TEnv>;
+/**
+ * Synchronously expand a lazy entry's (already-resolved) patterns into routes
+ * and splice any nested lazy includes as new entries. Runs once per entry.
+ */
+function runExpansion<TEnv = any>(
+  entry: RouteEntry<TEnv>,
+  deps: LazyEvalDeps<TEnv>,
+  lazyPatterns: UrlPatterns<TEnv>,
+): void {
+  // lazyEvaluated is set at the END, only after the handler ran and the routes
+  // (and any nested includes) were spliced. Setting it up-front would mark the
+  // entry done even if the handler throws mid-expansion: the async provider
+  // path clears _lazyInflight on rejection so a later request can retry, but a
+  // premature lazyEvaluated=true would make evaluateLazyEntry short-circuit
+  // (line ~77) forever, wedging the route at 404 until the isolate restarts.
   const lazyContext = entry.lazyContext;
 
-  // Create a new context for evaluating the lazy patterns
   const manifest = new Map<string, EntryData>();
   const patterns = new Map<string, string>();
   const patternsByPrefix = new Map<string, Map<string, string>>();
   const trailingSlashMap = new Map<string, TrailingSlashMode>();
 
-  // Capture the handler result to detect nested lazy includes
   let handlerResult: AllUseItems[] = [];
 
-  // Merge captured counters from include() to maintain consistent
-  // shortCode indices with sibling entries from pattern extraction
-  const lazyCounters: Record<string, number> = {};
-  if (lazyContext?.counters) {
-    for (const [key, value] of Object.entries(lazyContext.counters)) {
-      lazyCounters[key] = value;
-    }
-  }
+  const lazyCounters: Record<string, number> = lazyContext?.counters
+    ? { ...lazyContext.counters }
+    : {};
 
-  RSCRouterContext.run(
+  RangoContext.run(
     {
       manifest,
       patterns,
@@ -145,10 +174,8 @@ export function evaluateLazyEntry<TEnv = any>(
       includeScope: lazyContext?.includeScope,
     },
     () => {
-      // Run the lazy patterns handler with the original context prefixes
-      // The prefix comes from the IncludeItem stored in lazyPatterns
       const includePrefix = (entry as any)._lazyPrefix || "";
-      const fullPrefix = (lazyContext?.urlPrefix || "") + includePrefix;
+      const fullPrefix = joinPrefix(lazyContext?.urlPrefix, includePrefix);
 
       if (fullPrefix || lazyContext?.namePrefix) {
         runWithPrefixes(fullPrefix, lazyContext?.namePrefix, () => {
@@ -160,11 +187,9 @@ export function evaluateLazyEntry<TEnv = any>(
     },
   );
 
-  // Populate the entry's routes from the patterns
   const routesObject: Record<string, string> = {};
   for (const [name, pattern] of patterns.entries()) {
     routesObject[name] = pattern;
-    // Also add to merged route map for reverse() support
     const existingPattern = deps.mergedRouteMap[name];
     if (existingPattern !== undefined && existingPattern !== pattern) {
       console.warn(
@@ -175,46 +200,38 @@ export function evaluateLazyEntry<TEnv = any>(
     deps.mergedRouteMap[name] = pattern;
   }
 
-  // Update the entry in-place
   entry.routes = routesObject as ResolvedRouteMap<any>;
 
-  // Note: Do NOT clear lazyPatterns/lazyContext here.
-  // loadManifest() needs them on every request to re-run the handler
-  // in the correct AsyncLocalStorage context (Store.manifest).
-
-  // Update trailing slash config if available
   if (trailingSlashMap.size > 0) {
     entry.trailingSlash = Object.fromEntries(trailingSlashMap);
   }
 
-  // Detect nested lazy includes and register them as new entries
   const nestedLazyIncludes = findLazyIncludes(handlerResult);
   for (const lazyInclude of nestedLazyIncludes) {
-    // Compute the full URL prefix (combining parent prefix if any)
-    const fullPrefix = lazyInclude.context.urlPrefix
-      ? lazyInclude.context.urlPrefix + lazyInclude.prefix
-      : lazyInclude.prefix;
+    const fullPrefix = joinPrefix(
+      lazyInclude.context.urlPrefix,
+      lazyInclude.prefix,
+    );
 
     const nestedEntry: RouteEntry<TEnv> & { _lazyPrefix?: string } = {
       prefix: "",
       staticPrefix: extractStaticPrefix(fullPrefix),
-      routes: {} as ResolvedRouteMap<any>, // Empty until first match
+      routes: {} as ResolvedRouteMap<any>,
       trailingSlash: entry.trailingSlash,
-      handler: (lazyInclude.patterns as UrlPatterns<TEnv>).handler,
+      // include entries don't invoke their own handler (real handlers come from
+      // the expanded routes); use the parent's placeholder. A provider has no
+      // `.handler` until resolved, so never read it here.
+      handler: isIncludeProvider(lazyInclude.patterns)
+        ? entry.handler
+        : (lazyInclude.patterns as UrlPatterns<TEnv>).handler,
       mountIndex: deps.nextMountIndex(),
       routerId: deps.routerId,
-      // Lazy evaluation fields
       lazy: true,
       lazyPatterns: lazyInclude.patterns,
       lazyContext: lazyInclude.context,
       lazyEvaluated: false,
-      // Store the include prefix for evaluation
       _lazyPrefix: lazyInclude.prefix,
     };
-    // Insert nested lazy entry before any entry whose staticPrefix is a
-    // prefix of (but shorter than) this lazy entry's staticPrefix.
-    // This ensures more specific lazy includes are matched before
-    // less specific eager entries (e.g., "/href/nested" before "/href/:id").
     const nestedPrefix = nestedEntry.staticPrefix;
     let insertIndex = deps.routesEntries.length;
     if (nestedPrefix) {
@@ -232,6 +249,12 @@ export function evaluateLazyEntry<TEnv = any>(
     deps.routesEntries.splice(insertIndex, 0, nestedEntry);
   }
 
-  // Re-register route map for runtime reverse() usage
-  registerRouteMap(deps.mergedRouteMap);
+  // Delta only — see the matching comment on the precomputed branch above and
+  // the WHY block on registerRouteMap (issue #666).
+  registerRouteMap(routesObject);
+
+  // Expansion fully succeeded (handler ran, routes + nested includes spliced) —
+  // mark done now so a mid-expansion throw above leaves lazyEvaluated=false and
+  // the entry retriable.
+  entry.lazyEvaluated = true;
 }

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,12 +19,17 @@ import type {
   ErrorBoundaryFallbackProps,
   ErrorInfo,
 } from "../types";
-import type { LoaderRevalidationResult, ActionContext } from "./types";
 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 } from "../server/context.js";
+import {
+  isInsideLoaderScope,
+  runInsideLoaderBodyScope,
+  isInsidePushCallbackScope,
+  runInsidePushCallbackScope,
+} from "../server/context.js";
 import { debugLog } from "./logging.js";
 
 /**
@@ -66,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)
@@ -102,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", {
@@ -266,7 +297,10 @@ function createLoaderExecutor<TEnv>(
       search: (ctx as any).search,
       pathname: ctx.pathname,
       url: ctx.url,
+      originalUrl: ctx.originalUrl,
       env: ctx.env,
+      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>) => {
@@ -284,6 +318,12 @@ function createLoaderExecutor<TEnv>(
             );
           }
           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);
@@ -305,15 +345,7 @@ function createLoaderExecutor<TEnv>(
           );
         }
 
-        // Guard: reject streaming trees
         const reqCtx = reqCtxRef ?? _getRequestContext();
-        if (reqCtx?._treeHasStreaming) {
-          throw new Error(
-            `ctx.rendered() is not supported when the matched route tree uses loading(). ` +
-              `Streaming handlers may not have settled when rendered() resolves. ` +
-              `Remove loading() from the route tree or restructure to avoid rendered().`,
-          );
-        }
 
         if (renderedPromise) return renderedPromise;
 
@@ -324,7 +356,10 @@ function createLoaderExecutor<TEnv>(
         }
 
         // Bidirectional deadlock check: if a handler already started
-        // awaiting this loader, calling rendered() would deadlock.
+        // 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 ` +
@@ -342,20 +377,70 @@ function createLoaderExecutor<TEnv>(
         }
         reqCtx._renderBarrierWaiters.add(currentLoaderId);
 
-        renderedPromise = reqCtx._renderBarrier.then(() => {
+        // 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.
+    //
+    // `handlerInvoked` (!isDslLoader) rides on the scope for the CONSUMPTION-
+    // LANE RULE: a handler-consumed loader's value is a BAKED copy in every
+    // shared artifact (cache(), "use cache", the PPR shell), so its identity
+    // reads are exempt from the shell-capture guard — same allowance the
+    // cache-purity guards give it. DSL segment loaders keep their lane
+    // machinery (live = masked at capture, bake = guarded). A DSL loader's
+    // nested deps inherit isDslLoader=false only when the CHAIN started in a
+    // handler; a chain started by the segment funnel stays DSL (the loader
+    // scope ALS survives the body's awaits).
+    const promise = observePhase(PHASES.loader(loader.$$id), () =>
+      Promise.resolve(
+        runInsideLoaderBodyScope(
+          () => loaderFn(loaderCtx as LoaderContext<any, TEnv>),
+          loader.$$id,
+          !isDslLoader,
+        ),
+      ).finally(() => {
+        pendingLoaders.delete(loader.$$id);
+      }),
+    );
 
     loaderPromises.set(loader.$$id, promise);
     return promise;
@@ -387,12 +472,6 @@ export function setupLoaderAccess<TEnv>(
 
   const useLoader = createLoaderExecutor(ctx, loaderPromises);
 
-  // Track whether we're inside a handle push callback. Loaders started
-  // from push callbacks (e.g. push(async () => ctx.use(Loader))) do NOT
-  // block segment resolution, so they must not be registered as handler
-  // dependencies for deadlock detection.
-  let insideHandlePush = false;
-
   ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
     if (isHandle(item)) {
       const handle = item;
@@ -407,35 +486,40 @@ export function setupLoaderAccess<TEnv>(
         );
       }
 
-      return (
-        dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>),
-      ) => {
-        if (!store) return;
-
-        if (typeof dataOrFn === "function") {
-          // Mark scope so ctx.use(loader) calls inside the callback
-          // are not registered as handler-to-loader deps.
-          insideHandlePush = true;
-          try {
-            const result = (dataOrFn as () => Promise<unknown>)();
+      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);
-          } finally {
-            insideHandlePush = false;
+            return;
           }
-          return;
-        }
 
-        store.push(handle.$$id, segmentId, dataOrFn);
-      };
+          store.push(handle.$$id, segmentId, dataOrFn);
+        },
+      );
     }
 
     // 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).
+    // 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() && !insideHandlePush) {
+    if (!isInsideLoaderScope() && !isInsidePushCallbackScope()) {
       const reqCtx = reqCtxRef ?? _getRequestContext();
       if (reqCtx) {
         // Direction 1: handler awaits loader that already called rendered()
@@ -449,13 +533,18 @@ export function setupLoaderAccess<TEnv>(
               `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 when the barrier has already
-        // resolved — no deadlock is possible (rendered() resolves immediately).
-        // _renderBarrierSegmentOrder is undefined before resolution, string[]
-        // after. This also prevents false positives from handle push callbacks
-        // that resume after their first await (post-barrier-resolution).
-        if (reqCtx._renderBarrierSegmentOrder === undefined) {
+        // 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);
         }
@@ -489,18 +578,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
@@ -528,8 +620,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();