@rangojs/router 0.0.0-experimental.b02a2fec → 0.0.0-experimental.b3f2d0d9

package/src/browser/segment-reconciler.ts

@@ -6,6 +6,7 @@ import {
 } from "./merge-segment-loaders.js";
 import { assertSegmentStructure } from "./segment-structure-assert.js";
 import { splitInterceptSegments } from "./intercept-utils.js";
+import { debugLog } from "./logging.js";
 
 /**
  * Determines the merging behavior for segment reconciliation.
@@ -85,14 +86,29 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
   const cachedSegments = new Map<string, ResolvedSegment>();
   input.cachedSegments.forEach((s) => cachedSegments.set(s.id, s));
 
+  const diffSet = new Set(diff);
+  debugLog(
+    `[reconcile] actor=${actor}, matched=${matched.length}, diff=${diff.length}`,
+  );
+  debugLog(
+    `[reconcile] server segments: ${[...serverSegments.keys()].join(", ")}`,
+  );
+  debugLog(
+    `[reconcile] cached segments: ${[...cachedSegments.keys()].join(", ")}`,
+  );
+
   const segments = matched
     .map((segId: string) => {
       const fromServer = serverSegments.get(segId);
       const fromCache = cachedSegments.get(segId);
 
       if (fromServer) {
+        const inDiff = diffSet.has(segId);
         // Merge partial loader data when server returns fewer loaders than cached
         if (shouldMergeLoaders && needsLoaderMerge(fromServer, fromCache)) {
+          debugLog(
+            `[reconcile] ${segId}: MERGE loaders (server partial, ${inDiff ? "in diff" : "not in diff"})`,
+          );
           return mergeSegmentLoaders(fromServer, fromCache);
         }
 
@@ -143,8 +159,14 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
           // above fails to preserve a value it should have.
           assertSegmentStructure(fromCache, merged, context);
 
+          debugLog(
+            `[reconcile] ${segId}: SERVER+CACHE merge (${inDiff ? "in diff" : "not in diff"}, type=${fromServer.type}, component=${fromServer.component === null ? "null→cached" : "server"})`,
+          );
           return merged;
         }
+        debugLog(
+          `[reconcile] ${segId}: SERVER only (${inDiff ? "in diff" : "not in diff"}, type=${fromServer.type}, no cache entry)`,
+        );
         return fromServer;
       }
 
@@ -158,20 +180,20 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
         return fromCache;
       }
 
-      // For non-action actors: cached segments the server decided not to re-render.
-      // - Preserve loading=false (suppressed boundary) to maintain tree structure
-      // - 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 };
-        }
-      }
-
+      debugLog(
+        `[reconcile] ${segId}: CACHE only (not from server, type=${fromCache.type}, component=${fromCache.component != null ? "yes" : "null"})`,
+      );
+
+      // Return the cached segment as-is, regardless of actor. We used to clear
+      // truthy `loading` here to prevent a stale Suspense fallback from
+      // committing against cached content, but that swapped the render tree
+      // from the LoaderBoundary branch to the plain OutletProvider branch
+      // inside renderSegments, causing React to unmount the entire chain
+      // (LoaderBoundary > Suspense > LoaderResolver > RouteContentWrapper >
+      // Suspender) every time the user opened an intercept or navigated back
+      // to a cached page. The flicker is now prevented by renderSegments'
+      // promise memoization keeping React's use() in "known fulfilled" state,
+      // so preserving `loading` keeps the element tree stable.
       return fromCache;
     })
     .filter(Boolean) as ResolvedSegment[];

package/src/browser/segment-structure-assert.ts

@@ -48,7 +48,7 @@ export function assertSegmentStructure(
 
   if (cachedCategory !== incomingCategory) {
     console.warn(
-      `[RSC Router] Tree structure mismatch detected in ${context} ` +
+      `[Rango] Tree structure mismatch detected in ${context} ` +
         `for segment "${cached.id}": loading category changed from ` +
         `"${cachedCategory}" (${describeLoading(cached.loading)}) to ` +
         `"${incomingCategory}" (${describeLoading(incoming.loading)}). ` +
@@ -64,7 +64,7 @@ export function assertSegmentStructure(
   const incomingHasMount = !!incoming.mountPath;
   if (cachedHasMount !== incomingHasMount) {
     console.warn(
-      `[RSC Router] MountContextProvider mismatch detected in ${context} ` +
+      `[Rango] MountContextProvider mismatch detected in ${context} ` +
         `for segment "${cached.id}": mountPath changed from ` +
         `${cachedHasMount ? `"${cached.mountPath}"` : "undefined"} to ` +
         `${incomingHasMount ? `"${incoming.mountPath}"` : "undefined"}. ` +

package/src/browser/server-action-bridge.ts

@@ -25,6 +25,7 @@ import { validateRedirectOrigin } from "./validate-redirect-origin.js";
 import {
   extractRscHeaderUrl,
   emptyResponse,
+  handleReloadHeader,
   teeWithCompletion,
 } from "./response-adapter.js";
 import { mergeLocationState } from "./history-state.js";
@@ -77,6 +78,20 @@ export function createServerActionBridge(
     onNavigate,
   } = config;
 
+  // SPA-navigate when onNavigate is set, else hard-reload. state is omitted (not
+  // passed as undefined) to match the header path's prior call shape.
+  async function dispatchRedirect(url: string, state?: unknown): Promise<void> {
+    if (onNavigate) {
+      await onNavigate(url, {
+        ...(state !== undefined ? { state } : {}),
+        replace: true,
+        _skipCache: true,
+      });
+    } else {
+      window.location.href = url;
+    }
+  }
+
   let isRegistered = false;
 
   const fetchPartialUpdate = createPartialUpdater({
@@ -222,18 +237,12 @@ export function createServerActionBridge(
         handle.signal.removeEventListener("abort", onHandleAbort);
 
         // Check for version mismatch - server wants us to reload
-        const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
-        if (reload === "blocked") {
-          resolveStreamComplete();
-          return emptyResponse();
-        }
-        if (reload) {
-          log("version mismatch on action, reloading", {
-            reloadUrl: reload.url,
-          });
-          window.location.href = reload.url;
-          return new Promise<Response>(() => {});
-        }
+        const reloadResult = handleReloadHeader(response, {
+          onBlocked: resolveStreamComplete,
+          onReload: (url) =>
+            log("version mismatch on action, reloading", { reloadUrl: url }),
+        });
+        if (reloadResult) return reloadResult;
 
         // Simple redirect from action (no state, no RSC payload).
         // Short-circuits before createFromFetch — no Flight deserialization needed.
@@ -243,14 +252,7 @@ export function createServerActionBridge(
         if (redirect && redirect !== "blocked" && !handle.signal.aborted) {
           log("action simple redirect", { url: redirect.url });
           handle.complete(undefined);
-          if (onNavigate) {
-            await onNavigate(redirect.url, {
-              replace: true,
-              _skipCache: true,
-            });
-          } else {
-            window.location.href = redirect.url;
-          }
+          await dispatchRedirect(redirect.url);
           return new Promise<Response>(() => {});
         }
         if (redirect === "blocked") {
@@ -339,18 +341,9 @@ export function createServerActionBridge(
           handle.complete(returnValue?.data);
           return returnValue?.data;
         }
-        const redirectState = metadata.locationState;
         log("action redirect", { url: redirectUrl });
         handle.complete(returnValue?.data);
-        if (onNavigate) {
-          await onNavigate(redirectUrl, {
-            state: redirectState,
-            replace: true,
-            _skipCache: true,
-          });
-        } else {
-          window.location.href = redirectUrl;
-        }
+        await dispatchRedirect(redirectUrl, metadata.locationState);
         return returnValue?.data;
       }
 

package/src/browser/types.ts

@@ -39,6 +39,12 @@ export interface RscMetadata {
   isError?: boolean;
   matched?: string[];
   diff?: string[];
+  /**
+   * All segment ids re-resolved on the server, including null-component
+   * ones excluded from `segments`/`diff`. Drives client-side handle-bucket
+   * cleanup. Superset of `diff`. See MatchResult.resolvedIds.
+   */
+  resolvedIds?: string[];
   /** Merged route params from the matched route */
   params?: Record<string, string>;
   /**
@@ -427,6 +433,12 @@ export interface NavigationStore {
   markCacheAsStale(): void;
   markCacheAsStaleAndBroadcast(): void;
   clearHistoryCache(): void;
+  /**
+   * Clear this tab's nav + prefetch caches without broadcasting or rotating
+   * shared state. Intended for app-switch transitions that affect only this
+   * tab's session.
+   */
+  clearHistoryCacheLocal(): void;
   broadcastCacheInvalidation(): void;
 
   // Cross-tab refresh callback (set by navigation bridge)
