@rangojs/router 0.20.0 → 0.22.0

package/src/route-content-wrapper.tsx

@@ -1,7 +1,7 @@
 "use client";
-import type { ReactNode } from "react";
-import { Component, Suspense, use } from "react";
-import { OutletProvider } from "./outlet-provider.js";
+import type { ComponentProps, ReactElement, ReactNode } from "react";
+import { Component, Suspense, use, useMemo } from "react";
+import { AuditedOutletProvider, OutletProvider } from "./outlet-provider.js";
 import type { ResolvedSegment } from "./types.js";
 import {
   decodeLoaderResults,
@@ -10,6 +10,12 @@ import {
   LOADER_REDIRECT,
 } from "./decode-loader-results.js";
 import { LoaderRedirect } from "./loader-redirect.js";
+import type { BoundaryAudit } from "./suspense-audit.js";
+import {
+  AuditedFallback,
+  useBoundaryAudit,
+  useRevealAudit,
+} from "./suspense-audit-react.js";
 
 /**
  * Router-owned error boundary for read-site loader errors. segment-system
@@ -97,8 +103,8 @@ export function RouteContentWrapper({
   fallback,
   segmentId,
 }: {
-  // Normally a pending promise (use() suspends -> fallback). forceAwait paths
-  // pass an already-resolved node so Suspender renders it without suspending.
+  // A pending promise suspends (use()) and shows the fallback; a node renders
+  // without suspending (see getBoundaryContent).
   content: Promise<ReactNode> | ReactNode;
   fallback?: ReactNode;
   segmentId?: string;
@@ -113,19 +119,62 @@ export function RouteContentWrapper({
   );
 }
 
+// Dev only (suspense-audit.ts): RouteContentWrapper's Suspense, keys and
+// content, with the audit's hooks in components of their own.
+//
+// Chosen where the element is created, inside a NODE_ENV test, so a build
+// folds to the product component and nothing else. Two other ways leave
+// bytes in cloudflare-basic's router chunk, both measured: a dev branch
+// inside the product component (React Compiler runs before NODE_ENV is
+// folded and keeps the branch's memo slots, +76 B gzip), and one
+// `export const X = dev ? Audited : Product` per module (the alias statement
+// survives minification, +27 B gzip for three).
+//
+// Line comments on purpose, here and on the other dev-only declarations: the
+// server bundles are not minified and keep a JSDoc block even when the
+// declaration under it is removed.
+export function AuditedRouteContent({
+  content,
+  fallback,
+  segmentId,
+}: ComponentProps<typeof RouteContentWrapper>): ReactNode {
+  const audit = useBoundaryAudit(
+    `content:${segmentId}`,
+    segmentId ?? "",
+    content,
+  );
+  return (
+    <Suspense
+      fallback={
+        <AuditedFallback audit={audit}>{fallback ?? null}</AuditedFallback>
+      }
+      key={segmentId ? "route-content-suspense-" + segmentId : undefined}
+    >
+      <AuditedSuspender content={content} audit={audit} key={segmentId} />
+    </Suspense>
+  );
+}
+
+function AuditedSuspender({
+  content,
+  audit,
+}: {
+  content: Promise<ReactNode> | ReactNode;
+  audit: BoundaryAudit;
+}): ReactNode {
+  useRevealAudit(audit);
+  return Suspender({ content });
+}
+
 const Suspender = ({
   content,
 }: {
   content: Promise<ReactNode> | ReactNode;
 }): ReactNode => {
-  // Normally content is a pending promise -> use() suspends and the wrapping
-  // Suspense shows the loading() fallback. forceAwait paths (popstate,
-  // stale-revalidation, fully-prefetched nav) instead pass the ALREADY-RESOLVED
-  // node so first render does not suspend for a microtask and flash the loading()
-  // fallback on a NORMAL (non-transition) commit. The wrapper tree
-  // (RouteContentWrapper > Suspense > Suspender) is identical either way, so this
-  // preserves tree structure (see docs/tree-structure.md) — only whether use()
-  // suspends differs, exactly like LoaderResolver's resolved-data branch.
+  // A pending promise suspends here and the wrapping Suspense shows the
+  // loading() fallback; a node renders without suspending. The wrapper tree
+  // (RouteContentWrapper > Suspense > Suspender) is identical either way (see
+  // docs/tree-structure.md), like LoaderResolver's resolved-data branch.
   return content instanceof Promise ? use(content) : content;
 };
 
@@ -191,6 +240,51 @@ export function LoaderBoundary({
   );
 }
 
+// Dev only (suspense-audit.ts): LoaderBoundary, as AuditedRouteContent.
+export function AuditedLoaderBoundary({
+  fallback,
+  children,
+  ...resolver
+}: LoaderBoundaryProps): ReactNode {
+  const nodes = useMemo(
+    () => [children, resolver.outletContent],
+    [children, resolver.outletContent],
+  );
+  const audit = useBoundaryAudit(
+    `loaders:${resolver.outletKey}`,
+    resolver.segment.id,
+    resolver.loaderDataPromise,
+    resolver.loaderStreams,
+    nodes,
+  );
+  return (
+    <Suspense
+      fallback={
+        <AuditedFallback audit={audit}>{fallback ?? null}</AuditedFallback>
+      }
+      key={`loader-boundary-${resolver.outletKey}`}
+    >
+      <AuditedLoaderResolver audit={audit} {...resolver}>
+        {children}
+      </AuditedLoaderResolver>
+    </Suspense>
+  );
+}
+
+function AuditedLoaderResolver({
+  audit,
+  ...props
+}: Omit<LoaderBoundaryProps, "fallback"> & {
+  audit: BoundaryAudit;
+}): ReactNode {
+  useRevealAudit(audit);
+  // The resolver's OutletProvider, as its audited component.
+  const outlet = LoaderResolver(props) as ReactElement<
+    ComponentProps<typeof OutletProvider>
+  >;
+  return <AuditedOutletProvider {...outlet.props} key={outlet.key} />;
+}
+
 /**
  * Internal component that resolves loader promises and renders OutletProvider
  *

package/src/router/error-handling.ts

@@ -271,6 +271,17 @@ export function createErrorInfo(
   };
 }
 
+/** Invoke an errorBoundary() fallback that may be a handler or a plain node. */
+export function renderErrorFallback(
+  fallback: ReactNode | ErrorBoundaryHandler,
+  errorInfo: ErrorInfo,
+): ReactNode {
+  if (typeof fallback === "function") {
+    return fallback({ error: errorInfo } satisfies ErrorBoundaryFallbackProps);
+  }
+  return fallback;
+}
+
 /**
  * Create an error segment with the fallback component
  * Renders the fallback with error info and reset function
@@ -281,23 +292,12 @@ export function createErrorSegment(
   entry: EntryData,
   params: Record<string, string>,
 ): ResolvedSegment {
-  let component: ReactNode;
-
-  if (typeof fallback === "function") {
-    const props: ErrorBoundaryFallbackProps = {
-      error: errorInfo,
-    };
-    component = fallback(props);
-  } else {
-    component = fallback;
-  }
-
   return {
     id: entry.shortCode,
     namespace: entry.id,
     type: "error",
     index: 0,
-    component,
+    component: renderErrorFallback(fallback, errorInfo),
     params,
     error: errorInfo,
   };

package/src/router/find-match.ts

@@ -159,6 +159,7 @@ export function createFindMatch<TEnv = any>(
             redirectTo: trieResult.redirectTo,
             ...(trieResult.pr ? { pr: true } : {}),
             ...(trieResult.pt ? { pt: true } : {}),
+            ...(trieResult.od ? { od: true } : {}),
             ...(trieResult.responseType
               ? { responseType: trieResult.responseType }
               : {}),

package/src/router/handler-context.ts

@@ -383,6 +383,7 @@ export function createPrerenderContext<TEnv>(
   isPassthroughRoute?: boolean,
   buildEnv?: TEnv,
   devMode?: boolean,
+  onDemand?: boolean,
 ): InternalHandlerContext<any, TEnv> {
   const syntheticUrl = new URL(`http://prerender${pathname}`);
   const variables = buildVars ?? {};
@@ -401,6 +402,7 @@ export function createPrerenderContext<TEnv>(
     // gate. dynamic() only reaches the shell axis on a live request or capture.
     dynamic: () => {},
     dev: devMode ?? false,
+    onDemand: onDemand ?? false,
     get request(): Request {
       return throwUnavailable("request");
     },

package/src/router/intercept-resolution.ts

@@ -27,6 +27,7 @@ import {
   buildLoaderErrorContext,
 } from "./segment-resolution.js";
 import { catchSegmentError } from "./segment-resolution/helpers.js";
+import { trackStreamedHandler } from "./segment-resolution/streamed-handler-boundary.js";
 import { findInOrphans } from "./error-handling.js";
 import { resolveLoaderData } from "./segment-resolution/loader-cache.js";
 import type { SegmentResolutionDeps } from "./types.js";
@@ -390,14 +391,20 @@ export async function resolveInterceptEntry<TEnv>(
 
   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, {
+  // A streamed (loading()) handler resolves after the 200 has started: tracked
+  // like route handlers (onError report, handle-store completion) and
+  // recovered into the declared boundary, except on the skipMiddleware
+  // background re-render, which must reject so a failure is never cached.
+  const streamedComponent = (promise: Promise<unknown>): ReactNode =>
+    trackStreamedHandler(deps, promise, {
+      boundaryEntry: parentEntry,
       segmentId: `${parentEntry.shortCode}.${interceptEntry.slotName}`,
       segmentType: "parallel",
-    }) as ReactNode;
+      context,
+      routeKey: interceptEntry.routeName,
+      params,
+      recover: !options?.skipMiddleware,
+    });
 
   if (interceptEntry.loading && loaderPromises.length > 0) {
     if (handlerResult instanceof Promise) {
@@ -408,11 +415,11 @@ export async function resolveInterceptEntry<TEnv>(
     }
     component =
       handlerResult instanceof Promise
-        ? trackStreamedHandler(handlerResult)
+        ? streamedComponent(handlerResult)
         : (Promise.resolve(handlerResult) as ReactNode);
     loaderDataPromise = Promise.all(loaderPromises);
   } else if (interceptEntry.loading && handlerResult instanceof Promise) {
-    component = trackStreamedHandler(handlerResult);
+    component = streamedComponent(handlerResult);
   } else {
     if (loaderPromises.length > 0) {
       loaderDataPromise = await Promise.all(loaderPromises);

package/src/router/loader-resolution.ts

@@ -29,7 +29,6 @@ import type {
   LoaderContext,
   LoaderDataResult,
   ErrorBoundaryHandler,
-  ErrorBoundaryFallbackProps,
   ErrorInfo,
   NotFoundBoundaryHandler,
   NotFoundBoundaryFallbackProps,
@@ -44,6 +43,7 @@ import {
 } from "../redirect-origin.js";
 import {
   createNotFoundInfo,
+  renderErrorFallback,
   renderNotFoundFallback,
   resolveNotFoundFallback,
 } from "./error-handling.js";
@@ -302,15 +302,7 @@ export function wrapLoaderWithErrorHandling<T>(
       // error, and the wrapped promise still resolves to a LoaderDataResult.
       let renderedFallback: ReactNode;
       try {
-        if (typeof fallback === "function") {
-          // ErrorBoundaryHandler - call with error info
-          const props: ErrorBoundaryFallbackProps = {
-            error: errorInfo,
-          };
-          renderedFallback = fallback(props);
-        } else {
-          renderedFallback = fallback;
-        }
+        renderedFallback = renderErrorFallback(fallback, errorInfo);
       } catch (fallbackError) {
         debugLog("loader", "error boundary fallback render threw", {
           segmentId,

package/src/router/manifest.ts

@@ -38,6 +38,8 @@ const MODULE_LOAD_FAILURE = Symbol.for("rango.moduleLoadFailure");
 // LP1 in docs/internal/matching-and-lazy-discovery.md. VERSION comes from the
 // @rangojs/router:version virtual module which Vite invalidates on RSC module HMR.
 // When VERSION changes, this module re-evaluates and the cache is recreated empty.
+// Dev module generation only: in production VERSION is constant per process, so
+// the per-router cache versions play no part in this cache.
 const manifestModuleCache = new Map<string, Map<string, EntryData>>();
 
 /**

package/src/router/match-middleware/background-revalidation.ts

@@ -171,6 +171,8 @@ export async function rerenderAndCacheRoute<TEnv>(
     {
       _handleStore: handleStore,
       _metricsStore: undefined,
+      _renderErrors: [],
+      _recoveredHandlerErrors: undefined,
       _onResponseCallbacks: [],
       header: sink.header,
       setCookie: sink.setCookie,