@rangojs/router 0.0.0-experimental.c65e9248 → 0.0.0-experimental.c873df95

package/dist/vite/package-resolution.js

@@ -0,0 +1,112 @@
+/**
+ * Package Resolution Utilities
+ *
+ * Handles detection of workspace vs npm install context and generates
+ * appropriate aliases and exclude lists for Vite configuration.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import packageJson from "../../package.json" with { type: "json" };
+/**
+ * The canonical name used in virtual entries (without scope)
+ */
+const VIRTUAL_PACKAGE_NAME = "@rangojs/router";
+/**
+ * Get the published package name (e.g., "@rangojs/router")
+ */
+export function getPublishedPackageName() {
+    return packageJson.name;
+}
+/**
+ * Check if the package is installed from npm (scoped) vs workspace (unscoped)
+ *
+ * In workspace development:
+ * - Package is installed as "@rangojs/router" via pnpm workspace alias
+ * - The scoped name (@rangojs/router) doesn't exist in node_modules
+ *
+ * When installed from npm:
+ * - Package is installed as "@rangojs/router"
+ * - We need aliases to map "@rangojs/router/*" to "@rangojs/router/*"
+ */
+export function isInstalledFromNpm() {
+    const packageName = getPublishedPackageName();
+    // Check if the scoped package exists in node_modules
+    return existsSync(resolve(process.cwd(), "node_modules", packageName));
+}
+/**
+ * Check if we're in a monorepo/workspace development context
+ */
+export function isWorkspaceDevelopment() {
+    return !isInstalledFromNpm();
+}
+/**
+ * Subpaths that need to be excluded from Vite's dependency optimization
+ * and potentially aliased
+ */
+const PACKAGE_SUBPATHS = [
+    "",
+    "/browser",
+    "/client",
+    "/server",
+    "/rsc",
+    "/ssr",
+    "/internal/deps/browser",
+    "/internal/deps/html-stream-client",
+    "/internal/deps/ssr",
+    "/internal/deps/rsc",
+];
+/**
+ * Generate the list of modules to exclude from Vite's dependency optimization.
+ *
+ * We include both the published name and the virtual name because
+ * Vite's optimizer runs before alias resolution.
+ */
+export function getExcludeDeps() {
+    const packageName = getPublishedPackageName();
+    const excludes = [];
+    for (const subpath of PACKAGE_SUBPATHS) {
+        // Add scoped package paths
+        excludes.push(`${packageName}${subpath}`);
+        // Add virtual/aliased paths (before alias resolution)
+        if (packageName !== VIRTUAL_PACKAGE_NAME) {
+            excludes.push(`${VIRTUAL_PACKAGE_NAME}${subpath}`);
+        }
+    }
+    return excludes;
+}
+/**
+ * Subpaths that need aliasing (subset of PACKAGE_SUBPATHS)
+ */
+const ALIAS_SUBPATHS = [
+    "/internal/deps/browser",
+    "/internal/deps/ssr",
+    "/internal/deps/rsc",
+    "/internal/deps/html-stream-client",
+    "/internal/deps/html-stream-server",
+    "/browser",
+    "/client",
+    "/server",
+    "/rsc",
+    "/ssr",
+];
+/**
+ * Generate aliases to map virtual package paths to the actual published package.
+ *
+ * Only needed when installed from npm, where the package is under @rangojs/router
+ * but virtual entries import from rsc-router/*.
+ *
+ * Returns empty object in workspace development where rsc-router resolves directly.
+ */
+export function getPackageAliases() {
+    if (isWorkspaceDevelopment()) {
+        // No aliases needed - rsc-router resolves directly
+        return {};
+    }
+    const packageName = getPublishedPackageName();
+    const aliases = {};
+    for (const subpath of ALIAS_SUBPATHS) {
+        aliases[`${VIRTUAL_PACKAGE_NAME}${subpath}`] = `${packageName}${subpath}`;
+    }
+    return aliases;
+}
+//# sourceMappingURL=package-resolution.js.map

