@rangojs/router 0.15.0 → 0.16.0

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/loader-store.d.ts

@@ -33,6 +33,12 @@
  * realm, so there is no cross-request pollution. Server renders never mutate
  * the store — the hook falls back to `OutletContext.loaderData`.
  */
+/** The loader-segment shape announcePendingStreams reads (ResolvedSegment). */
+export interface PendingStreamSource {
+    type: string;
+    loaderId?: string;
+    loaderData?: unknown;
+}
 export interface LoaderEntry<T = unknown> {
     readonly value: T | undefined;
     /**
@@ -77,6 +83,14 @@ export interface SubscribeOptions {
      * Refreshes this bucket in place (no params/body) and rejects on failure.
      */
     refetch?: () => Promise<void>;
+    /**
+     * Called by `announcePendingStreams` (inside a transition commit) when a
+     * navigation stream for this bucket's loader is still pending. The hook pins
+     * `isLoading: true` with a useOptimistic update; React reverts it when that
+     * transition commits. Route-context readers only — an ephemeral reader owns
+     * its own lifecycle.
+     */
+    onStreamPending?: () => void;
 }
 export declare class LoaderStore {
     private readonly entries;
@@ -84,6 +98,18 @@ export declare class LoaderStore {
     private readonly families;
     /** refresh group name -> set of bucket keys, for refreshGroups(). */
     private readonly groups;
+    /**
+     * loader.$$id -> per-loader streams a committed navigation is still
+     * receiving. Registered and announced by announcePendingStreams(), which
+     * browser/partial-update.ts calls INSIDE every transition commit, so a
+     * reader whose content is held on screen by that transition pins
+     * `isLoading: true` for the data it is still showing until the transition
+     * lands (use-loader.tsx). The new tree's own read of the loader suspends at
+     * the read site and never observes the flag. A Set, not a flag: overlapping
+     * navigations (second click before the first stream lands) keep the family
+     * pending until the LAST stream settles.
+     */
+    private readonly pendingStreams;
     private getOrCreate;
     private registerFamily;
     /**
@@ -178,6 +204,29 @@ export declare class LoaderStore {
      */
     clearFamily(loaderId: string): void;
     private notify;
+    /**
+     * Register a still-streaming per-loader result for `loaderId`. No-op for a
+     * settled Flight chunk (unwrapsSynchronously / "rejected"): the forceAwait
+     * and action lanes commit settled chunks, and a { ssr: false } loader is
+     * awaited before flush. Released as the stream settles, either way.
+     */
+    trackPendingStream(loaderId: string, stream: Promise<unknown>): void;
+    /** True while any navigation stream for `loaderId` is still pending. */
+    isStreamPending(loaderId: string): boolean;
+    /**
+     * Register the loader segments of a tree being committed whose data is
+     * still a pending promise, then fire `onStreamPending` on every subscriber
+     * of every family with a pending stream. MUST run inside the startTransition
+     * that commits the tree: the hook answers with a useOptimistic update, which
+     * React reverts exactly when that transition commits — so the held reader
+     * reports isLoading:true for as long as its data stays on screen and not a
+     * frame longer. Outside a transition React reverts an optimistic update on
+     * the next render, pinning nothing useful. Registering here rather than in
+     * the tree build keeps register + announce in one call; settled chunks
+     * (cached/reused segments, forceAwait lanes) are skipped by
+     * trackPendingStream.
+     */
+    announcePendingStreams(segments: readonly PendingStreamSource[]): void;
     /**
      * Test-only escape hatch. Drops every entry. Production code should never
      * call this; the store is process-scoped and lives for the tab's lifetime.

package/dist/types/route-definition/helpers-types.d.ts

@@ -343,8 +343,10 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *    through React's startTransition, so a same-route nav (same route,
      *    different params, e.g. /product/1 -> /product/2) holds the previous
      *    content while the new loader resolves instead of flashing the route's
-     *    loading() skeleton (see segment-system.tsx inTransitionScope). This is
-     *    also the precondition for any view-transition animation.
+     *    loading() skeleton (see segment-system.tsx inTransitionScope). Held
+     *    useLoader readers of the re-run loaders report isLoading: true until
+     *    the new data commits (use-loader.tsx). This is also the precondition
+     *    for any view-transition animation.
      * 2. <ViewTransition> (experimental React only): the segment content is also
      *    wrapped in React's <ViewTransition>, so the held swap cross-fades/morphs.
      *    Layered on by default; pass { viewTransition: false } to keep #1 without

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

@@ -89,6 +89,8 @@ export type CacheItem = {
 export type TransitionItem = {
     name: string;
     type: "transition";
+    /** Wrapper form only: the children it wraps (see hasRoutesInItem). */
+    uses?: AllUseItems[];
 };
 /**
  * Typed transition item that carries child routes as phantom type

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/types/thenable-status.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Thenable statuses React's `use()` unwraps without suspending: React's
+ * re-check after `.then()` handles "fulfilled", and Flight chunks in the
+ * resolved_* states initialize synchronously inside that same call. Anything
+ * else (pending, blocked, an unstamped native promise) suspends at least once.
+ * Shared by the dev SSR-suspension diagnostic and the held-navigation
+ * isLoading registration (loader-store.ts), which must agree on "settled".
+ */
+export declare function unwrapsSynchronously(stream: Promise<unknown>): boolean;

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.16.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -3993,7 +3993,7 @@ var package_default = {
   },
   dependencies: {
     "@types/debug": "^4.1.12",
-    "@vitejs/plugin-rsc": "^0.5.34",
+    "@vitejs/plugin-rsc": "^0.5.35",
     debug: "^4.4.1",
     "magic-string": "^0.30.17",
     picomatch: "^4.0.4",
@@ -4026,7 +4026,7 @@ var package_default = {
     "@playwright/test": "^1.49.1",
     "@testing-library/react": ">=16",
     "@vercel/functions": "^3.0.0",
-    "@vitejs/plugin-rsc": "^0.5.34",
+    "@vitejs/plugin-rsc": "^0.5.35",
     react: ">=19.2.8 <20",
     "react-dom": ">=19.2.8 <20",
     vite: "^8.0.16",
@@ -7766,10 +7766,17 @@ import {
   useContext as useContext4,
   useEffect as useEffect2,
   useMemo as useMemo3,
+  useOptimistic,
   useRef,
   useState
 } from "react";
 
+// src/thenable-status.ts
+function unwrapsSynchronously(stream) {
+  const status = stream.status;
+  return status === "fulfilled" || status === "resolved_model" || status === "resolved_module";
+}
+
 // src/loader-store.ts
 var EMPTY_SNAPSHOT = Object.freeze({
   value: void 0,
@@ -7790,6 +7797,18 @@ var LoaderStore = class {
     this.families = /* @__PURE__ */ new Map();
     /** refresh group name -> set of bucket keys, for refreshGroups(). */
     this.groups = /* @__PURE__ */ new Map();
+    /**
+     * loader.$$id -> per-loader streams a committed navigation is still
+     * receiving. Registered and announced by announcePendingStreams(), which
+     * browser/partial-update.ts calls INSIDE every transition commit, so a
+     * reader whose content is held on screen by that transition pins
+     * `isLoading: true` for the data it is still showing until the transition
+     * lands (use-loader.tsx). The new tree's own read of the loader suspends at
+     * the read site and never observes the flag. A Set, not a flag: overlapping
+     * navigations (second click before the first stream lands) keep the family
+     * pending until the LAST stream settles.
+     */
+    this.pendingStreams = /* @__PURE__ */ new Map();
   }
   getOrCreate(bucketKey) {
     let e = this.entries.get(bucketKey);
@@ -7803,7 +7822,8 @@ var LoaderStore = class {
         pendingClear: false,
         clearWhenSettled: false,
         groups: /* @__PURE__ */ new Map(),
-        refetch: void 0
+        refetch: void 0,
+        streamPendingListeners: /* @__PURE__ */ new Set()
       };
       this.entries.set(bucketKey, e);
     }
@@ -7837,8 +7857,11 @@ var LoaderStore = class {
     e.pendingClear = false;
     e.clearWhenSettled = false;
     e.listeners.add(cb);
+    const onStreamPending = options?.onStreamPending;
+    if (onStreamPending) e.streamPendingListeners.add(onStreamPending);
     return () => {
       e.listeners.delete(cb);
+      if (onStreamPending) e.streamPendingListeners.delete(onStreamPending);
       for (const group of groups) this.releaseGroup(group, bucketKey, e);
       this.maybeScheduleRefcountClear(bucketKey, e);
     };
@@ -8080,6 +8103,63 @@ var LoaderStore = class {
   notify(e) {
     for (const cb of e.listeners) cb();
   }
+  /**
+   * Register a still-streaming per-loader result for `loaderId`. No-op for a
+   * settled Flight chunk (unwrapsSynchronously / "rejected"): the forceAwait
+   * and action lanes commit settled chunks, and a { ssr: false } loader is
+   * awaited before flush. Released as the stream settles, either way.
+   */
+  trackPendingStream(loaderId, stream) {
+    if (unwrapsSynchronously(stream) || stream.status === "rejected") {
+      return;
+    }
+    let set = this.pendingStreams.get(loaderId);
+    if (set?.has(stream)) return;
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.pendingStreams.set(loaderId, set);
+    }
+    set.add(stream);
+    const release = () => {
+      const current = this.pendingStreams.get(loaderId);
+      if (!current || !current.delete(stream)) return;
+      if (current.size === 0) this.pendingStreams.delete(loaderId);
+    };
+    stream.then(release, release);
+  }
+  /** True while any navigation stream for `loaderId` is still pending. */
+  isStreamPending(loaderId) {
+    return this.pendingStreams.has(loaderId);
+  }
+  /**
+   * Register the loader segments of a tree being committed whose data is
+   * still a pending promise, then fire `onStreamPending` on every subscriber
+   * of every family with a pending stream. MUST run inside the startTransition
+   * that commits the tree: the hook answers with a useOptimistic update, which
+   * React reverts exactly when that transition commits — so the held reader
+   * reports isLoading:true for as long as its data stays on screen and not a
+   * frame longer. Outside a transition React reverts an optimistic update on
+   * the next render, pinning nothing useful. Registering here rather than in
+   * the tree build keeps register + announce in one call; settled chunks
+   * (cached/reused segments, forceAwait lanes) are skipped by
+   * trackPendingStream.
+   */
+  announcePendingStreams(segments) {
+    for (const segment of segments) {
+      if (segment.type === "loader" && segment.loaderId && segment.loaderData instanceof Promise) {
+        this.trackPendingStream(segment.loaderId, segment.loaderData);
+      }
+    }
+    for (const loaderId of this.pendingStreams.keys()) {
+      const fam = this.families.get(loaderId);
+      if (!fam) continue;
+      for (const bucketKey of fam) {
+        const e = this.entries.get(bucketKey);
+        if (!e) continue;
+        for (const cb of e.streamPendingListeners) cb();
+      }
+    }
+  }
   /**
    * Test-only escape hatch. Drops every entry. Production code should never
    * call this; the store is process-scoped and lives for the tab's lifetime.
@@ -8089,6 +8169,7 @@ var LoaderStore = class {
     this.entries.clear();
     this.families.clear();
     this.groups.clear();
+    this.pendingStreams.clear();
   }
 };
 var loaderStore = new LoaderStore();
@@ -8098,7 +8179,7 @@ import {
   useContext as useContext5,
   useState as useState2,
   useEffect as useEffect3,
-  useOptimistic,
+  useOptimistic as useOptimistic2,
   startTransition as startTransition2,
   useRef as useRef2
 } from "react";
@@ -8134,7 +8215,7 @@ import {
   useState as useState6,
   useEffect as useEffect7,
   useRef as useRef6,
-  useOptimistic as useOptimistic2,
+  useOptimistic as useOptimistic3,
   startTransition as startTransition3
 } from "react";
 
@@ -8213,7 +8294,7 @@ import {
   useState as useState11,
   useEffect as useEffect11,
   useRef as useRef10,
-  useOptimistic as useOptimistic3,
+  useOptimistic as useOptimistic4,
   startTransition as startTransition4
 } from "react";
 var LinkContext = createContext7(
@@ -8677,7 +8758,7 @@ import {
   useState as useState13,
   useEffect as useEffect15,
   useRef as useRef13,
-  useOptimistic as useOptimistic4,
+  useOptimistic as useOptimistic5,
   startTransition as startTransition5
 } from "react";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -184,7 +184,7 @@
   },
   "dependencies": {
     "@types/debug": "^4.1.12",
-    "@vitejs/plugin-rsc": "^0.5.34",
+    "@vitejs/plugin-rsc": "^0.5.35",
     "debug": "^4.4.1",
     "magic-string": "^0.30.17",
     "picomatch": "^4.0.4",
@@ -217,7 +217,7 @@
     "@playwright/test": "^1.49.1",
     "@testing-library/react": ">=16",
     "@vercel/functions": "^3.0.0",
-    "@vitejs/plugin-rsc": "^0.5.34",
+    "@vitejs/plugin-rsc": "^0.5.35",
     "react": ">=19.2.8 <20",
     "react-dom": ">=19.2.8 <20",
     "vite": "^8.0.16",

package/skills/hooks/data.md

@@ -13,7 +13,8 @@ function ProductPrice() {
   const { data, isLoading, error } = useLoader(ProductLoader);
 
   // data: T (guaranteed - throws if not in context)
-  // isLoading: boolean (refetch/load() states — NOT the initial streamed read)
+  // isLoading: boolean (refetch/load() states + a held navigation replacing
+  //   this data — NOT the initial streamed read)
   // error: Error | null
 
   return <span>${data.price}</span>;
@@ -29,6 +30,27 @@ component renders, `data` is present. (On document loads a loader registered
 with `{ ssr: false }` is already settled at first paint, so its
 reads never suspend there — see `/loader`.)
 
+**A held navigation flags the data it keeps on screen.** When a navigation
+keeps the current content visible while the loader re-runs (a `transition()`
+same-route nav, a same-structure search/filter nav), the reader that is still
+showing the OLD data reports `isLoading: true` from
+the moment the new tree is committed until the new data lands — render your
+stale indicator from it. The flag never flashes back to `false` on the old
+data: it flips in the same commit that swaps `data`. Only loaders the
+navigation actually re-runs are flagged: a layout loader the server does not
+re-execute keeps its data and stays `isLoading: false`. It never applies to a
+navigation that remounts the route (that reader is gone; the skeleton shows),
+to a fully-prefetched nav (its data is already settled when it commits, so
+nothing is pending to flag), or to an ephemeral `useFetchLoader` read outside
+route context.
+
+```tsx
+function ProductPrice() {
+  const { data, isLoading } = useLoader(ProductLoader);
+  return <span style={{ opacity: isLoading ? 0.5 : 1 }}>${data.price}</span>; // dims while /products/1 -> /products/2 streams the next price
+}
+```
+
 **Precondition**: Loader must be registered on route via `loader()` helper.
 
 Loaders can also be passed as props from server to client components:

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/skills/view-transitions/SKILL.md

@@ -8,7 +8,7 @@ argument-hint: [layout|route|parallel|intercept]
 
 `transition()` opts a route (or group of routes) into transition-driven navigation. It does two things, and you choose how far to go:
 
-1. **`startTransition` (the foundation).** The navigation commit is driven through React's `startTransition`. That holds the previous content across a same-route navigation (stale-while-revalidate — no loading-skeleton flash) and is the **precondition** for any view-transition animation. Works on **all** React versions.
+1. **`startTransition` (the foundation).** The navigation commit is driven through React's `startTransition`. That holds the previous content across a same-route navigation (stale-while-revalidate — no loading-skeleton flash) and is the **precondition** for any view-transition animation. Works on **all** React versions. While the hold lasts, `useLoader` readers of the loaders being re-run report `isLoading: true` — render your stale indicator from it (see the hooks skill, `data.md`).
 2. **`<ViewTransition>` (the animation, layered on top).** On React 19.3+ (or an experimental build), rango also wraps the segment content in React's `<ViewTransition>` so the swap cross-fades/morphs. This is the only part that needs 19.3+; pass `viewTransition: false` to keep #1 without it (and place your own `<ViewTransition>` where you want it).
 
 > The `<ViewTransition>` layer requires a React that exports `<ViewTransition>` / `addTransitionType`: stable 19.3+ or an experimental build. Rango feature-detects it; on React 19.2 that layer is a no-op — but the `startTransition` driving (content hold) still applies.

package/src/browser/partial-update.ts

@@ -31,6 +31,7 @@ import {
 } from "./validate-redirect-origin.js";
 import type { NavigationUpdate } from "./types.js";
 import { OPTIMISTIC_COMMIT_TRANSITION_TYPE } from "./optimistic-commit.js";
+import { loaderStore } from "../loader-store.js";
 import {
   collectClientRevalidationDecisions,
   setActiveInterceptTargets,
@@ -140,6 +141,28 @@ export function createPartialUpdater(
     return cached?.segments || [];
   }
 
+  /**
+   * Transition commit. Every held commit announces the loader streams the
+   * committed tree is still receiving (loader-store.ts announcePendingStreams)
+   * so held useLoader readers pin isLoading:true until this transition lands;
+   * settled/cached segments make it a no-op. Urgent commits call onUpdate
+   * directly: nothing is held there, a reader of a pending stream suspends to
+   * its fallback.
+   */
+  function commitInTransition(
+    segments: readonly ResolvedSegment[],
+    update: NavigationUpdate,
+    transitionTypes: readonly string[],
+  ): void {
+    startTransition(() => {
+      loaderStore.announcePendingStreams(segments);
+      if (addTransitionType) {
+        for (const type of transitionTypes) addTransitionType(type);
+      }
+      onUpdate(update);
+    });
+  }
+
   async function fetchPartialUpdate(
     targetUrl: string,
     segmentIds: string[] | undefined,
@@ -351,12 +374,7 @@ export function createPartialUpdater(
           };
 
           if (shouldStartViewTransition(existingSegments)) {
-            startTransition(() => {
-              if (addTransitionType) {
-                addTransitionType("navigation");
-              }
-              onUpdate(cachedUpdate);
-            });
+            commitInTransition(existingSegments, cachedUpdate, ["navigation"]);
           } else {
             onUpdate(cachedUpdate);
           }
@@ -589,31 +607,25 @@ export function createPartialUpdater(
 
       const scrollPayload = toScrollPayload(navScroll);
 
+      const update: NavigationUpdate = {
+        root: newTree,
+        metadata: payload.metadata!,
+        scroll: scrollPayload,
+      };
       if (mode.type === "action" || mode.type === "stale-revalidation") {
-        startTransition(() => {
-          if (hasTransition && addTransitionType) {
-            addTransitionType("action");
-          }
-          onUpdate({
-            root: newTree,
-            metadata: payload.metadata!,
-            scroll: scrollPayload,
-          });
-        });
+        commitInTransition(
+          reconciled.mainSegments,
+          update,
+          hasTransition ? ["action"] : [],
+        );
       } else if (hasTransition) {
-        startTransition(() => {
-          if (addTransitionType) {
-            addTransitionType("navigation");
-            if (optimisticPresented) {
-              addTransitionType(OPTIMISTIC_COMMIT_TRANSITION_TYPE);
-            }
-          }
-          onUpdate({
-            root: newTree,
-            metadata: payload.metadata!,
-            scroll: scrollPayload,
-          });
-        });
+        commitInTransition(
+          reconciled.mainSegments,
+          update,
+          optimisticPresented
+            ? ["navigation", OPTIMISTIC_COMMIT_TRANSITION_TYPE]
+            : ["navigation"],
+        );
       } else if (fullyPrefetched || isSameStructureNav || optimisticPresented) {
         // Content-hold commit, two triggers. Fully-prefetched nav: the payload
         // is fully resolved (forceAwait above), so the transition commits
@@ -637,26 +649,17 @@ export function createPartialUpdater(
         // optimistic clientUrls() presentation commits here too: the group
         // segment reconciles in place (clientGroup key), so a read that still
         // suspends must hold the presented content, not flash a fallback.
-        startTransition(() => {
-          if (optimisticPresented && addTransitionType) {
-            addTransitionType(OPTIMISTIC_COMMIT_TRANSITION_TYPE);
-          }
-          onUpdate({
-            root: newTree,
-            metadata: payload.metadata!,
-            scroll: scrollPayload,
-          });
-        });
+        commitInTransition(
+          reconciled.mainSegments,
+          update,
+          optimisticPresented ? [OPTIMISTIC_COMMIT_TRANSITION_TYPE] : [],
+        );
       } else {
         // Cold/partially-prefetched nav that mounts NEW segments: normal
         // commit so fallbacks stream like a first load and the click has
         // visible feedback. Explicit transition() routes keep the
         // content-hold via the hasTransition branch above (the opt-in).
-        onUpdate({
-          root: newTree,
-          metadata: payload.metadata!,
-          scroll: scrollPayload,
-        });
+        onUpdate(update);
       }
 
       debugLog("[Browser] Navigation complete");
@@ -689,6 +692,11 @@ export function createPartialUpdater(
 
       const fullHasTransition = shouldStartViewTransition(segments);
       const fullScrollPayload = toScrollPayload(fullScroll);
+      const fullUpdate: NavigationUpdate = {
+        root: newTree,
+        metadata: payload.metadata!,
+        scroll: fullScrollPayload,
+      };
 
       if (mode.type === "stale-revalidation") {
         await rawStreamComplete;
@@ -704,44 +712,21 @@ export function createPartialUpdater(
           );
           return;
         }
-        startTransition(() => {
-          if (fullHasTransition && addTransitionType) {
-            addTransitionType("action");
-          }
-          onUpdate({
-            root: newTree,
-            metadata: payload.metadata!,
-            scroll: fullScrollPayload,
-          });
-        });
+        commitInTransition(
+          segments,
+          fullUpdate,
+          fullHasTransition ? ["action"] : [],
+        );
       } else if (mode.type === "action") {
-        startTransition(() => {
-          if (fullHasTransition && addTransitionType) {
-            addTransitionType("action");
-          }
-          onUpdate({
-            root: newTree,
-            metadata: payload.metadata!,
-            scroll: fullScrollPayload,
-          });
-        });
+        commitInTransition(
+          segments,
+          fullUpdate,
+          fullHasTransition ? ["action"] : [],
+        );
       } else if (fullHasTransition) {
-        startTransition(() => {
-          if (addTransitionType) {
-            addTransitionType("navigation");
-          }
-          onUpdate({
-            root: newTree,
-            metadata: payload.metadata!,
-            scroll: fullScrollPayload,
-          });
-        });
+        commitInTransition(segments, fullUpdate, ["navigation"]);
       } else {
-        onUpdate({
-          root: newTree,
-          metadata: payload.metadata!,
-          scroll: fullScrollPayload,
-        });
+        onUpdate(fullUpdate);
       }
 
       return;

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/loader-store.ts

@@ -34,6 +34,15 @@
  * the store — the hook falls back to `OutletContext.loaderData`.
  */
 
+import { unwrapsSynchronously } from "./thenable-status.js";
+
+/** The loader-segment shape announcePendingStreams reads (ResolvedSegment). */
+export interface PendingStreamSource {
+  type: string;
+  loaderId?: string;
+  loaderData?: unknown;
+}
+
 export interface LoaderEntry<T = unknown> {
   readonly value: T | undefined;
   /**
@@ -87,6 +96,14 @@ export interface SubscribeOptions {
    * Refreshes this bucket in place (no params/body) and rejects on failure.
    */
   refetch?: () => Promise<void>;
+  /**
+   * Called by `announcePendingStreams` (inside a transition commit) when a
+   * navigation stream for this bucket's loader is still pending. The hook pins
+   * `isLoading: true` with a useOptimistic update; React reverts it when that
+   * transition commits. Route-context readers only — an ephemeral reader owns
+   * its own lifecycle.
+   */
+  onStreamPending?: () => void;
 }
 
 interface InternalEntry {
@@ -118,6 +135,8 @@ interface InternalEntry {
   groups: Map<string, number>;
   /** Plain-GET refresh thunk for `refreshGroups`, set while in any group. */
   refetch: (() => Promise<void>) | undefined;
+  /** Subscribers' `onStreamPending` callbacks (see SubscribeOptions). */
+  streamPendingListeners: Set<() => void>;
 }
 
 /**
@@ -137,6 +156,18 @@ export class LoaderStore {
   private readonly families = new Map<string, Set<string>>();
   /** refresh group name -> set of bucket keys, for refreshGroups(). */
   private readonly groups = new Map<string, Set<string>>();
+  /**
+   * loader.$$id -> per-loader streams a committed navigation is still
+   * receiving. Registered and announced by announcePendingStreams(), which
+   * browser/partial-update.ts calls INSIDE every transition commit, so a
+   * reader whose content is held on screen by that transition pins
+   * `isLoading: true` for the data it is still showing until the transition
+   * lands (use-loader.tsx). The new tree's own read of the loader suspends at
+   * the read site and never observes the flag. A Set, not a flag: overlapping
+   * navigations (second click before the first stream lands) keep the family
+   * pending until the LAST stream settles.
+   */
+  private readonly pendingStreams = new Map<string, Set<Promise<unknown>>>();
 
   private getOrCreate(bucketKey: string): InternalEntry {
     let e = this.entries.get(bucketKey);
@@ -151,6 +182,7 @@ export class LoaderStore {
         clearWhenSettled: false,
         groups: new Map(),
         refetch: undefined,
+        streamPendingListeners: new Set(),
       };
       this.entries.set(bucketKey, e);
     }
@@ -195,8 +227,11 @@ export class LoaderStore {
     e.pendingClear = false;
     e.clearWhenSettled = false;
     e.listeners.add(cb);
+    const onStreamPending = options?.onStreamPending;
+    if (onStreamPending) e.streamPendingListeners.add(onStreamPending);
     return () => {
       e.listeners.delete(cb);
+      if (onStreamPending) e.streamPendingListeners.delete(onStreamPending);
       // Group membership is refcounted per subscriber so refreshGroups() never
       // fetches for an unmounted reader, and a bucket shared by subscribers in
       // different groups stays in each group until ALL of that group's
@@ -479,6 +514,73 @@ export class LoaderStore {
     for (const cb of e.listeners) cb();
   }
 
+  /**
+   * Register a still-streaming per-loader result for `loaderId`. No-op for a
+   * settled Flight chunk (unwrapsSynchronously / "rejected"): the forceAwait
+   * and action lanes commit settled chunks, and a { ssr: false } loader is
+   * awaited before flush. Released as the stream settles, either way.
+   */
+  trackPendingStream(loaderId: string, stream: Promise<unknown>): void {
+    if (
+      unwrapsSynchronously(stream) ||
+      (stream as { status?: string }).status === "rejected"
+    ) {
+      return;
+    }
+    let set = this.pendingStreams.get(loaderId);
+    if (set?.has(stream)) return;
+    if (!set) {
+      set = new Set();
+      this.pendingStreams.set(loaderId, set);
+    }
+    set.add(stream);
+    const release = () => {
+      const current = this.pendingStreams.get(loaderId);
+      if (!current || !current.delete(stream)) return;
+      if (current.size === 0) this.pendingStreams.delete(loaderId);
+    };
+    stream.then(release, release);
+  }
+
+  /** True while any navigation stream for `loaderId` is still pending. */
+  isStreamPending(loaderId: string): boolean {
+    return this.pendingStreams.has(loaderId);
+  }
+
+  /**
+   * Register the loader segments of a tree being committed whose data is
+   * still a pending promise, then fire `onStreamPending` on every subscriber
+   * of every family with a pending stream. MUST run inside the startTransition
+   * that commits the tree: the hook answers with a useOptimistic update, which
+   * React reverts exactly when that transition commits — so the held reader
+   * reports isLoading:true for as long as its data stays on screen and not a
+   * frame longer. Outside a transition React reverts an optimistic update on
+   * the next render, pinning nothing useful. Registering here rather than in
+   * the tree build keeps register + announce in one call; settled chunks
+   * (cached/reused segments, forceAwait lanes) are skipped by
+   * trackPendingStream.
+   */
+  announcePendingStreams(segments: readonly PendingStreamSource[]): void {
+    for (const segment of segments) {
+      if (
+        segment.type === "loader" &&
+        segment.loaderId &&
+        segment.loaderData instanceof Promise
+      ) {
+        this.trackPendingStream(segment.loaderId, segment.loaderData);
+      }
+    }
+    for (const loaderId of this.pendingStreams.keys()) {
+      const fam = this.families.get(loaderId);
+      if (!fam) continue;
+      for (const bucketKey of fam) {
+        const e = this.entries.get(bucketKey);
+        if (!e) continue;
+        for (const cb of e.streamPendingListeners) cb();
+      }
+    }
+  }
+
   /**
    * Test-only escape hatch. Drops every entry. Production code should never
    * call this; the store is process-scoped and lives for the tab's lifetime.
@@ -488,6 +590,7 @@ export class LoaderStore {
     this.entries.clear();
     this.families.clear();
     this.groups.clear();
+    this.pendingStreams.clear();
   }
 }
 

package/src/route-definition/dsl-helpers.ts

@@ -48,8 +48,17 @@ import { resolveHandlerUse, mergeHandlerUse } from "./resolve-handler-use.js";
 import { ALL_USE_ITEM_TYPES } from "./use-item-types.js";
 
 /**
- * Check if an item contains routes (directly or inside nested structures like cache).
+ * Check if an item contains routes (directly or inside nested wrappers).
  * Used to determine if a layout or cache should be treated as an orphan.
+ *
+ * Recurses through ANY item carrying `uses` (cache, layout, middleware,
+ * wrapper-form transition) rather than an enumerated list: a wrapper helper
+ * that returns `uses` is covered the moment it exists. Scar tissue: the list
+ * form missed `transition`, so `layout(Shell, () => [transition(cfg, () =>
+ * [routes])])` was classified orphan and pushed onto its PARENT's layout[] —
+ * rendering around every sibling route (test-app TxBlockShell wrapped "/").
+ * parallel()/intercept() register their children by side effect and return
+ * no `uses`, so a layout whose only children are those still reads as orphan.
  */
 const hasRoutesInItem = (item: AllUseItems): boolean => {
   if (item.type === "route") return true;
@@ -57,16 +66,8 @@ const hasRoutesInItem = (item: AllUseItems): boolean => {
   // to prevent the parent layout from being misclassified as orphan,
   // which would clear its parent pointer and break the middleware chain.
   if (item.type === "include") return true;
-  if (item.type === "cache" && item.uses) {
-    return item.uses.some((child) => hasRoutesInItem(child));
-  }
-  if (item.type === "layout" && item.uses) {
-    return item.uses.some((child) => hasRoutesInItem(child));
-  }
-  if (item.type === "middleware" && item.uses) {
-    return item.uses.some((child) => hasRoutesInItem(child));
-  }
-  return false;
+  const uses = (item as { uses?: AllUseItems[] }).uses;
+  return uses ? uses.some(hasRoutesInItem) : false;
 };
 
 /**
@@ -958,7 +959,11 @@ const transition = (
 
   if (isOrphan(result)) attachOrphanSibling(ctx.parent, entry);
 
-  return { name: namespace, type: "transition" } as TransitionItem;
+  return {
+    name: namespace,
+    type: "transition",
+    uses: result,
+  } as TransitionItem;
 };
 
 const route: RouteHelpers<any, any>["route"] = (name, handler, use) => {

package/src/route-definition/helpers-types.ts

@@ -457,8 +457,10 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *    through React's startTransition, so a same-route nav (same route,
    *    different params, e.g. /product/1 -> /product/2) holds the previous
    *    content while the new loader resolves instead of flashing the route's
-   *    loading() skeleton (see segment-system.tsx inTransitionScope). This is
-   *    also the precondition for any view-transition animation.
+   *    loading() skeleton (see segment-system.tsx inTransitionScope). Held
+   *    useLoader readers of the re-run loaders report isLoading: true until
+   *    the new data commits (use-loader.tsx). This is also the precondition
+   *    for any view-transition animation.
    * 2. <ViewTransition> (experimental React only): the segment content is also
    *    wrapped in React's <ViewTransition>, so the held swap cross-fades/morphs.
    *    Layered on by default; pass { viewTransition: false } to keep #1 without

package/src/route-types.ts

@@ -106,6 +106,8 @@ export type CacheItem = {
 export type TransitionItem = {
   name: string;
   type: "transition";
+  /** Wrapper form only: the children it wraps (see hasRoutesInItem). */
+  uses?: AllUseItems[];
 };
 
 /**

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())`,

package/src/ssr-suspension-warning.ts

@@ -18,20 +18,9 @@
  * render's warnings through the once-per-id set).
  */
 
-const warned = new Set<string>();
+import { unwrapsSynchronously } from "./thenable-status.js";
 
-/** Thenable statuses `use()` unwraps without suspending: React's re-check
- *  after `.then()` handles "fulfilled", and Flight chunks in the resolved_*
- *  states initialize synchronously inside that same call. Anything else
- *  (pending, blocked, an unstamped native promise) suspends at least once. */
-function unwrapsSynchronously(stream: Promise<unknown>): boolean {
-  const status = (stream as { status?: string }).status;
-  return (
-    status === "fulfilled" ||
-    status === "resolved_model" ||
-    status === "resolved_module"
-  );
-}
+const warned = new Set<string>();
 
 export function warnAwaitedSsrSuspension(
   loaderId: string,

package/src/theme/ThemeProvider.tsx

@@ -114,8 +114,6 @@ export function ThemeProvider({
   initialTheme,
   children,
 }: ThemeProviderProps): React.ReactNode {
-  const [mounted, setMounted] = useState(false);
-
   // HYDRATION PARITY: this initializer is the server (SSR/resume) render AND
   // the client's hydration render — both must produce the same value. It must
   // NEVER read cookie/localStorage: whenever the payload's initialTheme
@@ -132,7 +130,6 @@ export function ThemeProvider({
   const [systemTheme, setSystemTheme] = useState<ResolvedTheme>("light");
 
   useEffect(() => {
-    setMounted(true);
     setSystemTheme(getSystemTheme());
     // Re-sync state from an EXPLICITLY stored theme after mount. initialTheme
     // comes from the payload and can legitimately differ from the visitor's
@@ -229,18 +226,16 @@ export function ThemeProvider({
     };
   }, [config]);
 
+  // No pre-mount special case: `theme` and `systemTheme` ("light" until the
+  // mount effect) are identical on the server and in the hydration render, so
+  // this is hydration-safe, and a concrete defaultTheme without an initialTheme
+  // no longer flips at mount.
   const resolvedTheme: ResolvedTheme = useMemo(() => {
-    if (!mounted) {
-      if (initialTheme && initialTheme !== "system") {
-        return initialTheme as ResolvedTheme;
-      }
-      return "light";
-    }
     if (theme === "system" && config.enableSystem) {
       return systemTheme;
     }
     return theme as ResolvedTheme;
-  }, [theme, systemTheme, config.enableSystem, mounted, initialTheme]);
+  }, [theme, systemTheme, config.enableSystem]);
 
   const themes = useMemo(() => {
     if (config.enableSystem) {
@@ -249,16 +244,23 @@ export function ThemeProvider({
     return config.themes;
   }, [config.themes, config.enableSystem]);
 
+  // Keyed on the exposed field values only: a NEW context object with
+  // unchanged fields propagates into every dehydrated Suspense boundary still
+  // streaming in (React cannot see their consumers) and makes React
+  // client-render those boundaries instead of adopting the server HTML their
+  // $RC script delivers. A field that genuinely changes at mount (dark system
+  // theme, stored override) must still publish; that case stays open
+  // (CHANGELOG).
   const contextValue: ThemeContextValue = useMemo(
     () => ({
       theme,
       setTheme,
       resolvedTheme,
-      systemTheme: mounted ? systemTheme : "light",
+      systemTheme,
       themes,
       config,
     }),
-    [theme, setTheme, resolvedTheme, systemTheme, themes, config, mounted],
+    [theme, setTheme, resolvedTheme, systemTheme, themes, config],
   );
 
   return (

package/src/thenable-status.ts

@@ -0,0 +1,16 @@
+/**
+ * Thenable statuses React's `use()` unwraps without suspending: React's
+ * re-check after `.then()` handles "fulfilled", and Flight chunks in the
+ * resolved_* states initialize synchronously inside that same call. Anything
+ * else (pending, blocked, an unstamped native promise) suspends at least once.
+ * Shared by the dev SSR-suspension diagnostic and the held-navigation
+ * isLoading registration (loader-store.ts), which must agree on "settled".
+ */
+export function unwrapsSynchronously(stream: Promise<unknown>): boolean {
+  const status = (stream as { status?: string }).status;
+  return (
+    status === "fulfilled" ||
+    status === "resolved_model" ||
+    status === "resolved_module"
+  );
+}

package/src/use-loader.tsx

@@ -8,6 +8,7 @@ import {
   useContext,
   useEffect,
   useMemo,
+  useOptimistic,
   useRef,
   useState,
   type ReactNode,
@@ -261,6 +262,13 @@ function useLoaderInternal<T>(
     }
   }, [loaderId, bucketKey]);
 
+  // Held-navigation pin: a transition commit whose stream for this loader is
+  // still pending announces it (loader-store.ts announcePendingStreams, which
+  // documents the lane discipline); this optimistic update renders urgently
+  // on the held content and React reverts it when that transition commits,
+  // i.e. together with the new data.
+  const [streamPending, setStreamPending] = useOptimistic(false);
+
   const [sharedState, setSharedState] = useState<{
     bucketKey: string;
     snapshot: LoaderEntry;
@@ -295,6 +303,9 @@ function useLoaderInternal<T>(
         ephemeral: !hasContextData,
         group: hasGroups ? groupList : undefined,
         refetch: hasGroups ? groupRefetch : undefined,
+        onStreamPending: hasContextData
+          ? () => startTransition(() => setStreamPending(true))
+          : undefined,
       },
     );
     // eslint-disable-next-line react-hooks/exhaustive-deps -- intentional:
@@ -362,7 +373,7 @@ function useLoaderInternal<T>(
     : sharedSnapshot.hasValue
       ? (sharedSnapshot.value as T | undefined)
       : contextData;
-  const isLoading = localIsLoading || sharedSnapshot.isLoading;
+  const isLoading = localIsLoading || sharedSnapshot.isLoading || streamPending;
   const error = localError ?? sharedSnapshot.error;
 
   const throwOnError = options?.throwOnError ?? true;