@rangojs/router 0.26.1 → 0.26.3

package/src/rsc/render-pipeline.ts

@@ -2,6 +2,7 @@ import { appendMetric } from "../router/metrics.js";
 import type { MetricsStore } from "../server/context.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import { _getRequestContext } from "../server/request-context.js";
+import { printServerError } from "../server/print-server-error.js";
 import type { TraceSpan } from "../router/tracing.js";
 import type { RenderMode, RenderPhase } from "../router/timeout.js";
 import type { HandlerContext } from "./handler-context.js";
@@ -156,11 +157,18 @@ function createFlightStage<TEnv>(
     input.payload.metadata.devDiscoveryEpoch = input.ctx.devDiscoveryEpoch;
   }
   // Read once here: onError can fire outside the ALS frame.
-  const renderErrors = _getRequestContext()?._renderErrors;
+  const requestContext = _getRequestContext();
+  const renderErrors = requestContext?._renderErrors;
   const stream = input.ctx.renderToReadableStream<RscPayload>(input.payload, {
     temporaryReferences: input.temporaryReferences,
     onError: (error: unknown) => {
       renderErrors?.push(error);
+      // The client gets a masked copy (an error row); the original prints here.
+      printServerError(
+        error,
+        { label: "Rendering error", pathname: input.url.pathname },
+        requestContext,
+      );
       input.ctx.callOnError(error, "rendering", {
         request: input.request,
         url: input.url,

package/src/rsc/rsc-rendering.ts

@@ -28,6 +28,7 @@ import { getSSRSetup, createSsrHtmlStage, isRscRequest } from "./ssr-setup.js";
 import type { RscPayload } from "./types.js";
 import type { SSRModule } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
+import { markServerErrorPrinted } from "../server/print-server-error.js";
 import type { PprReplayBypassReason } from "./shell-capture-constants.js";
 import {
   createResponseWithMergedHeaders,
@@ -1988,8 +1989,11 @@ function serveShellHit(
         // The HIT request's origin — same host as the capture's (key-scoped).
         origin: url.origin,
         // The document cache reads the list before storing this composite.
+        // resumeShellHTML printed what started in the resume, or it is a copy
+        // whose original printed upstream: a refusing writer prints nothing.
         onError: (error) => {
           reqCtx._renderErrors?.push(error);
+          markServerErrorPrinted(error, reqCtx);
         },
       }),
     );

package/src/rsc/server-action.ts

@@ -17,9 +17,11 @@
 
 import { requestHeaders } from "../server/request-headers.js";
 import {
+  _getRequestContext,
   getRequestContext,
   setRequestContextParams,
 } from "../server/request-context.js";
+import { printServerError } from "../server/print-server-error.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import { resolveActionRefId } from "../router/is-action.js";
 import type { TraceSpan } from "../router/tracing.js";
@@ -161,6 +163,12 @@ export async function executeServerAction<TEnv>(
       actionId,
       handledByBoundary: !!decodeBoundary,
     });
+    // The server log gets the decode error itself, not the sanitized wrapper.
+    printServerError(
+      error,
+      { label: "Action decode error", name: actionId, pathname: url.pathname },
+      _getRequestContext(),
+    );
 
     if (decodeBoundary) {
       return {
@@ -248,6 +256,14 @@ export async function executeServerAction<TEnv>(
 
     returnValue = { ok: false, data: actionResultData };
     actionStatus = 500;
+    // Flight writes the error into the action's result without reporting it:
+    // printed here, once. A thrown non-redirect Response prints the Error that
+    // replaced it.
+    printServerError(
+      actionResultData,
+      { label: "Action error", name: actionId, pathname: url.pathname },
+      _getRequestContext(),
+    );
 
     // Try to render error boundary.
     // Report the action error first so it is not lost if matchError throws.

package/src/rsc/ssr-setup.ts

@@ -23,6 +23,7 @@ import {
 } from "../router/content-negotiation.js";
 import { _getRequestContext } from "../server/request-context.js";
 import { renderedLocation } from "./full-payload.js";
+import { markServerErrorPrinted } from "../server/print-server-error.js";
 
 export type SSRSetup = readonly [SSRModule, SSRStreamMode];
 
@@ -134,9 +135,30 @@ export function createSsrHtmlStage<TEnv>(
           origin: location.origin,
           // A component that throws inside a Suspense boundary leaves an
           // errored boundary in a completed document; the document cache
-          // reads the list before storing it.
+          // reads the list before storing it. renderHTML printed what Fizz
+          // reports, or it was printed where it originated (a loader's or a
+          // Flight copy), so the writer that refuses it prints nothing more.
           onError: (error) => {
             renderErrors?.push(error);
+            markServerErrorPrinted(error, reqCtx);
+          },
+          // Reported once, phase "rendering", only when the error started in
+          // the SSR render: a copy (a loader's masked rebuild, a Flight error,
+          // a payload failure) was reported with its original where it started,
+          // and a loader's notFound()/redirect() is control flow. Marked
+          // printed, so the handler's catch neither reports nor prints what
+          // dev rethrows.
+          onShellError: ({ error, originated, status, location }) => {
+            if (status !== undefined) reqCtx?._setStatus(status);
+            if (location) reqCtx?.res.headers.set("Location", location);
+            markServerErrorPrinted(error, reqCtx);
+            if (!originated) return;
+            options.ctx.callOnError(error, "rendering", {
+              request: options.request,
+              url: options.url,
+              env: options.env,
+              handledByBoundary: false,
+            });
           },
         }),
       ...(options.init && { init: options.init }),

package/src/rsc/types.ts

@@ -215,6 +215,21 @@ export interface SSRRenderOptions {
    * otherwise completed document. React's default console.error is kept.
    */
   onError?: (error: unknown) => void;
+
+  /**
+   * Called once when the render failed before any HTML was produced (a shell
+   * error), before renderHTML answers it with a recovery document or rethrows
+   * it to the host (dev). `status` and `location` are the answer's, absent on
+   * a rethrow. `originated`: the error started in this render; a copy (a
+   * loader's masked rebuild, an error Flight decoded, a payload that did not
+   * decode) was reported where it started. See ssr/shell-error-document.tsx.
+   */
+  onShellError?: (shellError: {
+    error: unknown;
+    originated: boolean;
+    status?: number;
+    location?: string;
+  }) => void;
 }
 
 /**

package/src/server/print-server-error.ts

@@ -0,0 +1,87 @@
+/**
+ * The server console's record of a failure: its original error, message and
+ * stack, printed once per request where it originated, in dev and production.
+ * Only what reaches the client is masked (router/error-handling.ts
+ * createErrorInfo, React's Flight error rows). A leaf module: the cache layer
+ * reads it too.
+ */
+import { isAbortedRender, isLoaderSignalError, isSkip } from "../errors.js";
+
+/** The request context fields the record reads. */
+interface PrintContext {
+  /** The errors this request printed (request-context.ts). */
+  _printedErrors?: WeakSet<object>;
+  request?: Request;
+}
+
+/**
+ * Control flow, never printed: notFound(), a redirect (a thrown Response or a
+ * loader's redirect marker), Skip, and the render's own cancellation.
+ */
+function isControlFlow(
+  error: unknown,
+  requestContext: PrintContext | undefined,
+): boolean {
+  return (
+    error instanceof Response ||
+    isLoaderSignalError(error) ||
+    isSkip(error) ||
+    isAbortedRender(error, requestContext?.request?.signal)
+  );
+}
+
+function printedSet(
+  requestContext: PrintContext | undefined,
+): WeakSet<object> | undefined {
+  if (!requestContext) return undefined;
+  return (requestContext._printedErrors ??= new WeakSet());
+}
+
+/**
+ * Print a server-side failure where it originates:
+ * `[RSC] <label> (<name>) <pathname>:` and the error object. Once per request:
+ * another place that sees the same error object in `requestContext` prints
+ * nothing more. A caller that can run outside the request's ALS frame (a
+ * Flight onError) passes the context it captured.
+ */
+export function printServerError(
+  error: unknown,
+  origin: { label: string; name?: string; pathname?: string },
+  requestContext: PrintContext | undefined,
+): void {
+  if (isControlFlow(error, requestContext)) return;
+  if (typeof error === "object" && error !== null) {
+    const printed = printedSet(requestContext);
+    if (printed?.has(error)) return;
+    printed?.add(error);
+  }
+  const name = origin.name ? ` (${origin.name})` : "";
+  const path = origin.pathname ? ` ${origin.pathname}` : "";
+  console.error(`[RSC] ${origin.label}${name}${path}:`, error);
+}
+
+/**
+ * Record an error this module did not print as done: the SSR render printed it
+ * in its own module graph, or it is a copy (a loader's masked rebuild, an
+ * error Flight decoded) whose original printed where it started.
+ */
+export function markServerErrorPrinted(
+  error: unknown,
+  requestContext: PrintContext | undefined,
+): void {
+  if (typeof error === "object" && error !== null) {
+    printedSet(requestContext)?.add(error);
+  }
+}
+
+/** Whether this request printed `error`, or recorded it as done. */
+export function wasServerErrorPrinted(
+  error: unknown,
+  requestContext: PrintContext | undefined,
+): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    requestContext?._printedErrors?.has(error) === true
+  );
+}

package/src/server/request-context.ts

@@ -909,6 +909,12 @@ export interface RequestContext<
   /** @internal Per-request error dedup set for onError reporting */
   _reportedErrors: WeakSet<object>;
 
+  /**
+   * @internal The errors this request printed to the server console, so a
+   * failure prints once where it originated (server/print-server-error.ts). A derived context shares it through the prototype.
+   */
+  _printedErrors?: WeakSet<object>;
+
   /**
    * @internal Errors this response's Flight or Fizz render reported through
    * onError: a component that threw does not fail the stream, which completes
@@ -1090,6 +1096,7 @@ export type PublicRequestContext<
   | "_inActionRevalidation"
   | "_actionRan"
   | "_reportedErrors"
+  | "_printedErrors"
   | "_renderErrors"
   | "_recoveredHandlerErrors"
   | "_renderBarrier"
@@ -1828,6 +1835,7 @@ export function createRequestContext<TEnv>(
     _locationState: undefined,
 
     _reportedErrors: new WeakSet<object>(),
+    _printedErrors: new WeakSet<object>(),
     _renderErrors: [],
     _metricsStore: undefined,
     _renderForeground: undefined,

package/src/ssr/index.tsx

@@ -12,6 +12,16 @@ import {
   SHELL_CAPTURE_MAX_WAIT_MS,
 } from "../rsc/shell-capture-constants.js";
 import { isThenable } from "../handles/is-thenable.js";
+import {
+  isAbortedRender,
+  isFlightDecodedError,
+  isLoaderSignalError,
+} from "../errors.js";
+import { isRebuiltLoaderError } from "../decode-loader-results.js";
+import {
+  answerShellError,
+  type ShellErrorRecovery,
+} from "./shell-error-document.js";
 import type { ErrorPhase } from "../types.js";
 import type { HeadScriptsOption } from "../vite/plugin-types.js";
 
@@ -141,6 +151,21 @@ export interface SSRRenderOptions {
    * otherwise completed document. React's default console.error is kept.
    */
   onError?: (error: unknown) => void;
+
+  /**
+   * Called once when the render failed before any HTML was produced (a shell
+   * error), before renderHTML answers it or rethrows it. `status` and
+   * `location` are the answer's; both are absent when the error is rethrown
+   * to the host (dev). `originated`: the error started in this render. When
+   * false it is a copy (a loader's masked rebuild, an error Flight decoded, a
+   * payload that did not decode) whose original was reported where it started.
+   */
+  onShellError?: (shellError: {
+    error: unknown;
+    originated: boolean;
+    status?: number;
+    location?: string;
+  }) => void;
 }
 
 /**
@@ -459,6 +484,23 @@ async function settleSsrFalseFirstFlush(
   }
 }
 
+/**
+ * Whether this render prints `error`. A failure prints once, where it
+ * originated: what reaches the SSR render from the server is a copy (a
+ * loader's masked rebuild, an error Flight decoded) whose original the server
+ * printed, and a loader's notFound()/redirect() is control flow, as is the
+ * render's own abort. A component that throws during this render is the
+ * original.
+ */
+function originatedHere(error: unknown): boolean {
+  return (
+    !isLoaderSignalError(error) &&
+    !isRebuiltLoaderError(error) &&
+    !isFlightDecodedError(error) &&
+    !isAbortedRender(error)
+  );
+}
+
 /**
  * Route an SSR error through the deps.onError notification callback with the
  * "rendering" phase. Swallows callback failures so a broken reporter never
@@ -849,13 +891,22 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       search,
       origin,
       onError: onRenderError,
+      onShellError,
     } = options ?? {};
 
+    // What a shell error is answered with (ssr/shell-error-document.tsx).
+    let flight: ReadableStream<Uint8Array> | undefined;
+    let recovery: ShellErrorRecovery | undefined;
+    let payloadFailed = false;
+    // The errors Fizz reported, which its onError below printed.
+    let reportedByFizz: Set<unknown> | undefined;
+
     try {
       // Tee the stream:
       // - rscStream1: For SSR rendering (deserialize to React VDOM)
       // - rscStream2: For browser hydration (inject as __FLIGHT_DATA__)
       const [rscStream1, rscStream2] = rscStream.tee();
+      flight = rscStream2;
 
       // Deserialization starts here (not lazily on SsrRoot's first render) so
       // the auto-raise below can read payload metadata before the fizz call.
@@ -880,6 +931,10 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
         // tree while static-part search reads render what the key names.
         search,
         origin,
+        // Runs before Fizz rejects (attached when the tree build starts).
+        onTreeError: () => {
+          recovery = undefined;
+        },
       });
 
       const bootstrap = await resolveBootstrap(deps);
@@ -888,7 +943,18 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       // Awaiting the payload here is latency-neutral: fizz cannot emit even
       // <html> until this same promise settles. A rejection lands in the
       // catch below — the same reportRenderError path a shell error takes.
-      const awaitsBeforeFlush = hasAwaitBeforeFlush(await payload);
+      let decoded: Awaited<typeof payload>;
+      try {
+        decoded = await payload;
+      } catch (error) {
+        payloadFailed = true;
+        throw error;
+      }
+      recovery = {
+        bootstrap,
+        themeConfig: decoded.metadata?.themeConfig ?? null,
+      };
+      const awaitsBeforeFlush = hasAwaitBeforeFlush(decoded);
       const progressiveChunkSize =
         deps.progressiveChunkSize ??
         (awaitsBeforeFlush ? Number.MAX_SAFE_INTEGER : undefined);
@@ -904,13 +970,12 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
           formState,
           nonce,
           ...(progressiveChunkSize !== undefined && { progressiveChunkSize }),
-          ...(onRenderError && {
-            onError: (error: unknown) => {
-              onRenderError(error);
-              // What React's default onError does (it only logs).
-              console.error(error);
-            },
-          }),
+          onError: (error: unknown) => {
+            onRenderError?.(error);
+            (reportedByFizz ??= new Set()).add(error);
+            // What React's default onError does (it only logs).
+            if (originatedHere(error)) console.error(error);
+          },
         }),
       );
 
@@ -938,12 +1003,49 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       // Inject RSC payload into HTML as <script nonce="...">__FLIGHT_DATA__</script>
       return html.pipeThrough(injectRSCPayload(rscStream2, { nonce }));
     } catch (error) {
-      reportRenderError(onError, error);
-      throw error;
+      // Fizz printed what it reported. Printed here: what never reached Fizz
+      // and started in this render, a bootstrap failure or a payload that did
+      // not decode without a Flight error row (no `digest`: the stream broke).
+      // A Flight copy printed with its original in the Flight render. The
+      // handler's catch skips what the html stage marked printed.
+      if (!isLoaderSignalError(error)) reportRenderError(onError, error);
+      if (originatedHere(error) && !reportedByFizz?.has(error)) {
+        console.error(error);
+      }
+      const originated = !payloadFailed && originatedHere(error);
+      if (shellErrorReachesHost(error)) {
+        onShellError?.({ error, originated });
+        throw error;
+      }
+      const answer = await answerShellError(
+        deps,
+        error,
+        recovery,
+        flight,
+        nonce,
+      );
+      onShellError?.({
+        error,
+        originated,
+        status: answer.status,
+        location: answer.location,
+      });
+      return answer.body;
     }
   };
 }
 
+/**
+ * In dev a shell error reaches the host as the original error object,
+ * so Vite's overlay shows its message and source-mapped stack. A loader's
+ * notFound()/redirect() is control flow and is answered as in production.
+ * This is the one gate: returning false here makes dev answer every shell
+ * error as production does.
+ */
+function shellErrorReachesHost(error: unknown): boolean {
+  return process.env.NODE_ENV !== "production" && !isLoaderSignalError(error);
+}
+
 /**
  * Create the PPR shell capture handler.
  *
@@ -1269,6 +1371,7 @@ export function createShellResumeHandler<TEnv = unknown>(
               onError: (error) => {
                 opts.onError?.(error);
                 reportRenderError(onError, error);
+                if (originatedHere(error)) console.error(error);
               },
               nonce,
             }),

package/src/ssr/shell-error-document.tsx

@@ -0,0 +1,139 @@
+/**
+ * What renderHTML answers when React's server render fails its shell: an
+ * error with no `<Suspense>` above it (a loader read, a component that throws
+ * only on the server). Fizz runs no error boundaries, so renderToReadableStream
+ * rejects; rethrown, the host would answer its own raw 500 (a stack with
+ * server paths in production).
+ *
+ * The answer, in order:
+ * - a loader `redirect()` with no state: a real 3xx (nothing has been sent);
+ * - the payload decoded and the tree built: a recovery document carrying the
+ *   same Flight payload, which the browser entry renders with createRoot
+ *   (`data-rango-ssr-error`), so the router's client boundaries run as on a
+ *   client navigation to the URL (the Next.js `__next_error__` design);
+ * - otherwise: a static document with no scripts and nothing from the error.
+ */
+import React from "react";
+import { isDataNotFoundError } from "../errors.js";
+import { loaderRedirectOf } from "../decode-loader-results.js";
+import { ThemeScript } from "../theme/ThemeScript.js";
+import type { ResolvedThemeConfig } from "../theme/types.js";
+import type { SSRDependencies } from "./index.js";
+
+/**
+ * Read by the browser entry (vite/plugins/virtual-entries.ts): render the
+ * document, do not hydrate it.
+ */
+const SSR_ERROR_ATTRIBUTE = "data-rango-ssr-error";
+
+/** What renderHTML answered a shell error with. */
+export interface ShellErrorAnswer {
+  body: ReadableStream<Uint8Array>;
+  status: number;
+  location?: string;
+}
+
+/**
+ * What a recovery document needs. Absent when the payload did not decode or
+ * the tree build rejected: the browser builds the same tree from the same
+ * payload and would reject the same way.
+ */
+export interface ShellErrorRecovery {
+  bootstrap: { bootstrapScriptContent?: string; bootstrapModules?: string[] };
+  themeConfig: ResolvedThemeConfig | null;
+}
+
+type ShellErrorRenderDeps = Pick<
+  SSRDependencies,
+  "renderToReadableStream" | "injectRSCPayload"
+>;
+
+const HEADINGS: Record<number, string> = {
+  200: "Redirecting",
+  404: "Not Found",
+  500: "Internal Server Error",
+};
+
+function staticErrorDocument(status: number): ReadableStream<Uint8Array> {
+  return new Response(
+    `<!DOCTYPE html><html ${SSR_ERROR_ATTRIBUTE}=""><head><meta charset="utf-8"/>` +
+      `<title>${HEADINGS[status]}</title></head><body><h1>${HEADINGS[status]}</h1></body></html>`,
+  ).body!;
+}
+
+/**
+ * The recovery document: the bootstrap scripts, the untouched second branch
+ * of the Flight tee, and the heading only in <noscript>, so a JavaScript
+ * visitor sees the client render's boundary without a flash of it. The theme
+ * script runs here, as the document's own does on a hydrated page: the client
+ * render inserts the root layout's inline scripts without running them.
+ */
+async function renderRecoveryDocument(
+  deps: ShellErrorRenderDeps,
+  recovery: ShellErrorRecovery,
+  flight: ReadableStream<Uint8Array>,
+  status: number,
+  nonce: string | undefined,
+): Promise<ReadableStream<Uint8Array>> {
+  const html = await deps.renderToReadableStream(
+    <html {...{ [SSR_ERROR_ATTRIBUTE]: "" }}>
+      <head>
+        <meta charSet="utf-8" />
+        {recovery.themeConfig && (
+          <ThemeScript config={recovery.themeConfig} nonce={nonce} />
+        )}
+      </head>
+      <body>
+        <noscript>
+          <h1>{HEADINGS[status]}</h1>
+        </noscript>
+      </body>
+    </html>,
+    { ...recovery.bootstrap, nonce },
+  );
+  return html.pipeThrough(deps.injectRSCPayload(flight, { nonce }));
+}
+
+/** Answer a shell error; see the module comment for the order. */
+export async function answerShellError(
+  deps: ShellErrorRenderDeps,
+  error: unknown,
+  recovery: ShellErrorRecovery | undefined,
+  flight: ReadableStream<Uint8Array> | undefined,
+  nonce: string | undefined,
+): Promise<ShellErrorAnswer> {
+  // A redirect with state keeps the recovery document: the state rides the
+  // history entry the client replace writes, which a 3xx cannot. Without
+  // this branch every loader redirect takes the client replace.
+  const redirect = loaderRedirectOf(error);
+  if (redirect && redirect.state === undefined) {
+    flight?.cancel().catch(() => {});
+    return {
+      body: new Response("").body!,
+      status: redirect.status ?? 302,
+      location: redirect.to,
+    };
+  }
+  // A redirect with state answers 200 like the same redirect inside a
+  // <Suspense>: the document, then the client replace.
+  const status = redirect ? 200 : isDataNotFoundError(error) ? 404 : 500;
+  if (recovery && flight) {
+    try {
+      return {
+        body: await renderRecoveryDocument(
+          deps,
+          recovery,
+          flight,
+          status,
+          nonce,
+        ),
+        status,
+      };
+    } catch {
+      // The static document below.
+    }
+  }
+  flight?.cancel().catch(() => {});
+  const failed = redirect ? 500 : status;
+  return { body: staticErrorDocument(failed), status: failed };
+}

package/src/ssr/ssr-root.tsx

@@ -221,6 +221,12 @@ export interface SsrRootOptions {
    * live fizz passes the request's origin; capture/resume pass theirs.
    */
   origin?: string;
+  /**
+   * Called when the segment tree build rejects. renderHTML answers that shell
+   * error with a static document: the browser builds the same tree from the
+   * same payload and would reject the same way (ssr/shell-error-document.tsx).
+   */
+  onTreeError?: (error: unknown) => void;
 }
 
 /**
@@ -248,6 +254,7 @@ export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
     onPayloadSettled,
     search,
     origin,
+    onTreeError,
   } = opts;
 
   // onPayloadSettled fires AFTER fragment expansion (inside
@@ -308,11 +315,14 @@ export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
     // Memoize like payload/handles above: renderSegments is async, so
     // React.use() on a fresh promise suspends and replays SsrRoot, which
     // would re-run the entire segment-tree build on every initial render.
-    rootPromise ??= Promise.resolve(
-      renderSegments(resolved.metadata?.segments ?? [], {
-        rootLayout: resolved.metadata?.rootLayout,
-      }),
-    );
+    if (!rootPromise) {
+      rootPromise = Promise.resolve(
+        renderSegments(resolved.metadata?.segments ?? [], {
+          rootLayout: resolved.metadata?.rootLayout,
+        }),
+      );
+      if (onTreeError) rootPromise.catch(onTreeError);
+    }
     let content: React.ReactNode = React.use(rootPromise);
 
     // Wrap content with ThemeProvider if theme is enabled