@rangojs/router 0.5.2 → 0.6.0

package/src/router/loader-resolution.ts

@@ -18,10 +18,28 @@ import type {
   ErrorBoundaryHandler,
   ErrorBoundaryFallbackProps,
   ErrorInfo,
+  NotFoundBoundaryHandler,
+  NotFoundBoundaryFallbackProps,
 } from "../types";
+import { createElement } from "react";
+import { isDataNotFoundError } from "../errors.js";
+import { isRedirectResponse } from "../response-utils.js";
+import {
+  resolveSoftRedirectUrl,
+  getRedirectState,
+  isExternalRedirect,
+} from "../redirect-origin.js";
+import {
+  createNotFoundInfo,
+  renderNotFoundFallback,
+  resolveNotFoundFallback,
+} from "./error-handling.js";
 import { isHandle, collectHandleData, type Handle } from "../handle.js";
 import { withDefer } from "../defer.js";
-import { buildHandleSnapshot } from "../server/handle-store.js";
+import {
+  buildHandleSnapshot,
+  type HandleStore,
+} from "../server/handle-store.js";
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
 import { _getRequestContext } from "../server/request-context.js";
 import {
@@ -46,11 +64,66 @@ export type LoaderErrorCallback = (
   },
 ) => void;
 
+/**
+ * Loader-thrown authority signals (notFound()/redirect()) are detected by the
+ * shape a consumer can actually throw: DataNotFoundError via the shared
+ * cross-realm-safe isDataNotFoundError, redirect by 3xx Response.
+ */
+
+/**
+ * Deliver one `ctx.use(Handle)(value)` push to the owning segment.
+ *
+ * Shared by the handler lane (setupLoaderAccess) and the loader-body lane
+ * (createLoaderExecutor) so a loader push attributes and scopes EXACTLY like a
+ * handler push — that parity is the contract `ctx.use` in a loader promises.
+ *
+ * A function value runs inside the push-callback scope so `ctx.use(loader)`
+ * calls it makes — including after its own awaits, for an async callback — are
+ * not registered as handler-to-loader deps and do not trip the deadlock guard.
+ * A pushed promise value is not tracked by handleStore.settled and does not
+ * block segment resolution, so it cannot form a rendered() deadlock. The ALS
+ * scope (not a plain boolean) is what survives the callback's awaits.
+ */
+function pushHandleValue(
+  store: HandleStore | undefined,
+  segmentId: string | undefined,
+  handleId: string,
+  dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>),
+): void {
+  if (!store || !segmentId) return;
+  if (typeof dataOrFn === "function") {
+    store.push(
+      handleId,
+      segmentId,
+      runInsidePushCallbackScope(() => (dataOrFn as () => Promise<unknown>)()),
+    );
+    return;
+  }
+  store.push(handleId, segmentId, dataOrFn);
+}
+
 /**
  * Wrap a loader promise with error handling for deferred client-side resolution.
  * Catches errors and converts them to LoaderDataResult objects that include
  * error info and pre-rendered fallback UI when an error boundary is available.
  *
+ * Loader-thrown SIGNALS are routed before error handling — they are control
+ * flow, not failures (onError is not invoked for them):
+ * - notFound(): the not-found UI is resolved and rendered HERE, server-side
+ *   (nearest notFoundBoundary → router notFound option → default), exactly
+ *   like the consumption lane (segment-resolution/helpers.ts), and rides the
+ *   envelope's `fallback` — the client swaps with zero extra fetches. The
+ *   response status is opportunistically set to 404 via the request stub: if
+ *   the rejection settles before the document Response is constructed the
+ *   status is a real 404; after, the stub write is inert (streamed fix-up
+ *   only). Nav-lane payloads are 200 either way — the client owns 404
+ *   presentation there.
+ * - redirect() (thrown 3xx Response): the target is resolved through the
+ *   soft-redirect same-origin rules NOW so unsafe targets never leave the
+ *   server; the client navigates when the entry decodes. No document-lane
+ *   302 — pre-stream redirect authority belongs to middleware (doctrine);
+ *   a loader redirect is always a client-side navigate.
+ *
  * @param onError - Optional callback invoked when loader errors occur.
  *   This has a simplified signature for internal use - the caller (typically
  *   wrapLoaderPromise in router.ts) is responsible for bridging to the full
@@ -70,6 +143,14 @@ export function wrapLoaderWithErrorHandling<T>(
     segmentType: ErrorInfo["segmentType"],
   ) => ErrorInfo,
   onError?: LoaderErrorCallback,
+  notFoundDeps?: {
+    findNearestNotFoundBoundary: (
+      entry: EntryData | null,
+    ) => ReactNode | NotFoundBoundaryHandler | null;
+    notFoundComponent?:
+      | ReactNode
+      | ((props: { pathname: string }) => ReactNode);
+  },
 ): Promise<LoaderDataResult<T>> {
   // Extract the trailing token from segmentId (format: "<shortCode>D<i>.<loaderId>").
   // The token is the loader's $$id (hash#export in prod, pathfrag#export in dev),
@@ -85,6 +166,92 @@ export function wrapLoaderWithErrorHandling<T>(
       }),
     )
     .catch((error): LoaderDataResult<T> => {
+      if (isDataNotFoundError(error)) {
+        // Opportunistic document 404: the stub status is read once when the
+        // document Response is constructed (createResponseWithMergedHeaders);
+        // a pre-construction write becomes the real status, a later write is
+        // harmless. Same mechanism as the consumption lane's setResponseStatus.
+        _getRequestContext()?._setStatus(404);
+
+        const effective = resolveNotFoundFallback(
+          notFoundDeps?.findNearestNotFoundBoundary(entry),
+          notFoundDeps?.notFoundComponent,
+          pathname,
+        );
+
+        const notFoundInfo = createNotFoundInfo(
+          error as { message: string },
+          segmentId,
+          "loader",
+          pathname,
+        );
+        let renderedNotFound: ReactNode;
+        try {
+          renderedNotFound = renderNotFoundFallback(effective, notFoundInfo);
+        } catch {
+          // A throwing boundary must not collapse the envelope (the wrapped
+          // promise is contracted to never reject); degrade to the default.
+          // Deliberately NOT shared with the consumption lane
+          // (segment-resolution/helpers.ts), which lets a throwing boundary
+          // propagate to the error boundary — only this lane is contracted to
+          // never reject.
+          renderedNotFound = createElement("h1", null, "Not Found");
+        }
+
+        debugLog("loader", "loader threw notFound()", {
+          segmentId,
+          pathname,
+        });
+
+        return {
+          __loaderResult: true,
+          ok: false,
+          notFound: true,
+          error: createErrorInfo(error, segmentId, "loader"),
+          fallback: renderedNotFound ?? null,
+        };
+      }
+
+      if (error instanceof Response && isRedirectResponse(error)) {
+        const reqCtx = _getRequestContext();
+        const requestOrigin = reqCtx?.originalUrl?.origin ?? reqCtx?.url.origin;
+        const location = error.headers.get("Location")!;
+        // Same-origin policy applied server-side; the wire never carries an
+        // unresolved target. redirect(url, { external: true })'s WeakSet brand
+        // survives (the thrown Response IS the branded object).
+        const to = requestOrigin
+          ? resolveSoftRedirectUrl(
+              location,
+              requestOrigin,
+              reqCtx?._basename,
+              isExternalRedirect(error),
+            )
+          : location;
+
+        debugLog("loader", "loader threw redirect()", {
+          segmentId,
+          to,
+        });
+
+        // redirect(url, { state }): the resolved state rides the thrown
+        // Response (attachRedirectState), NOT payload metadata — a streaming
+        // loader settles after the metadata flush, so the marker is the only
+        // carrier that reaches the client. LoaderRedirect navigates with it.
+        const redirectState = getRedirectState(error);
+
+        return {
+          __loaderResult: true,
+          ok: false,
+          redirect: { to, ...(redirectState && { state: redirectState }) },
+          error: createErrorInfo(
+            new Error(`Loader redirected to ${to}`),
+            segmentId,
+            "loader",
+          ),
+          fallback: null,
+        };
+      }
+
       // Find nearest error boundary
       const fallback = findNearestErrorBoundary(entry);
 
@@ -210,12 +377,23 @@ function detectLoaderCycle(
 function createLoaderExecutor<TEnv>(
   ctx: HandlerContext<any, TEnv>,
   loaderPromises: Map<string, Promise<any>>,
+  executorOptions?: {
+    /**
+     * Background proactive-caching mode: ctx.handle() pushes become no-ops
+     * (mirroring setupLoaderAccessSilent's handler-handle no-op) and loader
+     * bodies are NOT aux-tracked into the foreground handle store — a
+     * background run must neither duplicate handle data nor extend the live
+     * payload's handle-stream lifetime.
+     */
+    silentHandles?: boolean;
+  },
 ): (
   loader: LoaderDefinition<any, any>,
   callerLoaderId: string | null,
 ) => Promise<any> {
   // Capture RequestContext eagerly for cookie access (ALS protection on Cloudflare)
   const reqCtxRef = _getRequestContext();
+  const silentHandles = executorOptions?.silentHandles === true;
 
   // Dependency graph: loaderId -> set of loader IDs it directly depends on.
   const dependsOn = new Map<string, Set<string>>();
@@ -281,6 +459,16 @@ function createLoaderExecutor<TEnv>(
     // inside loader scope. This determines whether rendered() is allowed.
     const isDslLoader = isInsideLoaderScope();
 
+    // Owning segment for ctx.handle() attribution, captured SYNCHRONOUSLY at
+    // kickoff: segment resolution sets _currentSegmentId while resolving the
+    // segment that declares this loader (fresh.ts), and the value moves on as
+    // resolution continues — by the time the async body pushes, it would be
+    // stale. Attributing to the owning route/layout segment gives handle
+    // pushes the same granularity handler pushes have (segmentOrder-correct
+    // for breadcrumb accumulation).
+    const owningSegmentId = (ctx as InternalHandlerContext<any, TEnv>)
+      ._currentSegmentId;
+
     let renderedResolved = false;
     let renderedPromise: Promise<void> | null = null;
 
@@ -301,20 +489,20 @@ function createLoaderExecutor<TEnv>(
       env: ctx.env,
       waitUntil: ctx.waitUntil.bind(ctx),
       executionContext: ctx.executionContext,
-      get: ((keyOrVar: any) =>
-        contextGet(variables, keyOrVar)) as typeof ctx.get,
-      use: ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
-        if (isHandle(item)) {
+      get: ((keyOrVar: any) => {
+        // Handle READ (moved from ctx.use(handle)): collected data, available
+        // after `await ctx.rendered()` — the rendered-barrier contract.
+        if (isHandle(keyOrVar)) {
           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.`,
+              `ctx.get(handle) in a loader requires "await ctx.rendered()" first. ` +
+                `Handle "${keyOrVar.$$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.`,
+              `ctx.get(handle) failed: request context not available.`,
             );
           }
           const segmentOrder = reqCtx._renderBarrierSegmentOrder ?? [];
@@ -327,7 +515,35 @@ function createLoaderExecutor<TEnv>(
           const snapshot =
             reqCtx._renderBarrierHandleSnapshot ??
             buildHandleSnapshot(reqCtx._handleStore, segmentOrder);
-          return collectHandleData(item, snapshot, segmentOrder);
+          return collectHandleData(keyOrVar, snapshot, segmentOrder);
+        }
+        return contextGet(variables, keyOrVar);
+      }) as typeof ctx.get,
+      use: ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
+        if (isHandle(item)) {
+          // Handle WRITE — handler parity: `ctx.use(Meta)({...})` pushes from
+          // the loader body exactly like a handler push. Reads moved to
+          // ctx.get(handle) (rendered()-gated). Pushes attribute to the OWNING
+          // segment and are legal for the whole body: the body is tracked on
+          // the handle store's auxiliary lane, so the store stays open past
+          // the handler barrier. Delivery follows the race: pushes that beat
+          // the handler barrier ride the SSR snapshot, later ones stream via
+          // metadata.handlesLate (document) or the still-open handles
+          // generator (nav/action lanes).
+          const handleDef = item;
+          if (silentHandles) {
+            return withDefer((_dataOrFn: unknown) => {});
+          }
+          const store =
+            reqCtxRef?._handleStore ?? _getRequestContext()?._handleStore;
+          const segmentId = owningSegmentId;
+          return withDefer(
+            (
+              dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>),
+            ) => {
+              pushHandleValue(store, segmentId, handleDef.$$id, dataOrFn);
+            },
+          );
         }
 
         // Loader case
@@ -355,6 +571,24 @@ function createLoaderExecutor<TEnv>(
           );
         }
 
+        // awaitBeforeFlush cycle: segment resolution awaits this loader
+        // (loader(Def, { stream: "navigation" })), the barrier awaits segment
+        // resolution, and rendered() awaits the barrier — waiting here can
+        // never complete. Fail fast with the cause instead of hanging the
+        // document render. Only document renders populate the set (the flag is
+        // stamped per-isSSR), so the same loader may still use rendered() on
+        // navigation renders.
+        if (reqCtx._awaitBeforeFlushLoaderIds?.has(currentLoaderId)) {
+          throw new Error(
+            `Deadlock: loader "${currentLoaderId}" is registered with ` +
+              `stream: "navigation", so the document render awaits it before ` +
+              `the render barrier resolves — ctx.rendered() (and the ` +
+              `ctx.get(handle) read it gates) can never settle here. Drop ` +
+              `stream: "navigation" on this loader or move the handle read to ` +
+              `a component.`,
+          );
+        }
+
         // Bidirectional deadlock check: if a handler already started
         // awaiting this loader, calling rendered() would deadlock. This is the
         // real cycle guard (it holds for both streaming and non-streaming): the
@@ -458,6 +692,20 @@ function createLoaderExecutor<TEnv>(
       }),
     );
 