package/dist/vite/package-resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-resolution.js","sourceRoot":"","sources":["../../src/vite/package-resolution.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,WAAW,MAAM,oBAAoB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAEnE;;GAEG;AACH,MAAM,oBAAoB,GAAG,iBAAiB,CAAC;AAE/C;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,WAAW,CAAC,IAAI,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,WAAW,GAAG,uBAAuB,EAAE,CAAC;IAC9C,qDAAqD;IACrD,OAAO,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC;AACzE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,CAAC,kBAAkB,EAAE,CAAC;AAC/B,CAAC;AAED;;;GAGG;AACH,MAAM,gBAAgB,GAAG;IACvB,EAAE;IACF,UAAU;IACV,SAAS;IACT,SAAS;IACT,MAAM;IACN,MAAM;IACN,wBAAwB;IACxB,mCAAmC;IACnC,oBAAoB;IACpB,oBAAoB;CACZ,CAAC;AAEX;;;;;GAKG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,WAAW,GAAG,uBAAuB,EAAE,CAAC;IAC9C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,KAAK,MAAM,OAAO,IAAI,gBAAgB,EAAE,CAAC;QACvC,2BAA2B;QAC3B,QAAQ,CAAC,IAAI,CAAC,GAAG,WAAW,GAAG,OAAO,EAAE,CAAC,CAAC;QAC1C,sDAAsD;QACtD,IAAI,WAAW,KAAK,oBAAoB,EAAE,CAAC;YACzC,QAAQ,CAAC,IAAI,CAAC,GAAG,oBAAoB,GAAG,OAAO,EAAE,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,cAAc,GAAG;IACrB,wBAAwB;IACxB,oBAAoB;IACpB,oBAAoB;IACpB,mCAAmC;IACnC,mCAAmC;IACnC,UAAU;IACV,SAAS;IACT,SAAS;IACT,MAAM;IACN,MAAM;CACE,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,sBAAsB,EAAE,EAAE,CAAC;QAC7B,mDAAmD;QACnD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,WAAW,GAAG,uBAAuB,EAAE,CAAC;IAC9C,MAAM,OAAO,GAA2B,EAAE,CAAC;IAE3C,KAAK,MAAM,OAAO,IAAI,cAAc,EAAE,CAAC;QACrC,OAAO,CAAC,GAAG,oBAAoB,GAAG,OAAO,EAAE,CAAC,GAAG,GAAG,WAAW,GAAG,OAAO,EAAE,CAAC;IAC5E,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/vite/virtual-entries.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Default virtual entry file contents for rsc-router.
+ * These are used when users don't provide their own entry files.
+ */
+export declare const VIRTUAL_ENTRY_BROWSER: string;
+export declare const VIRTUAL_ENTRY_SSR: string;
+/**
+ * Generate the RSC entry content with the specified router path
+ */
+export declare function getVirtualEntryRSC(routerPath: string): string;
+/**
+ * Virtual module IDs
+ */
+export declare const VIRTUAL_IDS: {
+    readonly browser: "virtual:rsc-router/entry.browser.js";
+    readonly ssr: "virtual:rsc-router/entry.ssr.js";
+    readonly rsc: "virtual:rsc-router/entry.rsc.js";
+    readonly version: "@rangojs/router:version";
+};
+/**
+ * Virtual module content for version.
+ * Exports VERSION - a timestamp that changes on server restart (dev) or at build time (production).
+ */
+export declare function getVirtualVersionContent(version: string): string;
+//# sourceMappingURL=virtual-entries.d.ts.map

package/dist/vite/virtual-entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-entries.d.ts","sourceRoot":"","sources":["../../src/vite/virtual-entries.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,qBAAqB,EAAE,MA+B5B,CAAC;AAET,eAAO,MAAM,iBAAiB,EAAE,MAaxB,CAAC;AAET;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAuC7D;AAED;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;CAKd,CAAC;AAEX;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhE"}

package/dist/vite/virtual-entries.js

