@rangojs/router 0.0.0-experimental.3 → 0.0.0-experimental.30

package/src/browser/segment-reconciler.ts

@@ -0,0 +1,216 @@
+import type { ResolvedSegment } from "./types.js";
+import {
+  mergeSegmentLoaders,
+  needsLoaderMerge,
+  insertMissingDiffSegments,
+} from "./merge-segment-loaders.js";
+import { assertSegmentStructure } from "./segment-structure-assert.js";
+import { splitInterceptSegments } from "./intercept-utils.js";
+
+/**
+ * Determines the merging behavior for segment reconciliation.
+ *
+ * - 'action': From server-action-bridge's own merge. Always merges loaders,
+ *   always preserves cached loading (even undefined), never clears cached
+ *   segment loading.
+ * - 'navigation': From partial-update during normal navigation. Does NOT merge
+ *   loaders, preserves cached loading only when defined, clears truthy loading
+ *   on cached segments not in server diff.
+ * - 'stale-revalidation': From partial-update during stale revalidation or
+ *   action-triggered refetch. Merges loaders, always preserves cached loading
+ *   (same as action), clears truthy loading on cached segments not in server diff.
+ */
+export type ReconcileActor = "navigation" | "action" | "stale-revalidation";
+
+export interface ReconcileInput {
+  actor: ReconcileActor;
+  /** All segment IDs the server expects the client to have (matched array) */
+  matched: string[];
+  /** Segment IDs that changed (diff array) */
+  diff: string[];
+  /** Segments returned from server (raw array, keyed internally by ID) */
+  serverSegments: ResolvedSegment[];
+  /** Cached segments from current page (raw array, keyed internally by ID) */
+  cachedSegments: ResolvedSegment[];
+  /** When true, diff segments not in matched are inserted after their parent
+   *  layout. Used during navigation when consolidation fetch returns loader
+   *  segments that aren't in the matched array. */
+  insertMissingDiff?: boolean;
+}
+
+export interface ReconcileResult {
+  /** All merged segments in matched order (for caching and committing) */
+  segments: ResolvedSegment[];
+  /** Main segments excluding intercepts (for rendering) */
+  mainSegments: ResolvedSegment[];
+  /** Intercept segments only (passed via render options) */
+  interceptSegments: ResolvedSegment[];
+}
+
+/**
+ * Single source of truth for merging server segments with cached segments.
+ *
+ * Replaces the duplicated merge loops in server-action-bridge.ts and
+ * partial-update.ts. The actor parameter controls the subtle behavioral
+ * differences between action and navigation merging:
+ *
+ * Loading preservation:
+ * - action/stale-revalidation: Always preserves cached loading value when it
+ *   differs from server (even when cached is undefined). This prevents tree
+ *   structure changes that would remount components and destroy useActionState
+ *   during action revalidation or action-triggered refetch.
+ * - navigation: Preserves cached loading only when the cached value is defined
+ *   (not undefined). When cached is undefined, lets server value through
+ *   because we're building a new tree.
+ *
+ * Loader merging:
+ * - action/stale-revalidation: Merges partial loader data when server returns
+ *   fewer loaders than cached (revalidation only updated some loaders).
+ * - navigation: Does not merge (full navigation fetches complete data).
+ *
+ * Cached segment handling (segments in matched but not in server response):
+ * - action: Returns cached segment as-is (preserve tree structure).
+ * - navigation/stale-revalidation: Clears truthy loading to undefined
+ *   (prevents showing stale skeletons), but preserves loading=false
+ *   (suppressed boundary is structural).
+ */
+export function reconcileSegments(input: ReconcileInput): ReconcileResult {
+  const { actor, matched, diff, insertMissingDiff } = input;
+  const shouldMergeLoaders = actor !== "navigation";
+  const context = actor === "action" ? "action-bridge" : "partial-update";
+
+  // Build lookup maps from arrays
+  const serverSegments = new Map<string, ResolvedSegment>();
+  input.serverSegments.forEach((s) => serverSegments.set(s.id, s));
+  const cachedSegments = new Map<string, ResolvedSegment>();
+  input.cachedSegments.forEach((s) => cachedSegments.set(s.id, s));
+
+  const segments = matched
+    .map((segId: string) => {
+      const fromServer = serverSegments.get(segId);
+      const fromCache = cachedSegments.get(segId);
+
+      if (fromServer) {
+        // Merge partial loader data when server returns fewer loaders than cached
+        if (shouldMergeLoaders && needsLoaderMerge(fromServer, fromCache)) {
+          return mergeSegmentLoaders(fromServer, fromCache);
+        }
+
+        // Preserve cached structural properties to maintain consistent React tree.
+        // Changing these between renders alters the element nesting
+        // (with/without RouteContentWrapper, MountContextProvider, etc.),
+        // causing React to remount components and destroy useActionState.
+        if (fromCache) {
+          let merged = fromServer;
+
+          // When server returns component: null for a layout segment, it means
+          // "this segment doesn't need re-rendering" - preserve the cached component
+          // to maintain the outlet chain and prevent React tree changes
+          if (
+            fromServer.component === null &&
+            fromServer.type === "layout" &&
+            fromCache.component != null
+          ) {
+            merged = { ...merged, component: fromCache.component };
+          }
+
+          // Loading preservation is actor-aware:
+          // - action/stale-revalidation: always preserve cached value to prevent
+          //   tree remount (even when cached is undefined, to avoid adding a
+          //   Suspense boundary that wasn't there before)
+          // - navigation: only when cached is defined (building a new tree)
+          if (actor !== "navigation") {
+            if (fromServer.loading !== fromCache.loading) {
+              merged = { ...merged, loading: fromCache.loading };
+            }
+          } else {
+            if (
+              fromCache.loading !== undefined &&
+              fromServer.loading !== fromCache.loading
+            ) {
+              merged = { ...merged, loading: fromCache.loading };
+            }
+          }
+
+          // mountPath: SSR segments may lack mountPath while revalidated segments
+          // include it. The conditional MountContextProvider wrapper changes tree depth.
+          if (fromServer.mountPath !== fromCache.mountPath) {
+            merged = { ...merged, mountPath: fromCache.mountPath };
+          }
+
+          // Dev-mode assertion: warn if the merged result still differs from cache
+          // in tree-structural properties. This catches bugs where the merge code
+          // above fails to preserve a value it should have.
+          assertSegmentStructure(fromCache, merged, context);
+
+          return merged;
+        }
+        return fromServer;
+      }
+
+      // Fall back to cached segment (server expects client to already have it)
+      if (!fromCache) {
+        if (actor === "action") {
+          console.error(`[Browser] MISSING SEGMENT: ${segId} not in cache!`);
+        } else {
+          console.warn(`[Browser] Missing segment: ${segId}`);
+        }
+        return fromCache;
+      }
+
+      // 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
+      if (actor !== "action") {
+        if (fromCache.loading !== undefined && fromCache.loading !== false) {
+          return { ...fromCache, loading: undefined };
+        }
+      }
+
+      return fromCache;
+    })
+    .filter(Boolean) as ResolvedSegment[];
+
+  // Insert diff segments not in matched (e.g., loader segments from consolidation fetch).
+  // Only needed during navigation - action bridge doesn't use this.
+  if (insertMissingDiff) {
+    const matchedIdSet = new Set(matched);
+    insertMissingDiffSegments(segments, diff, matchedIdSet, serverSegments);
+  }
+
+  const { main, intercept } = splitInterceptSegments(segments);
+
+  return {
+    segments,
+    mainSegments: main,
+    interceptSegments: intercept,
+  };
+}
+
+/**
+ * Reconcile error segments with cached segments.
+ *
+ * For error responses, the server returns the error boundary segment.
+ * This function overlays error segments onto the full cached tree,
+ * preserving sibling layouts that aren't in the error parent chain.
+ */
+export function reconcileErrorSegments(
+  cachedSegments: ResolvedSegment[],
+  errorSegments: ResolvedSegment[],
+): ReconcileResult {
+  const errorMap = new Map<string, ResolvedSegment>();
+  errorSegments.forEach((s) => errorMap.set(s.id, s));
+
+  const segments = cachedSegments.map((cached) => {
+    const fromServer = errorMap.get(cached.id);
+    return fromServer || cached;
+  });
+
+  const { main, intercept } = splitInterceptSegments(segments);
+
+  return {
+    segments,
+    mainSegments: main,
+    interceptSegments: intercept,
+  };
+}

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