+    // Auxiliary-lane tracking: keeps the handle store open for this body's
+    // ctx.handle() pushes without joining `settled` (the handler barrier that
+    // gates SSR/hydration and rendered()-readers — joining it would block the
+    // document on the slowest loader and self-deadlock rendered() callers).
+    // DSL loaders only: handler-invoked loaders are awaited by their handler,
+    // so they complete inside the handler lane already. A nested DSL kickoff
+    // mid-body registers while its parent is still tracked, so the lane can
+    // never re-open after draining.
+    if (isDslLoader && !silentHandles) {
+      (reqCtxRef ?? _getRequestContext())?._handleStore?.trackAuxiliary(
+        promise,
+      );
+    }
+
     loaderPromises.set(loader.$$id, promise);
     return promise;
   }
@@ -504,24 +752,7 @@ export function setupLoaderAccess<TEnv>(
 
       return withDefer(
         (dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>)) => {
-          if (!store) return;
-
-          if (typeof dataOrFn === "function") {
-            // Run the callback inside the push-callback scope so ctx.use(loader)
-            // calls it makes — including after its own awaits, for an async
-            // callback — are not registered as handler-to-loader deps and do not
-            // trip the deadlock guard. A pushed promise value is not tracked by
-            // handleStore.settled and does not block segment resolution, so it
-            // cannot form a rendered() deadlock. The ALS scope (not a plain
-            // boolean) is what survives the callback's awaits.
-            const result = runInsidePushCallbackScope(() =>
-              (dataOrFn as () => Promise<unknown>)(),
-            );
-            store.push(handle.$$id, segmentId, result);
-            return;
-          }
-
-          store.push(handle.$$id, segmentId, dataOrFn);
+          pushHandleValue(store, segmentId, handle.$$id, dataOrFn);
         },
       );
     }
