@rangojs/router 0.0.0-experimental.64 → 0.0.0-experimental.65

package/dist/vite/index.js

@@ -910,9 +910,7 @@ function generateWholeFileStubs(cfg, bindings, code, filePath, isBuild) {
   });
   return { code: stubs.join("\n") + "\n", map: null };
 }
-function generateExprStubs(cfg, bindings, code, filePath, sourceId, isBuild) {
-  if (bindings.length === 0) return null;
-  const s = new MagicString2(code);
+function stubHandlerExprs(cfg, bindings, s, filePath, isBuild) {
   let hasChanges = false;
   for (const binding of bindings) {
     const exportName = binding.exportNames[0];
@@ -924,15 +922,7 @@ function generateExprStubs(cfg, bindings, code, filePath, sourceId, isBuild) {
     );
     hasChanges = true;
   }
-  if (!hasChanges) return null;
-  return {
-    code: s.toString(),
-    map: s.generateMap({
-      source: sourceId,
-      includeContent: true,
-      hires: "boundary"
-    })
-  };
+  return hasChanges;
 }
 function transformHandlerIds(cfg, bindings, s, filePath, isBuild) {
   let hasChanges = false;
@@ -1269,15 +1259,6 @@ ${lazyImports.join(",\n")}
           isBuild
         );
         if (wholeFile) return wholeFile;
-        const exprStubs = generateExprStubs(
-          PRERENDER_CONFIG,
-          bindings,
-          code,
-          filePath,
-          id,
-          isBuild
-        );
-        if (exprStubs) return exprStubs;
       }
       if (hasPrerenderHandlerCode && isRscEnv && isBuild) {
         const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
@@ -1329,15 +1310,6 @@ ${lazyImports.join(",\n")}
           isBuild
         );
         if (wholeFile) return wholeFile;
-        const exprStubs = generateExprStubs(
-          STATIC_CONFIG,
-          bindings,
-          code,
-          filePath,
-          id,
-          isBuild
-        );
-        if (exprStubs) return exprStubs;
       }
       if (hasStaticHandlerCode && isRscEnv && isBuild) {
         const fnNames = getFnNames(STATIC_CONFIG.fnName);
@@ -1372,25 +1344,41 @@ ${lazyImports.join(",\n")}
           isBuild
         ) || changed;
       }