@@ -0,0 +1,110 @@
+/**
+ * Default virtual entry file contents for rsc-router.
+ * These are used when users don't provide their own entry files.
+ */
+export const VIRTUAL_ENTRY_BROWSER = `
+import {
+  createFromReadableStream,
+  createFromFetch,
+  setServerCallback,
+  encodeReply,
+  createTemporaryReferenceSet,
+} from "@rangojs/router/internal/deps/browser";
+import { createElement, StrictMode } from "react";
+import { hydrateRoot } from "react-dom/client";
+import { rscStream } from "@rangojs/router/internal/deps/html-stream-client";
+import { initBrowserApp, RSCRouter } from "@rangojs/router/browser";
+
+async function initializeApp() {
+  const deps = {
+    createFromFetch,
+    createFromReadableStream,
+    encodeReply,
+    setServerCallback,
+    createTemporaryReferenceSet,
+  };
+
+  await initBrowserApp({ rscStream, deps });
+
+  hydrateRoot(
+    document,
+    createElement(StrictMode, null, createElement(RSCRouter))
+  );
+}
+
+initializeApp().catch(console.error);
+`.trim();
+export const VIRTUAL_ENTRY_SSR = `
+import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
+import { renderToReadableStream } from "react-dom/server.edge";
+import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
+import { createSSRHandler } from "@rangojs/router/ssr";
+
+export const renderHTML = createSSRHandler({
+  createFromReadableStream,
+  renderToReadableStream,
+  injectRSCPayload,
+  loadBootstrapScriptContent: () =>
+    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+});
+`.trim();
+/**
+ * Generate the RSC entry content with the specified router path
+ */
+export function getVirtualEntryRSC(routerPath) {
+    return `
+import {
+  renderToReadableStream,
+  decodeReply,
+  createTemporaryReferenceSet,
+  loadServerAction,
+  decodeAction,
+  decodeFormState,
+} from "@rangojs/router/internal/deps/rsc";
+import { router } from "${routerPath}";
+import { createRSCHandler } from "@rangojs/router/internal/rsc-handler";
+import { VERSION } from "@rangojs/router:version";
+
+// Import loader manifest to ensure all fetchable loaders are registered at startup
+// This is critical for serverless/multi-process deployments where the loader module
+// might not be imported before a GET request arrives
+import "virtual:rsc-router/loader-manifest";
+
+// Import pre-generated route manifest so href() works immediately on cold start.
+// In build mode, this contains the full route map generated at build time.
+// In dev mode, this is a no-op (manifest is populated in-memory by the discovery plugin).
+import "virtual:rsc-router/routes-manifest";
+
+export default createRSCHandler({
+  router,
+  version: VERSION,
+  deps: {
+    renderToReadableStream,
+    decodeReply,
+    createTemporaryReferenceSet,
+    loadServerAction,
+    decodeAction,
+    decodeFormState,
+  },
+  loadSSRModule: () =>
+    import.meta.viteRsc.loadModule("ssr", "index"),
+});
+`.trim();
+}
+/**
+ * Virtual module IDs
+ */
+export const VIRTUAL_IDS = {
+    browser: "virtual:rsc-router/entry.browser.js",
+    ssr: "virtual:rsc-router/entry.ssr.js",
+    rsc: "virtual:rsc-router/entry.rsc.js",
+    version: "@rangojs/router:version",
+};
+/**
+ * Virtual module content for version.
+ * Exports VERSION - a timestamp that changes on server restart (dev) or at build time (production).
+ */
+export function getVirtualVersionContent(version) {
+    return `export const VERSION = ${JSON.stringify(version)};`;
+}
+//# sourceMappingURL=virtual-entries.js.map

package/dist/vite/virtual-entries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-entries.js","sourceRoot":"","sources":["../../src/vite/virtual-entries.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+B5C,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,CAAC,MAAM,iBAAiB,GAAW;;;;;;;;;;;;;CAaxC,CAAC,IAAI,EAAE,CAAC;AAET;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAkB;IACnD,OAAO;;;;;;;;;0BASiB,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BnC,CAAC,IAAI,EAAE,CAAC;AACT,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,OAAO,EAAE,qCAAqC;IAC9C,GAAG,EAAE,iCAAiC;IACtC,GAAG,EAAE,iCAAiC;IACtC,OAAO,EAAE,yBAAyB;CAC1B,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAe;IACtD,OAAO,0BAA0B,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC;AAC9D,CAAC"}

package/package.json

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

package/skills/parallel/SKILL.md

