@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

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

@@ -19,66 +19,31 @@ import type {
 } from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";
 import { resolveLoaderData } from "./loader-cache.js";
-import { _getRequestContext } from "../../server/request-context.js";
-import { appendMetric } from "../metrics.js";
+import {
+  isShellCaptureActive,
+  entryLoadingMasksLoaders,
+} from "./loader-mask.js";
 import {
   handleHandlerResult,
   tryStaticHandler,
   tryStaticSlot,
   resolveLayoutComponent,
   resolveWithErrorBoundary,
+  warnOnStreamedResponse,
+  buildLoaderErrorContext,
 } from "./helpers.js";
+import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
-import { resolveSink, safeEmit } from "../telemetry.js";
+import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
+import { observeHandler } from "../instrument.js";
 import {
   track,
-  RSCRouterContext,
+  RangoContext,
   runInsideLoaderScope,
+  latchCachedHeaderScope,
+  latchPprHeaderScopeForEntries,
 } from "../../server/context.js";
 
-// ---------------------------------------------------------------------------
-// Streamed handler telemetry
-// ---------------------------------------------------------------------------
-
-/**
- * Attach a fire-and-forget rejection observer to a streamed handler promise.
- * React catches the actual error via its error boundary; this only emits
- * the handler.error telemetry event.
- */
-function observeStreamedHandler(
-  promise: Promise<ReactNode>,
-  segmentId: string,
-  segmentType: string,
-  pathname?: string,
-  routeKey?: string,
-  params?: Record<string, string>,
-): void {
-  let routerCtx;
-  try {
-    routerCtx = getRouterContext();
-  } catch {
-    return;
-  }
-  if (!routerCtx?.telemetry) return;
-  const sink = resolveSink(routerCtx.telemetry);
-  const reqId = routerCtx.requestId;
-  promise.catch((err: unknown) => {
-    const errorObj = err instanceof Error ? err : new Error(String(err));
-    safeEmit(sink, {
-      type: "handler.error",
-      timestamp: performance.now(),
-      requestId: reqId,
-      segmentId,
-      segmentType,
-      error: errorObj,
-      handledByBoundary: true,
-      pathname,
-      routeKey,
-      params,
-    });
-  });
-}
-
 // ---------------------------------------------------------------------------
 // Fresh path (full match, no revalidation)
 // ---------------------------------------------------------------------------