@@ -632,7 +863,9 @@ export function setupLoaderAccessSilent<TEnv>(
   ctx: HandlerContext<any, TEnv>,
   loaderPromises: Map<string, Promise<any>>,
 ): void {
-  const useLoader = createLoaderExecutor(ctx, loaderPromises);
+  const useLoader = createLoaderExecutor(ctx, loaderPromises, {
+    silentHandles: true,
+  });
 
   ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
     if (isHandle(item)) {

package/src/router/match-result.ts

@@ -111,6 +111,7 @@ import type { MatchResult, ResolvedSegment } from "../types.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
 import { debugLog } from "./logging.js";
 import { appendMetric } from "./metrics.js";
+import { collectInterceptTargetNames } from "./intercept-resolution.js";
 
 export async function collectSegments(
   generator: AsyncGenerator<ResolvedSegment>,
@@ -266,6 +267,11 @@ export function buildMatchResult<TEnv>(
     diff.push(s.id);
   }
 
+  // Intercept targets reachable when THIS location becomes a navigation
+  // origin — the browser-local clientUrls matcher declines its optimistic
+  // presentation for these (see collectInterceptTargetNames).
+  const interceptTargets = collectInterceptTargetNames(ctx.manifestEntry);
+
   return {
     segments: cleanedSegments,
     matched: matchedIds,
@@ -274,6 +280,7 @@ export function buildMatchResult<TEnv>(
     params: ctx.matched.params,
     routeName: ctx.routeKey,
     slots: Object.keys(state.slots).length > 0 ? state.slots : undefined,
+    ...(interceptTargets.length > 0 ? { interceptTargets } : {}),
     routeMiddleware:
       ctx.routeMiddleware.length > 0 ? ctx.routeMiddleware : undefined,
   };

package/src/router/revalidation.ts

@@ -96,8 +96,14 @@ interface EvaluateRevalidationOptions<TEnv> {
    * reason flows into the trace. Callers use this when client-knowledge
    * (e.g. parallel slot not in clientSegmentIds) should dictate the seed
    * instead of the params/method-based heuristic.
+   *
+   * `floor` makes a `true` seed a guarantee rather than a suggestion: user fns
+   * may raise the decision but never lower it. Set it when the segment has no
+   * client-side content to fall back on, so a `false` would render nothing
+   * instead of keeping a cached copy — see the parallel-slot call site in
+   * segment-resolution/revalidation.ts.
    */
-  defaultOverride?: { value: boolean; reason: string };
+  defaultOverride?: { value: boolean; reason: string; floor?: boolean };
 }
 
 /**
@@ -144,6 +150,20 @@ export async function evaluateRevalidation<TEnv>(
     });
   }
 
+  // A floored seed can only be raised, never lowered (see `defaultOverride`).
+  // Applied at every exit so one trace entry carries the real decision — a
+  // second, contradicting entry would let flushRevalidationTrace count the
+  // segment as both revalidated and skipped.
+  const floorTrue = defaultOverride?.floor === true && defaultOverride.value;
+  function decide(finalVal: boolean, reason: string): boolean {
+    if (floorTrue && !finalVal) {
+      pushTrace(defaultShouldRevalidate, true, `${reason}:floored`);
+      return true;
+    }
+    pushTrace(defaultShouldRevalidate, finalVal, reason);
+    return finalVal;
+  }
+
   let defaultShouldRevalidate: boolean;
   let defaultReason: string;
 
@@ -213,8 +233,7 @@ export async function evaluateRevalidation<TEnv>(
         segmentId: segment.id,
       });
     }
-    pushTrace(defaultShouldRevalidate, defaultShouldRevalidate, defaultReason);
-    return defaultShouldRevalidate;
+    return decide(defaultShouldRevalidate, defaultReason);
   }
 
   const prevSegment = getPrevSegment ? await getPrevSegment() : null;
@@ -303,8 +322,7 @@ export async function evaluateRevalidation<TEnv>(
         revalidator: name,
         revalidate: result,
       });
-      pushTrace(defaultShouldRevalidate, result, `hard:${name}`);
-      return result;
+      return decide(result, `hard:${name}`);
     } else if (
       result &&
       typeof result === "object" &&
@@ -330,10 +348,5 @@ export async function evaluateRevalidation<TEnv>(
     revalidate: currentSuggestion,
   });
   const softNames = revalidations.map((r) => r.name).join(",");
-  pushTrace(
-    defaultShouldRevalidate,
-    currentSuggestion,
-    `soft-chain:${softNames}`,
-  );
-  return currentSuggestion;
+  return decide(currentSuggestion, `soft-chain:${softNames}`);
 }