@rangojs/router 0.0.0-experimental.002d056c → 0.0.0-experimental.07cdfab0

package/dist/vite/index.js

@@ -1745,7 +1745,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.002d056c",
+  version: "0.0.0-experimental.07cdfab0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2884,11 +2884,11 @@ ${dim} \u2571${reset}    ${bold}\u2554\u2550\u2557${reset}${dim}      *      \u2
 ${dim}      ${reset}${bold}\u2551 \u2551${reset} ${bold}\u2554\u2550\u2557${reset}${dim}                    *                \u2727.   \u2571${reset}
 ${dim}   ${reset}${bold}\u2554\u2557 \u2551 \u2551 \u2551 \u2551${reset}${dim}                          *               \u2571${reset}
 ${dim}   ${reset}${bold}\u2551\u2551 \u2551 \u2551 \u2551 \u2551  \u2566\u2550\u2557\u2554\u2550\u2557\u2554\u2557\u2554\u2554\u2550\u2557\u2554\u2550\u2557${reset}${dim}             \u2727              \u2726${reset}
-${dim}  ${reset}${bold}\u2550\u2563\u2551 \u2551 \u2560\u2550\u255D \u2551  \u2560\u2566\u255D\u2560\u2550\u2563\u2551\u2551\u2551\u2551 \u2566\u2551 \u2551${reset}${dim}        *           \u2727${reset}
+${dim}   ${reset}${bold}\u2551\u2551 \u2551 \u2560\u2550\u255D \u2551  \u2560\u2566\u255D\u2560\u2550\u2563\u2551\u2551\u2551\u2551 \u2566\u2551 \u2551${reset}${dim}        *           \u2727${reset}
 ${dim}   ${reset}${bold}\u2551\u255A\u2550\u255D \u2554\u2550\u2550\u2550\u255D  \u2569\u255A\u2550\u2569 \u2569\u255D\u255A\u255D\u255A\u2550\u255D\u255A\u2550\u255D${reset}${dim}            \u2726          .      *${reset}
 ${dim}   ${reset}${bold}\u255A\u2550\u2550\u2557 \u2551${reset}${dim} *      RSC Wrangler         \u2727                \u2726${reset}
-${dim}  *   ${reset}${bold}\u2551 \u2560\u2550${reset}${dim}                         *            \u2727.    \u2571${reset}
-${bold}\u2550\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2569\u2550\u2550\u2550${reset}${dim}                  \u2726            *${reset}
+${dim}  *   ${reset}${bold}\u2551 \u2551${reset}${dim}                          *            \u2727.    \u2571${reset}
+${dim}   ${reset}${bold}\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550${reset}${dim}                           \u2726            *${reset}
 
    v${version} \xB7 ${preset} \xB7 ${mode}
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.002d056c",
+  "version": "0.0.0-experimental.07cdfab0",
   "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/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 || [];

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/document-cache.ts

@@ -13,6 +13,7 @@
 
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
 import { getRequestContext } from "../server/request-context.js";
+import { mayNeedSSR } from "../rsc/ssr-setup.js";
 import { sortedSearchString } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
 