@@ -0,0 +1,83 @@
+import type { ResolvedSegment } from "./types.js";
+
+/**
+ * Tree structure categories for the `loading` property.
+ *
+ * The `loading` value on a segment determines the React element tree
+ * that renderSegments() produces. Different categories produce different
+ * element nesting, which causes React to remount components when the
+ * category changes between renders (SSR -> navigation -> action).
+ *
+ * "none"       -> OutletProvider (no boundary wrapping)
+ * "suppressed" -> LoaderBoundary > Suspense > LoaderResolver > OutletProvider
+ *                 (boundary present, but no RouteContentWrapper for children)
+ * "active"     -> LoaderBoundary > Suspense > LoaderResolver > OutletProvider
+ *                 > RouteContentWrapper > Suspense > Suspender > component
+ */
+type LoadingCategory = "none" | "suppressed" | "active";
+
+function getLoadingCategory(loading: unknown): LoadingCategory {
+  if (loading === undefined || loading === null) return "none";
+  if (loading === false) return "suppressed";
+  return "active";
+}
+
+/**
+ * Assert that merging a server segment with a cached segment won't change
+ * the React tree structure. Logs a warning in development when a mismatch
+ * is detected.
+ *
+ * This catches the class of bugs where `loading()` with `{ ssr: false }`
+ * produces `loading=false` on SSR but `loading=<skeleton>` on actions,
+ * causing React to remount LoaderBoundary/RouteContentWrapper and destroy
+ * client state (useActionState, refs, etc.).
+ *
+ * @param cached - The currently cached segment
+ * @param incoming - The new segment from server
+ * @param context - Where this merge is happening (for the warning message)
+ */
+export function assertSegmentStructure(
+  cached: ResolvedSegment,
+  incoming: ResolvedSegment,
+  context: string,
+): void {
+  if (process.env.NODE_ENV === "production") return;
+
+  const cachedCategory = getLoadingCategory(cached.loading);
+  const incomingCategory = getLoadingCategory(incoming.loading);
+
+  if (cachedCategory !== incomingCategory) {
+    console.warn(
+      `[RSC Router] Tree structure mismatch detected in ${context} ` +
+        `for segment "${cached.id}": loading category changed from ` +
+        `"${cachedCategory}" (${describeLoading(cached.loading)}) to ` +
+        `"${incomingCategory}" (${describeLoading(incoming.loading)}). ` +
+        `This will cause React to remount the component, destroying ` +
+        `useActionState and other client state. ` +
+        `The merge code should preserve the cached loading value.`,
+    );
+  }
+
+  // Check mountPath consistency. MountContextProvider is conditionally added
+  // in renderSegments() when mountPath is truthy, changing tree depth.
+  const cachedHasMount = !!cached.mountPath;
+  const incomingHasMount = !!incoming.mountPath;
+  if (cachedHasMount !== incomingHasMount) {
+    console.warn(
+      `[RSC Router] MountContextProvider mismatch detected in ${context} ` +
+        `for segment "${cached.id}": mountPath changed from ` +
+        `${cachedHasMount ? `"${cached.mountPath}"` : "undefined"} to ` +
+        `${incomingHasMount ? `"${incoming.mountPath}"` : "undefined"}. ` +
+        `This will cause React to remount the component, destroying ` +
+        `useActionState and other client state. ` +
+        `The merge code should preserve the cached mountPath value.`,
+    );
+  }
+}
+
+function describeLoading(loading: unknown): string {
+  if (loading === undefined) return "undefined";
+  if (loading === null) return "null";
+  if (loading === false) return "false";
+  return "ReactNode";
+}