@rangojs/router 0.0.0-experimental.19 → 0.0.0-experimental.1fa245e2

package/src/segment-system.tsx

@@ -20,6 +20,61 @@ import { RootErrorBoundary } from "./root-error-boundary.js";
 const ReactViewTransition: any =
   "ViewTransition" in React ? (React as any).ViewTransition : null;
 
+function restoreParallelLoaderMarkers(
+  segments: ResolvedSegment[],
+): ResolvedSegment[] {
+  const parallelLoadingByNamespace = new Map<string, ReactNode>();
+  let nextSegments: ResolvedSegment[] | null = null;
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+
+    if (segment.type === "parallel") {
+      if (
+        segment.namespace &&
+        segment.loading !== undefined &&
+        segment.loading !== null &&
+        segment.loading !== false
+      ) {
+        parallelLoadingByNamespace.set(segment.namespace, segment.loading);
+      }
+      continue;
+    }
+
+    if (segment.type !== "loader" || segment.parallelLoading !== undefined) {
+      continue;
+    }
+
+    const parallelLoading = segment.namespace
+      ? parallelLoadingByNamespace.get(segment.namespace)
+      : undefined;
+    if (parallelLoading === undefined) {
+      continue;
+    }
+
+    if (!nextSegments) {
+      nextSegments = segments.slice();
+    }
+    nextSegments[i] = { ...segment, parallelLoading };
+  }
+
+  return nextSegments ?? segments;
+}
+
+function hasSameReferences(a: unknown[] | undefined, b: unknown[]): boolean {
+  if (!a || a.length !== b.length) {
+    return false;
+  }
+
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
 /**
  * Resolve loader data from raw results, unwrapping LoaderDataResult wrappers
  */
@@ -143,6 +198,10 @@ export async function renderSegments(
   } = options || {};
 
   const temporalLazyRefs: Promise<any>[] = [];
+  const normalizedSegments = restoreParallelLoaderMarkers(segments);
+  const normalizedInterceptSegments = interceptSegments
+    ? restoreParallelLoaderMarkers(interceptSegments)
+    : undefined;
 
   /**
    * Registers promises from lazy/async components for awaiting.
@@ -167,7 +226,7 @@ export async function renderSegments(
     );
   }
   // Separate segments by type, passing intercept segments for explicit injection
-  const tree = segmentTreeWalk(segments, interceptSegments);
+  const tree = segmentTreeWalk(normalizedSegments, normalizedInterceptSegments);
   // Render content segments as siblings
   let content: ReactNode = null;
   for (const node of tree) {
@@ -284,13 +343,90 @@ export async function renderSegments(
         children: nodeContent,
       });
     } else {
-      // Has loaders but no loading skeleton - await loaders and render directly
-      const resolvedData = await loaderDataPromise;
+      // Has loaders but no loading skeleton.
+      // Split: parallel-owned loaders stream (their parallel has loading()),
+      // layout-owned loaders are awaited (they gate the layout content).
+      const layoutLoaders = loaderEntries.filter((l) => !l.parallelLoading);
+      const parallelOwnedLoaders = loaderEntries.filter(
+        (l) => !!l.parallelLoading,
+      );
+
+      // Await only layout-owned loaders
+      const layoutLoaderIds = layoutLoaders.map((l) => l.loaderId!);
+      const layoutLoaderDataPromise =
+        layoutLoaders.length > 0
+          ? Promise.all(
+              layoutLoaders.map((l) =>
+                l.loaderData instanceof Promise
+                  ? l.loaderData
+                  : Promise.resolve(l.loaderData),
+              ),
+            )
+          : Promise.resolve([]);
+      const resolvedData = await layoutLoaderDataPromise;
       const { loaderData, errorFallback } = resolveLoaderData(
         resolvedData,
-        loaderIds,
+        layoutLoaderIds,
       );
 
+      // Parallel-owned loaders: attach to their owning parallel segment
+      // as loaderDataPromise so ParallelOutlet wraps in LoaderBoundary
+      if (parallelOwnedLoaders.length > 0) {
+        const loadersByParallelNamespace = new Map<string, ResolvedSegment[]>();
+
+        for (const loader of parallelOwnedLoaders) {
+          if (!loader.namespace) {
+            continue;
+          }
+          const existing = loadersByParallelNamespace.get(loader.namespace);
+          if (existing) {
+            existing.push(loader);
+          } else {
+            loadersByParallelNamespace.set(loader.namespace, [loader]);
+          }
+        }
+
+        for (const p of node.parallel) {
+          if (!p.loading || !p.namespace) {
+            continue;
+          }
+
+          const ownedLoaders = loadersByParallelNamespace.get(p.namespace);
+          if (!ownedLoaders || ownedLoaders.length === 0) {
+            continue;
+          }
+
+          const parallelLoaderIds = ownedLoaders.map((l) => l.loaderId!);
+          const parallelLoaderSources = ownedLoaders.map((l) => l.loaderData);
+          p.loaderIds = parallelLoaderIds;
+
+          const shouldReuseParallelPromise =
+            p.loaderDataPromise !== undefined &&
+            hasSameReferences(p.parallelLoaderSources, parallelLoaderSources);
+
+          const parallelLoaderDataPromise = shouldReuseParallelPromise
+            ? p.loaderDataPromise
+            : forceAwait || isAction
+              ? await Promise.all(
+                  ownedLoaders.map((l) =>
+                    l.loaderData instanceof Promise
+                      ? l.loaderData
+                      : Promise.resolve(l.loaderData),
+                  ),
+                )
+              : Promise.all(
+                  ownedLoaders.map((l) =>
+                    l.loaderData instanceof Promise
+                      ? l.loaderData
+                      : Promise.resolve(l.loaderData),
+                  ),
+                );
+
+          p.loaderDataPromise = parallelLoaderDataPromise;
+          p.parallelLoaderSources = parallelLoaderSources;
+        }
+      }
+
       content = createElement(OutletProvider, {
         key,
         content: outletContent,

package/src/server/context.ts

@@ -26,6 +26,7 @@ export interface PerformanceMetric {
   label: string; // e.g., "route-matching", "loader:UserLoader"
   duration: number; // milliseconds
   startTime: number; // relative to request start
+  depth?: number; // nesting level for hierarchical display (0 = top-level)
 }
 
 /**
@@ -156,10 +157,24 @@ export type InterceptEntry = {
   when: InterceptWhenFn[]; // Selector conditions - all must return true to intercept
 };
 
+export interface ParallelEntryData
+  extends EntryPropCommon, EntryPropDatas, EntryPropSegments {
+  type: "parallel";
+  handler: Record<`@${string}`, Handler<any, any, any> | ReactNode>;
+  loading?: ReactNode | false;
+  transition?: TransitionConfig;
+  /** Set when any parallel slot is a Static definition */
+  isStaticPrerender?: true;
+  /** Per-slot static handler $$ids for build-time store lookup */
+  staticHandlerIds?: Record<string, string>;
+}
+
+export type ParallelEntries = Partial<Record<`@${string}`, ParallelEntryData>>;
+
 export type EntryPropSegments = {
   loader: LoaderEntry[];
   layout: EntryData[];
-  parallel: EntryData[]; // type: "parallel" entries with their own loaders/revalidate/loading
+  parallel: ParallelEntries; // slot -> parallel entry (same entry may back multiple slots)
   intercept: InterceptEntry[]; // intercept definitions for soft navigation
 };
 