@@ -109,6 +109,65 @@ parallel(
 )
 ```
 
+### Streaming Behavior
+
+Parallels with `loading()` are **independent streaming units**. They don't
+block the parent layout or sibling routes during SSR:
+
+- **With `loading()`**: The skeleton renders immediately. The loader runs
+  in the background and streams data to the client when ready. The rest
+  of the page (layout, route content, other parallels) renders without
+  waiting.
+- **Without `loading()`**: The parallel's loaders block the parent layout's
+  rendering. Use this when the data must be available before the page
+  paints (e.g., critical above-the-fold content).
+- **SPA navigation**: Parallel loaders resolve in the background. The
+  existing parallel UI stays visible — no skeleton flash on route changes
+  within the same layout.
+
+```typescript
+// Sidebar streams independently — page renders immediately
+parallel(
+  { "@sidebar": () => <Sidebar /> },
+  () => [loader(SlowSidebarLoader), loading(<SidebarSkeleton />)]
+)
+
+// Cart data blocks layout — must be ready before paint
+parallel(
+  { "@cartBadge": () => <CartBadge /> },
+  () => [loader(CartCountLoader)]  // No loading() = awaited
+)
+```
+
+## Slot Override Semantics
+
+When multiple `parallel()` calls define the same slot name, **the last
+definition wins**. Earlier definitions of that slot are removed. Other
+slots from the earlier call are preserved.
+
+This enables composition patterns where included routes override
+parent-defined slots:
+
+```typescript
+layout(DashboardLayout, () => [
+  // Base slots
+  parallel({
+    "@sidebar": () => <DefaultSidebar />,
+    "@footer": () => <Footer />,
+  }),
+
+  // Override just @sidebar — @footer is preserved
+  parallel({ "@sidebar": () => <CustomSidebar /> }),
+
+  path("/", DashboardIndex, { name: "index" }),
+])
+```
+
+After resolution, the layout has two parallel entries:
+
+- `{ "@footer": () => <Footer /> }` (first call, `@sidebar` removed)
+- `{ "@sidebar": () => <CustomSidebar /> }` (second call, wins)
+
 ## Multiple Parallel Slots
 
 ```typescript

package/src/browser/event-controller.ts

