@rangojs/router 0.26.2 → 0.26.3

package/skills/testing/client-components.md

@@ -2,7 +2,7 @@
 
 **Layer:** unit (DOM) · **Import:** `@rangojs/router/testing/dom` · **DSL it tests:** a client component reading router context (see `/hooks`)
 
-`renderRoute(routes, options?)` is an RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter`), and it is async — `await` it. It mounts the router's REAL `NavigationProvider` plus a synthetic segment tree built from the `routes` you pass, so client hooks resolve against production context — no server, no Vite build, no Flight round-trip. Loader data, location state, and handle output are SEEDED into client context; nothing is executed. With `hydrate: true` it renders that same tree to HTML first and hydrates it ([Hydration](#hydration)).
+`renderRoute(routes, options?)` is an RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter`), and it is async — `await` it. It mounts the router's REAL `NavigationProvider` plus a synthetic segment tree built from the `routes` you pass, so client hooks resolve against production context — no server, no Vite build, no Flight round-trip. Loader data, location state, and handle output are SEEDED into client context; nothing is executed. With `hydrate: true` it renders that same tree to HTML first and hydrates it, or renders it as production's recovery document when that pass throws ([Hydration](#hydration)).
 
 ## API
 
@@ -25,7 +25,7 @@
 | `theme`           | `ThemeConfig \| true`                                                  | Theme config (`createRouter({ theme })` shape) to wrap the tree in a `ThemeProvider`. Defaults to no provider. A component calling `useTheme()` REQUIRES one.                                                                                 |
 | `nonce`           | `string`                                                               | CSP nonce to seed via `NonceContext`, so a component calling `useNonce()` (e.g. an analytics/GTM head script) sees it — mirroring SSR. Defaults to `undefined` (the browser default).                                                         |
 | `defaultPrefetch` | `PrefetchStrategy`                                                     | Router default for `<Link>` and eligible plain anchors. `data-prefetch="false"`/`"none"` opts out one anchor; ancestor `data-prefetch-scope="false"`/`"none"` hard-disables the subtree; `"true"` permits routed resource suffixes elsewhere. |
-| `hydrate`         | `boolean`                                                              | Render the same tree to HTML first (`renderToString`, no `window`/`document`), then hydrate that HTML instead of mounting fresh. The result gains `serverHtml` and `recoverableErrors`. See [Hydration](#hydration).                          |
+| `hydrate`         | `boolean`                                                              | Render the same tree to HTML first (`renderToString`, no `window`/`document`), then hydrate that HTML instead of mounting fresh. The result gains `serverHtml`, `recoverableErrors` and `shellError`. See [Hydration](#hydration).            |
 | `rewrite`         | `string`                                                               | The path middleware rewrote `request` to (`throw rewrite()`): the leaf is matched against it for params, while the location (`usePathname`, `useSearchParams`) stays `request`, as a rewritten document renders and hydrates.                 |
 
 `RenderRouteSpec = { path, Component, layout?, loaderIds?, name?, transition? }` — one node of the route definition. The array is the layout chain root-to-leaf; the LAST entry is the leaf route (its pattern is matched against `request` to extract params; layout patterns are informational). `loaderIds` attaches seeded loaders to THIS node's segment; `layout` on the leaf wraps it; `name` is informational. `transition` is the `transition()` config this node declares (`{}` for a bare `transition()`), attached to its segment exactly as the DSL does — see [Held navigation](#held-navigation).
@@ -296,20 +296,21 @@ it("hydrates as the server rendered it, then shows the stored count", async () =
 });
 ```
 
-| In your component                                                                     | Under `hydrate: true`                                                                                                                                                                                                                        |
-| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `typeof window` / `typeof document` in render                                         | `"undefined"` in the server pass: both globals are removed for it and restored before hydration. A branch renders its server side; if the client side differs, React reports the mismatch.                                                   |
-| An unguarded `window.x` / `document.x` in render                                      | Throws `ReferenceError` in the server pass, as in SSR. Inside a `<Suspense>` the boundary is client-rendered and reported; outside one `renderRoute` rejects.                                                                                |
-| Hydration adopts the server HTML                                                      | `hydrateRoot` adopts the server-rendered DOM nodes instead of replacing them, and `recoverableErrors` stays empty; a client render of the same tree would replace the nodes.                                                                 |
-| A text or element mismatch                                                            | React re-renders that tree on the client and reports it: `recoverableErrors` gets `"Hydration failed because ..."` with the diff.                                                                                                            |
-| An attribute-only mismatch (`className`, `href`)                                      | NOT in `recoverableErrors`. React keeps the server attribute and logs `console.error` in development; assert it with `vi.spyOn(console, "error")`.                                                                                           |
-| `<Suspense>` whose content renders synchronously                                      | In `serverHtml`. It hydrates in a later pass than the tree above it, after that tree's effects, before `renderRoute` resolves.                                                                                                               |
-| Content that suspends in the server pass (`lazy`, a pending or plain `use()` promise) | NOT hydrated: `serverHtml` has the fallback, the client renders the content, and `recoverableErrors` reports the boundary. With no `<Suspense>` above it `renderRoute` rejects. A settled promise (Caveats, below) stays in the server HTML. |
-| Render counts and module state                                                        | Every component renders once in the server pass before its hydration render. Both passes share one module realm, so module state written while rendering is still there at hydration.                                                        |
-| `history`, `localStorage`, `navigator` read outside a server snapshot                 | FIDELITY LIMIT: still defined in the server pass (only `window` and `document` are removed), so the read renders the same in both passes here and can still mismatch in real SSR.                                                            |
-| `data-hydrated` on `<html>`                                                           | Set after hydration, as the production root sets it from its effect, and removed on unmount. A `<Suspense>` boundary therefore hydrates with it already set.                                                                                 |
-| `useHandle` with `lateHandles`                                                        | The `handles` values in the server pass and in every hydration render, a `<Suspense>` boundary's included; the `lateHandles` values on the render after.                                                                                     |
-| `useLocationState` of a seeded definition                                             | `undefined` in the server pass and the hydration render, the seeded value on the render after. A `clearOnReload` definition stays `undefined`: its seeded slot is removed from `history.state` before hydration, as on a real document load. |
+| In your component                                                                     | Under `hydrate: true`                                                                                                                                                                                                                                                                                          |
+| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `typeof window` / `typeof document` in render                                         | `"undefined"` in the server pass: both globals are removed for it and restored before hydration. A branch renders its server side; if the client side differs, React reports the mismatch.                                                                                                                     |
+| An unguarded `window.x` / `document.x` in render                                      | Throws `ReferenceError` in the server pass, as in SSR. Inside a `<Suspense>` the boundary is client-rendered and reported; outside one it is a shell error (next row).                                                                                                                                         |
+| An error thrown in the server pass outside any `<Suspense>` (a shell error)           | As production's recovery document: `shellError` holds the error, `serverHtml` is `""`, and the tree is rendered with `createRoot`, so your error boundaries (or the component itself, if it throws only on the server) show what the document ends on.                                                         |
+| Hydration adopts the server HTML                                                      | `hydrateRoot` adopts the server-rendered DOM nodes instead of replacing them, and `recoverableErrors` stays empty; a client render of the same tree would replace the nodes.                                                                                                                                   |
+| A text or element mismatch                                                            | React re-renders that tree on the client and reports it: `recoverableErrors` gets `"Hydration failed because ..."` with the diff.                                                                                                                                                                              |
+| An attribute-only mismatch (`className`, `href`)                                      | NOT in `recoverableErrors`. React keeps the server attribute and logs `console.error` in development; assert it with `vi.spyOn(console, "error")`.                                                                                                                                                             |
+| `<Suspense>` whose content renders synchronously                                      | In `serverHtml`. It hydrates in a later pass than the tree above it, after that tree's effects, before `renderRoute` resolves.                                                                                                                                                                                 |
+| Content that suspends in the server pass (`lazy`, a pending or plain `use()` promise) | NOT hydrated: `serverHtml` has the fallback, the client renders the content, and `recoverableErrors` reports the boundary. With no `<Suspense>` above it `renderRoute` rejects: the production server waits for it, this synchronous pass cannot. A settled promise (Caveats, below) stays in the server HTML. |
+| Render counts and module state                                                        | Every component renders once in the server pass before its hydration render. Both passes share one module realm, so module state written while rendering is still there at hydration.                                                                                                                          |
+| `history`, `localStorage`, `navigator` read outside a server snapshot                 | FIDELITY LIMIT: still defined in the server pass (only `window` and `document` are removed), so the read renders the same in both passes here and can still mismatch in real SSR.                                                                                                                              |
+| `data-hydrated` on `<html>`                                                           | Set after hydration, as the production root sets it from its effect, and removed on unmount. A `<Suspense>` boundary therefore hydrates with it already set.                                                                                                                                                   |
+| `useHandle` with `lateHandles`                                                        | The `handles` values in the server pass and in every hydration render, a `<Suspense>` boundary's included; the `lateHandles` values on the render after.                                                                                                                                                       |
+| `useLocationState` of a seeded definition                                             | `undefined` in the server pass and the hydration render, the seeded value on the render after. A `clearOnReload` definition stays `undefined`: its seeded slot is removed from `history.state` before hydration, as on a real document load.                                                                   |
 
 A handle value can reach the page after hydration: a loader push made after an `await`, or any loader push on a PPR shell HIT (`/ppr`, "Handles on a shell HIT"). `lateHandles` models it. The server HTML is rendered from `handles`; the update is applied once the root has hydrated, so a reader inside a `<Suspense>` hydrates after it arrived, as a streamed boundary does in production:
 
@@ -337,6 +338,19 @@ it("hydrates with the document's notes, then shows the late one", async () => {
 });
 ```
 
+A server-only throw fails the document's shell in production; the router answers a recovery document and the browser renders the page (`/loader`, "A read outside any `<Suspense>`"). `shellError` lets a test pin where that document ends:
+
+```tsx
+it("a widget that needs the browser still renders on a document load", async () => {
+  const { shellError, getByTestId } = await renderRoute(
+    [{ path: "/products", Component: ProductsPage }], // ProductsPage reads window.matchMedia
+    { hydrate: true },
+  );
+  expect(shellError).toBeInstanceOf(ReferenceError);
+  expect(getByTestId("products")).toBeTruthy(); // rendered in the browser
+});
+```
+
 - Needs `@testing-library/react` 16.2.0 or newer. 16.0 and 16.1 never pass `onRecoverableError` to `hydrateRoot`, so a mismatch would be invisible; `renderRoute` throws there instead.
 - `recoverableErrors` is live: React appends to it for as long as the root is mounted.
 - The server pass is the HTML render of the CLIENT tree. It runs no handler, loader, middleware, or Flight, and it is not the streamed document: streaming order, client-reference identity, and the browser's HTML parser stay at e2e.

package/src/cache/cache-error.ts

@@ -16,6 +16,7 @@
  */
 
 import { _getRequestContext } from "../server/request-context.js";
+import { wasServerErrorPrinted } from "../server/print-server-error.js";
 
 /**
  * Minimal shape of a request context for error reporting. Passed explicitly by
@@ -29,6 +30,8 @@ export interface CacheErrorReporter {
     error: unknown,
     category: CacheErrorCategory,
   ) => void;
+  /** The errors the request printed (router/error-handling.ts printServerError). */
+  _printedErrors?: WeakSet<object>;
 }
 
 export type CacheErrorCategory =
@@ -70,9 +73,15 @@ export function reportCacheError(
   label: string,
   ctx?: CacheErrorReporter,
 ): void {
-  console.error(`${label}:`, error);
+  let target: CacheErrorReporter | undefined;
+  try {
+    target = ctx ?? _getRequestContext();
+  } catch {
+    // Reporting must never itself break the cache path.
+  }
+  // A render error a writer refuses to store printed where it originated.
+  if (!wasServerErrorPrinted(error, target)) console.error(`${label}:`, error);
   try {
-    const target = ctx ?? _getRequestContext();
     target?._reportBackgroundError?.(error, category);
   } catch {
     // Reporting must never itself break the cache path.

package/src/decode-loader-results.ts

@@ -19,7 +19,10 @@ import { LoaderRedirect } from "./loader-redirect.js";
  *
  * Only decodeLoaderEntry (the read-site path — client components, so the
  * throw lands in the router-owned boundary; during document SSR, Fizz emits
- * the Suspense fallback and replays the throw at hydration) throws these.
+ * the Suspense fallback and replays the throw at hydration, and with no
+ * Suspense above the read the throw fails the shell, which renderHTML answers
+ * with a recovery document or a 3xx, ssr/shell-error-document.tsx) throws
+ * these.
  * decodeLoaderResults runs during the tree build on settled results, where a
  * throw would collapse the whole payload — it routes signals through the
  * errorFallback slot instead (same visual: the slot replaces the children
@@ -33,6 +36,16 @@ export const LOADER_NOT_FOUND_FALLBACK: unique symbol = Symbol(
 );
 export const LOADER_REDIRECT: unique symbol = Symbol("rango.loaderRedirect");
 
+/** The redirect a `LoaderRedirect` thrown by throwSignal carries, if any. */
+export function loaderRedirectOf(
+  error: unknown,
+): { to: string; status?: number; state?: unknown } | undefined {
+  if (error === null || typeof error !== "object") return undefined;
+  return (error as Record<PropertyKey, unknown>)[LOADER_REDIRECT] as
+    | { to: string; status?: number; state?: unknown }
+    | undefined;
+}
+
 function throwSignal(result: any): void {
   if (result.notFound === true) {
     const err = new Error(result.error?.message ?? "Not found");
@@ -70,6 +83,13 @@ function signalFallback(result: any): ReactNode | undefined {
   return undefined;
 }
 
+/**
+ * Marks an error loaderResultError rebuilt from a loader's ErrorInfo (masked
+ * in production). The server printed the original where the loader ran, so
+ * the SSR render never prints the rebuild.
+ */
+const REBUILT_LOADER_ERROR: unique symbol = Symbol();
+
 /**
  * A failed loader entry's error, rebuilt with the ErrorInfo identity
  * (name/stack/code/cause) instead of a stripped generic Error.
@@ -83,9 +103,17 @@ export function loaderResultError(result: { error: ErrorInfo }): Error {
   if (info.name) err.name = info.name;
   if (info.stack) err.stack = info.stack;
   if (info.code !== undefined) (err as { code?: string }).code = info.code;
+  (err as { [REBUILT_LOADER_ERROR]?: true })[REBUILT_LOADER_ERROR] = true;
   return err;
 }
 
+/** Whether `error` is a rebuild loaderResultError made (see the marker). */
+export function isRebuiltLoaderError(error: unknown): boolean {
+  return (
+    typeof error === "object" && error !== null && REBUILT_LOADER_ERROR in error
+  );
+}
+
 /** A loader that threw: not ok, and not a notFound()/redirect() signal. */
 export function isLoaderError(
   result: unknown,

package/src/errors.ts

@@ -76,6 +76,45 @@ export function isDataNotFoundError(
   );
 }
 
+/**
+ * A loader's notFound() or redirect() rethrown at its read site
+ * (decode-loader-results.ts throwSignal): control flow answered with its own
+ * status, not an error to print or report. Name-based, so the RSC environment,
+ * whose module instances differ from the SSR one's, classifies it too.
+ */
+export function isLoaderSignalError(error: unknown): boolean {
+  return (
+    isDataNotFoundError(error) ||
+    (error instanceof Error && error.name === "LoaderRedirect")
+  );
+}
+
+/**
+ * An error React's Flight client decoded from an error row: it always sets
+ * `digest`. The Flight render printed and reported the original.
+ */
+export function isFlightDecodedError(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "digest" in error;
+}
+
+/**
+ * A render's own cancellation, not a failure: the error React's Flight and
+ * Fizz report for each pending task when a stream is aborted with no reason
+ * (a client disconnect), or an AbortError while the request itself is
+ * aborted. A loader's own AbortController or fetch timeout on a live request
+ * is a failure.
+ */
+export function isAbortedRender(
+  error: unknown,
+  requestSignal?: AbortSignal,
+): boolean {
+  if (!(error instanceof Error)) return false;
+  if (error.message.startsWith("The render was aborted by the server")) {
+    return true;
+  }
+  return error.name === "AbortError" && requestSignal?.aborted === true;
+}
+
 /**
  * Convenience function to throw a DataNotFoundError
  * Shorter syntax for common not-found scenarios

package/src/router/loader-resolution.ts

@@ -76,6 +76,7 @@ import {
   type ScopableReverse,
 } from "../server/context.js";
 import { debugLog } from "./logging.js";
+import { printServerError } from "../server/print-server-error.js";
 
 /**
  * Internal callback signature for loader error notifications.
@@ -147,9 +148,11 @@ function pushHandleValue(
  *   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.
+ *   server; the client navigates when the entry decodes. A read outside
+ *   Suspense fails the document's server-render shell before anything was
+ *   sent: that document answers a real 3xx when the redirect carries no
+ *   state (ssr/shell-error-document.tsx); otherwise a loader redirect is a
+ *   client-side navigate.
  *
  * @param onError - Optional callback invoked when loader errors occur.
  *   This has a simplified signature for internal use - the caller (typically
@@ -157,7 +160,8 @@ function pushHandleValue(
  *   OnErrorCallback with complete request context (request, url, env, etc.).
  * @param useDefaultErrorBoundary - An `ssr: false` loader on a document or
  *   capture render: an error with no declared boundary gets
- *   `DefaultErrorFallback` and a 500 (it would otherwise reject the tree).
+ *   `DefaultErrorFallback` (it would otherwise reject the tree), and every
+ *   error answers 500.
  */
 export function wrapLoaderWithErrorHandling<T>(
   promise: Promise<T>,
@@ -276,7 +280,13 @@ export function wrapLoaderWithErrorHandling<T>(
         return {
           __loaderResult: true,
           ok: false,
-          redirect: { to, ...(redirectState && { state: redirectState }) },
+          // status: a document whose shell this read fails answers it as a
+          // real redirect (ssr/shell-error-document.tsx).
+          redirect: {
+            to,
+            status: error.status,
+            ...(redirectState && { state: redirectState }),
+          },
           error: createErrorInfo(
             new Error(`Loader redirected to ${to}`),
             segmentId,
@@ -290,6 +300,17 @@ export function wrapLoaderWithErrorHandling<T>(
       // Flight nor Fizz reports: record it like their errors, so a writer
       // that reads _renderErrors (the document cache) does not store it.
       renderErrors?.push(error);
+      // The original, once, here: the payload carries a masked rebuild that
+      // the SSR render must not print (decode-loader-results.ts).
+      printServerError(
+        error,
+        {
+          label: "Loader error",
+          name: loaderName.slice(loaderName.lastIndexOf("#") + 1),
+          pathname,
+        },
+        requestContext,
+      );
 
       // Find nearest error boundary
       const declared = findNearestErrorBoundary(entry);
@@ -349,8 +370,12 @@ export function wrapLoaderWithErrorHandling<T>(
         segmentId,
         message: errorInfo.message,
       });
-      // The default boundary answers 500, as in catchSegmentError.
-      if (!declared) requestContext?._setStatus(500);
+      if (useDefaultErrorBoundary) {
+        // Settled before the first flush, so the document answers
+        // 500 whichever boundary renders it, as a handler error does. On a
+        // shell HIT the status went out with the shell and the write is inert.
+        requestContext?._setStatus(500);
+      }
 
       return {
         __loaderResult: true,

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

@@ -17,7 +17,11 @@ import {
   createNotFoundSegment,
   resolveNotFoundFallback,
 } from "../error-handling.js";
-import { getRequestContext } from "../../server/request-context.js";
+import { printServerError } from "../../server/print-server-error.js";
+import {
+  _getRequestContext,
+  getRequestContext,
+} from "../../server/request-context.js";
 import { DefaultErrorFallback } from "../../default-error-boundary.js";
 import type { EntryData } from "../../server/context";
 import type {
@@ -295,6 +299,13 @@ export function catchSegmentError<TEnv>(
     );
   }
 
+  // The client gets the masked ErrorInfo; the original prints here.
+  printServerError(
+    error,
+    { label: "Handler error", name: entry.shortCode, pathname },
+    _getRequestContext(),
+  );
+
   const fallback = deps.findNearestErrorBoundary(entry);
   const segmentType: ErrorInfo["segmentType"] = entry.type;
   const errorInfo = createErrorInfo(error, entry.shortCode, segmentType);

package/src/router.ts

@@ -61,6 +61,7 @@ import {
   findNearestNotFoundBoundary as findNotFoundBoundary,
   invokeOnError,
 } from "./router/error-handling.js";
+import { printServerError } from "./server/print-server-error.js";
 
 // Extracted module factories
 import { createSegmentWrappers } from "./router/segment-wrappers.js";
@@ -497,8 +498,20 @@ export function createRouter<TEnv = any>(
     // Report streaming handler errors to onError as a side-effect.
     // The rejection still propagates to the RSC stream for client error boundaries.
     // Captures request context eagerly (closure) so the catch handler has full context.
-    if (reqCtx && onError) {
+    // Printed here, where it originated, whether a boundary recovers it or
+    // Flight reports it again (printed once per request).
+    if (reqCtx) {
       tracked.catch((error) => {
+        printServerError(
+          error,
+          {
+            label: "Handler error",
+            name: errorContext?.segmentId,
+            pathname: reqCtx.url.pathname,
+          },
+          reqCtx,
+        );
+        if (!onError) return;
         callOnError(error, "handler", {
           request: reqCtx.request,
           url: reqCtx.url,

package/src/rsc/handler.ts

@@ -63,6 +63,10 @@ import {
   invokeOnError,
   resolveDefaultNotFound,
 } from "../router/error-handling.js";
+import {
+  printServerError,
+  wasServerErrorPrinted,
+} from "../server/print-server-error.js";
 import { createReverseFunction } from "../router/handler-context.js";
 import { contextSet } from "../context-var.js";
 import {
@@ -1304,7 +1308,15 @@ export function createRSCHandler<
             actionId: plan.actionId,
             handledByBoundary: false,
           });
-          console.error(`[RSC] Action error:`, error);
+          printServerError(
+            error,
+            {
+              label: "Action error",
+              name: plan.actionId,
+              pathname: url.pathname,
+            },
+            reqCtx,
+          );
           throw error;
         }
       }
@@ -1548,14 +1560,24 @@ export function createRSCHandler<
           );
         }
 
-        // Report unhandled errors
-        callOnError(error, "routing", {
-          request,
-          url,
-          env,
-          handledByBoundary: false,
-        });
-        console.error(`[RSC] Error:`, error);
+        // Report unhandled errors. Skip one the request already printed or
+        // recorded as done: a shell error renderHTML rethrew to the host (dev),
+        // which the html stage (rsc/ssr-setup.ts) reported when it started in
+        // the SSR render; a copy's original was reported where it started.
+        const printedContext = _getRequestContext();
+        if (!wasServerErrorPrinted(error, printedContext)) {
+          callOnError(error, "routing", {
+            request,
+            url,
+            env,
+            handledByBoundary: false,
+          });
+          printServerError(
+            error,
+            { label: "Error", pathname: url.pathname },
+            printedContext,
+          );
+        }
         throw error;
       }
     };

package/src/rsc/loader-fetch.ts

@@ -15,8 +15,12 @@ import { requestHeaders } from "../server/request-headers.js";
 import { FORBIDDEN_KEYS } from "../context-var.js";
 import { getLoaderLazy } from "../server/loader-registry.js";
 import { isDataNotFoundError } from "../errors.js";
+import { printServerError } from "../server/print-server-error.js";
 import { executeLoaderMiddleware } from "../router/middleware.js";
-import { getRequestContext } from "../server/request-context.js";
+import {
+  _getRequestContext,
+  getRequestContext,
+} from "../server/request-context.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import {
   createReverseFunction,
@@ -54,10 +58,17 @@ export function renderLoaderError<TEnv>(
   meta: LoaderErrorMeta<TEnv>,
 ): Response {
   const { request, url, env, loaderId } = meta;
+  // Read once here: onError can fire outside the ALS frame.
+  const requestContext = _getRequestContext();
   const rscStream = ctx.renderToReadableStream(
     { loaderResult: null, loaderError },
     {
       onError: (renderError: unknown) => {
+        printServerError(
+          renderError,
+          { label: "Rendering error", name: loaderId, pathname: url.pathname },
+          requestContext,
+        );
         ctx.callOnError(renderError, "rendering", {
           request,
           url,
@@ -78,19 +89,22 @@ export function renderLoaderError<TEnv>(
  * Build the 500 RSC error Response for a failed fetchable loader. Shared by the
  * module-load-error catch (the import itself threw) and the loader-execution
  * error catch — both call onError("loader") and serialize the same dev-gated
- * error payload. The only per-site difference is the console.error label,
- * passed in.
+ * error payload. The only per-site difference is the printed label, passed in.
  */
 function buildLoaderErrorResponse<TEnv>(
   ctx: HandlerContext<TEnv>,
   error: unknown,
   meta: LoaderErrorMeta<TEnv>,
-  logLabel: string,
+  label: string,
 ): Response {
   const { request, url, env, loaderId } = meta;
   const isDev = process.env.NODE_ENV !== "production";
 
-  console.error(logLabel, error);
+  printServerError(
+    error,
+    { label, name: loaderId, pathname: url.pathname },
+    _getRequestContext(),
+  );
 
   ctx.callOnError(error, "loader", {
     request,
@@ -145,7 +159,7 @@ export async function handleLoaderFetch<TEnv>(
       ctx,
       error,
       { request, url, env, loaderId },
-      `[RSC] Loader module load failed for "${loaderId}":`,
+      "Loader module load error",
     );
   }
   if (!registeredLoader) {
@@ -288,10 +302,21 @@ export async function handleLoaderFetch<TEnv>(
             loaderResult: unknown;
           }
           const loaderPayload: LoaderPayload = { loaderResult: result };
+          // Read once here: onError can fire outside the ALS frame.
+          const requestContext = _getRequestContext();
           const rscStream = ctx.renderToReadableStream<LoaderPayload>(
             loaderPayload,
             {
               onError: (error: unknown) => {
+                printServerError(
+                  error,
+                  {
+                    label: "Rendering error",
+                    name: loaderId,
+                    pathname: url.pathname,
+                  },
+                  requestContext,
+                );
                 ctx.callOnError(error, "rendering", {
                   request,
                   url,
@@ -342,7 +367,7 @@ export async function handleLoaderFetch<TEnv>(
       ctx,
       error,
       { request, url, env, loaderId },
-      "[RSC] Loader error:",
+      "Loader error",
     );
   }
 }

package/src/rsc/progressive-enhancement.ts

@@ -8,9 +8,11 @@
 
 import { bodylessHeaders, requestHeaders } from "../server/request-headers.js";
 import {
+  _getRequestContext,
   getRequestContext,
   setRequestContextParams,
 } from "../server/request-context.js";
+import { printServerError } from "../server/print-server-error.js";
 import { createSsrHtmlStage } from "./ssr-setup.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 import { executeMiddleware } from "../router/middleware.js";
@@ -146,7 +148,6 @@ async function runFormAction<TEnv>(
     if (failure.boundary) {
       return { reactFormState: null, directActionId: null, failure };
     }
-    console.error("[RSC] Progressive enhancement form parse error:", error);
     return createResponseWithMergedHeaders(null, { status: 400 });
   }
 
@@ -226,9 +227,6 @@ async function runFormAction<TEnv>(
   if (failure?.boundary) {
     return { reactFormState: null, directActionId, failure };
   }
-  if (failure) {
-    console.error("[RSC] Progressive enhancement action error:", failure.error);
-  }
 
   // Handle Response returned from action during PE.
   // In the JS path, executeServerAction intercepts redirect Responses and
@@ -512,6 +510,17 @@ async function matchPeFailure<TEnv>(
     getRequestContext()._inActionRevalidation = true;
   }
 
+  // Printed here, once, whether or not a boundary renders it.
+  printServerError(
+    error,
+    {
+      label: actionRan ? "Action error" : "Action form parse error",
+      name: actionId ?? undefined,
+      pathname: url.pathname,
+    },
+    _getRequestContext(),
+  );
+
   let boundary: MatchResult | null;
   try {
     boundary = await ctx.router.matchError(request, { env }, error, "route");

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);
         },
       }),
     );