-      if (hasPrerenderHandlerCode && isRscEnv) {
+      if (hasPrerenderHandlerCode) {
         const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
-        changed = transformHandlerIds(
-          PRERENDER_CONFIG,
-          getBindings(code, fnNames),
-          s,
-          filePath,
-          isBuild
-        ) || changed;
+        const bindings = getBindings(code, fnNames);
+        if (isRscEnv) {
+          changed = transformHandlerIds(
+            PRERENDER_CONFIG,
+            bindings,
+            s,
+            filePath,
+            isBuild
+          ) || changed;
+        } else {
+          changed = stubHandlerExprs(
+            PRERENDER_CONFIG,
+            bindings,
+            s,
+            filePath,
+            isBuild
+          ) || changed;
+        }
       }
-      if (hasStaticHandlerCode && isRscEnv) {
+      if (hasStaticHandlerCode) {
         const fnNames = getFnNames(STATIC_CONFIG.fnName);
-        changed = transformHandlerIds(
-          STATIC_CONFIG,
-          getBindings(code, fnNames),
-          s,
-          filePath,
-          isBuild
-        ) || changed;
+        const bindings = getBindings(code, fnNames);
+        if (isRscEnv) {
+          changed = transformHandlerIds(
+            STATIC_CONFIG,
+            bindings,
+            s,
+            filePath,
+            isBuild
+          ) || changed;
+        } else {
+          changed = stubHandlerExprs(STATIC_CONFIG, bindings, s, filePath, isBuild) || changed;
+        }
       }
       if (!changed) return;
       return {
@@ -1745,7 +1733,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.64",
+  version: "0.0.0-experimental.65",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -4785,7 +4773,26 @@ ${err.stack}`
           res.end("Missing pathname");
           return;
         }
-        let registry = mainRegistry;
+        const rscEnv = server.environments?.rsc;
+        let registry = null;
+        if (rscEnv?.runner && s.resolvedEntryPath) {
+          try {
+            await rscEnv.runner.import(s.resolvedEntryPath);
+            const serverMod = await rscEnv.runner.import(
+              "@rangojs/router/server"
+            );
+            registry = serverMod.RouterRegistry ?? null;
+          } catch (err) {
+            console.warn(
+              `[rsc-router] Dev prerender module refresh failed: ${err.message}`
+            );
+            res.statusCode = 500;
+            res.end(`Prerender handler error: ${err.message}`);
+            return;
+          }
+        } else {
+          registry = mainRegistry;
+        }
         if (!registry) {
           if (!prerenderNodeRegistry) {
             await getOrCreateTempServer();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.64",
+  "version": "0.0.0-experimental.65",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -132,6 +132,15 @@
     "access": "public",
     "tag": "experimental"
   },
+  "scripts": {
+    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "prepublishOnly": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest"
+  },
   "dependencies": {
     "@vitejs/plugin-rsc": "^0.5.19",
     "magic-string": "^0.30.17",
@@ -141,12 +150,12 @@
   "devDependencies": {
     "@playwright/test": "^1.49.1",
     "@types/node": "^24.10.1",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
     "esbuild": "^0.27.0",
     "jiti": "^2.6.1",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
+    "react": "catalog:",
+    "react-dom": "catalog:",
     "tinyexec": "^0.3.2",
     "typescript": "^5.3.0",
     "vitest": "^4.0.0"
@@ -164,13 +173,5 @@
     "vite": {
       "optional": true
     }
-  },
-  "scripts": {
-    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "typecheck": "tsc --noEmit",
-    "test": "playwright test",
-    "test:ui": "playwright test --ui",
-    "test:unit": "vitest run",
-    "test:unit:watch": "vitest"
   }
-}
+}

package/src/browser/react/use-handle.ts

@@ -9,64 +9,11 @@ import {
   startTransition,
 } from "react";
 import type { Handle } from "../../handle.js";
-import { getCollectFn } from "../../handle.js";
+import { collectHandleData } from "../../handle.js";
 import type { HandleData } from "../types.js";
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.js";
 
-/**
- * Resolve the collect function for a handle.
- * Handle objects are plain { __brand, $$id } - collect is stored in the registry
- * (populated when createHandle runs on the client).
- */
-function resolveCollect<T, A>(handle: Handle<T, A>): (segments: T[][]) => A {
-  // Look up collect from the registry (populated when the handle module is imported).
-  const registered = getCollectFn(handle.$$id);
-  if (registered) {
-    return registered as (segments: T[][]) => A;
-  }
-
-  // Fall back to default flat collect with a dev warning.
-  if (process.env.NODE_ENV !== "production") {
-    console.warn(
-      `[rsc-router] Handle "${handle.$$id}" was passed as a prop but its collect ` +
-        `function could not be resolved. Falling back to flat array. ` +
-        `Import the handle module in a client component to register its collect function.`,
-    );
-  }
-  return ((segments: unknown[][]) => segments.flat()) as unknown as (
-    segments: T[][],
-  ) => A;
-}
-
-/**
- * Collect handle data from segments and transform to final value.
- */
-function collectHandle<T, A>(
-  handle: Handle<T, A>,
-  data: HandleData,
-  segmentOrder: string[],
-): A {
-  const collect = resolveCollect(handle);
-  const segmentData = data[handle.$$id];
-
-  if (!segmentData) {
-    return collect([]);
-  }
-
-  // Build array of segment arrays in parent -> child order
-  const segmentArrays: T[][] = [];
-  for (const segmentId of segmentOrder) {
-    const entries = segmentData[segmentId];
-    if (entries && entries.length > 0) {
-      segmentArrays.push(entries as T[]);
-    }
-  }
-
-  // Call collect once with all segment data
-  return collect(segmentArrays);
-}
-
 /**
  * Hook to access collected handle data.
  *
@@ -99,13 +46,13 @@ export function useHandle<T, A, S>(
   // Initial state from context event controller, or empty fallback without provider.
   const [value, setValue] = useState<A | S>(() => {
     if (!ctx) {
-      const collected = collectHandle(handle, {}, []);
+      const collected = collectHandleData(handle, {}, []);
       return selector ? selector(collected) : collected;
     }
 
     // On client, use event controller state
     const state = ctx.eventController.getHandleState();
-    const collected = collectHandle(handle, state.data, state.segmentOrder);
+    const collected = collectHandleData(handle, state.data, state.segmentOrder);
     return selector ? selector(collected) : collected;
   });
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
@@ -125,7 +72,7 @@ export function useHandle<T, A, S>(
     // Sync current state for the (possibly new) handle so that switching
     // handles on an idle page doesn't leave stale data from the old handle.
     const currentHandleState = ctx.eventController.getHandleState();
-    const currentCollected = collectHandle(
+    const currentCollected = collectHandleData(
       handle,
       currentHandleState.data,
       currentHandleState.segmentOrder,
@@ -142,7 +89,11 @@ export function useHandle<T, A, S>(
       const state = ctx.eventController.getHandleState();
       const isAction =
         ctx.eventController.getState().inflightActions.length > 0;
-      const collected = collectHandle(handle, state.data, state.segmentOrder);
+      const collected = collectHandleData(
+        handle,
+        state.data,
+        state.segmentOrder,
+      );
       const nextValue = selectorRef.current
         ? selectorRef.current(collected)
         : collected;

package/src/handle.ts

@@ -133,3 +133,43 @@ export function isHandle(value: unknown): value is Handle<unknown, unknown> {
     (value as { __brand: unknown }).__brand === "handle"
   );
 }
+
+/**
+ * Collect handle data from a HandleData map, applying the handle's collect
+ * function over segments in order. Shared between server-side rendered()
+ * reads and client-side useHandle().
+ *
+ * @param handle - The handle to collect data for
+ * @param data - Full handle data map (handleName -> segmentId -> entries[])
+ * @param segmentOrder - Segment IDs in parent -> child resolution order
+ */
+export function collectHandleData<TData, TAccumulated>(
+  handle: Handle<TData, TAccumulated>,
+  data: Record<string, Record<string, unknown[]>>,
+  segmentOrder: string[],
+): TAccumulated {
+  const collectFn = getCollectFn(handle.$$id);
+  if (!collectFn && process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[rsc-router] Handle "${handle.$$id}" has no registered collect function. ` +
+        `Falling back to flat array. Ensure the handle module is imported so ` +
+        `createHandle() runs and registers the collect function.`,
+    );
+  }
+  const collect = (collectFn ??
+    (defaultCollect as unknown as (segments: unknown[][]) => unknown)) as (
+    segments: TData[][],
+  ) => TAccumulated;
+
+  const segmentData = data[handle.$$id];
+  if (!segmentData) return collect([]);
+
+  const segmentArrays: TData[][] = [];
+  for (const segmentId of segmentOrder) {
+    const entries = segmentData[segmentId];
+    if (entries && entries.length > 0) {
+      segmentArrays.push(entries as TData[]);
+    }
+  }
+  return collect(segmentArrays);
+}

