@rangojs/router 0.26.1 → 0.26.3

package/dist/bin/rango.js

@@ -1644,7 +1644,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@rangojs/router",
-      version: "0.26.1",
+      version: "0.26.3",
       description: "Django-inspired RSC router with composable URL patterns",
       keywords: [
         "react",
@@ -1966,7 +1966,7 @@ import {
   createTemporaryReferenceSet,
 } from "@rangojs/router/internal/deps/browser";
 import { createElement, StrictMode } from "react";
-import { hydrateRoot } from "react-dom/client";
+import { createRoot, hydrateRoot } from "react-dom/client";
 import { rscStream } from "@rangojs/router/internal/deps/html-stream-client";
 import { initBrowserApp, Rango } from "@rangojs/router/browser";
 
@@ -2002,11 +2002,15 @@ async function initializeApp() {
   }
 
   const app = createElement(Rango);
-  hydrateRoot(
-    document,
-    strictMode === false ? app : createElement(StrictMode, null, app),
-    formState ? { formState } : undefined
-  );
+  const root = strictMode === false ? app : createElement(StrictMode, null, app);
+  // The server render failed its shell and answered a recovery document
+  // (ssr/shell-error-document.tsx): nothing to hydrate, so render it, and the
+  // router's error boundaries run as on a client navigation.
+  if (document.documentElement.hasAttribute("data-rango-ssr-error")) {
+    createRoot(document).render(root);
+  } else {
+    hydrateRoot(document, root, formState ? { formState } : undefined);
+  }
 }
 
 initializeApp().catch(console.error);

package/dist/types/cache/cache-error.d.ts

@@ -23,6 +23,8 @@
  */
 export interface CacheErrorReporter {
     _reportBackgroundError?: (error: unknown, category: CacheErrorCategory) => void;
+    /** The errors the request printed (router/error-handling.ts printServerError). */
+    _printedErrors?: WeakSet<object>;
 }
 export type CacheErrorCategory = 
 /** A read failed (transient infra: KV/Cache API error). Degrade to a miss. */

package/dist/types/decode-loader-results.d.ts

@@ -11,7 +11,10 @@ import { type ErrorInfo, type ResolvedSegment } from "./types.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
@@ -22,6 +25,12 @@ import { type ErrorInfo, type ResolvedSegment } from "./types.js";
  */
 export declare const LOADER_NOT_FOUND_FALLBACK: unique symbol;
 export declare const LOADER_REDIRECT: unique symbol;
