@rangojs/router 0.0.0-experimental.122 → 0.0.0-experimental.125

package/src/segment-system.tsx

@@ -1,6 +1,6 @@
 import * as React from "react";
 import { createElement, type ReactNode, type ComponentType } from "react";
-import { OutletProvider } from "./client.js";
+import { OutletProvider } from "./outlet-provider.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
 import type { ResolvedSegment, RootLayoutProps } from "./types.js";
 import { decodeLoaderResults } from "./decode-loader-results.js";
@@ -11,13 +11,25 @@ import {
 } from "./route-content-wrapper.js";
 import { RootErrorBoundary } from "./root-error-boundary.js";
 import { getMemoizedContentPromise } from "./segment-content-promise.js";
-import { getMemoizedLoaderPromise } from "./segment-loader-promise.js";
+import {
+  buildLoaderPromise,
+  getMemoizedLoaderPromise,
+} from "./segment-loader-promise.js";
 
 // ViewTransition is only available in React experimental.
 // Access via namespace import to avoid compile-time errors on stable React.
 const ReactViewTransition: any =
   "ViewTransition" in React ? (React as any).ViewTransition : null;
 
+// A loading skeleton is renderable only when it is a real ReactNode value.
+// `false` is treated as "not renderable" here. This is the three-term gate;
+// the distinct two-term gate at the LoaderBoundary site deliberately treats
+// `false` as "create a boundary without a RouteContentWrapper"
+// (tree-structure.md), so it must NOT use this helper.
+function isRenderableLoading(loading: ReactNode): boolean {
+  return loading !== undefined && loading !== null && loading !== false;
+}
+
 function restoreParallelLoaderMarkers(
   segments: ResolvedSegment[],
 ): ResolvedSegment[] {
@@ -28,12 +40,7 @@ function restoreParallelLoaderMarkers(
     const segment = segments[i];
 
     if (segment.type === "parallel") {
-      if (
-        segment.namespace &&
-        segment.loading !== undefined &&
-        segment.loading !== null &&
-        segment.loading !== false
-      ) {
+      if (segment.namespace && isRenderableLoading(segment.loading)) {
         parallelLoadingByNamespace.set(segment.namespace, segment.loading);
       }
       continue;
@@ -142,8 +149,14 @@ function wrapDefaultOutletContent(
 /**
  * Render segments into a React tree with proper layout nesting
  *
- * Layouts nest using OutletProvider, while route + parallel + error + notFound segments
- * render as siblings in a Fragment.
+ * Layouts nest using OutletProvider; a layout receives the inner content via
+ * its `<Outlet />`. Parallel segments do NOT render as inline Fragment siblings
+ * — they flow through OutletContext.parallel and are resolved where a layout
+ * places `<ParallelOutlet name="@sidebar" />` (or `<Outlet name="@sidebar" />`).
+ *
+ * The result is always wrapped in RootErrorBoundary so unhandled errors never
+ * blank the screen. When `options.rootLayout` is provided it wraps the error
+ * boundary at the OUTERMOST level (so the app shell survives errors).
  *
  * Error segments are treated like route segments - they render their fallback
  * component in place of the failed segment. When an error occurs in a handler,
@@ -155,27 +168,30 @@ function wrapDefaultOutletContent(
  * notFoundBoundary's fallback component.
  *
  * @param segments - Array of resolved segments to render
- * @returns ReactNode representing the component tree
+ * @returns Promise resolving to the ReactNode tree (the function is async)
  *
  * @example
  * ```typescript
  * const segments = [
- *   { id: 'L0.0', type: 'layout', component: <RootLayout /> },
- *   { id: 'L1.0', type: 'layout', component: <BlogLayout /> },
- *   { id: 'R2.0', type: 'route', component: <BlogPost /> },
- *   { id: 'P3.0', type: 'parallel', component: <Sidebar />, slot: '@sidebar' }
+ *   { id: 'L0.0', type: 'layout', component: <BlogLayout /> },
+ *   { id: 'L0R1', type: 'route', component: <BlogPost /> },
+ *   { id: 'L0R1.@sidebar', type: 'parallel', component: <Sidebar />, slot: '@sidebar' }
  * ];
  *
- * const tree = renderSegments(segments);
- * // Results in:
- * // <OutletProvider><RootLayout>
- * //   <OutletProvider><BlogLayout>
- * //     <><BlogPost /><Sidebar /></>
- * //   </BlogLayout></OutletProvider>
- * // </RootLayout></OutletProvider>
+ * // BlogLayout renders <Outlet /> for the route and
+ * // <ParallelOutlet name="@sidebar" /> for the parallel slot.
+ * const tree = await renderSegments(segments, { rootLayout: RootLayout });
+ * // Results in (outermost first):
+ * // <RootLayout>
+ * //   <RootErrorBoundary>
+ * //     <OutletProvider segment={BlogLayout} parallel={[Sidebar]}>
+ * //       <BlogPost />
+ * //     </OutletProvider>
+ * //   </RootErrorBoundary>
+ * // </RootLayout>
  *
  * // For server actions, pass isAction to await components:
- * const tree = renderSegments(segments, { isAction: true });
+ * const tree = await renderSegments(segments, { isAction: true });
  * ```
  */
 export async function renderSegments(
@@ -283,31 +299,25 @@ export async function renderSegments(
             .map(([k, v]) => `${k}=${v}`)
             .join(",")
         : "";
-    const key = `${paramStr ? `${id}-${paramStr}` : id}`;
+    const key = paramStr ? `${id}-${paramStr}` : id;
 
-    // Get loader entries for this node
     const loaderEntries = node.loaders.filter(
       (loader) => loader.loaderId && loader.loaderData !== undefined,
     );
 
-    // Determine the component content (with or without Suspense wrapper)
-    // Wrap when loading skeleton defined OR component is Promise (needs Suspense)
-    // During actions, await component Promise to prevent Suspense from triggering
-    // This keeps existing content visible instead of showing loading skeleton
     let resolvedComponent = component;
     if (isAction && component instanceof Promise) {
       resolvedComponent = await component;
     }
 
-    let nodeContent: ReactNode =
-      loading !== null && loading !== undefined && loading !== false
-        ? createElement(RouteContentWrapper, {
-            key: `suspense-loading-${id}`,
-            content: getMemoizedContentPromise(resolvedComponent),
-            fallback: loading,
-            segmentId: id,
-          })
-        : registerLazyRef(resolvedComponent);
+    let nodeContent: ReactNode = isRenderableLoading(loading)
+      ? createElement(RouteContentWrapper, {
+          key: `suspense-loading-${id}`,
+          content: getMemoizedContentPromise(resolvedComponent),
+          fallback: loading,
+          segmentId: id,
+        })
+      : registerLazyRef(resolvedComponent);
 
     // Wrap with <ViewTransition> if transition config exists (React experimental only).
     // An empty config ({}) creates a bare <ViewTransition> boundary that participates
@@ -351,13 +361,7 @@ export async function renderSegments(
     // Prepare loader data if there are loaders
     const loaderIds = loaderEntries.map((loader) => loader.loaderId!);
 
-    // Use LoaderBoundary when loading is defined to maintain consistent tree structure
-    // This ensures cached segments (which may not have loader segments) have the same
-    // tree structure as fresh segments, preventing React remounts
-    // If forceAwait or isAction is set, pre-resolve promises so LoaderBoundary won't suspend
     if (loading !== undefined && loading !== null) {
-      // Aggregate built here only — the loaderless and no-loading branches don't
-      // read it (the latter builds its own per-parallel promises).
       const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
       content = createElement(LoaderBoundary, {
         key: `loader-boundary-${key}`,
@@ -372,7 +376,6 @@ export async function renderSegments(
         children: nodeContent,
       });
     } else if (loaderEntries.length === 0) {
-      // No loaders, no loading - simple OutletProvider
       content = createElement(OutletProvider, {
         key,
         content: outletContent,
@@ -381,34 +384,18 @@ export async function renderSegments(
         children: nodeContent,
       });
     } else {
-      // Has loaders but no loading skeleton.
-      // Split: parallel-owned loaders stream (their parallel has loading()),
-      // layout-owned loaders are awaited (they gate the layout content).
       const layoutLoaders = loaderEntries.filter((l) => !l.parallelLoading);
       const parallelOwnedLoaders = loaderEntries.filter(
         (l) => !!l.parallelLoading,
       );
 
-      // Await only layout-owned loaders
       const layoutLoaderIds = layoutLoaders.map((l) => l.loaderId!);
-      const layoutLoaderDataPromise =
-        layoutLoaders.length > 0
-          ? Promise.all(
-              layoutLoaders.map((l) =>
-                l.loaderData instanceof Promise
-                  ? l.loaderData
-                  : Promise.resolve(l.loaderData),
-              ),
-            )
-          : Promise.resolve([]);
-      const resolvedData = await layoutLoaderDataPromise;
+      const resolvedData = await buildLoaderPromise(layoutLoaders);
       const { loaderData, errorFallback } = decodeLoaderResults(
         resolvedData,
         layoutLoaderIds,
       );
 
-      // Parallel-owned loaders: attach to their owning parallel segment
-      // as loaderDataPromise so ParallelOutlet wraps in LoaderBoundary
       if (parallelOwnedLoaders.length > 0) {
         const loadersByParallelNamespace = new Map<string, ResolvedSegment[]>();
 
@@ -465,8 +452,6 @@ export async function renderSegments(
     }
   }
 
-  // Always wrap with root error boundary to prevent white screens
-  // This catches any unhandled errors that bubble up from the segment tree
   const errorBoundaryWrapped = createElement(RootErrorBoundary, {
     children: content,
   });
@@ -474,11 +459,8 @@ export async function renderSegments(
     await Promise.allSettled(temporalLazyRefs);
   }
 
-  // Build the final result, optionally wrapped with root layout
   let result: ReactNode = errorBoundaryWrapped;
 
-  // If rootLayout is provided, wrap the error boundary with it
-  // This ensures the app shell stays mounted even during errors (prevents FOUC)
   if (RootLayout) {
     result = createElement(RootLayout, {
       children: errorBoundaryWrapped,
@@ -516,6 +498,28 @@ export async function renderSegments(
  * @param segments - Main segments from the route tree
  * @param interceptSegments - Optional intercept segments to inject
  */
+// Loader segment ids have the grammar `${parentId}D${index}.${loaderId}`.
+// parentId is the parent shortCode (M/L/P/R/C + digits, never "D") for normal
+// loaders, or `${shortCode}.${slotName}` for intercept-slot loaders, where the
+// slot name is user-controlled (`@${string}`) and may contain an uppercase "D"
+// (e.g. "@Detail"). Strip from the first `D<index>.` separator so the slot name
+// is preserved; splitting on a bare "D" mis-cut "@Detail" to "@" and silently
+// dropped the loader's data.
+function loaderParentId(loaderSegmentId: string): string {
+  return loaderSegmentId.replace(/D\d+\..*$/, "");
+}
+
+// Append a value to the array stored under `key`, creating the array on first
+// use. Single Map lookup (vs the has/get!().push double-lookup idiom).
+function pushToGroup<K, V>(map: Map<K, V[]>, key: K, value: V): void {
+  const arr = map.get(key);
+  if (arr) {
+    arr.push(value);
+  } else {
+    map.set(key, [value]);
+  }
+}
+
 function* segmentTreeWalk(
   segments: ResolvedSegment[],
   interceptSegments?: ResolvedSegment[],
@@ -536,19 +540,12 @@ function* segmentTreeWalk(
       // Extract parent ID from parallel ID
       // Example: "L0R1L0.@sidebar" → "L0R1L0"
       const parentId = segment.id.split(".")[0];
-      if (!parallelsByParent.has(parentId)) {
-        parallelsByParent.set(parentId, []);
-      }
-      parallelsByParent.get(parentId)!.push(segment);
+      pushToGroup(parallelsByParent, parentId, segment);
     } else if (segment.type === "loader") {
       // Extract parent ID from loader ID
-      // Example: "L0D0.cart" → "L0"
-      // Loader ID format: {parentShortCode}D{index}.{loaderId}
-      const parentId = segment.id.split("D")[0];
-      if (!loadersByParent.has(parentId)) {
-        loadersByParent.set(parentId, []);
-      }
-      loadersByParent.get(parentId)!.push(segment);
+      // Example: "L0D0.cart" → "L0"; "L0.@DetailD0.x" → "L0.@Detail"
+      const parentId = loaderParentId(segment.id);
+      pushToGroup(loadersByParent, parentId, segment);
     } else {
       // Layout, route, error, and notFound segments are all rendered in the tree
       // Error/notFound segments replace the failed segment with fallback UI
@@ -563,17 +560,11 @@ function* segmentTreeWalk(
       if (intercept.type === "parallel" && intercept.slot) {
         // Extract parent ID from intercept ID (e.g., "M4L0L0L2.@modal" → "M4L0L0L2")
         const parentId = intercept.id.split(".")[0];
-        if (!parallelsByParent.has(parentId)) {
-          parallelsByParent.set(parentId, []);
-        }
-        parallelsByParent.get(parentId)!.push(intercept);
+        pushToGroup(parallelsByParent, parentId, intercept);
       } else if (intercept.type === "loader") {
-        // Intercept loaders - extract parent from loader ID
-        const parentId = intercept.id.split("D")[0];
-        if (!loadersByParent.has(parentId)) {
-          loadersByParent.set(parentId, []);
-        }
-        loadersByParent.get(parentId)!.push(intercept);
+        // Intercept loaders - extract parent from loader ID (slot name preserved)
+        const parentId = loaderParentId(intercept.id);
+        pushToGroup(loadersByParent, parentId, intercept);
       }
     }
   }

package/src/server/cookie-store.ts

@@ -8,7 +8,7 @@
  */
 
 import type { CookieOptions } from "../router/middleware-types.js";
-import { getRequestContext } from "./request-context.js";
+import { getRequestContext, _getRequestContext } from "./request-context.js";
 import { isInsideCacheScope } from "./context.js";
 import { INSIDE_CACHE_EXEC } from "../cache/taint.js";
 
@@ -168,6 +168,57 @@ export function headers(): ReadonlyHeaders {
   }) as unknown as ReadonlyHeaders;
 }
 
+/**
+ * Force the calling client's caches to miss from now on, from the server seat:
+ * write a rotated `Set-Cookie` for the rango state. The responding client
+ * applies it on receipt, and its history cache is marked stale by the
+ * jar-divergence observer at its next read. Per-client and lazy — it rotates
+ * only the client that receives this response, not every client.
+ *
+ * Idempotent within a request (one `Set-Cookie`). Inert (a dev warning) when
+ * called outside a request context. Like `cookies()`, it throws inside a
+ * `"use cache"` / `cache()` boundary, but is allowed from a loader (loaders are
+ * the dynamic holes of a cached document).
+ */
+export function invalidateClientCache(): void {
+  const ctx = _getRequestContext();
+  if (!ctx) {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(
+        "[rango] invalidateClientCache() was called outside a request context; ignored.",
+      );
+    }
+    return;
+  }
+  assertNotInsideCacheContext(ctx, "invalidateClientCache");
+  ctx._rotateStateCookie();
+}
+
+/**
+ * Suppress a server action's automatic client-cache invalidation: tell the
+ * action bridge this action changed nothing a route renders, so it should leave
+ * the client's state and caches alone (no rotation, no prefetch wipe, no
+ * broadcast, no revalidation refetch). Per-response, not per-action-definition —
+ * only the execution knows whether anything changed.
+ *
+ * Sets an internal response header the bridge reads. Idempotent within a
+ * request. Inert (a dev warning) outside a request context — there is no
+ * automatic invalidation to suppress.
+ */
+export function keepClientCache(): void {
+  const ctx = _getRequestContext();
+  if (!ctx) {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(
+        "[rango] keepClientCache() was called outside a request context; ignored.",
+      );
+    }
+    return;
+  }
+  assertNotInsideCacheContext(ctx, "keepClientCache");
+  ctx._setKeepCacheDirective();
+}
+
 /**
  * Create a CookieStore backed by a RequestContext.
  * @internal Shared between cookies() shorthand and context methods.

package/src/server/handle-store.ts

@@ -45,10 +45,6 @@ function createLateHandlePushError(
   return error;
 }
 
-/**
- * Deep clone handle data to create a snapshot.
- * @internal
- */
 function cloneHandleData(data: HandleData): HandleData {
   const clone: HandleData = {};
   for (const handleName in data) {
@@ -205,11 +201,9 @@ export function createHandleStore(): HandleStore {
   return {
     track<T>(promise: Promise<T>): Promise<T> {
       inflightCount++;
-      // Use .then(onSettle, onSettle) instead of .finally() to avoid
-      // creating an unhandled rejection branch when the tracked promise
-      // rejects (e.g. error route handlers). .finally() re-throws the
-      // rejection on a new branch that nobody catches, which can crash
-      // the server process.
+      // Use .then() instead of .finally() to avoid creating an unhandled rejection
+      // branch when the promise rejects. .finally() re-throws on a new branch that
+      // can crash the process if not caught.
       const onSettle = () => {
         inflightCount--;
         notifyDrain();
@@ -255,42 +249,32 @@ export function createHandleStore(): HandleStore {
     },
 
     async *stream(): AsyncGenerator<HandleData, void, unknown> {
-      // Auto-seal: stream() is called after all track() registrations.
       sealInternal();
 
-      // Set up completion handler
       this.settled.then(() => {
         completed = true;
         signalEmission();
       });
 
-      // Initial small delay to batch rapid synchronous pushes
-      // This allows multiple handles pushing in quick succession to be batched
+      // Batch rapid synchronous pushes with initial delay
       await new Promise((resolve) => setTimeout(resolve, 0));
 
-      // If we already have data, yield the accumulated state
       if (Object.keys(data).length > 0) {
-        // Clear pending emissions since we're yielding current state
         pendingEmissions = [];
         const snapshot = cloneHandleData(data);
         yield snapshot;
       }
 
-      // Continue streaming on each push
       while (!completed) {
         await waitForEmission();
 
-        // Yield all pending emissions (yield latest only)
         if (pendingEmissions.length > 0) {
-          // Skip intermediate states, yield the latest
           const latest = pendingEmissions[pendingEmissions.length - 1];
           pendingEmissions = [];
           yield latest;
         }
       }
 
-      // Final yield only if there are pending emissions that weren't yielded
-      // (handles that pushed after our last yield but before completion)
       if (pendingEmissions.length > 0) {
         yield cloneHandleData(data);
       }
@@ -314,12 +298,11 @@ export function createHandleStore(): HandleStore {
         if (!data[handleName]) {
           data[handleName] = {};
         }
-        // Replace with replayed data (not append) to avoid handle bleeding between routes.
-        // When a cached segment is restored, its handles should replace any existing data
-        // for that segment, not accumulate on top of data from a different route.
+        // Replace (not append) to avoid handle bleeding between routes.
+        // Cached segment restoration should replace existing data for that
+        // segment, not accumulate on top of data from a different route.
         data[handleName][segmentId] = [...segmentHandles[handleName]];
       }
-      // Trigger emission for streaming
       pendingEmissions.push(cloneHandleData(data));
       signalEmission();
     },

package/src/server/loader-registry.ts

@@ -11,17 +11,10 @@ import {
   type LoaderRegistryEntry,
 } from "./fetchable-loader-store.js";
 
-// Server-side cache - maps loader $$id to function and middleware
-// This is a CACHE populated by getLoaderLazy() when loaders are first accessed.
-// The source of truth is fetchableLoaderRegistry in loader.ts, which is populated
-// when createLoader() runs. This cache exists to:
-// 1. Avoid repeated lookups/imports for the same loader
-// 2. Support lazy loading in production (loaders imported on-demand)
-// 3. Provide a stable reference for the RSC handler
+// Cache populated by getLoaderLazy() when loaders are first accessed.
+// Source of truth is fetchableLoaderRegistry in loader.ts (populated on createLoader).
 const loaderRegistry = new Map<string, LoaderRegistryEntry>();
 
-// Lazy import map - set by the loader manifest
-// Maps loader $$id to a function that imports the loader module
 type LazyLoaderImport = () => Promise<{ $$id: string }>;
 let lazyLoaderImports: Map<string, LazyLoaderImport> | null = null;
 
@@ -44,30 +37,25 @@ export function setLoaderImports(
 export async function getLoaderLazy(
   id: string,
 ): Promise<LoaderRegistryEntry | undefined> {
-  // Always check fetchableLoaderRegistry first — it's the source of truth.
-  // createLoader() updates it during module re-evaluation (HMR), so checking
-  // here ensures we pick up the fresh function after a loader file change.
+  // Check fetchableLoaderRegistry first — it's the source of truth.
+  // createLoader() updates it on HMR, ensuring fresh functions after file changes.
   const fetchable = getFetchableLoader(id);
   if (fetchable) {
     loaderRegistry.set(id, fetchable);
     return fetchable;
   }
 
-  // Fall back to local cache (populated by previous lazy imports in production)
   const existing = loaderRegistry.get(id);
   if (existing) {
     return existing;
   }
 
-  // Try to lazy load from the import map (production mode)
   if (lazyLoaderImports && lazyLoaderImports.size > 0) {
     const lazyImport = lazyLoaderImports.get(id);
     if (lazyImport) {
       try {
-        // Import the loader module - this triggers createLoader which registers fn
         await lazyImport();
 
-        // Now try to get from fetchable registry (createLoader registered it)
         const registered = getFetchableLoader(id);
         if (registered) {
           loaderRegistry.set(id, registered);
@@ -79,18 +67,14 @@ export async function getLoaderLazy(
     }
   }
 
-  // Dev mode fallback: parse the ID and use Vite's dynamic import
-  // ID format in dev: "src/path/to/file.ts#ExportName"
+  // Dev fallback: parse ID (format: "src/path/to/file.ts#ExportName") and import
   const hashIndex = id.indexOf("#");
   if (hashIndex !== -1) {
     const filePath = id.slice(0, hashIndex);
 
     try {
-      // In dev mode, Vite handles dynamic imports
-      // Just importing the module triggers createLoader which registers the fn
       await import(/* @vite-ignore */ `/${filePath}`);
 
-      // Now try to get from fetchable registry
       const registered = getFetchableLoader(id);
       if (registered) {
         loaderRegistry.set(id, registered);
@@ -115,15 +99,12 @@ export function registerLoaderById(loader: {
   if (!loader.$$id) {
     return;
   }
-  // For fetchable loaders, fn is stored in the fetchable registry by $$id.
-  // Always re-check the fetchable registry so HMR picks up the new function.
   const fetchable = getFetchableLoader(loader.$$id);
   if (fetchable) {
     loaderRegistry.set(loader.$$id, fetchable);
     return;
   }
 
-  // Fall back to using fn from the loader object (non-fetchable loaders)
   if (loader.fn) {
     loaderRegistry.set(loader.$$id, {
       fn: loader.fn,