package/src/router/loader-resolution.ts

@@ -20,10 +20,11 @@ import type {
   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 type { HandleStore, HandleData } 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 { debugLog } from "./logging.js";
 
 /**
@@ -243,6 +244,15 @@ function createLoaderExecutor<TEnv>(
 
     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
@@ -259,14 +269,74 @@ function createLoaderExecutor<TEnv>(
       env: ctx.env,
       get: ((keyOrVar: any) =>
         contextGet(variables, keyOrVar)) as typeof ctx.get,
-      use: <TDep, TDepParams = any>(
-        dep: LoaderDefinition<TDep, TDepParams>,
-      ): Promise<TDep> => {
-        return useLoader(dep, currentLoaderId);
-      },
+      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 ?? [];
+          const snapshot = 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().`,
+          );
+        }
+
+        // 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;
+
+        if (!reqCtx) {
+          throw new Error(
+            `ctx.rendered() failed: request context not available.`,
+          );
+        }
+
+        // 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);
+
+        renderedPromise = reqCtx._renderBarrier.then(() => {
+          renderedResolved = true;
+        });
+        return renderedPromise;
+      },
     };
 
     const doneLoader = track(`loader:${loader.$$id}`, 2);
@@ -284,6 +354,25 @@ function createLoaderExecutor<TEnv>(
   return useLoader;
 }
 
+/**
+ * Build a HandleData snapshot from the HandleStore using segment ordering.
+ * Reads data directly from the store for each segment in order.
+ */
+function buildHandleSnapshot(
+  handleStore: HandleStore,
+  segmentOrder: string[],
+): HandleData {
+  const data: HandleData = {};
+  for (const segmentId of segmentOrder) {
+    const segData = handleStore.getDataForSegment(segmentId);
+    for (const handleName in segData) {
+      if (!data[handleName]) data[handleName] = {};
+      data[handleName][segmentId] = segData[handleName];
+    }
+  }
+  return data;
+}
+
 /**
  * Set up the use() method on handler context to access loaders and handles.
  *
@@ -334,7 +423,23 @@ export function setupLoaderAccess<TEnv>(
       };
     }
 
-    return useLoader(item as LoaderDefinition<any, any>, null);
+    // Deadlock guard: if a HANDLER awaits a loader that called rendered(),
+    // the handler blocks segment resolution which blocks the barrier.
+    // Skip this check when inside a DSL loader scope (resolveLoaderData
+    // also calls ctx.use() but that's DSL-to-DSL, not handler-to-loader).
+    const loader = item as LoaderDefinition<any, any>;
+    if (loaderPromises.has(loader.$$id) && !isInsideLoaderScope()) {
+      const reqCtx = _getRequestContext();
+      if (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.`,
+        );
+      }
+    }
+
+    return useLoader(loader, null);
   }) as typeof ctx.use;
 }
 

package/src/router/match-middleware/cache-lookup.ts

@@ -96,6 +96,7 @@ import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
 import { pushRevalidationTraceEntry, isTraceActive } from "../logging.js";
+import { treeHasStreaming } from "./segment-resolution.js";
 import type { PrerenderStore, PrerenderEntry } from "../../prerender/store.js";
 import type { HandleStore } from "../../server/handle-store.js";
 import {
@@ -193,6 +194,14 @@ async function* yieldFromStore<TEnv>(
   state.cachedSegments = segments;
   state.cachedMatchedIds = segments.map((s) => s.id);
 
+  // Set streaming flag and resolve render barrier.
+  const reqCtx = handleStoreRef ? undefined : _lazyGetRequestContext?.();
+  const barrierReqCtx = reqCtx ?? _getRequestContext();
+  if (barrierReqCtx) {
+    barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+    barrierReqCtx._resolveRenderBarrier(segments);
+  }
+
   // For partial navigation, nullify components the client already has
   // so parent layouts stay live (client keeps its existing versions).
   // When params changed (e.g., different guide slug), the segments have
@@ -614,6 +623,13 @@ export function withCacheLookup<TEnv>(
       yield segment;
     }
 
+    // Set streaming flag and resolve render barrier.
+    const barrierReqCtx = _getRequestContext();
+    if (barrierReqCtx) {
+      barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+      barrierReqCtx._resolveRenderBarrier(cacheResult.segments);
+    }
+
     // Resolve loaders fresh (loaders are NOT cached by default)
     // This ensures fresh data even on cache hit
     const Store = ctx.Store;

package/src/router/match-middleware/segment-resolution.ts

@@ -87,10 +87,49 @@
  *   if (state.cacheHit) return;   // Now we can check
  */
 import type { ResolvedSegment } from "../../types.js";
+import type { EntryData } from "../../server/context.js";
+import { _getRequestContext } from "../../server/request-context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 
+/**
+ * Check whether any entry in the tree uses loading() (streaming).
+ * Matches the router's streaming semantics in fresh.ts: streaming is
+ * enabled when `loading` is defined AND not `false`. `loading: false`
+ * explicitly disables streaming; `undefined` means no loading at all.
+ */
+export function treeHasStreaming(entries: EntryData[]): boolean {
+  for (const entry of entries) {
+    if (
+      "loading" in entry &&
+      entry.loading !== undefined &&
+      entry.loading !== false
+    )
+      return true;
+    if (entry.layout) {
+      if (treeHasStreaming(entry.layout)) return true;
+    }
+    if (entry.parallel) {
+      for (const key in entry.parallel) {
+        const parallelEntry = entry.parallel[key as `@${string}`];
+        if (parallelEntry) {
+          if (
+            "loading" in parallelEntry &&
+            parallelEntry.loading !== undefined &&
+            parallelEntry.loading !== false
+          )
+            return true;
+          if (parallelEntry.layout) {
+            if (treeHasStreaming(parallelEntry.layout)) return true;
+          }
+        }
+      }
+    }
+  }
+  return false;
+}
+
 /**
  * Creates segment resolution middleware
  *
@@ -116,6 +155,7 @@ export function withSegmentResolution<TEnv>(
     const ownStart = performance.now();
 
     // If cache hit, segments were already yielded by cache lookup
+    // (render barrier is resolved on the cache-hit path)
     if (state.cacheHit) {
       if (ms) {
         ms.metrics.push({
@@ -127,6 +167,11 @@ export function withSegmentResolution<TEnv>(
       return;
     }
 
+    const reqCtx = _getRequestContext();
+    if (reqCtx) {
+      reqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+    }
+
     const { resolveAllSegmentsWithRevalidation, resolveAllSegments } =
       getRouterContext<TEnv>();
 
@@ -148,6 +193,10 @@ export function withSegmentResolution<TEnv>(
       state.segments = segments;
       state.matchedIds = segments.map((s: { id: string }) => s.id);
 
+      if (reqCtx) {
+        reqCtx._resolveRenderBarrier(segments);
+      }
+
       // Yield all resolved segments
       for (const segment of segments) {
         yield segment;
@@ -178,6 +227,10 @@ export function withSegmentResolution<TEnv>(
       state.segments = result.segments;
       state.matchedIds = result.matchedIds;
 
+      if (reqCtx) {
+        reqCtx._resolveRenderBarrier(result.segments);
+      }
+
       // Yield all resolved segments
       for (const segment of result.segments) {
         yield segment;

package/src/router/prerender-match.ts

@@ -216,6 +216,8 @@ export async function matchForPrerender<TEnv = any>(
       _onResponseCallbacks: [],
       setLocationState() {},
       _locationState: undefined,
+      _renderBarrier: Promise.resolve(),
+      _resolveRenderBarrier: () => {},
       _reportedErrors: new WeakSet<object>(),
       reverse: createReverseFunction(
         deps.mergedRouteMap,
@@ -450,6 +452,8 @@ export async function renderStaticSegment<TEnv = any>(
     _onResponseCallbacks: [],
     setLocationState() {},
     _locationState: undefined,
+    _renderBarrier: Promise.resolve(),
+    _resolveRenderBarrier: () => {},
     _reportedErrors: new WeakSet<object>(),
     reverse: createReverseFunction(
       mergedRouteMap,

package/src/router/segment-resolution/fresh.ts

@@ -709,18 +709,28 @@ export async function resolveLoadersOnly<TEnv>(
     const childBelongsToRoute = belongsToRoute || entry.type === "route";
     for (const layoutEntry of entry.layout) {
       await collectEntryLoaders(layoutEntry, childBelongsToRoute);
-      // Inherit route loaders for orphan layouts with parallels
+      // Inherit route loaders for orphan layouts with parallels.
+      // Resolve directly — do NOT re-enter collectEntryLoaders with the
+      // route entry, as that would re-iterate route.layout and loop.
       if (
         entry.type === "route" &&
         entry.loader &&
         entry.loader.length > 0 &&
         Object.keys(layoutEntry.parallel).length > 0
       ) {
-        await collectEntryLoaders(
+        const inherited = await resolveLoaders(
           entry,
+          context,
           childBelongsToRoute,
+          deps,
           layoutEntry.shortCode,
         );
+        for (const seg of inherited) {
+          if (!seenIds.has(seg.id)) {
+            seenIds.add(seg.id);
+            loaderSegments.push(seg);
+          }
+        }
       }
     }
   }

package/src/router/segment-resolution/revalidation.ts

@@ -319,18 +319,37 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
     const childBelongsToRoute = belongsToRoute || entry.type === "route";
     for (const layoutEntry of entry.layout) {
       await collectEntryLoaders(layoutEntry, childBelongsToRoute);
-      // Inherit route loaders for orphan layouts with parallels
+      // Inherit route loaders for orphan layouts with parallels.
+      // Resolve directly — do NOT re-enter collectEntryLoaders with the
+      // route entry, as that would re-iterate route.layout and loop.
       if (
         entry.type === "route" &&
         entry.loader &&
         entry.loader.length > 0 &&
         Object.keys(layoutEntry.parallel).length > 0
       ) {
-        await collectEntryLoaders(
+        const inherited = await resolveLoadersWithRevalidation(
           entry,
+          context,
           childBelongsToRoute,
+          clientSegmentIds,
+          prevParams,
+          request,
+          prevUrl,
+          nextUrl,
+          routeKey,
+          deps,
+          actionContext,
           layoutEntry.shortCode,
+          stale,
         );
+        for (const seg of inherited.segments) {
+          if (!seenIds.has(seg.id)) {
+            seenIds.add(seg.id);
+            allLoaderSegments.push(seg);
+          }
+        }
+        allMatchedIds.push(...inherited.matchedIds);
       }
     }
   }

package/src/server/context.ts

@@ -698,6 +698,15 @@ export function isInsideCacheScope(): boolean {
   return true;
 }
 
+/**
+ * Check if the current execution is inside a DSL loader scope
+ * (wrapped by runInsideLoaderScope). Used by rendered() barrier
+ * to distinguish DSL loaders from handler-invoked loaders.
+ */
+export function isInsideLoaderScope(): boolean {
+  return loaderScopeALS.getStore()?.active === true;
+}
+
 /**
  * Run `fn` inside a loader scope. While active, cache-scope guards
  * are bypassed because loaders are always fresh (never cached) and

package/src/server/request-context.ts

@@ -271,6 +271,41 @@ 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 Per-request error dedup set for onError reporting */
   _reportedErrors: WeakSet<object>;
 
@@ -322,6 +357,11 @@ export type PublicRequestContext<
   | "_routeName"
   | "_prevRouteKey"
   | "_reportedErrors"
+  | "_renderBarrier"
+  | "_resolveRenderBarrier"
+  | "_renderBarrierSegmentOrder"
+  | "_treeHasStreaming"
+  | "_renderBarrierWaiters"
   | "_reportBackgroundError"
   | "_debugPerformance"
   | "_metricsStore"
@@ -750,9 +790,50 @@ 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;
+    ctx._renderBarrierSegmentOrder = segments
+      .filter((s) => s.type !== "loader")
+      .map((s) => s.id);
+    ctx._renderBarrierWaiters = 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,
@@ -936,12 +1017,12 @@ export function createUseFunction<TEnv>(
       url: ctx.url,
       env: ctx.env 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(
@@ -950,6 +1031,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/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";
@@ -57,11 +58,38 @@ export type LoaderContext<
     <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", ... })

package/src/vite/plugins/expose-ids/handler-transform.ts

@@ -138,6 +138,36 @@ export function generateExprStubs(
   };
 }
 
+/**
+ * Replace handler call expressions with lightweight stub objects on an
+ * existing MagicString. Unlike generateExprStubs (which creates its own
+ * MagicString and returns the full result), this integrates into the
+ * unified transform pipeline so all transforms share one sourcemap.
+ */
+export function stubHandlerExprs(
+  cfg: HandlerTransformConfig,
+  bindings: CreateExportBinding[],
+  s: MagicString,
+  filePath: string,
+  isBuild: boolean,
+): boolean {
+  let hasChanges = false;
+  for (const binding of bindings) {
+    const exportName = binding.exportNames[0];
+    const handlerId = isBuild
+      ? hashId(filePath, exportName)
+      : `${filePath}#${exportName}`;
+
+    s.overwrite(
+      binding.callExprStart,
+      binding.callCloseParenPos + 1,
+      `{ __brand: "${cfg.brand}", $$id: "${handlerId}" }`,
+    );
+    hasChanges = true;
+  }
+  return hasChanges;
+}
+
 /**
  * Inject $$id into export const handler calls in RSC environments.
  */

package/src/vite/plugins/expose-internal-ids.ts

@@ -34,6 +34,7 @@ import {
   transformLocationState,
   generateWholeFileStubs,
   generateExprStubs,
+  stubHandlerExprs,
   transformHandlerIds,
 } from "./expose-ids/handler-transform.js";
 
@@ -385,7 +386,9 @@ ${lazyImports.join(",\n")}
         if (stubResult) return stubResult;
       }
 
-      // --- PrerenderHandler: non-RSC stub replacement ---
+      // --- PrerenderHandler: non-RSC whole-file stub replacement ---
+      // When ALL exports are Prerender() calls, replace the entire file.
+      // Mixed-export files are handled in the unified pipeline below.
       if (hasPrerenderHandlerCode && !isRscEnv) {
         const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
         const bindings = getBindings(code, fnNames);
@@ -397,16 +400,6 @@ ${lazyImports.join(",\n")}
           isBuild,
         );
         if (wholeFile) return wholeFile;
-
-        const exprStubs = generateExprStubs(
-          PRERENDER_CONFIG,
-          bindings,
-          code,
-          filePath,
-          id,
-          isBuild,
-        );
-        if (exprStubs) return exprStubs;
       }
 
       // --- PrerenderHandler: RSC build module tracking ---