@@ -79,6 +79,8 @@ export interface DerivedNavigationState {
   state: "idle" | "loading";
   /** Whether any operation is streaming */
   isStreaming: boolean;
+  /** Whether a navigation is active (fetching or streaming, before commit) */
+  isNavigating: boolean;
   /** Current committed location */
   location: NavigationLocation;
   /** URL being navigated to (null if idle) */
@@ -389,6 +391,9 @@ export function createEventController(
     return {
       state,
       isStreaming,
+      // True when a navigation is active (fetching or streaming, before
+      // commit). Broader than pendingUrl which clears during streaming.
+      isNavigating: currentNavigation !== null,
       location,
       // pendingUrl only during fetching phase - once streaming starts (URL changed), not pending.
       // Background revalidations (skipLoadingState) don't expose a pending URL.

package/src/browser/navigation-client.ts

@@ -19,8 +19,8 @@ import {
 } from "./response-adapter.js";
 import {
   buildPrefetchKey,
-  consumePrefetch,
   consumeInflightPrefetch,
+  consumePrefetch,
 } from "./prefetch/cache.js";
 
 /**
@@ -89,22 +89,18 @@ export function createNavigationClient(
         fetchUrl.searchParams.set("_rsc_v", version);
       }
 
-      // Check in-memory prefetch cache before making a network request.
+      // Check completed in-memory prefetch cache before making a network request.
       // The cache key includes the source URL (previousUrl) because the
       // server's diff response depends on the source page context.
       // Skip cache for stale revalidation (needs fresh data), HMR (needs
       // fresh modules), and intercept contexts (source-dependent responses).
+      //
       const canUsePrefetch = !staleRevalidation && !hmr && !interceptSourceUrl;
       const cacheKey = buildPrefetchKey(previousUrl, fetchUrl);
       const cachedResponse = canUsePrefetch ? consumePrefetch(cacheKey) : null;
-      // If no completed cache entry, check for in-flight prefetch.
-      // This reuses a prefetch that is still downloading rather than
-      // starting a duplicate request from scratch.
-      const inflightPrefetch =
-        !cachedResponse && canUsePrefetch
-          ? consumeInflightPrefetch(cacheKey)
-          : null;
-
+      const inflightResponsePromise = canUsePrefetch
+        ? consumeInflightPrefetch(cacheKey)
+        : null;
       // Track when the stream completes
       let resolveStreamComplete: () => void;
       const streamComplete = new Promise<void>((resolve) => {
@@ -195,33 +191,24 @@ export function createNavigationClient(
             signal,
           );
         });
-      } else if (inflightPrefetch) {
+      } else if (inflightResponsePromise) {
         if (tx) {
           browserDebugLog(tx, "reusing inflight prefetch", { key: cacheKey });
         }
-        // Await the in-flight prefetch. If it resolves with a Response,
-        // use it like a cache hit. If it fails (null), fall back to
-        // a fresh navigation fetch.
-        responsePromise = inflightPrefetch.then((prefetchResponse) => {
-          if (!prefetchResponse) {
+        responsePromise = inflightResponsePromise.then(async (response) => {
+          if (!response) {
             if (tx) {
-              browserDebugLog(
-                tx,
-                "inflight prefetch failed, falling back to fetch",
-              );
+              browserDebugLog(tx, "inflight prefetch unavailable, refetching");
             }
             return doFreshFetch();
           }
-          if (tx) {
-            browserDebugLog(tx, "inflight prefetch resolved", {
-              key: cacheKey,
-            });
-          }
+
           return teeWithCompletion(
-            prefetchResponse,
+            response,
             () => {
-              if (tx)
+              if (tx) {
                 browserDebugLog(tx, "stream complete (from inflight prefetch)");
+              }
               resolveStreamComplete();
             },
             signal,

package/src/browser/partial-update.ts

@@ -259,6 +259,17 @@ export function createPartialUpdater(
             existingSegments,
           );
 
+          // Fix: tx.commit() cached the source page's handleData because
+          // eventController hasn't been updated yet. Overwrite with the
+          // correct cached handleData to prevent cache corruption on
+          // subsequent navigations to this same URL.
+          if (mode.targetCacheHandleData) {
+            store.updateCacheHandleData(
+              store.getHistoryKey(),
+              mode.targetCacheHandleData,
+            );
+          }
+
           // Include cachedHandleData in metadata so NavigationProvider can restore
           // breadcrumbs and other handle data from cache.
           // Remove `handles` from metadata to prevent NavigationProvider from

package/src/browser/prefetch/cache.ts

@@ -1,14 +1,14 @@
 /**
  * Prefetch Cache
  *
- * In-memory cache storing prefetch Response objects for instant cache hits
+ * In-memory cache storing prefetched Response objects for instant cache hits
  * on subsequent navigation. Cache key is source-dependent (includes the
  * current page URL) because the server's diff-based response depends on
  * where the user navigates from.
  *
- * Also tracks in-flight prefetch promises so navigation can reuse a
- * prefetch that is still downloading rather than starting a duplicate
- * request. See consumeInflightPrefetch().
+ * Also tracks in-flight prefetch promises. Each promise resolves to the
+ * navigation branch of a tee'd Response, allowing navigation to adopt a
+ * still-downloading prefetch without reparsing or buffering the body.
  *
  * Replaces the previous browser HTTP cache approach which was unreliable
  * due to response draining race conditions and browser inconsistencies.
@@ -130,8 +130,8 @@ export function consumeInflightPrefetch(
 
 /**
  * Store a prefetch response in the in-memory cache.
- * The response body must be fully buffered (e.g. via arrayBuffer()) before
- * storing, so the cached Response is self-contained and network-independent.
+ * The response should be a clone() of the original so the caller can
+ * still consume the body. The clone's body streams independently.
  *
  * Skips storage if the generation has changed since the fetch started
  * (a server action invalidated the cache mid-flight).

package/src/browser/prefetch/fetch.ts

@@ -55,10 +55,10 @@ function buildPrefetchUrl(
 }
 
 /**
- * Core prefetch fetch logic. Fetches the response, fully buffers the body,
- * and stores it in the in-memory cache. The returned Promise resolves to
- * the buffered Response (or null on failure) so navigation can reuse
- * in-flight prefetches via consumeInflightPrefetch().
+ * Core prefetch fetch logic. Fetches the response, tees the body, and stores
+ * one branch in the in-memory cache. The returned Promise resolves to the
+ * sibling navigation branch (or null on failure) so navigation can safely
+ * reuse an in-flight prefetch via consumeInflightPrefetch().
  */
 function executePrefetchFetch(
   key: string,
@@ -77,20 +77,19 @@ function executePrefetchFetch(
       "X-Rango-Prefetch": "1",
     },
   })
-    .then(async (response) => {
+    .then((response) => {
       if (!response.ok) return null;
-      // Fully buffer the response body so the cached Response is
-      // self-contained and doesn't depend on the network connection.
-      // This eliminates the race condition where the user clicks before
-      // the response body has been fully downloaded.
-      const buffer = await response.arrayBuffer();
-      const cachedResponse = new Response(buffer, {
+      // Don't buffer with arrayBuffer() — that blocks until the entire
+      // body downloads, defeating streaming for slow loaders.
+      // Tee the body: one branch for navigation, one for cache storage.
+      const [navStream, cacheStream] = response.body!.tee();
+      const responseInit = {
         headers: response.headers,
         status: response.status,
         statusText: response.statusText,
-      });
-      storePrefetch(key, cachedResponse.clone(), gen);
-      return cachedResponse;
+      };
+      storePrefetch(key, new Response(cacheStream, responseInit), gen);
+      return new Response(navStream, responseInit);
     })
     .catch(() => null)
     .finally(() => {

package/src/browser/rsc-router.tsx

@@ -286,6 +286,18 @@ export async function initBrowserApp(
       // Debounce: wait 200ms of quiet before fetching
       hmrTimer = setTimeout(async () => {
         hmrTimer = null;
+
+        // Don't interrupt an active user navigation — startNavigation()
+        // would abort it and refetch the old URL (window.location.href
+        // hasn't updated yet). The user's navigation will pick up the
+        // new server code when it completes. isNavigating covers the
+        // full lifecycle (fetching + streaming, before commit) without
+        // blocking on server actions.
+        if (eventController.getState().isNavigating) {
+          console.log("[RSCRouter] HMR: Skipping — navigation in progress");
+          return;
+        }
+
         console.log("[RSCRouter] HMR: Server update, refetching RSC");
 
         const abort = new AbortController();
@@ -310,6 +322,13 @@ export async function initBrowserApp(
 
           if (abort.signal.aborted) return;
 
+          // If the server returned a non-RSC response (404, 500 without
+          // error boundary), the payload won't have valid metadata.
+          // Reload to recover rather than leaving the page stale.
+          if (!payload.metadata) {
+            throw new Error("HMR refetch returned invalid payload");
+          }
+
           if (payload.metadata?.isPartial) {
             const segments = payload.metadata.segments || [];
             const matched = payload.metadata.matched || [];
@@ -352,7 +371,9 @@ export async function initBrowserApp(
           console.log("[RSCRouter] HMR: RSC stream complete");
         } catch (err) {
           if (abort.signal.aborted) return;
-          throw err;
+          console.warn("[RSCRouter] HMR: Refetch failed, reloading page", err);
+          window.location.reload();
+          return;
         } finally {
           if (hmrAbort === abort) hmrAbort = null;
           streamingToken.end();

package/src/browser/segment-reconciler.ts

@@ -160,8 +160,13 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
 
       // For non-action actors: cached segments the server decided not to re-render.
       // - Preserve loading=false (suppressed boundary) to maintain tree structure
-      // - Clear truthy loading (active skeleton) to prevent suspense on cached content
+      // - Preserve parallel segment loading so renderSegments can reconstruct
+      //   parallel-owned loader markers from the cached slot metadata
+      // - Clear other truthy loading values to prevent suspense on cached content
       if (actor !== "action") {
+        if (fromCache.type === "parallel" && fromCache.loading !== undefined) {
+          return fromCache;
+        }
         if (fromCache.loading !== undefined && fromCache.loading !== false) {
           return { ...fromCache, loading: undefined };
         }

package/src/cache/cache-runtime.ts

@@ -214,11 +214,21 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             bgStopCapture = c.stop;
           }
 
-          // Stamp tainted args and RequestContext so request-scoped
-          // reads (cookies, headers) and side effects (ctx.set, etc.)
-          // throw inside background revalidation, same as the miss path.
-          // Uses ref-counted stamp/unstamp so overlapping executions
-          // sharing the same ctx don't clear each other's guards.
+          // Stamp tainted ARGS only — not requestCtx. The args stamp guards
+          // direct ctx method calls (ctx.set, ctx.header, ctx.onResponse, etc.)
+          // which is sufficient for correctness.
+          //
+          // We intentionally skip stamping requestCtx here because:
+          // 1. runBackground starts the async task synchronously (before the
+          //    first await), so stampCacheExec would pollute the shared
+          //    requestCtx while the foreground pipeline is still running.
+          //    This causes assertNotInsideCacheExec to fire when cache-store
+          //    later calls requestCtx.onResponse().
+          // 2. requestCtx methods are closure-bound to the original ctx, so
+          //    neither Object.create() nor a proxy can isolate the stamp.
+          // 3. The foreground miss path already stamps requestCtx and catches
+          //    cookies()/headers() misuse on first execution. The background
+          //    re-runs the same function with the same request.
           const bgTaintedArgs: unknown[] = [];
           for (const arg of args) {
             if (isTainted(arg)) {
@@ -226,9 +236,6 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
               bgTaintedArgs.push(arg);
             }
           }
-          if (requestCtx) {
-            stampCacheExec(requestCtx as object);
-          }
 
           try {
             const freshResult = await fn.apply(this, args);
@@ -249,9 +256,6 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             for (const arg of bgTaintedArgs) {
               unstampCacheExec(arg as object);
             }
-            if (requestCtx) {
-              unstampCacheExec(requestCtx as object);
-            }
             // Restore original handle store
             if (originalHandleStore && requestCtx) {
               requestCtx._handleStore = originalHandleStore;