@@ -540,8 +552,17 @@ export interface NavigationBridge {
   refresh(): Promise<void>;
   handlePopstate(): Promise<void>;
   registerLinkInterception(): () => void;
+  /** Current RSC version (live, reflects the latest updateVersion). */
+  getVersion(): string | undefined;
   /** Update the RSC version (e.g. after HMR). Clears prefetch cache. */
   updateVersion(newVersion: string): void;
+  /**
+   * Replace the active app-shell snapshot (rootLayout, basename, version)
+   * atomically. Used on cross-app navigations when the response's routerId
+   * indicates the user entered a different app. Theme, warmup, and prefetch
+   * TTL are document-lifetime and not part of the shell.
+   */
+  updateAppShell(next: import("./app-shell.js").AppShell): void;
 }
 
 /**

package/src/build/collect-fallback-refs.ts

@@ -0,0 +1,107 @@
+// Collect the `"use client"` client-reference keys reachable from an error /
+// notFound boundary registration, for routing them into the dedicated
+// `app-fallback` chunk (see vite/utils/client-chunks.ts).
+//
+// A boundary registration is not always a bare client element. The common,
+// load-bearing pattern wraps the client boundary in providers a thrown handler
+// needs (the layout that would normally supply them did not mount):
+//
+//   defaultErrorBoundary: ({ error }) => (
+//     <FallbackIntl locales={...}>
+//       <ThemedError error={error} />   // <- the real "use client" boundary
+//     </FallbackIntl>
+//   )
+//
+// So the value may be (a) a handler FUNCTION returning a tree, or (b) an element
+// tree with the client boundary nested below server wrappers. We:
+//   1. If it's a function, CALL it with synthetic props to get the returned tree.
+//      This only constructs JSX — the inner components are element `type`s, never
+//      invoked — so no hooks run. Guarded: a boundary that needs a real render
+//      context (request globals, etc.) throws and is skipped (graceful: it simply
+//      stays on the default grouping, as before).
+//   2. Walk the resulting tree and report every element whose `.type` is a
+//      plugin-rsc client reference.
+//
+// Limit: a boundary that *conditionally* renders different client components based
+// on the runtime error cannot be resolved statically — only the branch taken with
+// the synthetic error is seen. Such cases fall back to the default chunk; the
+// custom `clientChunks` function is the escape hatch.
+
+const CLIENT_REF = Symbol.for("react.client.reference");
+const MAX_DEPTH = 40;
+
+// Synthetic props covering the error-boundary (`{ error, reset }`) and notFound
+// (`{ pathname }`) handler shapes. The handler destructures what it needs.
+const SYNTHETIC_PROPS = {
+  error: new Error("rango: build-time fallback-chunk discovery"),
+  reset: () => {},
+  pathname: "/",
+  info: { componentStack: "" },
+};
+
+interface MaybeElement {
+  type?: { $$typeof?: symbol; $$id?: string };
+  props?: Record<string, unknown>;
+}
+
+function isReactNodeLike(v: unknown): boolean {
+  return (
+    Array.isArray(v) ||
+    (typeof v === "object" && v !== null && "$$typeof" in (v as object))
+  );
+}
+
+function walkElementTree(
+  node: unknown,
+  report: (refKey: string) => void,
+  depth: number,
+): void {
+  if (node == null || depth > MAX_DEPTH) return;
+  if (Array.isArray(node)) {
+    for (const child of node) walkElementTree(child, report, depth + 1);
+    return;
+  }
+  if (typeof node !== "object") return;
+
+  const el = node as MaybeElement;
+  const type = el.type;
+  if (type?.$$typeof === CLIENT_REF && typeof type.$$id === "string") {
+    // $$id is `<referenceKey>#<exportName>` in build mode — keep the referenceKey.
+    report(type.$$id.split("#")[0]);
+  }
+
+  const props = el.props;
+  if (props && typeof props === "object") {
+    // Children are always nodes; other props are followed only when they look
+    // like React nodes (slots/icons), never arbitrary data objects.
+    walkElementTree(props.children, report, depth + 1);
+    for (const key in props) {
+      if (key === "children") continue;
+      const value = props[key];
+      if (isReactNodeLike(value)) walkElementTree(value, report, depth + 1);
+    }
+  }
+}
+
+/**
+ * Report every `"use client"` client-reference key reachable from a single
+ * error/notFound boundary registration (handler function or element tree).
+ */
+export function collectFallbackClientRefs(
+  boundary: unknown,
+  report: (refKey: string) => void,
+): void {
+  try {
+    let node = boundary;
+    if (typeof node === "function") {
+      node = (node as (props: unknown) => unknown)(SYNTHETIC_PROPS);
+    }
+    walkElementTree(node, report, 0);
+  } catch {
+    // The boundary needs a real render context (request globals, hooks at the
+    // top level) or its tree has hostile getters. Its client refs can't be
+    // resolved statically — skip. It stays on the default grouping (no
+    // regression vs. not collecting), and the custom clientChunks fn is the
+    // escape hatch for such cases.
+  }
+}