@@ -98,11 +63,46 @@ export async function resolveLoaders<TEnv>(
   if (loaderEntries.length === 0) return [];
 
   const shortCode = shortCodeOverride ?? entry.shortCode;
+
+  // Pin `_currentSegmentId` to the OWNING entry BEFORE the loader kickoffs:
+  // createLoaderExecutor captures it synchronously at kickoff for
+  // ctx.use(Handle) push attribution (loader writes land in the same bucket
+  // as the entry's handler pushes — shortCode is in matched/segmentOrder, so
+  // collectHandleData keeps them; an id outside the order is silently
+  // dropped). resolveLoaders runs BEFORE the handler-resolution sites assign
+  // this (fresh.ts handler-first ordering), so without the pin the captured
+  // value is a stale sibling's id (document lane) or undefined (navigation
+  // lane — pushes silently vanished).
+  (ctx as InternalHandlerContext<any, TEnv>)._currentSegmentId = shortCode;
   const hasLoading = "loading" in entry && entry.loading !== undefined;
   const loadingDisabled = hasLoading && entry.loading === false;
-  const ms = _getRequestContext()?._metricsStore;
 
-  if (!loadingDisabled) {
+  // Emit the streaming (non-awaiting) loader shape when loading is enabled OR
+  // during a PPR shell capture. In capture, LIVE-lane loaders are masked with
+  // never-resolving promises (loader-mask.ts); the loading-disabled branch below
+  // AWAITS the loader promises, which would hang the capture render's match()
+  // forever on those masked promises. Forcing the streaming shape lets match()
+  // complete so the prerender can postpone the loader subtrees as holes. The
+  // `!loadingDisabled` short-circuit keeps the ALS check off the hot path (only
+  // loading-disabled entries consult it), so normal requests are unchanged.
+  const emitStreaming = !loadingDisabled || isShellCaptureActive();
+
+  // PPR lane decision for this entry's loaders (loader-container-bake): an
+  // entry WITHOUT renderable loading() puts its loaders on the BAKE lane —
+  // executed at capture (container bakes, nested pending promises hole at the
+  // consumer's Suspense) and overlay-pinned from the shell snapshot on a HIT.
+  // Renderable loading() keeps the LIVE lane (masked at capture, always
+  // fresh). Computed per entry; resolveLoaderData applies the policy.
+  const bakeLane = !entryLoadingMasksLoaders(entry.loading);
+
+  // Error context for wrapLoaderPromise: without it, a throwing DSL loader never
+  // fires createRouter({ onError }) (phase "loader") nor emits the loader.error
+  // telemetry event — wrapLoaderPromise only builds the onError/telemetry path
+  // when errorContext is supplied. Built from ctx so the live render path reports
+  // loader failures the same way handlers/actions/routing/fetchable-loaders do.
+  const errorContext = buildLoaderErrorContext(ctx);
+
+  if (emitStreaming) {
     // Streaming loaders: promises kick off now, settle during RSC serialization.
     const segments = loaderEntries.map((loaderEntry, i) => {
       const { loader } = loaderEntry;
@@ -117,11 +117,17 @@ export async function resolveLoaders<TEnv>(
         loaderId: loader.$$id,
         loaderData: deps.wrapLoaderPromise(
           runInsideLoaderScope(() =>
-            resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+            resolveLoaderData(
+              loaderEntry,
+              ctx,
+              ctx.pathname,
+              bakeLane ? segmentId : null,
+            ),
           ),
           entry,
           segmentId,
           ctx.pathname,
+          errorContext,
         ),
         belongsToRoute,
       };
@@ -132,46 +138,51 @@ export async function resolveLoaders<TEnv>(
 
   // Loading disabled: still start all loaders in parallel, but only emit
   // settled promises so handlers don't stream loading placeholders.
-  const pendingLoaderData = loaderEntries.map((loaderEntry) => {
-    const start = performance.now();
-    const promise = runInsideLoaderScope(() =>
-      resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+  //
+  // Wrap each loader promise with wrapLoaderPromise BEFORE awaiting. The wrapped
+  // promise resolves to a LoaderDataResult and never rejects, routing a failed
+  // loader to its own per-loader error boundary. Awaiting the RAW promises here
+  // instead would (1) propagate a rejection to the segment-level boundary,
+  // collapsing the whole entry and discarding successful sibling data, and
+  // (2) leave the other in-flight raw promises without a .catch, producing
+  // unhandled rejections. Mirrors the loading path and intercept-resolution.
+  const pendingLoaderData = loaderEntries.map((loaderEntry, i) => {
+    const { loader } = loaderEntry;
+    const segmentId = `${shortCode}D${i}.${loader.$$id}`;
+    const wrapped = deps.wrapLoaderPromise(
+      runInsideLoaderScope(() =>
+        resolveLoaderData(
+          loaderEntry,
+          ctx,
+          ctx.pathname,
+          bakeLane ? segmentId : null,
+        ),
+      ),
+      entry,
+      segmentId,
+      ctx.pathname,
+      errorContext,
     );
-    return { promise, start, loaderId: loaderEntry.loader.$$id };
+    return { wrapped, segmentId };
   });
-  await Promise.all(pendingLoaderData.map((p) => p.promise));
+  await Promise.all(pendingLoaderData.map((p) => p.wrapped));
 
   return loaderEntries.map((loaderEntry, i) => {
     const { loader } = loaderEntry;
-    const segmentId = `${shortCode}D${i}.${loader.$$id}`;
     const pending = pendingLoaderData[i]!;
-    if (ms && !ms.metrics.some((m) => m.label === `loader:${loader.$$id}`)) {
-      // All loaders ran in parallel via Promise.all — each span covers
-      // from its own kickoff to the batch settlement, giving a ceiling
-      // on that loader's contribution to the overall wait.
-      const batchEnd = performance.now();
-      appendMetric(
-        ms,
-        `loader:${loader.$$id}`,
-        pending.start,
-        batchEnd - pending.start,
-        2,
-      );
-    }
+    // The "loader:<id>" perf metric is recorded by observePhase at the single
+    // loader-metering site (useLoader, reached via ctx.use during
+    // resolveLoaderData), with the real per-loader duration rather than a
+    // Promise.all batch ceiling.
     return {
-      id: segmentId,
+      id: pending.segmentId,
       namespace: entry.id,
       type: "loader" as const,
       index: i,
       component: null,
       params: ctx.params,
       loaderId: loader.$$id,
-      loaderData: deps.wrapLoaderPromise(
-        pending.promise,
-        entry,
-        segmentId,
-        ctx.pathname,
-      ),
+      loaderData: pending.wrapped,
       belongsToRoute,
     };
   });
@@ -183,6 +194,15 @@ export async function resolveLoaders<TEnv>(
 export interface ResolveSegmentOptions {
   /** When true, skip resolveLoaders() calls (used for pre-rendering) */
   skipLoaders?: boolean;
+  /**
+   * When true, a thrown render error is re-thrown instead of being converted
+   * into an error-boundary segment. Set only by the pre-render path so a
+   * build-time render failure (and a `throw new Skip()` inside a render fn)
+   * surfaces to the build instead of being silently baked into a frozen error
+   * page served as a 200 (issue #587). The live request path leaves this unset,
+   * so error boundaries keep catching at request time.
+   */
+  throwOnError?: boolean;
 }
 
 /**
@@ -224,7 +244,11 @@ export async function resolveSegment<TEnv>(
       index: 0,
       component,
       loading: entry.loading === false ? null : entry.loading,
-      transition: entry.transition,
+      transition: applyViewTransitionDefault(
+        entry.transition,
+        deps.viewTransitionDefault,
+        entry.shortCode,
+      ),
       params,
       belongsToRoute: false,
       layoutName: entry.id,
@@ -291,8 +315,11 @@ export async function resolveSegment<TEnv>(
         !context.build && entry.liveHandler ? entry.liveHandler : entry.handler;
       const doneRouteHandler = track(`handler:${entry.id}`, 2);
       if (entry.loading) {
-        const result = handleHandlerResult(handler(context));
+        const result = handleHandlerResult(
+          observeHandler(entry.id, handler, context),
+        );
         if (result instanceof Promise) {
+          warnOnStreamedResponse(result, entry.id);
           result.finally(doneRouteHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
             segmentId: entry.shortCode,
@@ -312,7 +339,9 @@ export async function resolveSegment<TEnv>(
           component = result;
         }
       } else {
-        component = handleHandlerResult(await handler(context));
+        component = handleHandlerResult(
+          await observeHandler(entry.id, handler, context),
+        );
         doneRouteHandler();
       }
     }
@@ -359,7 +388,11 @@ export async function resolveSegment<TEnv>(
       index: 0,
       component: component ?? null,
       loading: entry.loading === false ? null : entry.loading,
-      transition: entry.transition,
+      transition: applyViewTransitionDefault(
+        entry.transition,
+        deps.viewTransitionDefault,
+        entry.shortCode,
+      ),
       params,
       belongsToRoute: true,
       ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
@@ -443,7 +476,11 @@ export async function resolveOrphanLayout<TEnv>(
     belongsToRoute,
     layoutName: orphan.id,
     loading: orphan.loading === false ? null : orphan.loading,
-    transition: orphan.transition,
+    transition: applyViewTransitionDefault(
+      orphan.transition,
+      deps.viewTransitionDefault,
+      orphan.shortCode,
+    ),
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });
 
@@ -515,6 +552,14 @@ export async function resolveParallelEntry<TEnv>(
       if (handler === undefined) {
         continue;
       }
+      // Pin `_currentSegmentId` to the slot's own id so handle pushes from
+      // inside the slot handler get their own bucket in the HandleStore.
+      // Parent-keying would collapse them into the parent layout's bucket;
+      // the partial-update merge then replaces the parent's bucket on a
+      // slot-only revalidation and drops layout-pushed Meta/Breadcrumbs.
+      // filterSegmentOrder() retains slot ids so the client preserves them.
+      (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+        `${parentShortCode}.${slot}`;
       const doneParallelHandler = track(
         `handler:${parallelEntry.id}.${slot}`,
         2,
@@ -523,7 +568,9 @@ export async function resolveParallelEntry<TEnv>(
         parallelEntry.loading !== undefined && parallelEntry.loading !== false;
       if (hasLoadingFallback) {
         const result =
-          typeof handler === "function" ? handler(context) : handler;
+          typeof handler === "function"
+            ? observeHandler(`${parallelEntry.id}.${slot}`, handler, context)
+            : handler;
         if (result instanceof Promise) {
           result.finally(doneParallelHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
@@ -545,7 +592,13 @@ export async function resolveParallelEntry<TEnv>(
         }
       } else {
         component =
-          typeof handler === "function" ? await handler(context) : handler;
+          typeof handler === "function"
+            ? await observeHandler(
+                `${parallelEntry.id}.${slot}`,
+                handler,
+                context,
+              )
+            : handler;
         doneParallelHandler();
       }
     }
@@ -557,7 +610,11 @@ export async function resolveParallelEntry<TEnv>(
       index: 0,
       component,
       loading: parallelEntry.loading === false ? null : parallelEntry.loading,
-      transition: parallelEntry.transition,
+      transition: applyViewTransitionDefault(
+        parallelEntry.transition,
+        deps.viewTransitionDefault,
+        `${parentShortCode}.${slot}`,
+      ),
       params,
       slot,
       belongsToRoute,
@@ -606,6 +663,12 @@ export async function resolveAllSegments<TEnv>(
   const allSegments: ResolvedSegment[] = [];
   const seenIds = new Set<string>();
 
+  // ppr routes are document-scoped cached territory: the whole chain (root
+  // layout down to the page) bakes into the shared shell, so the header-write
+  // guard latches BEFORE any entry resolves (unlike the positional cache()
+  // latch below). See assertCachedHeaderWriteAllowed (server/context.ts).
+  latchPprHeaderScopeForEntries(entries, routeKey);
+
   // Safe request access: during build-time prerendering, context.request
   // is a throwing getter. Use undefined when unavailable.
   let safeRequest: Request | undefined;
@@ -621,11 +684,13 @@ export async function resolveAllSegments<TEnv>(
 
   for (const entry of entries) {
     // Set ALS flag when entering a cache() boundary so that ctx.get()
-    // can guard non-cacheable variable reads. Also guards response-level
-    // side effects (headers.set). Persists for all descendant entries.
+    // can guard non-cacheable variable reads. Also latch the header-write
+    // scope (response-level side effects — headers/cookies/status).
+    // Persists for all descendant entries.
     if (entry.type === "cache") {
-      const store = RSCRouterContext.getStore();
+      const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
+      latchCachedHeaderScope("cache", routeKey);
     }
     const doneEntry = track(`segment:${entry.id}`, 1);
     const resolvedSegments = await resolveWithErrorBoundary(
@@ -646,6 +711,7 @@ export async function resolveAllSegments<TEnv>(
       deps,
       { request: safeRequest, url: context.url, routeKey, telemetry },
       context.pathname,
+      options?.throwOnError,
     );
     doneEntry();
     // Deduplicate by segment ID. include() scopes can produce entries that
@@ -673,6 +739,15 @@ export async function resolveLoadersOnly<TEnv>(
   const loaderSegments: ResolvedSegment[] = [];
   const seenIds = new Set<string>();
 
+  // Loader-only serves (cached non-loader segments) still run loaders live —
+  // on a ppr route their header writes are dead letters (headers flushed with
+  // the shell), so the guard latches here too. cache() needs no latch: loader
+  // writes are exempt under cache() (see assertCachedHeaderWriteAllowed).
+  latchPprHeaderScopeForEntries(
+    entries,
+    (context as InternalHandlerContext<any, TEnv>)._routeName,
+  );
+
   async function collectEntryLoaders(
     entry: EntryData,
     belongsToRoute: boolean,

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

@@ -8,24 +8,60 @@
  * - Error boundary segment creation
  */
 
-import { createElement, type ReactNode } from "react";
-import { DataNotFoundError } from "../../errors";
+import type { ReactNode } from "react";
+import { isDataNotFoundError } from "../../errors";
 import {
   createErrorInfo,
   createErrorSegment,
   createNotFoundInfo,
   createNotFoundSegment,
+  resolveNotFoundFallback,
 } from "../error-handling.js";
 import { getRequestContext } from "../../server/request-context.js";
 import { DefaultErrorFallback } from "../../default-error-boundary.js";
 import type { EntryData } from "../../server/context";
-import type { ResolvedSegment, ErrorInfo, HandlerContext } from "../../types";
+import type {
+  ResolvedSegment,
+  ErrorInfo,
+  HandlerContext,
+  InternalHandlerContext,
+} from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";
 import { debugLog } from "../logging.js";
 import { tryStaticLookup } from "./static-store.js";
+import { observeHandler } from "../instrument.js";
 import type { TelemetrySink } from "../telemetry.js";
 import { resolveSink, safeEmit, getRequestId } from "../telemetry.js";
 
+/** The errorContext shape wrapLoaderPromise expects as its 5th argument. */
+type LoaderErrorContext<TEnv> = NonNullable<
+  Parameters<SegmentResolutionDeps<TEnv>["wrapLoaderPromise"]>[4]
+>;
+
+/**
+ * Build the errorContext passed to wrapLoaderPromise so a throwing DSL loader
+ * fires createRouter({ onError }) (phase "loader") and emits the loader.error
+ * telemetry event. wrapLoaderPromise only wires the onError/telemetry path when
+ * this 5th argument is present; every real call site previously omitted it, so
+ * loaders were the one phase whose failures were silently dropped (handlers,
+ * actions, routing, rendering, and fetchable loaders all reported correctly).
+ *
+ * The fields come off the handler context, which already carries the request,
+ * url, params, env, and (on the internal shape) the matched route name.
+ */
+export function buildLoaderErrorContext<TEnv>(
+  ctx: HandlerContext<any, TEnv>,
+): LoaderErrorContext<TEnv> {
+  const internal = ctx as InternalHandlerContext<any, TEnv>;
+  return {
+    request: ctx.request,
+    url: ctx.url,
+    routeKey: internal._routeName,
+    params: ctx.params as Record<string, string>,
+    env: ctx.env,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Handler result processing
 // ---------------------------------------------------------------------------
@@ -36,7 +72,7 @@ import { resolveSink, safeEmit, getRequestId } from "../telemetry.js";
  * the short-circuit mechanism. Otherwise return the ReactNode.
  */
 export function handleHandlerResult(
-  result: ReactNode | Response | Promise<ReactNode> | Promise<Response>,
+  result: ReactNode | Response | Promise<ReactNode | Response>,
 ): ReactNode {
   if (result instanceof Response) {
     throw result;
@@ -52,6 +88,40 @@ export function handleHandlerResult(
   return result;
 }
 
+/**
+ * Dev-only: warn when a handler on a route that declares loading() resolves or
+ * rejects with a Response (e.g. redirect()).
+ *
+ * On a non-loading route a returned/thrown Response short-circuits to an HTTP
+ * redirect. But when the route declares loading(), the handler result is
+ * streamed (not awaited at the resolution boundary), so the Response surfaces
+ * only during RSC serialization and is rendered into the stream instead of
+ * becoming a 302/308 — a silent failure mode. Issue redirects from middleware,
+ * a loader, or a synchronous handler return instead. Compiled out in production.
+ */
+export function warnOnStreamedResponse(
+  result: Promise<unknown>,
+  entryId: string,
+): void {
+  if (process.env.NODE_ENV === "production") return;
+  // A Response can surface either as a rejection (handleHandlerResult rethrows a
+  // resolved Response) or as a resolved value (the raw parallel-slot handler is
+  // not run through handleHandlerResult). Check both so every streamed path is
+  // covered. Each handler is an independent observer; it does not consume the
+  // rejection for the trackHandler/observeStreamedHandler chains.
+  const check = (value: unknown) => {
+    if (value instanceof Response) {
+      console.warn(
+        `[rango] Handler for "${entryId}" returned a Response (e.g. ` +
+          `redirect()), but it declares loading(): the Response is rendered ` +
+          `into the RSC stream, NOT sent as an HTTP redirect. Issue redirects ` +
+          `from middleware, a loader, or a synchronous handler return.`,
+      );
+    }
+  };
+  result.then(check, check);
+}
+
 // ---------------------------------------------------------------------------
 // Static handler interception
 // ---------------------------------------------------------------------------
@@ -96,11 +166,16 @@ export async function resolveLayoutComponent<TEnv>(
   entry: EntryData,
   context: HandlerContext<any, TEnv>,
 ): Promise<ReactNode> {
-  const component = await tryStaticHandler(entry, entry.shortCode);
-  if (component !== undefined) return component;
-  return typeof entry.handler === "function"
-    ? handleHandlerResult(await entry.handler(context))
-    : (entry.handler as ReactNode);
+  // Static/prerender hit: no handler runs, so emit no rango.handler span.
+  const staticComponent = await tryStaticHandler(entry, entry.shortCode);
+  if (staticComponent !== undefined) return staticComponent;
+  const handler = entry.handler;
+  if (typeof handler !== "function") return handler as ReactNode;
+  // Wrap ONLY the handler call in the rango.handler span (the perf metric is owned
+  // by track("handler:<id>") at the call site). handleHandlerResult stays OUTSIDE
+  // the span so a handler that returns a Response (redirect control flow, which it
+  // rethrows) is not recorded as a span error — mirrors the route-handler sites.
+  return handleHandlerResult(await observeHandler(entry.id, handler, context));
 }
 
 // ---------------------------------------------------------------------------
@@ -178,15 +253,12 @@ export function catchSegmentError<TEnv>(
     }
   };
 
-  if (error instanceof DataNotFoundError) {
-    const notFoundFallback = deps.findNearestNotFoundBoundary(entry);
-    // Fall back to router's notFound component, then a plain default
-    const notFoundOption = deps.notFoundComponent;
-    const defaultFallback =
-      typeof notFoundOption === "function"
-        ? notFoundOption({ pathname: pathname ?? "" })
-        : (notFoundOption ?? createElement("h1", null, "Not Found"));
-    const effectiveNotFoundFallback = notFoundFallback ?? defaultFallback;
+  if (isDataNotFoundError(error)) {
+    const effectiveNotFoundFallback = resolveNotFoundFallback(
+      deps.findNearestNotFoundBoundary(entry),
+      deps.notFoundComponent,
+      pathname,
+    );
 
     const notFoundInfo = createNotFoundInfo(
       error,
@@ -250,11 +322,17 @@ export async function resolveWithErrorBoundary<TEnv, TResult>(
   deps: SegmentResolutionDeps<TEnv>,
   report?: ErrorReportContext,
   pathname?: string,
+  throwOnError?: boolean,
 ): Promise<TResult> {
   try {
     return await resolveFn();
   } catch (error) {
     if (error instanceof Response) throw error;
+    // Pre-render surfaces render failures to the build instead of baking the
+    // error boundary as a frozen 200 (issue #587). A `throw new Skip()` in a
+    // render fn also propagates here so the build can skip that URL rather than
+    // bake its error page. The live request path leaves throwOnError unset.
+    if (throwOnError) throw error;
     const segment = catchSegmentError(
       error,
       entry,