+/** The redirect a `LoaderRedirect` thrown by throwSignal carries, if any. */
+export declare function loaderRedirectOf(error: unknown): {
+    to: string;
+    status?: number;
+    state?: unknown;
+} | undefined;
 /**
  * A failed loader entry's error, rebuilt with the ErrorInfo identity
  * (name/stack/code/cause) instead of a stripped generic Error.
@@ -29,6 +38,8 @@ export declare const LOADER_REDIRECT: unique symbol;
 export declare function loaderResultError(result: {
     error: ErrorInfo;
 }): Error;
+/** Whether `error` is a rebuild loaderResultError made (see the marker). */
+export declare function isRebuiltLoaderError(error: unknown): boolean;
 /** A loader that threw: not ok, and not a notFound()/redirect() signal. */
 export declare function isLoaderError(result: unknown): result is {
     error: ErrorInfo;

package/dist/types/errors.d.ts

@@ -39,6 +39,26 @@ export declare class DataNotFoundError extends Error {
     constructor(message?: string, options?: ErrorOptions);
 }
 export declare function isDataNotFoundError(error: unknown): error is DataNotFoundError;
+/**
+ * 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 declare function isLoaderSignalError(error: unknown): boolean;
+/**
+ * An error React's Flight client decoded from an error row: it always sets
+ * `digest`. The Flight render printed and reported the original.
+ */
+export declare function isFlightDecodedError(error: unknown): boolean;
+/**
+ * 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 declare function isAbortedRender(error: unknown, requestSignal?: AbortSignal): boolean;
 /**
  * Convenience function to throw a DataNotFoundError
  * Shorter syntax for common not-found scenarios

package/dist/types/router/loader-resolution.d.ts

@@ -34,21 +34,27 @@ export type LoaderErrorCallback = (error: unknown, context: {
  *   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
  *   wrapLoaderPromise in router.ts) is responsible for bridging to the full
  *   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` (it would otherwise reject the tree), and every
+ *   error answers 500.
  */
 export declare function wrapLoaderWithErrorHandling<T>(promise: Promise<T>, entry: EntryData, segmentId: string, pathname: string, findNearestErrorBoundary: (entry: EntryData | null) => ReactNode | ErrorBoundaryHandler | null, createErrorInfo: (error: unknown, segmentId: string, segmentType: ErrorInfo["segmentType"]) => ErrorInfo, onError?: LoaderErrorCallback, notFoundDeps?: {
     findNearestNotFoundBoundary: (entry: EntryData | null) => ReactNode | NotFoundBoundaryHandler | null;
     notFoundComponent?: ReactNode | ((props: {
         pathname: string;
     }) => ReactNode);
-}): Promise<LoaderDataResult<T>>;
+}, useDefaultErrorBoundary?: boolean): Promise<LoaderDataResult<T>>;
 /**
  * Set up the use() method on handler context to access loaders and handles.
  *

package/dist/types/router/types.d.ts

@@ -25,7 +25,9 @@ export interface SegmentResolutionDeps<TEnv = any> {
         env?: TEnv;
         isPartial?: boolean;
         requestStartTime?: number;
-    }) => Promise<LoaderDataResult<T>>;
+    }, 
+    /** An `ssr: false` loader on a document or capture render. */
+    useDefaultErrorBoundary?: boolean) => Promise<LoaderDataResult<T>>;
     trackHandler: <T>(promise: Promise<T>, errorContext?: {
         segmentId?: string;
         segmentType?: string;

package/dist/types/rsc/types.d.ts

@@ -202,6 +202,20 @@ 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;
 }
 /**
  * SSR module interface for HTML rendering

package/dist/types/server/print-server-error.d.ts

@@ -0,0 +1,27 @@
+/** The request context fields the record reads. */
+interface PrintContext {
+    /** The errors this request printed (request-context.ts). */
+    _printedErrors?: WeakSet<object>;
+    request?: Request;
+}
+/**
+ * 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 declare function printServerError(error: unknown, origin: {
+    label: string;
+    name?: string;
+    pathname?: string;
+}, requestContext: PrintContext | undefined): void;
+/**
+ * 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 declare function markServerErrorPrinted(error: unknown, requestContext: PrintContext | undefined): void;
+/** Whether this request printed `error`, or recorded it as done. */
+export declare function wasServerErrorPrinted(error: unknown, requestContext: PrintContext | undefined): boolean;
+export {};

package/dist/types/server/request-context.d.ts

@@ -755,6 +755,11 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     _renderBarrierGuardClosed?: boolean;
     /** @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
@@ -861,7 +866,7 @@ export interface RouteRecordWindow {
  * This is the type exported to library consumers. Internal code should
  * use the full RequestContext interface directly.
  */
-export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "_readCookie" | "_readCookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhenRefs" | "_pprReplayPostMatchReason" | "_cacheStore" | "_prerender" | "_onDemandProducer" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellCaptureForVisitor" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureUnrecordedLoaderPush" | "_shellCaptureLoaderLanes" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_prerenderWarm" | "_runAtRequestEntry" | "_routeRecordWindow" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "_payloadDeferred" | "_requestKind" | "_payloadVisitorLocation" | "_locationState" | "_routeName" | "_prevRouteKey" | "_visitorMoved" | "_inActionRevalidation" | "_actionRan" | "_reportedErrors" | "_renderErrors" | "_recoveredHandlerErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_versions" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_freshReads" | "_setFreshReadsCookie" | "_requestRoot" | "_requestStart" | "_responseSent" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
+export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "_readCookie" | "_readCookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhenRefs" | "_pprReplayPostMatchReason" | "_cacheStore" | "_prerender" | "_onDemandProducer" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellCaptureForVisitor" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureUnrecordedLoaderPush" | "_shellCaptureLoaderLanes" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_prerenderWarm" | "_runAtRequestEntry" | "_routeRecordWindow" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "_payloadDeferred" | "_requestKind" | "_payloadVisitorLocation" | "_locationState" | "_routeName" | "_prevRouteKey" | "_visitorMoved" | "_inActionRevalidation" | "_actionRan" | "_reportedErrors" | "_printedErrors" | "_renderErrors" | "_recoveredHandlerErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_versions" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_freshReads" | "_setFreshReadsCookie" | "_requestRoot" | "_requestStart" | "_responseSent" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
 /**
  * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
  * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:

package/dist/types/ssr/index.d.ts

@@ -106,6 +106,20 @@ 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;
 }
 /**
  * SSR dependencies from external packages

package/dist/types/ssr/shell-error-document.d.ts

@@ -0,0 +1,24 @@
+import type { ResolvedThemeConfig } from "../theme/types.js";
+import type { SSRDependencies } from "./index.js";
+/** 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">;
+/** Answer a shell error; see the module comment for the order. */
+export declare function answerShellError(deps: ShellErrorRenderDeps, error: unknown, recovery: ShellErrorRecovery | undefined, flight: ReadableStream<Uint8Array> | undefined, nonce: string | undefined): Promise<ShellErrorAnswer>;
+export {};

package/dist/types/ssr/ssr-root.d.ts

@@ -80,6 +80,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;
 }
 /**
  * Build the closure component that deserializes the Flight payload, consumes

package/dist/types/testing/render-route.d.ts

@@ -299,7 +299,12 @@ export interface RenderRouteOptions {
      * - Content that suspends in the server pass (`lazy`, a pending or untracked
      *   `use()` promise) is emitted as its fallback and client-rendered, not
      *   hydrated; React reports the boundary in `recoverableErrors`. Outside any
-     *   `<Suspense>` it rejects.
+     *   `<Suspense>` it rejects: production's server waits for it, this
+     *   synchronous pass cannot.
+     * - An error the server pass throws outside any `<Suspense>` fails the
+     *   shell. Production answers a recovery document and the browser renders
+     *   the tree with `createRoot` instead of hydrating it; so does this mode,
+     *   and the result's `shellError` holds the error.
      * - Needs @testing-library/react >= 16.2.0; throws on older versions.
      */
     hydrate?: boolean;