package/src/build/generate-manifest.ts

@@ -11,11 +11,12 @@
 import type { UrlPatterns } from "../urls.js";
 import type { AllUseItems } from "../route-types.js";
 import { extractStaticPrefix } from "../router/pattern-matching.js";
-import { RSCRouterContext, runWithPrefixes } from "../server/context.js";
+import { RangoContext, runWithPrefixes } from "../server/context.js";
 import type { EntryData, TrackedInclude } from "../server/context.js";
 import type { TrailingSlashMode } from "../types.js";
 import { createRouteHelpers } from "../route-definition.js";
 import MapRootLayout from "../server/root-layout.js";
+import { collectFallbackClientRefs } from "./collect-fallback-refs.js";
 
 /**
  * Node in the prefix tree
@@ -57,6 +58,26 @@ export interface GeneratedManifest {
  * Build prefix tree node by running the patterns with proper context.
  * Uses a visited set to detect circular includes and prevent infinite recursion.
  */
+// Merge tracked nested includes into `target`. Multiple includes can share a
+// fullPrefix (e.g. include("/", a), include("/", b)) — concat their routes and
+// Object.assign children rather than overwrite.
+function mergeIncludeNodes(
+  target: Record<string, PrefixTreeNode>,
+  includes: TrackedInclude[],
+  buildChild: (include: TrackedInclude) => PrefixTreeNode,
+): void {
+  for (const include of includes) {
+    const node = buildChild(include);
+    const existing = target[include.fullPrefix];
+    if (existing) {
+      existing.routes.push(...node.routes);
+      Object.assign(existing.children, node.children);
+    } else {
+      target[include.fullPrefix] = node;
+    }
+  }
+}
+
 function buildPrefixTreeNode(
   urlPrefix: string,
   namePrefix: string | undefined,
@@ -93,7 +114,7 @@ function buildPrefixTreeNode(
   const searchSchemasMap = new Map<string, Record<string, string>>();
   const trackedIncludes: TrackedInclude[] = [];
 
-  RSCRouterContext.run(
+  RangoContext.run(
     {
       manifest,
       patterns: patternsMap,
@@ -166,13 +187,9 @@ function buildPrefixTreeNode(
     }
   }
 
-  // Build children from tracked nested includes.
-  // Multiple includes can share the same fullPrefix (e.g., include("/", patternsA),
-  // include("/", patternsB)). Merge their routes instead of overwriting.
   const children: Record<string, PrefixTreeNode> = {};
-
-  for (const include of trackedIncludes) {
-    const childNode = buildPrefixTreeNode(
+  mergeIncludeNodes(children, trackedIncludes, (include) =>
+    buildPrefixTreeNode(
       include.fullPrefix,
       include.namePrefix,
       include.patterns as UrlPatterns<any>,
@@ -186,16 +203,8 @@ function buildPrefixTreeNode(
       passthroughRoutes,
       responseTypeRoutes,
       routeSearchSchemas,
-    );
-
-    const existing = children[include.fullPrefix];
-    if (existing) {
-      existing.routes.push(...childNode.routes);
-      Object.assign(existing.children, childNode.children);
-    } else {
-      children[include.fullPrefix] = childNode;
-    }
-  }
+    ),
+  );
 
   // Remove from visited so sibling branches can reuse the same patterns
   // without false circular-include detection. Only ancestors in the current
@@ -282,7 +291,17 @@ export function generateManifest<TEnv>(
 export function generateManifestFull<TEnv>(
   urlpatterns: UrlPatterns<TEnv, any>,
   mountIndex: number = 0,
-  options?: { urlPrefix?: string },
+  options?: {
+    urlPrefix?: string;
+    /**
+     * Called once per `"use client"` component registered as an
+     * errorBoundary/notFoundBoundary fallback, with its client-reference key
+     * (`$$id`). Lets the build collect fallback module ids for dedicated
+     * chunking without exposing the otherwise-discarded EntryData tree. The
+     * EntryData map built below is local; this is the only seam that surfaces it.
+     */
+    collectClientFallbackRef?: (refKey: string) => void;
+  },
 ): FullManifest {
   const routeManifest: Record<string, string> = {};
   const routeAncestry: Record<string, string[]> = {};
@@ -296,7 +315,7 @@ export function generateManifestFull<TEnv>(
   const searchSchemasMap = new Map<string, Record<string, string>>();
   const trackedIncludes: TrackedInclude[] = [];
 
-  RSCRouterContext.run(
+  RangoContext.run(
     {
       manifest,
       patterns: patternsMap,
@@ -320,6 +339,22 @@ export function generateManifestFull<TEnv>(
     },
   );
 
+  // Surface the "use client" components registered as error/notFound fallbacks
+  // (route-tree errorBoundary()/notFoundBoundary() helpers, stored on EntryData).
+  // The boundary may be a handler function and/or wrap the client boundary in
+  // server providers, so walk the whole tree (see collectFallbackClientRefs).
+  if (options?.collectClientFallbackRef) {
+    const report = options.collectClientFallbackRef;
+    const collect = (boundary: unknown[] | undefined) => {
+      for (const item of boundary ?? [])
+        collectFallbackClientRefs(item, report);
+    };
+    for (const entry of manifest.values()) {
+      collect(entry.errorBoundary);
+      collect(entry.notFoundBoundary);
+    }
+  }
+
   // Collect root-level routes and trailing slash config
   const routeTrailingSlash: Record<string, string> = {};
   for (const [name, pattern] of patternsMap.entries()) {
@@ -356,12 +391,10 @@ export function generateManifestFull<TEnv>(
     }
   }
 
-  // Build prefix tree from tracked includes (shared visited set for cycle detection).
-  // Multiple includes can share the same fullPrefix (e.g., include("/", patternsA),
-  // include("/", patternsB)). Merge their routes instead of overwriting.
+  // Shared visited set for cycle detection across all root-level includes.
   const visited = new Set<unknown>();
-  for (const include of trackedIncludes) {
-    const node = buildPrefixTreeNode(
+  mergeIncludeNodes(prefixTree, trackedIncludes, (include) =>
+    buildPrefixTreeNode(
       include.fullPrefix,
       include.namePrefix,
       include.patterns as UrlPatterns<any>,
@@ -375,16 +408,8 @@ export function generateManifestFull<TEnv>(
       passthroughRoutes,
       responseTypeRoutes,
       routeSearchSchemas,
-    );
-
-    const existing = prefixTree[include.fullPrefix];
-    if (existing) {
-      existing.routes.push(...node.routes);
-      Object.assign(existing.children, node.children);
-    } else {
-      prefixTree[include.fullPrefix] = node;
-    }
-  }
+    ),
+  );
 
   return {
     prefixTree,

package/src/build/generate-route-types.ts

@@ -35,5 +35,7 @@ export {
   formatNestedRouterConflictError,
   findRouterFiles,
   writeCombinedRouteTypes,
+  genFileTsPath,
+  resolveSearchSchemas,
 } from "./route-types/router-processing.js";
 export { findUrlsVariableNames } from "./route-types/per-module-writer.js";

package/src/build/index.ts

@@ -24,6 +24,8 @@ export {
 
 export { buildRouteTrie, type TrieNode, type TrieLeaf } from "./route-trie.js";
 
+export { collectFallbackClientRefs } from "./collect-fallback-refs.js";
+
 export {
   writePerModuleRouteTypes,
   extractRoutesFromSource,