@rangojs/router 0.15.0 → 0.15.1

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

@@ -14,7 +14,10 @@ import type { ReactNode } from "react";
  * decodeLoaderResults runs during the SERVER tree build on forceAwait/action
  * lanes, where a throw would collapse the whole payload — it routes signals
  * through the errorFallback slot instead (same visual: the slot replaces the
- * children under OutletProvider).
+ * children under OutletProvider). The document lane's `{ ssr: false }`
+ * results take the same non-throwing route (segment-system
+ * buildLoaderStreams): they are settled before the tree is built, and the
+ * read-site throw would land in the Fizz shell with no boundary to absorb it.
  */
 export declare const LOADER_NOT_FOUND_FALLBACK: unique symbol;
 export declare const LOADER_REDIRECT: unique symbol;

package/dist/types/rsc/shell-capture.d.ts

@@ -78,7 +78,6 @@ declare const REFUSED_CAPTURE_MAX_MS = 60000;
  * docs/design/ppr-shell-resume.md ("Refused-capture backoff").
  */
 declare const REFUSED_CAPTURE_DEV_MAX_MS = 2000;
-/** True iff `key` is still inside its (exponential) backoff window. */
 declare function isCaptureBackedOff(key: string): boolean;
 /**
  * Record a refused/failed capture, escalating the backoff window exponentially up

package/dist/vite/index.js

@@ -3795,7 +3795,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.15.0",
+  version: "0.15.1",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

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

package/skills/loader/SKILL.md

@@ -695,6 +695,15 @@ Semantics by lane:
 | `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         |
 
+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:
+`redirect()` replaces the whole page with the redirect carrier (still a 200
+document, the client replaces to the target on hydration) and `notFound()`
+renders the not-found UI at the owning segment with a real 404. No read site
+runs, so a `useLoader` in a layout above every Suspense boundary is safe.
+(Before this was fixed, the flagged read threw inside the Fizz shell and
+500ed the document.)
+
 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/src/decode-loader-results.ts

@@ -18,7 +18,10 @@ import { LoaderRedirect } from "./loader-redirect.js";
  * decodeLoaderResults runs during the SERVER tree build on forceAwait/action
  * lanes, where a throw would collapse the whole payload — it routes signals
  * through the errorFallback slot instead (same visual: the slot replaces the
- * children under OutletProvider).
+ * children under OutletProvider). The document lane's `{ ssr: false }`
+ * results take the same non-throwing route (segment-system
+ * buildLoaderStreams): they are settled before the tree is built, and the
+ * read-site throw would land in the Fizz shell with no boundary to absorb it.
  */
 export const LOADER_NOT_FOUND_FALLBACK: unique symbol = Symbol(
   "rango.loaderNotFound",

package/src/rsc/shell-capture.ts

@@ -17,6 +17,7 @@
  */
 
 import React from "react";
+import { isLoaderDataResult } from "../types.js";
 import { bufferToBase64 } from "../cache/cf/cf-base64.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import { runBackground } from "../cache/background-task.js";
@@ -311,6 +312,14 @@ function refusedCaptureCeilingMs(): number {
 const refusedCaptures = new Map<string, { failures: number; until: number }>();
 
 /** True iff `key` is still inside its (exponential) backoff window. */
+function isSettledLoaderSignal(value: unknown): boolean {
+  return (
+    isLoaderDataResult(value) &&
+    !value.ok &&
+    (value.redirect !== undefined || value.notFound === true)
+  );
+}
+
 function isCaptureBackedOff(key: string): boolean {
   const entry = refusedCaptures.get(key);
   if (entry === undefined) return false;
@@ -1936,6 +1945,19 @@ async function captureAndStoreShell(
         // The container itself never settled: it is a hole (under an ancestor
         // boundary) or the trivial-prelude gate already fired. Omit — no pin.
         if (isLoaderHoleMarker(elided.value)) continue;
+        // redirect()/notFound() RESOLVE as ok:false envelopes
+        // (wrapLoaderWithErrorHandling), so the rejection check above never
+        // sees them; the tree builder resolves them to LoaderRedirect / the
+        // not-found UI (segment-system buildLoaderStreams), which must not
+        // bake into a shell every visitor shares.
+        if (isSettledLoaderSignal(elided.value)) {
+          warnCaptureRefusedOnce(
+            capture.key,
+            `the loader for segment "${segmentKey}" settled with redirect()/notFound() during capture; a request-specific signal must not bake into the shared shell. ` +
+              "Give its entry a loading() boundary so it stays on the live lane, or move the decision into middleware.",
+          );
+          return "refused";
+        }
         // Past the hole check: this container settled with real material that
         // bakes into the shell prelude (independent of the snapshot pin below).
         bakedLoaderMaterial = true;

package/src/segment-system.tsx

@@ -1,10 +1,16 @@
 import * as React from "react";
-import { createElement, type ReactNode, type ComponentType } from "react";
+import {
+  createElement,
+  type ReactNode,
+  type ComponentType,
+  isValidElement,
+} from "react";
 import { OutletProvider } from "./outlet-provider.js";
 import { withOptimisticCommitNone } from "./browser/optimistic-commit.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
 import type { ResolvedSegment, RootLayoutProps } from "./types.js";
 import { decodeLoaderResults } from "./decode-loader-results.js";
+import { LoaderRedirect } from "./loader-redirect.js";
 import { invariant } from "./errors.js";
 import {
   RouteContentWrapper,
@@ -203,20 +209,43 @@ function wrapDefaultOutletContent(
  * SSR-completeness contract must not depend on. Unflagged siblings keep the
  * promise (deliberate streaming). Flagged ids are collected as input for the
  * dev SSR-suspension diagnostic (ssr-suspension-warning.ts).
+ *
+ * The settled results also go through decodeLoaderResults here: a settled
+ * redirect()/notFound() (or an error with an errorBoundary() fallback) must
+ * be resolved to its node while the tree is built, exactly as the
+ * forceAwait/action lanes do, because the read-site throw has no boundary on
+ * the document lane — flagged content renders without Suspense and a layout
+ * reader sits above every boundary, so the throw is a Fizz shell error (500).
+ * `settledFallback` is that node; the caller plants it and, for a redirect,
+ * replaces the whole page (an ancestor reading the loader would still throw).
  */
 async function buildLoaderStreams(loaders: ResolvedSegment[]): Promise<{
   streams: Record<string, unknown>;
   awaitedIds: string[] | undefined;
+  settledFallback: ReactNode | undefined;
 }> {
   const streams: Record<string, unknown> = {};
   let awaitedIds: string[] | undefined;
+  let awaitedValues: unknown[] | undefined;
   for (const l of loaders) {
-    streams[l.loaderId!] = l.awaitBeforeFlush
-      ? await l.loaderData
-      : l.loaderData;
-    if (l.awaitBeforeFlush) (awaitedIds ??= []).push(l.loaderId!);
+    if (l.awaitBeforeFlush) {
+      const value = await l.loaderData;
+      streams[l.loaderId!] = value;
+      (awaitedIds ??= []).push(l.loaderId!);
+      (awaitedValues ??= []).push(value);
+    } else {
+      streams[l.loaderId!] = l.loaderData;
+    }
   }
-  return { streams, awaitedIds };
+  const settledFallback = awaitedIds
+    ? (decodeLoaderResults(awaitedValues!, awaitedIds).errorFallback ??
+      undefined)
+    : undefined;
+  return { streams, awaitedIds, settledFallback };
+}
+
+function isLoaderRedirectNode(node: ReactNode): boolean {
+  return isValidElement(node) && node.type === LoaderRedirect;
 }
 
 /**
@@ -539,10 +568,19 @@ export async function renderSegments(
           });
         }
       } else if (loaderEntries.length > 0) {
+        let settledFallback: ReactNode | undefined;
         ({
           streams: boundaryLoaderStreams,
           awaitedIds: boundaryAwaitedLoaderIds,
+          settledFallback,
         } = await buildLoaderStreams(loaderEntries));
+        if (settledFallback !== undefined) {
+          if (isLoaderRedirectNode(settledFallback)) {
+            content = settledFallback;
+            break;
+          }
+          nodeContent = settledFallback;
+        }
         if (segDebug) {
           segDebugLog(
             `segment ${id}: per-loader streams via LoaderBoundary (read-site suspense)`,
@@ -614,8 +652,19 @@ export async function renderSegments(
           }
         }
       } else if (layoutLoaders.length > 0) {
-        ({ streams: loaderStreams, awaitedIds: awaitedLoaderIds } =
-          await buildLoaderStreams(layoutLoaders));
+        let settledFallback: ReactNode | undefined;
+        ({
+          streams: loaderStreams,
+          awaitedIds: awaitedLoaderIds,
+          settledFallback,
+        } = await buildLoaderStreams(layoutLoaders));
+        if (settledFallback !== undefined) {
+          if (isLoaderRedirectNode(settledFallback)) {
+            content = settledFallback;
+            break;
+          }
+          errorFallback = settledFallback;
+        }
         if (segDebug) {
           segDebugLog(
             `segment ${id}: layout loaders streaming to read sites (no loading())`,