@@ -389,6 +394,14 @@ export type RenderRouteHydrateResult = RenderRouteResult & {
      * with `console.error` in development.
      */
     recoverableErrors: string[];
+    /**
+     * The error the server pass threw outside any `<Suspense>` (a shell error),
+     * or undefined. When set, the tree was rendered with `createRoot`, as the
+     * browser renders production's recovery document, so the router's error
+     * boundaries ran on the client: assert what they show. `serverHtml` is then
+     * empty.
+     */
+    shellError: unknown;
 };
 export declare function renderRoute(routes: RenderRouteSpec[], options: RenderRouteOptions & {
     hydrate: true;

package/dist/types/types/boundaries.d.ts

@@ -79,10 +79,13 @@ export type LoaderDataResult<T = unknown> = {
      * resolved `redirect(url, { state })` record (`__rsc_ls_*` keys) — it
      * travels on the marker because a streaming loader settles after
      * payload metadata flushed; the redirect navigation merges it at the
-     * target entry.
+     * target entry. `status` is the redirect's own: a document whose shell
+     * the read fails answers it as a real redirect when there is no state
+     * (ssr/shell-error-document.tsx).
      */
     redirect?: {
         to: string;
+        status?: number;
         state?: Record<string, unknown>;
     };
 };

package/dist/vite/index.js

@@ -5209,7 +5209,7 @@ import { useContext as useContext13, useEffect as useEffect11, useRef as useRef9
 import {
   useState as useState11,
   useEffect as useEffect13,
-  useLayoutEffect as useLayoutEffect3,
+  useLayoutEffect as useLayoutEffect4,
   useCallback as useCallback4,
   useMemo as useMemo7,
   useRef as useRef11,
@@ -5225,6 +5225,7 @@ import { jsx as jsx5, jsxs as jsxs3 } from "react/jsx-runtime";
 import {
   useCallback as useCallback3,
   useEffect as useEffect12,
+  useLayoutEffect as useLayoutEffect3,
   useMemo as useMemo6,
   useState as useState10
 } from "react";
@@ -5877,7 +5878,7 @@ import {
   Fragment as Fragment4,
   Suspense as Suspense3,
   useDeferredValue,
-  useLayoutEffect as useLayoutEffect4,
+  useLayoutEffect as useLayoutEffect5,
   useMemo as useMemo10,
   useState as useState13
 } from "react";
@@ -7077,7 +7078,7 @@ function resolveVersionsFrom(table, routerId2) {
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.26.1",
+  version: "0.26.3",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -7387,7 +7388,7 @@ import {
   createTemporaryReferenceSet,
 } from "@rangojs/router/internal/deps/browser";
 import { createElement, StrictMode } from "react";
-import { hydrateRoot } from "react-dom/client";
+import { createRoot, hydrateRoot } from "react-dom/client";
 import { rscStream } from "@rangojs/router/internal/deps/html-stream-client";
 import { initBrowserApp, Rango } from "@rangojs/router/browser";
 
@@ -7423,11 +7424,15 @@ async function initializeApp() {
   }
 
   const app = createElement(Rango);
-  hydrateRoot(
-    document,
-    strictMode === false ? app : createElement(StrictMode, null, app),
-    formState ? { formState } : undefined
-  );
+  const root = strictMode === false ? app : createElement(StrictMode, null, app);
+  // The server render failed its shell and answered a recovery document
+  // (ssr/shell-error-document.tsx): nothing to hydrate, so render it, and the
+  // router's error boundaries run as on a client navigation.
+  if (document.documentElement.hasAttribute("data-rango-ssr-error")) {
+    createRoot(document).render(root);
+  } else {
+    hydrateRoot(document, root, formState ? { formState } : undefined);
+  }
 }
 
 initializeApp().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.26.1",
+  "version": "0.26.3",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/loader/SKILL.md

@@ -980,10 +980,10 @@ export const ProductLoader = createLoader(async (ctx) => {
 
 Semantics by lane:
 
-| Signal       | Document load                                                                                                                                                                                                                                               | Client navigation                                 |
-| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| `notFound()` | Not-found UI resolves server-side (nearest `notFoundBoundary` → router option → default) and rides the envelope; the 404 STATUS is **opportunistic** — real only if the rejection beats Response construction. `ssr: false` (below) makes it deterministic. | 404 UI swaps in, URL preserved, payload stays 200 |
-| `redirect()` | 200 document, then a client-side replace to the target — **no document-lane 302 from loaders**; pre-stream redirect authority belongs to middleware                                                                                                         | Redirect envelope navigates to the target         |
+| Signal       | Document load, read inside `<Suspense>` or under `loading()`                                                                                                                                                                                                | Document load, read outside any `<Suspense>`                                                                                          | Client navigation                                 |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `notFound()` | Not-found UI resolves server-side (nearest `notFoundBoundary` → router option → default) and rides the envelope; the 404 STATUS is **opportunistic** — real only if the rejection beats Response construction. `ssr: false` (below) makes it deterministic. | A real 404; the browser renders the not-found UI with the layouts kept (the recovery document, below)                                 | 404 UI swaps in, URL preserved, payload stays 200 |
+| `redirect()` | 200 document, then a client-side replace to the target                                                                                                                                                                                                      | A real 3xx (the redirect's own status) with `Location`; with `state`, the recovery document (200), then the client replace carries it | Redirect envelope navigates to the target         |
 
 With `loader(Def, { ssr: false })` the result is settled BEFORE the document
 flushes, so both signals are resolved server-side while the tree is built:
@@ -995,6 +995,55 @@ runs, so a `useLoader` in a layout above every Suspense boundary is safe. On a
 during the shell capture refuses the capture (warned once per key): that URL
 gets no shell, and its renders deliver the signal as above.
 
+A flagged loader that throws (anything but `notFound()` or `redirect()`) is
+resolved the same way: its route's `errorBoundary()` renders at the owning
+segment, else `createRouter({ defaultErrorBoundary })`, else the router's
+default error boundary (the "Internal Server Error" page), with a 500 in every
+case, as a handler that throws does. Layouts above it stay. On a `ppr` shell HIT whose run throws, the status
+went out with the shell (200), the baked content shows first, and the boundary
+replaces it at hydration, after React reports a hydration mismatch.
+
+### A read outside any `<Suspense>` on a document load
+
+A read that throws with no `<Suspense>` above it (no `loading()`, no inline
+boundary) fails React's server render before any HTML exists: React's server
+renderer runs no error boundaries. In production the router then answers a
+small recovery document that carries the same page data, and the browser
+renders the page instead of hydrating it, so the document ends where a client
+navigation to the URL ends:
+
+| What the read throws       | Document status    | What the browser shows                                                                                             |
+| -------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| An error                   | 500                | The route's `errorBoundary()` (or `defaultErrorBoundary`) with the layouts kept; with neither, `RootErrorBoundary` |
+| `notFound()`               | 404                | The not-found UI, layouts kept                                                                                     |
+| `redirect()`               | the redirect's 3xx | The target (the browser follows `Location`)                                                                        |
+| `redirect(url, { state })` | 200                | The target, after the client replace that carries the state                                                        |
+
+The same holds for any client component that throws only during the server
+render: the recovery document is a 500, and the page renders in the browser.
+In dev an error keeps Vite's error overlay with the original stack;
+`notFound()` and `redirect()` are answered as in production. A `ppr` route
+never stores such a document as its shell, and the document cache never stores
+it. `onError` gets the loader's own report (phase `loader`), with the original
+error, and no second report for the document. `notFound()` and
+`redirect()` are control flow: neither is reported nor printed.
+
+A read under `loading()` or a `<Suspense>` streams the page with that
+boundary's fallback and keeps the 200 it already sent.
+
+### What the server prints
+
+A loader that throws prints its original error, message and stack, to the
+server console once per request, where it ran:
+`[RSC] Loader error (ProductLoader) /product/1:` and the error. That holds
+whatever renders it (a route `errorBoundary()`, `defaultErrorBoundary`, the
+default page, `RootErrorBoundary` in the browser), on every lane (a document,
+a client navigation, an action's revalidation, a prefetch, a `ppr` capture),
+in dev and production. Only the copy the browser receives is masked
+(`An error occurred` in production). A handler that reads the same loader
+with `ctx.use()` does not print it again. `notFound()` and `redirect()` never
+print.
+
 Session/auth gates belong in middleware (they are request-shaped, not
 data-shaped, and middleware CAN emit a real pre-stream 302). Data-dependent
 "this slug moved / does not exist" belongs in the loader.

package/skills/ppr/SKILL.md

@@ -733,8 +733,11 @@ boundary, and streamed fresh on every request. It needs a boundary —
 `loading()` or an inline `<Suspense>` above the reader — or the shell is
 refused: a masked read with no boundary above it root-postpones, the `<body>`
 sanity gate refuses the capture, and the route stays an eternal MISS (warned
-once per key). A route whose loaders are ALL `ssr: false` needs no
-`loading()`: nothing masks, and the shell captures complete.
+once per key). When that read also throws on the MISS render, the document is
+the 500 recovery document the `/loader` skill describes ("A read outside any
+`<Suspense>`"), and nothing is stored. A route whose loaders are ALL
+`ssr: false` needs no `loading()`: nothing masks, and the shell captures
+complete.
 
 ```typescript
 export const ProductLoader = createLoader(async (ctx) => {
@@ -926,9 +929,10 @@ by a navigation alone carries no pins, and its replay runs these loaders fresh.
   fill the holes — and the recorded baked paths are overlaid onto the fresh
   result, so the payload matches the prelude while the nested promises stream
   fresh. A fresh rejection skips the overlay and goes to the loader's error
-  boundary: on a document HIT the payload then carries the error where the
-  HTML has the baked value, and React renders that part again on the client
-  (one hydration mismatch, the one known residual of a HIT). Give it its own cache,
+  boundary (the route's `errorBoundary()`, else the router's default one): on
+  a document HIT the payload then carries the error where the HTML has the
+  baked value, and React renders that part again on the client (one
+  hydration mismatch, the one known residual of a HIT). Give it its own cache,
   `loader(Def, { ssr: false }, () => [cache({ ttl })])`, so that run reads
   through the loader cache.
 
@@ -1119,7 +1123,8 @@ Four hard edges (each e2e/unit-pinned):
 - **A rejecting bake-lane loader refuses.** Error UI never bakes. So does a
   value that fails to encode: a function, a class instance, a promise inside a
   `Map` that rejects, or a server component in the value that throws. The
-  capture stores nothing, logs the error, reports `cache-write` and backs the
+  capture stores nothing, prints the error once (a loader's as
+  `[RSC] Loader error`), reports `cache-write` and backs the
   key off, the same as a shell component that throws (below). The capture
   encodes the value a second time to pin it for HITs, so a server component
   that throws only on that run refuses it too. A build-time capture skips the
@@ -1611,14 +1616,18 @@ evicted by tag at all — move always-fresh data into a live-lane loader (no
 - **HIT status is committed at the flush**: a failing hole cannot become a
   500/redirect after the first shell byte — error UI renders inline via
   Suspense/error boundaries (the same property any streamed SSR page has after
-  its shell flushes).
+  its shell flushes). A MISS has sent nothing yet: an `ssr: false` loader that
+  throws answers 500 there with its route's `errorBoundary()` (or the default
+  one), and the capture stores nothing.
 - **A shell component that throws during capture refuses it**: an async
   server component (or a client component during SSR) inside a Suspense
   boundary that throws does not fail the capture render, so its errored
   boundary would bake into the shared prelude. The capture stores nothing
-  instead, logs `[ShellCache] capture` with the error (it goes to `onError`
-  as `cache-write` unless the router already reported that same error during
-  the render), and backs the key off like any refused capture; the next
+  instead, logs `[ShellCache] capture` with the error unless the error was
+  already printed where it happened (a server component's or a loader's
+  error prints once, as `[RSC] Rendering error` or `[RSC] Loader error`), it
+  goes to `onError` as `cache-write` unless the router already reported that
+  same error during the render, and backs the key off like any refused capture; the next
   capture after the window stores normally. The request that triggered the
   capture is served as before. Only a throw during the capture counts: a
   component that failed in the live render and succeeds when captured is

package/skills/route/SKILL.md

@@ -564,7 +564,10 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
   `loading(fallback, { ssr: false })` on a document load) still sets 500 / 404.
   A loader's 404 is likewise only set when its rejection settles before the
   response is built.
-- `onError` fires once per failure.
+- `onError` fires once per failure, and the server console prints the
+  original error once, where it happened
+  (`[RSC] Handler error (<segment>) <path>:`); only what the browser receives
+  is masked.
 - A failed render is never stored: `cache()` skips the write for the scope that
   holds the failed segment, a `ppr` shell and the document cache refuse the
   whole document, and a Prerender route still fails the build.

package/skills/router-setup/SKILL.md

@@ -130,7 +130,7 @@ interface RangoOptions<TEnv> {
   id?: string; // Router id; namespaces build output and route maps. Auto-generated.
 
   // --- Fallbacks and errors ---
-  defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler; // When no errorBoundary() matches
+  defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler; // When no errorBoundary() matches; unset: the built-in "Internal Server Error" page
   defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler; // When no notFoundBoundary() matches
   notFound?: ReactNode | ((props: { pathname: string }) => ReactNode); // 404 page
   onError?: OnErrorCallback<TEnv>; // Logging/reporting hook; cannot change the response
@@ -706,6 +706,34 @@ The resolver receives `{ request, env, url }` and may be async. It runs only
 for HTML document responses; RSC payloads (navigations, prefetches, `__rsc`
 requests) and response routes are unaffected.
 
+### When the server render fails before any HTML
+
+An error thrown during the server render with no `<Suspense>` above it (a
+`useLoader` read of a failed loader, a client component that throws only on
+the server) leaves React no HTML to send: its server renderer runs no error
+boundaries. In production the router answers a small recovery document
+instead of the host's raw 500. It carries the page's data, and the generated
+browser entry renders the page with `createRoot` instead of hydrating it, so
+the route's `errorBoundary()`, `defaultErrorBoundary` or the root error page
+shows with the layouts, as after a client navigation. The status is 500, 404
+for a loader's `notFound()`, and a loader's `redirect()` without state answers
+a real 3xx (with state, 200 and the client replace). When the page data itself failed, the answer is a static error
+page with no scripts and nothing from the error. In dev the error reaches
+Vite's error overlay unchanged. The `/loader` skill has the full table.
+
+The browser entry is generated by `rango()`. A hand-written browser entry must
+make the same choice, or React reports a hydration error (#418) on the
+recovery document before it renders the same page:
+
+```typescript
+const root = createElement(StrictMode, null, createElement(Rango));
+if (document.documentElement.hasAttribute("data-rango-ssr-error")) {
+  createRoot(document).render(root);
+} else {
+  hydrateRoot(document, root, formState ? { formState } : undefined);
+}
+```
+
 ## Timeouts
 
 Off by default. A timed-out action or render start returns a `504` (with an

package/skills/server-actions/SKILL.md

@@ -688,7 +688,9 @@ layout(CheckoutLayout, () => [
 
 In production `error.message` is replaced with `"An error occurred"` (and
 `stack` / `cause` are dropped), while `error.name` and `error.code` are kept —
-branch on `name` or `code`, not on the message.
+branch on `name` or `code`, not on the message. The server console prints the
+original once, message and stack, JS or no-JS, boundary or not:
+`[RSC] Action error (<action id>) <path>:`.
 
 ### Not found from an action