@rangojs/router 0.0.0-experimental.133 → 0.0.0-experimental.134

package/dist/vite/index.js

@@ -2296,7 +2296,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.133",
+  version: "0.0.0-experimental.134",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -4031,6 +4031,19 @@ import { readFileSync as readFileSync6 } from "node:fs";
 import { createRequire as createRequire2, register } from "node:module";
 import { pathToFileURL } from "node:url";
 
+// src/vite/inject-client-debug.ts
+function injectClientDebugFlag(id) {
+  if (!id.includes("internal-debug")) return null;
+  const norm = id.replace(/\\/g, "/");
+  const isInternalDebug = /\/internal-debug\.[cm]?[jt]sx?(\?|$)/.test(norm) && (norm.includes("/@rangojs/router/") || norm.includes("/packages/rangojs-router/"));
+  if (!isInternalDebug) return null;
+  return {
+    code: `export const INTERNAL_RANGO_DEBUG = ${!!process.env.INTERNAL_RANGO_DEBUG};
+`,
+    map: null
+  };
+}
+
 // src/vite/plugins/virtual-stub-plugin.ts
 function createVirtualStubPlugin() {
   const STUB_PREFIXES = [
@@ -4318,7 +4331,7 @@ function checkSelfGenWrite(state, filePath, consume) {
 import { AsyncLocalStorage } from "node:async_hooks";
 
 // src/internal-debug.ts
-var INTERNAL_RANGO_DEBUG = typeof __RANGO_DEBUG__ !== "undefined" ? __RANGO_DEBUG__ : typeof process !== "undefined" && Boolean(process.env?.INTERNAL_RANGO_DEBUG);
+var INTERNAL_RANGO_DEBUG = typeof process !== "undefined" && Boolean(process.env?.INTERNAL_RANGO_DEBUG);
 
 // src/router/logging.ts
 var routerLogContext = new AsyncLocalStorage();
@@ -6102,13 +6115,13 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
   let viteMode = "production";
   return {
     name: "@rangojs/router:discovery",
-    config() {
-      const config = {
-        define: {
-          __RANGO_DEBUG__: JSON.stringify(!!process.env.INTERNAL_RANGO_DEBUG)
-        }
-      };
-      return config;
+    // Make INTERNAL_RANGO_DEBUG reach the CLIENT debug logs by just setting the
+    // env var. See injectClientDebugFlag: bakes the resolved flag into the
+    // internal-debug module so FE debug no longer depends on Vite delivering the
+    // `__RANGO_DEBUG__` define to the client (which it does only as an injected
+    // global whose presence varies across consumer setups). Runs in dev and build.
+    transform(_code, id) {
+      return injectClientDebugFlag(id);
     },
     configResolved(config) {
       s.projectRoot = config.root;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.133",
+  "version": "0.0.0-experimental.134",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/composability/SKILL.md

@@ -22,7 +22,6 @@ import {
   loading,
   parallel,
   intercept,
-  when,
   errorBoundary,
   notFoundBoundary,
 } from "@rangojs/router";

package/skills/handler-use/SKILL.md

@@ -51,13 +51,13 @@ Now `ProductPage` carries its loader, loading state, and response-header middlew
 
 `handler.use()` is the same callback shape regardless of where the handler runs, but the runtime validates that the items it returns are valid for the mount site. Driven by `MOUNT_SITE_ALLOWED_TYPES` in [resolve-handler-use.ts](../../src/route-definition/resolve-handler-use.ts):
 
-| Mount site                                        | Allowed item types                                                                                                                             |
-| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `path()` / `route()`                              | `layout`, `parallel`, `intercept`, `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `cache`, `transition` |
-| `layout()`                                        | All of the above, plus `route`, `include`                                                                                                      |
-| `parallel()` (per slot)                           | `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `transition`                                                           |
-| `intercept()`                                     | `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `layout`, `route`, `when`, `transition`                  |
-| Response routes (`path.json()`, `path.text()`, …) | `middleware`, `cache`                                                                                                                          |
+| Mount site                                        | Allowed item types                                                                                                                                                                        |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path()` / `route()`                              | `layout`, `parallel`, `intercept`, `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `cache`, `transition`                                            |
+| `layout()`                                        | All of the above, plus `route`, `include`                                                                                                                                                 |
+| `parallel()` (per slot)                           | `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `transition`                                                                                                      |
+| `intercept()`                                     | `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `layout`, `route`, `transition` (conditional activation is config-only: `intercept(..., { when })`) |
+| Response routes (`path.json()`, `path.text()`, …) | `middleware`, `cache`                                                                                                                                                                     |
 
 For per-item semantics see the dedicated skills: [middleware](../middleware/SKILL.md), [loader](../loader/SKILL.md), [parallel](../parallel/SKILL.md), [intercept](../intercept/SKILL.md), [layout](../layout/SKILL.md), [view-transitions](../view-transitions/SKILL.md).
 

package/skills/intercept/SKILL.md

@@ -142,18 +142,41 @@ layout(ProductLayout, () => [
 ]);
 ```
 
-## Conditional Intercept with when()
+## Conditional Intercept with the `when` config
 
-Only intercept based on navigation context:
+Only intercept based on navigation context. `when` is the 4th argument
+(an `InterceptConfig` object); the other use-items go in the 5th-argument
+callback.
 
 ```typescript
 intercept(
   "@modal",
   "product",
   <ProductModal />,
+  // Only intercept when coming from a different section
+  { when: ({ from }) => !from.pathname.startsWith("/shop/product/") },
+  () => [
+    loader(ProductLoader),
+  ]
+)
+```
+
+`when` is a match-time selector receiving `{ from, to, params, segments, ... }`.
+Pass an array of predicates for AND logic (all must return true). Omit `when`
+entirely and the intercept always activates.
+
+```typescript
+intercept(
+  "@modal",
+  "product",
+  <ProductModal />,
+  {
+    when: [
+      ({ from }) => from.pathname.startsWith("/shop"),
+      ({ params }) => params.slug !== "featured",
+    ],
+  },
   () => [
-    // Only intercept when coming from a different section
-    when(({ from }) => !from.pathname.startsWith("/shop/product/")),
     loader(ProductLoader),
   ]
 )
@@ -242,10 +265,13 @@ layout(ShopLayout, () => [
   ]),
 
   // This intercept is also pre-rendered at build time
-  intercept("@modal", ".detail", <ProductModal />, () => [
-    when(({ from }) => from.pathname.startsWith("/shop")),
-    loader(ProductLoader),
-  ]),
+  intercept(
+    "@modal",
+    ".detail",
+    <ProductModal />,
+    { when: ({ from }) => from.pathname.startsWith("/shop") },
+    () => [loader(ProductLoader)],
+  ),
 ])
 ```
 
@@ -253,8 +279,8 @@ Build-time behavior:
 
 - The intercept handler (`<ProductModal />`) is resolved with BuildContext
 - Result is stored under the key `"detail/paramHash/i"` (intercept variant)
-- `when()` conditions are skipped at build time (all intercepts pre-rendered unconditionally)
-- `when()` is still evaluated at runtime by the intercept-resolution middleware
+- `when` config conditions are skipped at build time (all intercepts pre-rendered unconditionally)
+- `when` is still evaluated at runtime by the intercept-resolution middleware
 
 Runtime behavior:
 
@@ -305,7 +331,6 @@ export const shopPatterns = urls(({
   intercept,
   loader,
   loading,
-  when,
 }) => [
   layout(<ShopLayout />, () => [
     parallel({
@@ -317,8 +342,8 @@ export const shopPatterns = urls(({
       "@modal",
       "product",  // Route name (without prefix)
       <ProductModalContent />,
+      { when: ({ from }) => !from.pathname.startsWith("/shop/product/") },
       () => [
-        when(({ from }) => !from.pathname.startsWith("/shop/product/")),
         layout(<ModalWrapper />),
         loading(<ProductModalSkeleton />),
         loader(ProductLoader, () => [cache()]),
@@ -338,7 +363,7 @@ export const shopPatterns = urls(({
 
 ## Handler-attached `.use`
 
-Intercept handlers can carry their own middleware, loaders, loading state, error/notFound boundaries, and even nested `layout`/`route`/`when` defaults via `.use` — useful for self-contained modal components that travel with their own data and chrome.
+Intercept handlers can carry their own middleware, loaders, loading state, error/notFound boundaries, and even nested `layout`/`route` defaults via `.use` — useful for self-contained modal components that travel with their own data and chrome. (Conditional activation is set via the `when` config on the mount-site `intercept()` call, not inside `.use`.)
 
 ```typescript
 const QuickViewModal: Handler = async (ctx) => {

package/skills/migrate-nextjs/SKILL.md

@@ -193,9 +193,9 @@ The main content always goes through `<Outlet />` via the `path()` handler.
 // Rango: explicit intercept in layout
 layout(<ShopLayout />, () => [
   path("/product/:id", ProductPage, { name: "product" }),
-  intercept("@modal", ".product", <ProductModal />, () => [
-    when(({ from }) => from.pathname.startsWith("/shop")),
-  ]),
+  intercept("@modal", ".product", <ProductModal />, {
+    when: ({ from }) => from.pathname.startsWith("/shop"),
+  }),
 ])
 ```
 

package/skills/prerender/SKILL.md

@@ -243,16 +243,16 @@ path("/blog/:slug", BlogPost, { name: "blog.post" }, () => [
 
 ## Interaction with DSL Items
 
-| DSL item       | Behavior with Prerender                                                                                                                                                                                                                                             |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `loader()`     | Live at runtime, bundled normally. Use `cache()` for caching.                                                                                                                                                                                                       |
-| `revalidate()` | Not allowed without Passthrough. Allowed with Passthrough.                                                                                                                                                                                                          |
-| `cache()`      | Orthogonal -- use on parent layouts and loaders.                                                                                                                                                                                                                    |
-| `layout()`     | Child layouts inside path are pre-rendered. Parent layouts are live.                                                                                                                                                                                                |
-| `parallel()`   | Parallel slots inside path are pre-rendered.                                                                                                                                                                                                                        |
-| `middleware()` | Skipped during pre-render (no request). Runs at request time for loaders.                                                                                                                                                                                           |
-| `loading()`    | Ignored without Passthrough. Works for live fallback with Passthrough.                                                                                                                                                                                              |
-| `intercept()`  | Pre-rendered at build time. Intercept variant stored under `/i` key alongside main segments. At runtime, the correct variant is served based on `ctx.isIntercept`. `when()` conditions are skipped at build time (all intercepts are pre-rendered unconditionally). |
+| DSL item       | Behavior with Prerender                                                                                                                                                                                                                                                  |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `loader()`     | Live at runtime, bundled normally. Use `cache()` for caching.                                                                                                                                                                                                            |
+| `revalidate()` | Not allowed without Passthrough. Allowed with Passthrough.                                                                                                                                                                                                               |
+| `cache()`      | Orthogonal -- use on parent layouts and loaders.                                                                                                                                                                                                                         |
+| `layout()`     | Child layouts inside path are pre-rendered. Parent layouts are live.                                                                                                                                                                                                     |
+| `parallel()`   | Parallel slots inside path are pre-rendered.                                                                                                                                                                                                                             |
+| `middleware()` | Skipped during pre-render (no request). Runs at request time for loaders.                                                                                                                                                                                                |
+| `loading()`    | Ignored without Passthrough. Works for live fallback with Passthrough.                                                                                                                                                                                                   |
+| `intercept()`  | Pre-rendered at build time. Intercept variant stored under `/i` key alongside main segments. At runtime, the correct variant is served based on `ctx.isIntercept`. `when` config conditions are skipped at build time (all intercepts are pre-rendered unconditionally). |
 
 When Passthrough revalidation is enabled, remember that revalidation is
 still partial: opting a child segment into revalidation does not
@@ -609,12 +609,12 @@ At runtime, the cache-lookup middleware checks `ctx.isIntercept`:
   (filtered by `namespace?.startsWith("intercept:")`) and sets up slots.
 - **Direct navigation**: looks up `paramHash` (no suffix). Standard prerender path.
 - **Intercept miss (no `/i` entry)**: falls through to the normal pipeline so
-  intercept-resolution middleware runs live. This handles `when()` conditions
+  intercept-resolution middleware runs live. This handles `when` config conditions
   that prevented pre-rendering.
 
-The `when()` callback receives an `InterceptSelectorContext` with `from.pathname`
+The `when` config selector receives an `InterceptSelectorContext` with `from.pathname`
 which is unknown at build time. All intercepts are pre-rendered unconditionally;
-`when()` is evaluated at runtime by the intercept-resolution middleware.
+`when` is evaluated at runtime by the intercept-resolution middleware.
 
 ### Example: Pre-rendered route with intercept
 
@@ -633,10 +633,13 @@ layout(ShopLayout, () => [
 
   // Intercept detail from shop index into a modal.
   // At build time, this is resolved and stored under the /i key.
-  intercept("@modal", ".detail", <ProductModal />, () => [
-    when(({ from }) => from.pathname === "/shop"),
-    loader(ProductLoader),
-  ]),
+  intercept(
+    "@modal",
+    ".detail",
+    <ProductModal />,
+    { when: ({ from }) => from.pathname === "/shop" },
+    () => [loader(ProductLoader)],
+  ),
 ])
 ```
 

package/skills/router-setup/SKILL.md

@@ -60,8 +60,7 @@ urls(
     cache, // Configure caching
     middleware, // Add middleware
     revalidate, // Control revalidation
-    intercept, // Intercept routes for modals
-    when, // Conditional rendering
+    intercept, // Intercept routes for modals (conditional via intercept(..., { when }))
     errorBoundary, // Add an error boundary
     notFoundBoundary, // Add a not-found boundary
     transition, // Configure view transitions

package/skills/testing/SKILL.md

@@ -88,6 +88,7 @@ Each primitive links to its sub-file (API + recipe + caveats).
 | a loader's cookie / header / redirect output (auth-loader pattern)                                                                 | unit (node)  | [`runLoaderResult`](./loader.md)                                                              | `@rangojs/router/testing`        |
 | one middleware's ordering / short-circuit / cookie+header merge                                                                    | unit (node)  | [`runMiddleware`](./middleware.md)                                                            | `@rangojs/router/testing`        |
 | a `"use server"` action's cookie / header / flash output (even on `throw redirect()`)                                              | unit (node)  | [`runInRequestContext`](./server-actions.md)                                                  | `@rangojs/router/testing`        |
+| a `transition({ when })` gate (keep/drop) against nav source / target / action metadata                                            | unit (node)  | `runTransitionWhen` (`{ kept, whenContext }`)                                                 | `@rangojs/router/testing`        |
 | a handle's `collect`/accumulator, or a seeded handle read                                                                          | unit         | [`collectHandle` / seeded `handles`](./handles.md)                                            | `@rangojs/router/testing`        |
 | a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                       | `@rangojs/router/testing/dom`    |
 | a redirect / status / headers / cookies / **response route** (json/text/html/xml/md), no Flight                                    | integration  | [`dispatch`](./response-routes.md)                                                            | `@rangojs/router/testing`        |

package/skills/view-transitions/SKILL.md

@@ -209,6 +209,10 @@ interface TransitionConfig {
   default?: string | Record<string, string>; // fallback for any phase
   name?: string; // explicit view-transition-name
   viewTransition?: "auto" | false; // boundary opt-out (see below)
+  // Conditional gate, evaluated server-side AFTER the route handler. Return
+  // false to drop this transition for the request, so the navigation streams its
+  // loading() fallback instead of holding. See the gate section below.
+  when?: (ctx: TransitionWhenContext) => boolean;
 }
 ```
 
@@ -217,6 +221,45 @@ interface TransitionConfig {
 - `name` lets you participate in cross-page morphs by name (advanced; you usually don't need this on a layout/route-level wrap).
 - `viewTransition` toggles whether rango places its own `<ViewTransition>` boundary. `"auto"` (default) wraps as described above; `false` opts out — see the next section.
 
+## Conditional transitions (`when`)
+
+`transition({ when })` gates the hold per request. The predicate runs **server-side, AFTER the route handler** and outside any cache scope; return `false` to drop this segment's transition for the request (the navigation streams its `loading()` fallback instead of holding).
+
+Its context mirrors the `revalidate()` predicate args — the same navigation/action metadata — plus `get`/`env` for post-handler reads:
+
+```ts
+import type { TransitionWhenContext } from "@rangojs/router";
+
+// Hold only when the handler marked this request (handler sets, gate reads):
+transition({ when: (ctx) => ctx.get(KeepScroll) === true });
+
+// Hold only when arriving from a specific page (the navigation SOURCE):
+transition({
+  when: ({ currentUrl }) => currentUrl?.pathname.startsWith("/list") === true,
+});
+transition({ when: ({ fromRouteName }) => fromRouteName === "products.list" });
+
+// Hold only after a specific action revalidated the route:
+transition({
+  when: ({ actionId }) => actionId === "src/actions/cart.ts#addToCart",
+});
+```
+
+| field                                                  | meaning                                      | populated                                                                             |
+| ------------------------------------------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `currentUrl` / `currentParams` / `fromRouteName`       | navigation **source**                        | soft nav + action-success; `undefined` on initial full load and action/PE error paths |
+| `nextUrl` / `nextParams`                               | navigation **target**                        | always                                                                                |
+| `toRouteName` (and `fromRouteName`)                    | route **name**                               | when the route is named (undefined for unnamed/auto-generated)                        |
+| `actionId` / `actionUrl` / `actionResult` / `formData` | the server action that triggered this render | action-triggered renders only                                                         |
+| `method`                                               | `"GET"` (nav) / `"POST"` (action)            | always                                                                                |
+| `get` / `env`                                          | read handler/middleware vars + app env       | always                                                                                |
+
+A predicate that throws is reported to `router.onError` (phase `"rendering"`) and treated as no-hold (conservative).
+
+**Same-route content-holds need the transition present on the FIRST render.** The same-route hold works by giving the route a param-agnostic key so a param change reconciles instead of remounting — but that key is established when the route first mounts. A source gate that returns `false` on the initial full load (where `currentUrl`/`currentParams`/`fromRouteName` are undefined) drops the transition before the route mounts, so the route mounts _outside_ a transition scope and **every** later same-route param nav remounts (flashing the skeleton) regardless of what the gate decides on those navs. Write source gates so they hold when there is no source — e.g. `({ currentParams }) => currentParams?.tab !== "raw"` (true on the initial load) rather than `=== "details"` (false on the initial load) — when the same-route content-hold must engage. This only affects same-route param navigations; action-only or cross-route gating is unaffected (no shared param key is in play).
+
+**Prefetch / cache caveat.** The gate runs during resolution, so a **prefetched** navigation decides at prefetch time — `currentUrl`/`currentParams`/`fromRouteName` reflect the page the prefetch fired from, not necessarily the click-time source — and a `cache()`/prerender hit replays the stored transition without re-running the predicate. A source-sensitive gate can therefore be frozen to prefetch/store-time state. This covers ~99% of navigations; if yours must reflect the exact click-time source, source-scope the prefetch (`<Link prefetchKey=":source">`) and don't `cache()` that segment.
+
 ## Opting out of the router boundary (place your own `<ViewTransition>`)
 
 By default a `transition()` segment gets a rango-placed `<ViewTransition>` boundary — a cross-fade of the whole outlet/route. If you'd rather animate specific elements yourself (place `<ViewTransition name="...">` in your components), set `viewTransition: false`. The router then contributes **no boundary of its own** but still:

package/src/browser/navigation-bridge.ts

@@ -32,6 +32,7 @@ import { isInterceptOnlyCache } from "./intercept-utils.js";
 import {
   toNetworkError,
   emitNetworkError,
+  emitNavigationError,
   isBackgroundSuppressible,
 } from "./network-error-handler.js";
 import { debugLog } from "./logging.js";
@@ -215,17 +216,20 @@ export function createNavigationBridge(
         store.setInterceptSourceUrl(null);
       }
 
-      // Before navigating away, update the source page's cache with the latest handleData.
-      // This ensures the cache has correct handleData even if handles were streaming.
+      // Before navigating away, update the source page's cache with the latest
+      // handleData. This ensures the cache has correct handleData even if handles
+      // were streaming. Use updateCacheHandleData (not cacheSegmentsForHistory):
+      // the source page's segments are unchanged, so this is a handleData refresh,
+      // not a commit. Critically it PRESERVES the entry's stale flag — when the
+      // source page has a deferred Meta still pending, its entry was marked stale
+      // (invalidate-on-pending) so a popstate return revalidates; re-committing it
+      // here would reset stale to false and serve the carried (pre-resolution)
+      // title as fresh. It also leaves the nav-instance token intact.
       const sourceHistoryKey = store.getHistoryKey();
       const sourceCached = store.getCachedSegments(sourceHistoryKey);
       if (sourceCached?.segments && sourceCached.segments.length > 0) {
         const currentHandleData = eventController.getHandleState().data;
-        store.cacheSegmentsForHistory(
-          sourceHistoryKey,
-          sourceCached.segments,
-          currentHandleData,
-        );
+        store.updateCacheHandleData(sourceHistoryKey, currentHandleData);
       }
 
       // Check if we have cached segments for target URL
@@ -325,8 +329,15 @@ export function createNavigationBridge(
           } as NavigateOptionsInternal);
         }
 
-        if (error instanceof DOMException && error.name === "AbortError") {
-          debugLog("[Browser] Navigation aborted by newer navigation");
+        // Aborted, or superseded by a newer navigation. A superseded nav may
+        // reject with a non-AbortError (e.g. a Flight decode that fails after its
+        // signal was aborted), so check the signal too -- otherwise we would
+        // render a boundary that clobbers the newer navigation's content.
+        if (
+          (error instanceof DOMException && error.name === "AbortError") ||
+          tx.handle.signal.aborted
+        ) {
+          debugLog("[Browser] Navigation aborted or superseded");
           return;
         }
 
@@ -343,7 +354,13 @@ export function createNavigationBridge(
           return;
         }
 
-        throw error;
+        // A response we could not process (undecodable Flight body, or an
+        // unanticipated failure building the response). Surface the route's
+        // error boundary rather than let the rejection abort the navigation
+        // silently. Prefetched responses funnel here too: a failed warm-prefetch
+        // payload rejects on consumption and propagates to this catch.
+        console.error("[Browser] Unprocessable navigation response:", error);
+        emitNavigationError(onUpdate, error, url);
       } finally {
         tx[Symbol.dispose]();
       }
@@ -372,6 +389,14 @@ export function createNavigationBridge(
           tx.with({ url: window.location.href, replace: true, scroll: false }),
         );
       } catch (error) {
+        // Aborted or superseded: bail without rendering a boundary (see navigate()).
+        if (
+          (error instanceof DOMException && error.name === "AbortError") ||
+          tx.handle.signal.aborted
+        ) {
+          return;
+        }
+
         const networkError = toNetworkError(error, {
           url: window.location.href,
           operation: "revalidation",
@@ -384,7 +409,12 @@ export function createNavigationBridge(
           emitNetworkError(onUpdate, networkError, window.location.href);
           return;
         }
-        throw error;
+
+        // refresh() shares the fetchPartialUpdate chokepoint with navigate()/
+        // popstate, so an unprocessable response must surface the error boundary
+        // here too rather than become an uncaught rejection.
+        console.error("[Browser] Unprocessable refresh response:", error);
+        emitNavigationError(onUpdate, error, window.location.href);
       } finally {
         tx[Symbol.dispose]();
       }
@@ -527,8 +557,19 @@ export function createNavigationBridge(
           // SWR: If stale, trigger background revalidation
           if (isStale) {
             debugLog("[Browser] Cache is stale, background revalidating...");
-            // Background revalidation - don't await, just fire and forget
-            const segmentIds = cachedSegments.map((s) => s.id);
+            // Background revalidation - don't await, just fire and forget.
+            // When the entry's handles are incomplete (a deferred Meta was still
+            // pending when the user navigated away — see handlesPending), send NO
+            // segment IDs so the server returns a FULL re-render with the handle
+            // stream. A normal stale revalidation sends the cached IDs and the
+            // server returns a diff-only payload that omits unchanged segments'
+            // handles, so a deferred Meta would never re-stream and the title
+            // would stay the pre-resolution carry. handlesPending is set only for
+            // the deferred-Meta-aborted case, so action/cross-tab SWR keeps the
+            // cheap diff path.
+            const segmentIds = cached?.handlesPending
+              ? []
+              : cachedSegments.map((s) => s.id);
 
             const tx = createNavigationTransaction(
               store,
@@ -602,8 +643,13 @@ export function createNavigationBridge(
         // Restore scroll position after fetch completes
         handleNavigationEnd({ restore: true, isStreaming });
       } catch (error) {
-        if (error instanceof DOMException && error.name === "AbortError") {
-          debugLog("[Browser] Popstate navigation aborted");
+        // Aborted or superseded by a newer navigation: bail without clobbering
+        // content with a boundary (see navigate()).
+        if (
+          (error instanceof DOMException && error.name === "AbortError") ||
+          tx.handle.signal.aborted
+        ) {
+          debugLog("[Browser] Popstate navigation aborted or superseded");
           return;
         }
 
@@ -620,7 +666,10 @@ export function createNavigationBridge(
           return;
         }
 
-        throw error;
+        // Unprocessable response on a back/forward navigation: surface the
+        // error boundary instead of an uncaught rejection (see navigate()).
+        console.error("[Browser] Unprocessable popstate response:", error);
+        emitNavigationError(onUpdate, error, url);
       } finally {
         tx[Symbol.dispose]();
       }

package/src/browser/navigation-client.ts

@@ -260,6 +260,10 @@ export function createNavigationClient(
 
       let payloadPromise: Promise<RscPayload>;
       let streamCompletePromise: Promise<void>;
+      // True only for a prefetch-cache hit whose stream had already fully drained
+      // (complete === true). A still-streaming hit and the fresh path stay false,
+      // so only a fully-warmed prefetch commits in a transition (no fallback flash).
+      let fullyPrefetched = false;
 
       if (cachedEntry) {
         if (tx) {
@@ -270,6 +274,9 @@ export function createNavigationClient(
         }
         payloadPromise = cachedEntry.payload;
         streamCompletePromise = cachedEntry.streamComplete;
+        // Only a hit whose stream already fully drained is "fully prefetched";
+        // a still-streaming hit must keep streaming its fallbacks like a cold load.
+        fullyPrefetched = cachedEntry.complete;
       } else if (inflightEntryPromise) {
         if (tx) {
           browserDebugLog(tx, "reusing inflight prefetch", {
@@ -299,6 +306,9 @@ export function createNavigationClient(
         } else {
           payloadPromise = entry.payload;
           streamCompletePromise = entry.streamComplete;
+          // Adopted inflight is normally still streaming (false), but read the
+          // flag in case it completed between publish and adoption.
+          fullyPrefetched = entry.complete;
         }
       } else {
         ({ payload: payloadPromise, streamComplete: streamCompletePromise } =
@@ -315,7 +325,11 @@ export function createNavigationClient(
             diffCount: payload.metadata?.diff?.length ?? 0,
           });
         }
-        return { payload, streamComplete: streamCompletePromise };
+        return {
+          payload,
+          streamComplete: streamCompletePromise,
+          fullyPrefetched,
+        };
       } catch (error) {
         // Convert network-level errors to NetworkError for proper handling
         if (isNetworkError(error)) {