@@ -204,18 +205,24 @@ export function createDocumentCacheMiddleware<TEnv = any>(
   ): Promise<Response> {
     const url = ctx.url;
 
+    // Use the original request URL for _rsc* param detection and cache key
+    // differentiation. ctx.url is stripped of _rsc* params by the middleware
+    // pipeline (stripInternalParams), so _rsc_partial, _rsc_segments, etc.
+    // are not visible on ctx.url in production.
+    const rawUrl = new URL(ctx.request.url);
+
     // Only cache GET requests — mutations and other methods must not be cached
     if (ctx.request.method !== "GET") {
       return next();
     }
 
     // Skip RSC action requests (mutations shouldn't be cached)
-    if (url.searchParams.has("_rsc_action")) {
+    if (rawUrl.searchParams.has("_rsc_action")) {
       return next();
     }
 
     // Skip loader requests (have their own caching)
-    if (url.searchParams.has("_rsc_loader")) {
+    if (rawUrl.searchParams.has("_rsc_loader")) {
       return next();
     }
 
@@ -241,9 +248,12 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       return next();
     }
 
-    // Determine request type for cache key differentiation
-    const isPartial = url.searchParams.has("_rsc_partial");
-    const typeLabel = isPartial ? "RSC" : "HTML";
+    // Determine request type for cache key differentiation.
+    // Uses rawUrl for _rsc* param checks and mayNeedSSR for Accept-based
+    // detection. Full-document RSC fetches must not share the HTML cache slot.
+    const isPartial = rawUrl.searchParams.has("_rsc_partial");
+    const isRscRequest = !mayNeedSSR(ctx.request, rawUrl);
+    const typeLabel = isRscRequest ? "RSC" : "HTML";
 
     // Track whether next() has been called so the catch block knows
     // whether it is safe to fall through to the handler.
@@ -254,10 +264,10 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       // gracefully to the origin handler instead of rejecting the request.
       // This is a deliberate fail-open-to-origin policy: the fallback is
       // "serve uncached from origin", not "use a different cache key".
-      const clientSegments = url.searchParams.get("_rsc_segments") || "";
+      const clientSegments = rawUrl.searchParams.get("_rsc_segments") || "";
       const segmentHash =
         isPartial && clientSegments ? `:${hashSegmentIds(clientSegments)}` : "";
-      const typeSuffix = isPartial ? ":rsc" : ":html";
+      const typeSuffix = isRscRequest ? ":rsc" : ":html";
 
       let searchSuffix = "";
       if (!keyGenerator) {

package/src/debug.ts

@@ -2,7 +2,7 @@
  * Debug utilities for manifest inspection and comparison
  */
 
-import type { EntryData } from "./server/context";
+import { getParallelSlotCount, type EntryData } from "./server/context";
 
 /**
  * Serialized entry for debug output
@@ -64,7 +64,7 @@ export function serializeManifest(
       hasLoader: entry.loader?.length > 0,
       hasMiddleware: entry.middleware?.length > 0,
       hasErrorBoundary: entry.errorBoundary?.length > 0,
-      parallelCount: entry.parallel?.length ?? 0,
+      parallelCount: getParallelSlotCount(entry.parallel),
       interceptCount: entry.intercept?.length ?? 0,
     };
 

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

@@ -282,7 +282,7 @@ const cache: RouteHelpers<any, any>["cache"] = (
       errorBoundary: [],
       notFoundBoundary: [],
       layout: [],
-      parallel: [],
+      parallel: {},
       intercept: [],
       loader: [],
       ...(cacheUrlPrefix ? { mountPath: cacheUrlPrefix } : {}),
@@ -320,7 +320,7 @@ const cache: RouteHelpers<any, any>["cache"] = (
     errorBoundary: [],
     notFoundBoundary: [],
     layout: [],
-    parallel: [],
+    parallel: {},
     intercept: [],
     loader: [],
     ...(cacheUrlPrefix2 ? { mountPath: cacheUrlPrefix2 } : {}),
@@ -393,6 +393,8 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
     "parallel() cannot be nested inside another parallel()",
   );
 
+  const slotNames = Object.keys(slots as Record<string, any>) as `@${string}`[];
+
   const namespace = `${ctx.namespace}.$${store.getNextIndex("parallel")}`;
 
   // Unwrap any static handler definitions in parallel slots
@@ -431,7 +433,7 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
     errorBoundary: [],
     notFoundBoundary: [],
     layout: [],
-    parallel: [],
+    parallel: {},
     intercept: [],
     loader: [],
     ...(parallelUrlPrefix ? { mountPath: parallelUrlPrefix } : {}),
@@ -454,7 +456,30 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
     );
   }
 
-  ctx.parent.parallel.push(entry);
+  for (const slotName of slotNames) {
+    const slotEntry = {
+      ...entry,
+      handler: { [slotName]: unwrappedSlots[slotName]! },
+      middleware: [...entry.middleware],
+      revalidate: [...entry.revalidate],
+      errorBoundary: [...entry.errorBoundary],
+      notFoundBoundary: [...entry.notFoundBoundary],
+      layout: [...entry.layout],
+      parallel: { ...entry.parallel },
+      intercept: [...entry.intercept],
+      loader: [...entry.loader],
+      ...(entry.staticHandlerIds?.[slotName]
+        ? {
+            isStaticPrerender: true as const,
+            staticHandlerIds: { [slotName]: entry.staticHandlerIds[slotName]! },
+          }
+        : {
+            isStaticPrerender: undefined,
+            staticHandlerIds: undefined,
+          }),
+    } satisfies EntryData;
+    ctx.parent.parallel[slotName] = slotEntry;
+  }
   return { name: namespace, type: "parallel" } as ParallelItem;
 };
 
@@ -687,7 +712,7 @@ const transitionFn = (
     errorBoundary: [],
     notFoundBoundary: [],
     layout: [],
-    parallel: [],
+    parallel: {},
     intercept: [],
     loader: [],
   } as EntryData;
@@ -734,7 +759,7 @@ const routeFn: RouteHelpers<any, any>["route"] = (name, handler, use) => {
     errorBoundary: [],
     notFoundBoundary: [],
     layout: [],
-    parallel: [],
+    parallel: {},
     intercept: [],
     loader: [],
   } satisfies EntryData;
@@ -791,7 +816,7 @@ const layout: RouteHelpers<any, any>["layout"] = (handler, use) => {
     revalidate: [],
     errorBoundary: [],
     notFoundBoundary: [],
-    parallel: [],
+    parallel: {},
     intercept: [],
     layout: [],
     loader: [],

package/src/router/lazy-includes.ts

@@ -4,6 +4,7 @@ import {
   EntryData,
   RSCRouterContext,
   runWithPrefixes,
+  getIsolatedLazyParent,
 } from "../server/context";
 import type { UrlPatterns } from "../urls.js";
 import type { AllUseItems, IncludeItem } from "../route-types.js";
@@ -138,7 +139,7 @@ export function evaluateLazyEntry<TEnv = any>(
       patternsByPrefix,
       trailingSlash: trailingSlashMap,
       namespace: "lazy",
-      parent: (lazyContext?.parent as EntryData | null) ?? null,
+      parent: getIsolatedLazyParent(lazyContext?.parent as EntryData | null),
       counters: lazyCounters,
       cacheProfiles: (lazyContext as any)?.cacheProfiles,
       rootScoped: (lazyContext as any)?.rootScoped,

package/src/router/manifest.ts

@@ -9,6 +9,7 @@ import { createRouteHelpers } from "../route-definition";
 import {
   getContext,
   runWithPrefixes,
+  getIsolatedLazyParent,
   type EntryData,
   type MetricsStore,
 } from "../server/context";
@@ -114,8 +115,11 @@ export async function loadManifest(
     // This ensures routes are registered under the correct layout hierarchy
     const lazyContext =
       entry.lazy && entry.lazyPatterns ? entry.lazyContext : null;
-    const parentForContext =
-      (lazyContext?.parent as EntryData | null) ?? Store.parent;
+    const parentForContext = lazyContext
+      ? getIsolatedLazyParent(
+          (lazyContext.parent as EntryData | null) ?? Store.parent,
+        )
+      : Store.parent;
 
     // For lazy entries, merge captured counters from include() so the
     // handler's entries get shortCode indices after sibling entries that