@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

package/src/router/loader-resolution.ts

@@ -7,6 +7,7 @@
 import type { ReactNode } from "react";
 import { track } from "../server/context";
 import type { EntryData } from "../server/context";
+import { contextGet } from "../context-var.js";
 import type {
   ResolvedSegment,
   HandlerContext,
@@ -241,16 +242,23 @@ function createLoaderExecutor<TEnv>(
     pendingLoaders.add(loader.$$id);
 
     const currentLoaderId = loader.$$id;
+    const variables = (ctx as InternalHandlerContext<any, TEnv>)._variables;
+    // 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
+    // function itself always re-executes. Also handles nested deps
+    // (loaderA → use(loaderB)) since all share this unguarded get.
     const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
       params: ctx.params,
+      routeParams: (ctx.params ?? {}) as Record<string, string>,
       request: ctx.request,
       searchParams: ctx.searchParams,
       search: (ctx as any).search,
       pathname: ctx.pathname,
       url: ctx.url,
       env: ctx.env,
-      var: ctx.var,
-      get: ctx.get,
+      get: ((keyOrVar: any) =>
+        contextGet(variables, keyOrVar)) as typeof ctx.get,
       use: <TDep, TDepParams = any>(
         dep: LoaderDefinition<TDep, TDepParams>,
       ): Promise<TDep> => {
@@ -261,7 +269,7 @@ function createLoaderExecutor<TEnv>(
       reverse: ctx.reverse as LoaderContext["reverse"],
     };
 
-    const doneLoader = track(`loader:${loader.$$id}`);
+    const doneLoader = track(`loader:${loader.$$id}`, 2);
     const promise = Promise.resolve(
       loaderFn(loaderCtx as LoaderContext<any, TEnv>),
     ).finally(() => {

package/src/router/logging.ts

@@ -1,10 +1,48 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 
+// -- Revalidation trace types --
+
+export interface RevalidationTraceEntry {
+  segmentId: string;
+  segmentType: string;
+  belongsToRoute: boolean;
+  source:
+    | "segment-resolution"
+    | "cache-hit"
+    | "loader"
+    | "parallel"
+    | "orphan-layout"
+    | "route-handler"
+    | "layout-handler"
+    | "intercept-loader";
+  defaultShouldRevalidate: boolean;
+  finalShouldRevalidate: boolean;
+  reason: string;
+  customRevalidators?: number;
+}
+
+export interface RevalidationTraceMeta {
+  method: string;
+  prevUrl: string;
+  nextUrl: string;
+  routeKey: string;
+  isAction: boolean;
+  stale?: boolean;
+}
+
+export interface RevalidationTrace {
+  meta: RevalidationTraceMeta;
+  entries: RevalidationTraceEntry[];
+}
+
+// -- Log context --
+
 interface RouterLogContext {
   requestId: string;
   transactionId: string;
   depth: number;
+  revalidationTrace?: RevalidationTrace;
 }
 
 interface RouterLogOptions {
@@ -36,7 +74,7 @@ function getHeaderRequestId(request: Request): string | null {
   return trimmed.length > 0 ? trimmed : null;
 }
 
-function getOrCreateRequestId(request: Request): string {
+export function getOrCreateRequestId(request: Request): string {
   const existing = requestIds.get(request);
   if (existing) return existing;
 
@@ -94,9 +132,16 @@ export function withRouterLogScope<T>(
     try {
       const result = fn();
       if (result && typeof (result as Promise<T>).then === "function") {
-        return (result as Promise<T>).finally(() => {
-          debugLog(label, "end");
-        });
+        return (result as Promise<T>).then(
+          (value) => {
+            debugLog(label, "end");
+            return value;
+          },
+          (error) => {
+            debugLog(label, "error", { error: String(error) });
+            throw error;
+          },
+        );
       }
       debugLog(label, "end");
       return result;
@@ -149,3 +194,58 @@ export function debugWarn(
 
   console.warn(`${prefix} ${message}`);
 }
+
+// -- Revalidation trace helpers --
+
+export function isTraceActive(): boolean {
+  if (!INTERNAL_RANGO_DEBUG) return false;
+  const ctx = routerLogContext.getStore();
+  return !!ctx?.revalidationTrace;
+}
+
+export function startRevalidationTrace(meta: RevalidationTraceMeta): void {
+  const ctx = routerLogContext.getStore();
+  if (!ctx || !INTERNAL_RANGO_DEBUG) return;
+  ctx.revalidationTrace = { meta, entries: [] };
+}
+
+export function pushRevalidationTraceEntry(
+  entry: RevalidationTraceEntry,
+): void {
+  const ctx = routerLogContext.getStore();
+  if (!ctx?.revalidationTrace) return;
+  ctx.revalidationTrace.entries.push(entry);
+}
+
+export function flushRevalidationTrace(): RevalidationTrace | null {
+  const ctx = routerLogContext.getStore();
+  if (!ctx?.revalidationTrace) return null;
+  const trace = ctx.revalidationTrace;
+  ctx.revalidationTrace = undefined;
+
+  if (trace.entries.length === 0) return trace;
+
+  const revalidated = trace.entries.filter((e) => e.finalShouldRevalidate);
+  const skipped = trace.entries.filter((e) => !e.finalShouldRevalidate);
+
+  debugLog("revalidation-trace", "flush", {
+    method: trace.meta.method,
+    routeKey: trace.meta.routeKey,
+    isAction: trace.meta.isAction,
+    stale: trace.meta.stale,
+    prevUrl: trace.meta.prevUrl,
+    nextUrl: trace.meta.nextUrl,
+    total: trace.entries.length,
+    revalidated: revalidated.length,
+    skipped: skipped.length,
+    entries: trace.entries.map((e) => ({
+      segmentId: e.segmentId,
+      type: e.segmentType,
+      source: e.source,
+      revalidate: e.finalShouldRevalidate,
+      reason: e.reason,
+    })),
+  });
+
+  return trace;
+}

package/src/router/manifest.ts

@@ -9,6 +9,7 @@ import { createRouteHelpers } from "../route-definition";
 import {
   getContext,
   runWithPrefixes,
+  getIsolatedLazyParent,
   type EntryData,
   type MetricsStore,
 } from "../server/context";
@@ -65,7 +66,9 @@ export async function loadManifest(
   const mountIndex = entry.mountIndex;
 
   // Check module-level cache (persists across requests within same isolate)
-  const cacheKey = `${VERSION}:${mountIndex ?? ""}:${routeKey}:${isSSR ? 1 : 0}`;
+  // Include routerId so multi-router setups (host routing) don't share cached
+  // EntryData across routers with overlapping mountIndex + routeKey combinations.
+  const cacheKey = `${VERSION}:${entry.routerId ?? ""}:${mountIndex ?? ""}:${routeKey}:${isSSR ? 1 : 0}`;
   const cached = manifestModuleCache.get(cacheKey);
   if (cached) {
     const cacheStart = performance.now();
@@ -112,8 +115,11 @@ export async function loadManifest(
     // This ensures routes are registered under the correct layout hierarchy
     const lazyContext =
       entry.lazy && entry.lazyPatterns ? entry.lazyContext : null;
-    const parentForContext =
-      (lazyContext?.parent as EntryData | null) ?? Store.parent;
+    const parentForContext = lazyContext
+      ? getIsolatedLazyParent(
+          (lazyContext.parent as EntryData | null) ?? Store.parent,
+        )
+      : Store.parent;
 
     // For lazy entries, merge captured counters from include() so the
     // handler's entries get shortCode indices after sibling entries that
@@ -127,6 +133,22 @@ export async function loadManifest(
       }
     }
 
+    // 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;
+    }
+
+    // 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;
+    }
+
     const handlerExecStart = performance.now();
     const useItems = await getContext().runWithStore(
       Store,
@@ -178,15 +200,28 @@ export async function loadManifest(
             "default" in load
           ) {
             // Promise<{ default: () => Array }> - e.g., dynamic import
-            // Lazy-loaded handlers may need helpers (passed as optional arg)
+            if (typeof load.default !== "function") {
+              throw new Error(
+                `[@rangojs/router] Unsupported async handler: { default } must be a function, ` +
+                  `got ${typeof load.default}. Use () => import('./urls') for lazy loading.`,
+              );
+            }
             return (load.default as (h?: any) => any)(helpers);
           }
           if (typeof load === "function") {
             // Promise<() => Array>
             return (load as (h?: any) => any)(helpers);
           }
-          // Promise<Array> - direct array from async handler
-          return load;
+          // Reject unsupported async handler results. Supported shapes are:
+          //   Promise<{ default: fn }> — dynamic import
+          //   Promise<fn> — lazy function
+          // Direct Promise<Array> is not supported; use a function wrapper.
+          throw new Error(
+            `[@rangojs/router] Unsupported async handler result (${typeof load}). ` +
+              `Lazy route handlers must resolve to a function or { default: fn }, ` +
+              `not a direct array. Wrap your handler: () => import('./urls') or ` +
+              `() => Promise.resolve((h) => [...])`,
+          );
         }
 
         // Inline handler - routes were registered with correct parent inside layout
@@ -213,7 +248,10 @@ export async function loadManifest(
 
     invariant(
       Store.manifest.has(routeKey),
-      `Route must be registered for ${routeKey}`,
+      `Route must be registered for ${routeKey}. ` +
+        `Registered keys: [${[...Store.manifest.keys()].join(", ")}]. ` +
+        `Entry lazy=${!!entry.lazy}, lazyContext.namePrefix=${lazyContext?.namePrefix ?? "(none)"}, ` +
+        `lazyContext.urlPrefix=${(lazyContext as any)?.urlPrefix ?? "(none)"}`,
     );
     pushMetric?.("manifest:validation", validationStart);
 

package/src/router/match-api.ts

@@ -31,7 +31,11 @@ import type { ErrorBoundaryHandler, ErrorInfo, MatchResult } from "../types";
 import type { ReactNode } from "react";
 import type { MatchContext } from "./match-context.js";
 import type { MatchApiDeps, ActionContext } from "./types.js";
-import { getRequestContext } from "../server/request-context.js";
+import {
+  getRequestContext,
+  setRequestContextPrevRouteKey,
+} from "../server/request-context.js";
+import { isAutoGeneratedRouteName } from "../route-name.js";
 import { debugLog, debugWarn } from "./logging.js";
 
 /**
@@ -87,6 +91,13 @@ export async function createMatchContextForFull<TEnv>(
     });
   }
 
+  if (
+    manifestEntry.type === "route" &&
+    manifestEntry.prerenderDef?.options?.passthrough === true
+  ) {
+    matched.pt = true;
+  }
+
   const routeMiddleware = collectRouteMiddleware(
     traverseBack(manifestEntry),
     matched.params,
@@ -105,6 +116,7 @@ export async function createMatchContextForFull<TEnv>(
     deps.getRouteMap(),
     matched.routeKey,
     matched.responseType,
+    matched.pt === true,
   );
 
   const loaderPromises = new Map<string, Promise<any>>();
@@ -161,6 +173,10 @@ export async function createMatchContextForFull<TEnv>(
       request,
       env,
       segments: { path: [], ids: [] },
+      toRouteName:
+        matched.routeKey && !isAutoGeneratedRouteName(matched.routeKey)
+          ? matched.routeKey
+          : undefined,
     },
     isSameRouteNavigation: false,
     interceptResult: null,
@@ -207,10 +223,21 @@ export async function createMatchContextForPartial<TEnv>(
     return null;
   }
 
-  const prevUrl = new URL(previousUrl, url.origin);
-  const interceptContextUrl = interceptSourceUrl
-    ? new URL(interceptSourceUrl, url.origin)
-    : prevUrl;
+  let prevUrl: URL;
+  try {
+    prevUrl = new URL(previousUrl, url.origin);
+  } catch {
+    return null;
+  }
+
+  let interceptContextUrl: URL;
+  try {
+    interceptContextUrl = interceptSourceUrl
+      ? new URL(interceptSourceUrl, url.origin)
+      : prevUrl;
+  } catch {
+    interceptContextUrl = prevUrl;
+  }
 
   const routeMatchStart = metricsStore ? performance.now() : 0;
   const prevMatch = deps.findMatch(prevUrl.pathname);
@@ -262,6 +289,13 @@ export async function createMatchContextForPartial<TEnv>(
     });
   }
 
+  if (
+    manifestEntry.type === "route" &&
+    manifestEntry.prerenderDef?.options?.passthrough === true
+  ) {
+    matched.pt = true;
+  }
+
   const routeMiddleware = collectRouteMiddleware(
     traverseBack(manifestEntry),
     matched.params,
@@ -280,6 +314,7 @@ export async function createMatchContextForPartial<TEnv>(
     deps.getRouteMap(),
     matched.routeKey,
     matched.responseType,
+    matched.pt === true,
   );
 
   const clientSegmentSet = new Set(clientSegmentIds);
@@ -325,16 +360,35 @@ export async function createMatchContextForPartial<TEnv>(
     if (/D\d+\./.test(id)) return false;
     return true;
   });
+  const effectiveFromUrl = interceptSourceUrl ? interceptContextUrl : prevUrl;
+  const effectiveFromMatch = interceptSourceUrl
+    ? interceptContextMatch
+    : prevMatch;
+
+  // Store previous route key on the request context for revalidation
+  // fromRouteName. Uses effectiveFromMatch so intercept-source navigations
+  // see the intercept origin route, not the plain previous URL route.
+  setRequestContextPrevRouteKey(effectiveFromMatch?.routeKey);
+
   const interceptSelectorContext: InterceptSelectorContext = {
-    from: prevUrl,
+    from: effectiveFromUrl,
     to: cleanUrl,
     params: matched.params,
     request,
     env,
     segments: {
-      path: prevUrl.pathname.split("/").filter(Boolean),
+      path: effectiveFromUrl.pathname.split("/").filter(Boolean),
       ids: filteredSegmentIds,
     },
+    fromRouteName:
+      effectiveFromMatch?.routeKey &&
+      !isAutoGeneratedRouteName(effectiveFromMatch.routeKey)
+        ? effectiveFromMatch.routeKey
+        : undefined,
+    toRouteName:
+      matched.routeKey && !isAutoGeneratedRouteName(matched.routeKey)
+        ? matched.routeKey
+        : undefined,
   };
   const isAction = !!actionContext;
 
@@ -537,7 +591,7 @@ export async function matchError<TEnv>(
 
   const reqCtx = getRequestContext();
   if (reqCtx) {
-    reqCtx.setStatus(500);
+    reqCtx._setStatus(500);
   }
 
   const effectiveFallback = fallback || DefaultErrorFallback;

package/src/router/match-context.ts

@@ -210,6 +210,9 @@ export interface MatchPipelineState {
   // Whether cache should be revalidated (SWR)
   shouldRevalidate?: boolean;
 
+  // Source of cache hit ("runtime" or "prerender")
+  cacheSource?: "runtime" | "prerender";
+
   // Resolved segments from pipeline
   segments: ResolvedSegment[];
   matchedIds: string[];