@@ -467,7 +460,9 @@ ${lazyImports.join(",\n")}
         }
       }
 
-      // --- StaticHandler: non-RSC stub replacement ---
+      // --- StaticHandler: non-RSC whole-file stub replacement ---
+      // When ALL exports are Static() calls, replace the entire file.
+      // Mixed-export files are handled in the unified pipeline below.
       if (hasStaticHandlerCode && !isRscEnv) {
         const fnNames = getFnNames(STATIC_CONFIG.fnName);
         const bindings = getBindings(code, fnNames);
@@ -479,16 +474,6 @@ ${lazyImports.join(",\n")}
           isBuild,
         );
         if (wholeFile) return wholeFile;
-
-        const exprStubs = generateExprStubs(
-          STATIC_CONFIG,
-          bindings,
-          code,
-          filePath,
-          id,
-          isBuild,
-        );
-        if (exprStubs) return exprStubs;
       }
 
       // --- StaticHandler: RSC build module tracking ---
@@ -535,27 +520,48 @@ ${lazyImports.join(",\n")}
             isBuild,
           ) || changed;
       }
-      if (hasPrerenderHandlerCode && isRscEnv) {
+      if (hasPrerenderHandlerCode) {
         const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
-        changed =
-          transformHandlerIds(
-            PRERENDER_CONFIG,
-            getBindings(code, fnNames),
-            s,
-            filePath,
-            isBuild,
-          ) || changed;
+        const bindings = getBindings(code, fnNames);
+        if (isRscEnv) {
+          changed =
+            transformHandlerIds(
+              PRERENDER_CONFIG,
+              bindings,
+              s,
+              filePath,
+              isBuild,
+            ) || changed;
+        } else {
+          // Non-RSC mixed-export file: replace Prerender() calls with stubs
+          // on the shared MagicString so sourcemaps stay accurate.
+          changed =
+            stubHandlerExprs(
+              PRERENDER_CONFIG,
+              bindings,
+              s,
+              filePath,
+              isBuild,
+            ) || changed;
+        }
       }
-      if (hasStaticHandlerCode && isRscEnv) {
+      if (hasStaticHandlerCode) {
         const fnNames = getFnNames(STATIC_CONFIG.fnName);
-        changed =
-          transformHandlerIds(
-            STATIC_CONFIG,
-            getBindings(code, fnNames),
-            s,
-            filePath,
-            isBuild,
-          ) || changed;
+        const bindings = getBindings(code, fnNames);
+        if (isRscEnv) {
+          changed =
+            transformHandlerIds(
+              STATIC_CONFIG,
+              bindings,
+              s,
+              filePath,
+              isBuild,
+            ) || changed;
+        } else {
+          changed =
+            stubHandlerExprs(STATIC_CONFIG, bindings, s, filePath, isBuild) ||
+            changed;
+        }
       }
 
       if (!changed) return;

package/src/vite/router-discovery.ts

@@ -480,9 +480,31 @@ export function createRouterDiscoveryPlugin(
           return;
         }
 
-        // Prefer the main server's registry (Node.js preset: module runner available).
-        // Fall back to a temp server for Cloudflare where the main RSC env uses workerd.
-        let registry = mainRegistry;
+        // Import the user's entry module to force re-evaluation of any
+        // HMR-invalidated modules in the chain (entry → router → urls → handlers).
+        // This ensures createRouter() re-runs with updated handler code before
+        // we read RouterRegistry. Without this, edits to prerender handler files
+        // produce stale content because the old router instance remains registered.
+        const rscEnv = (server.environments as any)?.rsc;
+        let registry: Map<string, any> | null = null;
+        if (rscEnv?.runner && s.resolvedEntryPath) {
+          try {
+            await rscEnv.runner.import(s.resolvedEntryPath);
+            const serverMod = await rscEnv.runner.import(
+              "@rangojs/router/server",
+            );
+            registry = serverMod.RouterRegistry ?? null;
+          } catch (err: any) {
+            console.warn(
+              `[rsc-router] Dev prerender module refresh failed: ${err.message}`,
+            );
+            res.statusCode = 500;
+            res.end(`Prerender handler error: ${err.message}`);
+            return;
+          }
+        } else {
+          registry = mainRegistry;
+        }
 
         if (!registry) {
           // No main registry: the RSC env has no module runner (Cloudflare dev).