@rangojs/router 0.16.0 → 0.18.0

package/src/router/error-handling.ts

@@ -105,31 +105,67 @@ export function invokeOnError<TEnv = any>(
   }
 }
 
+/**
+ * First non-undefined `pick(orphan)` over the routeless entries in
+ * `entry.layout` and, recursively, in theirs: depth-first in render order
+ * (resolveOrphanLayout in segment-resolution/fresh.ts). Since #922 a routeless
+ * entry nested in another renders (a layout() after a bare cache() marker, a
+ * layout() in a routeless wrapper); a one-level scan missed the boundaries and
+ * intercepts it declares (#926).
+ *
+ * `skip` is the entry an upward walk came from. Only a bare cache() marker is
+ * both in its layout's layout[] and in the chain, and its subtree was already
+ * scanned at its chain position.
+ */
+export function findInOrphans<T>(
+  entry: EntryData,
+  pick: (orphan: EntryData) => T | undefined,
+  skip?: EntryData | null,
+): T | undefined {
+  for (const orphan of entry.layout ?? []) {
+    if (orphan === skip) continue;
+    const found = pick(orphan) ?? findInOrphans(orphan, pick);
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}
+
+/** `findInOrphans` pick: the orphan when it declares an errorBoundary(). */
+export const withErrorBoundary = (entry: EntryData): EntryData | undefined =>
+  entry.errorBoundary && entry.errorBoundary.length > 0 ? entry : undefined;
+
+const withNotFoundBoundary = (entry: EntryData): EntryData | undefined =>
+  entry.notFoundBoundary && entry.notFoundBoundary.length > 0
+    ? entry
+    : undefined;
+
 /**
  * Find the nearest error boundary by walking up the entry chain
  * Also checks sibling layouts (orphan layouts) for error boundaries
  * Returns the first fallback found, or the default error boundary if configured
+ *
+ * An orphan's parent is null, so from an orphan the walk continues at its
+ * orphanOwner (EntryData). Without that step, errors from an intercept declared
+ * in a routeless layout, or from that layout's loaders, stopped at the orphan
+ * and skipped every ancestor boundary (#898).
  */
 export function findNearestErrorBoundary(
   entry: EntryData | null,
   defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler,
 ): ReactNode | ErrorBoundaryHandler | null {
   let current: EntryData | null = entry;
+  let prev: EntryData | null = null;
 
   while (current) {
     if (current.errorBoundary && current.errorBoundary.length > 0) {
       return current.errorBoundary[current.errorBoundary.length - 1];
     }
 
-    if (current.layout && current.layout.length > 0) {
-      for (const orphan of current.layout) {
-        if (orphan.errorBoundary && orphan.errorBoundary.length > 0) {
-          return orphan.errorBoundary[orphan.errorBoundary.length - 1];
-        }
-      }
-    }
+    const orphan = findInOrphans(current, withErrorBoundary, prev);
+    if (orphan) return orphan.errorBoundary[orphan.errorBoundary.length - 1];
 
-    current = current.parent;
+    prev = current;
+    current = current.parent ?? current.orphanOwner ?? null;
   }
 
   // Return default error boundary if configured
@@ -145,6 +181,7 @@ export function findNearestNotFoundBoundary(
   defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler,
 ): ReactNode | NotFoundBoundaryHandler | null {
   let current: EntryData | null = entry;
+  let prev: EntryData | null = null;
 
   while (current) {
     if (current.notFoundBoundary && current.notFoundBoundary.length > 0) {
@@ -154,15 +191,14 @@ export function findNearestNotFoundBoundary(
     // Check orphan layouts mirroring findNearestErrorBoundary: notFoundBoundary
     // attaches identically (onto parent.notFoundBoundary), and an orphan layout
     // (parent=null) is reachable only via this scan. First sibling is "outer".
-    if (current.layout && current.layout.length > 0) {
-      for (const orphan of current.layout) {
-        if (orphan.notFoundBoundary && orphan.notFoundBoundary.length > 0) {
-          return orphan.notFoundBoundary[orphan.notFoundBoundary.length - 1];
-        }
-      }
+    const orphan = findInOrphans(current, withNotFoundBoundary, prev);
+    if (orphan) {
+      return orphan.notFoundBoundary[orphan.notFoundBoundary.length - 1];
     }
 
-    current = current.parent;
+    // Orphan: continue at its owner, as findNearestErrorBoundary does.
+    prev = current;
+    current = current.parent ?? current.orphanOwner ?? null;
   }
 
   // Return default notFound boundary if configured

package/src/router/handler-context.ts

@@ -5,7 +5,10 @@
  */
 
 import type { HandlerContext, InternalHandlerContext } from "../types";
-import { _getRequestContext } from "../server/request-context.js";
+import {
+  _getRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
 import { getSearchSchema, isRouteRootScoped } from "../route-map-builder.js";
 import { parseSearchParams, serializeSearchParams } from "../search-params.js";
 import {
@@ -16,8 +19,9 @@ import {
 } from "../context-var.js";
 import {
   assertCachedHeaderWriteAllowed,
-  isInsideCacheScope,
+  assertNonCacheableReadAllowed,
 } from "../server/context.js";
+import { assertThemeReadAllowed } from "../server/cookie-store.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { PRERENDER_PASSTHROUGH } from "../prerender.js";
@@ -29,6 +33,60 @@ import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 // once at module load instead of per createHandlerContext (per-request) call.
 const MUTATING_HEADERS_METHODS = new Set(["set", "append", "delete"]);
 
+/** The request context a handler ctx's `theme` getter reads (THEME_DESCRIPTOR). */
+const THEME_REQUEST_CONTEXT = Symbol("rango:theme-request-context");
+
+/**
+ * ctx.theme is the visitor's theme cookie, guarded like cookies() (#971,
+ * assertThemeReadAllowed): a getter, so creating the ctx reads nothing and
+ * only a handler that reads the theme refuses a ppr capture or throws on a
+ * cache() miss. Non-enumerable, so serializing the ctx does not read it:
+ * React's dev Flight debug info JSON-stringifies server component props and
+ * replayed console.log args, and an enumerable getter read there refused the
+ * capture of a route that never read the theme. The trade: a spread or
+ * Object.assign copy of the ctx does not carry `theme`. One shared getter
+ * with the request context on a symbol key: a getter closure per ctx gives
+ * every ctx its own property shape (V8 dictionary mode). The guard reads the
+ * ambient context, as cookies() does, and falls back to the ctx's own when
+ * there is none.
+ */
+const THEME_DESCRIPTOR: PropertyDescriptor = {
+  get(this: { [THEME_REQUEST_CONTEXT]?: RequestContext }) {
+    const requestContext = this[THEME_REQUEST_CONTEXT];
+    if (!requestContext?._themeConfig) return undefined;
+    assertThemeReadAllowed(_getRequestContext() ?? requestContext, "ctx.theme");
+    return requestContext._readTheme();
+  },
+  enumerable: false,
+  configurable: true,
+};
+
+/**
+ * `headers` whose mutating methods run `assertWrite(method)` first. Shared by
+ * the handler ctx (createHandlerContext) and the middleware ctx
+ * (createMiddlewareContext).
+ */
+export function guardHeaderWrites(
+  headers: Headers,
+  assertWrite: (method: string | symbol) => void,
+): Headers {
+  return new Proxy(headers, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value === "function") {
+        if (MUTATING_HEADERS_METHODS.has(prop as string)) {
+          return (...args: any[]) => {
+            assertWrite(prop);
+            return value.apply(target, args);
+          };
+        }
+        return value.bind(target);
+      }
+      return value;
+    },
+  });
+}
+
 /**
  * Strip internal _rsc* query params from a URL.
  * Returns a new URL with only user-facing params.
@@ -224,23 +282,10 @@ export function createHandlerContext<TEnv>(
   // assertCachedHeaderWriteAllowed, the unified #713 guard).
   // Uses lazy `ctx` reference (assigned below) — only the specific handler ctx
   // is stamped by cache-runtime, not the shared request context.
-  // MUTATING_HEADERS_METHODS is hoisted to module scope (constant, read-only).
   let ctx: InternalHandlerContext<any, TEnv>;
-  const guardedHeaders = new Proxy(stubResponse.headers, {
-    get(target, prop, receiver) {
-      const value = Reflect.get(target, prop, receiver);
-      if (typeof value === "function") {
-        if (MUTATING_HEADERS_METHODS.has(prop as string)) {
-          return (...args: any[]) => {
-            assertNotInsideCacheExec(ctx, "headers");
-            assertCachedHeaderWriteAllowed("ctx.headers", prop);
-            return value.apply(target, args);
-          };
-        }
-        return value.bind(target);
-      }
-      return value;
-    },
+  const guardedHeaders = guardHeaderWrites(stubResponse.headers, (prop) => {
+    assertNotInsideCacheExec(ctx, "headers");
+    assertCachedHeaderWriteAllowed("ctx.headers", prop);
   });
 
   ctx = {
@@ -263,14 +308,10 @@ export function createHandlerContext<TEnv>(
     executionContext: requestContext?.executionContext,
     _variables: variables,
     get: ((keyOrVar: any) => {
-      // Read-time guard: non-cacheable var inside cache() → throw.
-      // Works for both ContextVar tokens and string keys.
-      if (isNonCacheable(variables, keyOrVar) && isInsideCacheScope()) {
-        throw new Error(
-          `ctx.get() for a non-cacheable variable cannot be called inside a cache() boundary. ` +
-            `The variable was created with { cache: false } or set with { cache: false }, ` +
-            `and its value would be stale on cache hit. Move the read outside the cached scope.`,
-        );
+      // Read-time guard: non-cacheable var inside "use cache" or cache() →
+      // throw. Works for both ContextVar tokens and string keys.
+      if (isNonCacheable(variables, keyOrVar)) {
+        assertNonCacheableReadAllowed(keyOrVar, _getRequestContext());
       }
       return contextGet(variables, keyOrVar);
     }) as HandlerContext<any, TEnv>["get"],
@@ -286,8 +327,7 @@ export function createHandlerContext<TEnv>(
     use: () => {
       throw new Error("ctx.use() called before loaders were initialized");
     },
-    // Theme support (when enabled via router config)
-    theme: requestContext?.theme,
+    // theme: THEME_DESCRIPTOR, defined after this literal.
     setTheme: requestContext?.setTheme,
     // Location state support (delegates to request context)
     setLocationState(entries) {
@@ -316,6 +356,9 @@ export function createHandlerContext<TEnv>(
     _responseType: responseType,
     _routeName: routeName,
   };
+  (ctx as { [THEME_REQUEST_CONTEXT]?: unknown })[THEME_REQUEST_CONTEXT] =
+    requestContext;
+  Object.defineProperty(ctx, "theme", THEME_DESCRIPTOR);
   // Brand with taint symbol so "use cache" excludes ctx from cache keys
   (ctx as any)[NOCACHE_SYMBOL] = true;
   return ctx;

package/src/router/instrument.ts

@@ -28,7 +28,14 @@
  * is a direct call — no wrapper, no timestamp, no allocation.
  */
 
-import { _getRequestContext } from "../server/request-context.js";
+import {
+  _getRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
+import {
+  recordTagOwnersArmed,
+  runInSegmentTagScope,
+} from "../cache/cache-tag.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { getRouterContext } from "./router-context.js";
 import { resolveSink, safeEmit, type TelemetryEvent } from "./telemetry.js";
@@ -352,11 +359,56 @@ export function observeHandler<C, R>(
   handler: (ctx: C) => R,
   ctx: C,
 ): R {
-  const tracing = _getRequestContext()?._tracing;
+  return observeHandlerIn(_getRequestContext(), id, handler, ctx);
+}
+
+function observeHandlerIn<C, R>(
+  reqCtx: RequestContext | undefined,
+  id: string,
+  handler: (ctx: C) => R,
+  ctx: C,
+): R {
+  const tracing = reqCtx?._tracing;
   if (!tracing || tracing.phases.handler === false) return handler(ctx);
   return observePhase(PHASES.handler(id), () => handler(ctx));
 }
 
+/**
+ * observeHandler, inside segment `segmentId`'s tag scope, so the tags the
+ * handler records reach the route's cache() record (#957, cache-tag.ts
+ * runInSegmentTagScope). `spanId` is observeHandler's `id`. A request that
+ * cannot write a record takes observeHandler's path as is, with the same one
+ * request-context read: no scope, no closure.
+ */
+export function observeSegmentHandler<C, R>(
+  segmentId: string,
+  spanId: string,
+  handler: (ctx: C) => R,
+  ctx: C,
+): R {
+  const reqCtx = _getRequestContext();
+  if (!recordTagOwnersArmed(reqCtx)) {
+    return observeHandlerIn(reqCtx, spanId, handler, ctx);
+  }
+  return observeInSegmentScope(segmentId, reqCtx, spanId, handler, ctx);
+}
+
+// Separate from observeSegmentHandler: a closure there would make V8
+// allocate its captured-variable context on every call, armed or not.
+function observeInSegmentScope<C, R>(
+  segmentId: string,
+  reqCtx: RequestContext | undefined,
+  spanId: string,
+  handler: (ctx: C) => R,
+  ctx: C,
+): R {
+  return runInSegmentTagScope(
+    segmentId,
+    (c) => observeHandlerIn(reqCtx, spanId, handler, c),
+    ctx,
+  );
+}
+
 /**
  * Emit one discrete telemetry event (the event-shaped counterpart to
  * observePhase). Resolves the sink from the active router context and stamps the

package/src/router/intercept-resolution.ts

@@ -26,8 +26,13 @@ import {
   warnOnStreamedResponse,
   buildLoaderErrorContext,
 } from "./segment-resolution.js";
+import { catchSegmentError } from "./segment-resolution/helpers.js";
+import { findInOrphans } from "./error-handling.js";
+import { resolveLoaderData } from "./segment-resolution/loader-cache.js";
 import type { SegmentResolutionDeps } from "./types.js";
 import { debugLog } from "./logging.js";
+import { getRouterContext } from "./router-context.js";
+import { runInSegmentTagScope } from "../cache/cache-tag.js";
 import {
   RangoContext,
   latchPprHeaderScopeForEntries,
@@ -101,15 +106,20 @@ export function collectInterceptTargetNames(
   fromEntry: EntryData | null,
 ): string[] {
   const names = new Set<string>();
+  // Tolerate partial entries (unit-test mocks omit the arrays); real
+  // registration always populates layout/intercept.
+  const add = (source: EntryData): undefined => {
+    for (const intercept of source.intercept ?? []) {
+      names.add(intercept.routeName);
+    }
+    return undefined;
+  };
   let current: EntryData | null = fromEntry;
+  let prev: EntryData | null = null;
   while (current) {
-    // Tolerate partial entries (unit-test mocks omit the arrays); real
-    // registration always populates layout/intercept.
-    for (const source of [current, ...(current.layout ?? [])]) {
-      for (const intercept of source.intercept ?? []) {
-        names.add(intercept.routeName);
-      }
-    }
+    add(current);
+    findInOrphans(current, add, prev);
+    prev = current;
     current = current.parent;
   }
   return [...names];
@@ -121,27 +131,62 @@ export function findInterceptForRoute(
   selectorContext: InterceptSelectorContext | null = null,
   isAction: boolean = false,
 ): { intercept: InterceptEntry; entry: EntryData } | null {
+  const match = (source: EntryData) => {
+    for (const intercept of source.intercept) {
+      if (
+        intercept.routeName === targetRouteKey &&
+        evaluateInterceptWhen(intercept, selectorContext, isAction)
+      ) {
+        return { intercept, entry: source };
+      }
+    }
+    return undefined;
+  };
   let current: EntryData | null = fromEntry;
+  let prev: EntryData | null = null;
 
   while (current) {
-    // current first, then its sibling layouts — same order as before.
-    for (const source of [current, ...current.layout]) {
-      for (const intercept of source.intercept) {
-        if (
-          intercept.routeName === targetRouteKey &&
-          evaluateInterceptWhen(intercept, selectorContext, isAction)
-        ) {
-          return { intercept, entry: source };
-        }
-      }
-    }
+    // current first, then its orphans (nested ones included) in render order.
+    const found = match(current) ?? findInOrphans(current, match, prev);
+    if (found) return found;
 
+    prev = current;
     current = current.parent;
   }
 
   return null;
 }
 
+/**
+ * An intercept handler's throw or notFound() renders the declaring entry's
+ * boundary as the slot component (catchSegmentError, as for route handlers on
+ * partial navigations: 500/404 status, onError "handler"). Responses and every
+ * error on the background re-render (skipMiddleware) rethrow, so a failed
+ * re-render aborts its cache write instead of storing the fallback.
+ */
+function renderInterceptHandlerError<TEnv>(
+  error: unknown,
+  parentEntry: EntryData,
+  params: Record<string, string>,
+  context: HandlerContext<any, TEnv>,
+  deps: SegmentResolutionDeps<TEnv>,
+  skipMiddleware: boolean | undefined,
+): ReactNode {
+  if (error instanceof Response || skipMiddleware) throw error;
+  return catchSegmentError(
+    error,
+    parentEntry,
+    params,
+    deps,
+    {
+      ...buildLoaderErrorContext(context),
+      isPartial: true,
+      telemetry: getRouterContext()?.telemetry,
+    },
+    context.pathname,
+  ).component;
+}
+
 /**
  * Resolve an intercept entry and emit segment with the slot name.
  */
@@ -210,8 +255,8 @@ export async function resolveInterceptEntry<TEnv>(
   const loaderIds: string[] = [];
 
   for (let i = 0; i < interceptEntry.loader.length; i++) {
-    const { loader, revalidate: loaderRevalidateFns } =
-      interceptEntry.loader[i];
+    const loaderEntry = interceptEntry.loader[i];
+    const { loader, revalidate: loaderRevalidateFns } = loaderEntry;
     const segmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}D${i}.${loader.$$id}`;
 
     if (revalidationContext) {
@@ -273,7 +318,11 @@ export async function resolveInterceptEntry<TEnv>(
     loaderIds.push(loader.$$id);
     loaderPromises.push(
       deps.wrapLoaderPromise(
-        runInsideLoaderScope(() => context.use(loader)),
+        // The DSL binding's funnel, as for route loaders: a loader's own
+        // cache() applies here too.
+        runInsideLoaderScope(() =>
+          resolveLoaderData(loaderEntry, context, context.pathname),
+        ),
         parentEntry,
         segmentId,
         context.pathname,
@@ -284,26 +333,61 @@ export async function resolveInterceptEntry<TEnv>(
     );
   }
 
-  const handlerResult =
-    typeof interceptEntry.handler === "function"
-      ? handleHandlerResult(interceptEntry.handler(context))
-      : interceptEntry.handler;
+  // The intercept segment's id, and the tag scope its handler and layout
+  // record in (#957, cache-tag.ts runInSegmentTagScope).
+  const slotSegmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}`;
+  let handlerResult: ReactNode;
+  try {
+    const handler = interceptEntry.handler;
+    handlerResult =
+      typeof handler === "function"
+        ? handleHandlerResult(
+            runInSegmentTagScope(slotSegmentId, handler, context),
+          )
+        : handler;
+  } catch (error) {
+    handlerResult = renderInterceptHandlerError(
+      error,
+      parentEntry,
+      params,
+      context,
+      deps,
+      options?.skipMiddleware,
+    );
+  }
+  // Consumed only after the layout and loader awaits below; a rejection in that
+  // window would be an unhandledRejection (process crash on Node's default
+  // mode). The later await / trackHandler still observes it.
+  if (handlerResult instanceof Promise) handlerResult.catch(() => {});
 
   let layoutElement: ReactNode | undefined;
   if (interceptEntry.layout) {
-    if (typeof interceptEntry.layout === "function") {
-      const layoutResult = await interceptEntry.layout(context);
+    const layout = interceptEntry.layout;
+    if (typeof layout === "function") {
+      const layoutResult = await runInSegmentTagScope(
+        slotSegmentId,
+        layout,
+        context,
+      );
       if (layoutResult instanceof Response) {
         throw layoutResult;
       }
       layoutElement = layoutResult;
     } else {
-      layoutElement = interceptEntry.layout;
+      layoutElement = layout;
     }
   }
 
   let component: ReactNode;
   let loaderDataPromise: Promise<any[]> | any[] | undefined;
+  // A streamed (loading()) handler resolves after the 200 has started, so its
+  // rejection stays with the client; track it like route handlers do
+  // (onError report, handle-store completion).
+  const trackStreamedHandler = (promise: Promise<unknown>): ReactNode =>
+    deps.trackHandler(promise, {
+      segmentId: `${parentEntry.shortCode}.${interceptEntry.slotName}`,
+      segmentType: "parallel",
+    }) as ReactNode;
 
   if (interceptEntry.loading && loaderPromises.length > 0) {
     if (handlerResult instanceof Promise) {
@@ -314,24 +398,34 @@ export async function resolveInterceptEntry<TEnv>(
     }
     component =
       handlerResult instanceof Promise
-        ? handlerResult
+        ? trackStreamedHandler(handlerResult)
         : (Promise.resolve(handlerResult) as ReactNode);
     loaderDataPromise = Promise.all(loaderPromises);
-  } else if (loaderPromises.length > 0) {
-    loaderDataPromise = await Promise.all(loaderPromises);
-    component =
-      handlerResult instanceof Promise ? await handlerResult : handlerResult;
+  } else if (interceptEntry.loading && handlerResult instanceof Promise) {
+    component = trackStreamedHandler(handlerResult);
   } else {
-    component =
-      interceptEntry.loading && handlerResult instanceof Promise
-        ? handlerResult
-        : handlerResult instanceof Promise
-          ? await handlerResult
-          : handlerResult;
+    if (loaderPromises.length > 0) {
+      loaderDataPromise = await Promise.all(loaderPromises);
+    }
+    component = handlerResult;
+    if (handlerResult instanceof Promise) {
+      try {
+        component = await handlerResult;
+      } catch (error) {
+        component = renderInterceptHandlerError(
+          error,
+          parentEntry,
+          params,
+          context,
+          deps,
+          options?.skipMiddleware,
+        );
+      }
+    }
   }
 
   const interceptSegment = {
-    id: `${parentEntry.shortCode}.${interceptEntry.slotName}`,
+    id: slotSegmentId,
     namespace: `intercept:${interceptEntry.routeName}`,
     type: "parallel" as const,
     index: 0,
@@ -401,8 +495,8 @@ export async function resolveInterceptLoadersOnly<TEnv>(
   } = revalidationContext;
 
   for (let i = 0; i < interceptEntry.loader.length; i++) {
-    const { loader, revalidate: loaderRevalidateFns } =
-      interceptEntry.loader[i];
+    const loaderEntry = interceptEntry.loader[i];
+    const { loader, revalidate: loaderRevalidateFns } = loaderEntry;
     const segmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}D${i}.${loader.$$id}`;
 
     const interceptSegmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}`;
@@ -451,7 +545,11 @@ export async function resolveInterceptLoadersOnly<TEnv>(
     loaderIds.push(loader.$$id);
     loaderPromises.push(
       deps.wrapLoaderPromise(
-        runInsideLoaderScope(() => context.use(loader)),
+        // The DSL binding's funnel, as for route loaders: a loader's own
+        // cache() applies here too.
+        runInsideLoaderScope(() =>
+          resolveLoaderData(loaderEntry, context, context.pathname),
+        ),
         parentEntry,
         segmentId,
         context.pathname,