@@ -176,8 +191,12 @@ export type EntryData =
       /** Original PrerenderHandlerDefinition (for build-time getParams access) */
       prerenderDef?: {
         getParams?: (ctx: any) => Promise<any[]> | any[];
-        options?: { passthrough?: boolean };
+        options?: { concurrency?: number };
       };
+      /** Set when route is wrapped with Passthrough() — has a separate live handler */
+      isPassthrough?: true;
+      /** Live handler for runtime fallback (only set on Passthrough routes) */
+      liveHandler?: Handler<any, any, any>;
       /** Set when handler is a Static definition (build-time only) */
       isStaticPrerender?: true;
       /** Static handler $$id for build-time store lookup */
@@ -199,18 +218,7 @@ export type EntryData =
     } & EntryPropCommon &
       EntryPropDatas &
       EntryPropSegments)
-  | ({
-      type: "parallel";
-      handler: Record<`@${string}`, Handler<any, any, any> | ReactNode>;
-      loading?: ReactNode | false;
-      transition?: TransitionConfig;
-      /** Set when any parallel slot is a Static definition */
-      isStaticPrerender?: true;
-      /** Per-slot static handler $$ids for build-time store lookup */
-      staticHandlerIds?: Record<string, string>;
-    } & EntryPropCommon &
-      EntryPropDatas &
-      EntryPropSegments)
+  | ParallelEntryData
   | ({
       type: "cache";
       /** Cache entries create cache boundaries and render like layouts (with Outlet) */
@@ -269,6 +277,9 @@ interface HelperContext {
     string,
     import("../cache/profile-registry.js").CacheProfile
   >;
+  /** True when resolving handlers inside a cache() DSL boundary.
+   *  Read by ctx.get() to guard non-cacheable variable reads. */
+  insideCacheScope?: boolean;
 }
 // Use a global symbol key so the AsyncLocalStorage instance survives HMR
 // module re-evaluation. Without this, Vite's RSC module runner may create
@@ -552,6 +563,80 @@ export function getRootScoped(): boolean {
 // Export HelperContext type for use in other modules
 export type { HelperContext };
 
+/**
+ * Return an isolated copy of a lazy include's captured parent entry.
+ *
+ * DSL helpers (loader(), middleware(), etc.) mutate ctx.parent in place.
+ * Multiple include() scopes capture the *same* syntheticMapRoot as their
+ * parent, so without isolation one include's loaders/middleware leak into
+ * every other route that shares that root.
+ *
+ * The clone is shallow: only the mutable arrays are copied so each
+ * include pushes to its own list. The rest of the entry (id, shortCode,
+ * parent pointer, handler) stays shared, which is correct and cheap.
+ */
+export function getIsolatedLazyParent(
+  captured: EntryData | null | undefined,
+): EntryData | null {
+  if (!captured) return null;
+  return {
+    ...captured,
+    loader: [...captured.loader],
+    middleware: [...captured.middleware],
+    revalidate: [...captured.revalidate],
+    errorBoundary: [...captured.errorBoundary],
+    notFoundBoundary: [...captured.notFoundBoundary],
+    layout: [...captured.layout],
+    parallel: { ...captured.parallel },
+    intercept: [...captured.intercept],
+  };
+}
+
+export function getParallelEntries(
+  parallels: ParallelEntries | EntryData[] | undefined,
+): ParallelEntryData[] {
+  if (!parallels) return [];
+  if (Array.isArray(parallels)) {
+    return parallels.filter(
+      (entry): entry is ParallelEntryData => entry.type === "parallel",
+    );
+  }
+  return Object.values(parallels).filter(
+    (entry): entry is ParallelEntryData => !!entry,
+  );
+}
+
+export function getParallelSlotEntries(
+  parallels: ParallelEntries | EntryData[] | undefined,
+): Array<{ slot: `@${string}`; entry: ParallelEntryData }> {
+  if (!parallels) return [];
+
+  if (Array.isArray(parallels)) {
+    return getParallelEntries(parallels).flatMap((entry) =>
+      (Object.keys(entry.handler) as `@${string}`[]).map((slot) => ({
+        slot,
+        entry,
+      })),
+    );
+  }
+
+  return Object.entries(parallels)
+    .filter(([, entry]) => !!entry)
+    .map(([slot, entry]) => ({
+      slot: slot as `@${string}`,
+      entry: entry!,
+    }));
+}
+
+export function getParallelSlotCount(
+  parallels: ParallelEntries | EntryData[] | undefined,
+): number {
+  if (!parallels) return 0;
+  return Array.isArray(parallels)
+    ? parallels.filter((entry) => entry?.type === "parallel").length
+    : Object.keys(parallels).length;
+}
+
 // ============================================================================
 //  Performance Metrics Helpers
 // ============================================================================
@@ -567,7 +652,7 @@ export type { HelperContext };
  * done(); // Records duration
  * ```
  */
-export function track(label: string): () => void {
+export function track(label: string, depth?: number): () => void {
   const store = RSCRouterContext.getStore();
 
   // No-op if context unavailable or metrics not enabled
@@ -580,6 +665,53 @@ export function track(label: string): () => void {
   return () => {
     const duration =
       performance.now() - store.metrics!.requestStart - startTime;
-    store.metrics!.metrics.push({ label, duration, startTime });
+    store.metrics!.metrics.push({
+      label,
+      duration,
+      startTime,
+      ...(depth != null ? { depth } : {}),
+    });
   };
 }
+
+/**
+ * Separate ALS for tracking loader execution scope.
+ * Uses a dedicated ALS (not RSCRouterContext) to avoid issues with
+ * nested RSCRouterContext.run() calls in Vite's module runner.
+ */
+const LOADER_SCOPE_KEY = Symbol.for("rangojs-router:loader-scope");
+const loaderScopeALS: AsyncLocalStorage<{ active: true }> = ((
+  globalThis as any
+)[LOADER_SCOPE_KEY] ??= new AsyncLocalStorage<{ active: true }>());
+
+/**
+ * Check if the current execution is inside a cache() DSL boundary.
+ * Returns false inside loader execution — loaders are always fresh
+ * (never cached), so non-cacheable reads are safe.
+ */
+export function isInsideCacheScope(): boolean {
+  if (RSCRouterContext.getStore()?.insideCacheScope !== true) return false;
+  // Loaders are always fresh — even inside a cache() boundary, the loader
+  // function re-executes on every request. Skip the guard when running
+  // inside a loader.
+  if (loaderScopeALS.getStore()?.active) return false;
+  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
+ * their side effects (setCookie, header, etc.) are safe.
+ */
+export function runInsideLoaderScope<T>(fn: () => T): T {
+  return loaderScopeALS.run({ active: true }, fn);
+}

package/src/server/loader-registry.ts

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