@rangojs/router 0.0.0-experimental.0f44aca1

package/src/browser/partial-update.ts

@@ -0,0 +1,550 @@
+import type {
+  NavigationStore,
+  NavigationClient,
+  UpdateSubscriber,
+  ResolvedSegment,
+} from "./types.js";
+import type { ReactNode } from "react";
+import * as React from "react";
+import { startTransition } from "react";
+
+// addTransitionType is only available in React experimental
+const addTransitionType: ((type: string) => void) | undefined =
+  "addTransitionType" in React ? (React as any).addTransitionType : undefined;
+import type { RenderSegmentsOptions } from "../segment-system.js";
+import { reconcileSegments } from "./segment-reconciler.js";
+import type { ReconcileActor } from "./segment-reconciler.js";
+import { hasActiveIntercept as hasActiveInterceptSlots } from "./intercept-utils.js";
+import type { BoundTransaction } from "./navigation-transaction.js";
+import { ServerRedirect } from "../errors.js";
+import { debugLog } from "./logging.js";
+import { validateRedirectOrigin } from "./validate-redirect-origin.js";
+
+/**
+ * Configuration for creating a partial updater
+ */
+export interface PartialUpdateConfig {
+  store: NavigationStore;
+  client: NavigationClient;
+  onUpdate: UpdateSubscriber;
+  renderSegments: (
+    segments: ResolvedSegment[],
+    options?: RenderSegmentsOptions,
+  ) => Promise<ReactNode> | ReactNode;
+  /** RSC version received from server (from initial payload metadata) */
+  version?: string;
+}
+
+/**
+ * Options that can override the pre-configured commit settings
+ */
+export interface CommitOverrides {
+  /** Override scroll behavior (e.g., disable for intercepts) */
+  scroll?: boolean;
+  /** Override replace behavior (e.g., force replace for intercepts) */
+  replace?: boolean;
+  /** Mark this as an intercept route */
+  intercept?: boolean;
+  /** Source URL where intercept was triggered from */
+  interceptSourceUrl?: string;
+  /** Server-set location state to merge into history.pushState */
+  serverState?: Record<string, unknown>;
+}
+
+/**
+ * Discriminated update mode for partial updates.
+ */
+export type UpdateMode =
+  | {
+      type: "navigate";
+      /** Cached segments for the target URL. When provided, these are used to build
+       * the segment map instead of the current page's segments. This ensures consistency
+       * when we send cached segment IDs to the server - if the server returns empty diff,
+       * we use the same segments we told the server we have. */
+      targetCacheSegments?: ResolvedSegment[];
+      /** Cached handle data for the target URL. When server returns empty diff and we're
+       * rendering from cache, this is passed to the UI to restore breadcrumbs etc. */
+      targetCacheHandleData?: Record<string, Record<string, unknown[]>>;
+      /** Source URL for intercept restore (popstate cache miss) */
+      interceptSourceUrl?: string;
+    }
+  | { type: "leave-intercept" }
+  | { type: "stale-revalidation"; interceptSourceUrl?: string }
+  | { type: "action"; interceptSourceUrl?: string };
+
+/**
+ * Type for the fetchPartialUpdate function
+ */
+export type PartialUpdater = (
+  targetUrl: string,
+  segmentIds: string[] | undefined,
+  isRetry: boolean,
+  signal: AbortSignal | undefined,
+  tx: BoundTransaction,
+  mode?: UpdateMode,
+) => Promise<void>;
+
+/**
+ * Create a partial updater for fetching and applying RSC partial updates
+ *
+ * This function is shared between navigation-bridge and server-action-bridge
+ * to handle partial RSC updates with HMR resilience.
+ *
+ * @param config - Partial update configuration
+ * @returns fetchPartialUpdate function
+ */
+export function createPartialUpdater(
+  config: PartialUpdateConfig,
+): PartialUpdater {
+  const { store, client, onUpdate, renderSegments, version } = config;
+
+  /**
+   * Get current page's cached segments as an array
+   */
+  function getCurrentCachedSegments(): ResolvedSegment[] {
+    const currentKey = store.getHistoryKey();
+    const cached = store.getCachedSegments(currentKey);
+    return cached?.segments || [];
+  }
+
+  /**
+   * Fetch partial update and trigger UI update
+   *
+   * @param tx - Transaction for committing segment state (required)
+   * @param signal - AbortSignal to check if navigation is stale (not for aborting fetch)
+   */
+  async function fetchPartialUpdate(
+    targetUrl: string,
+    segmentIds: string[] | undefined,
+    isRetry: boolean,
+    signal: AbortSignal | undefined,
+    tx: BoundTransaction,
+    mode: UpdateMode = { type: "navigate" },
+  ): Promise<void> {
+    const segmentState = store.getSegmentState();
+    const url = targetUrl || window.location.href;
+
+    // Capture history key at start for stale revalidation consistency check
+    const historyKeyAtStart = store.getHistoryKey();
+
+    // Derive interceptSourceUrl from modes that carry it
+    const interceptSourceUrl =
+      mode.type === "stale-revalidation" ||
+      mode.type === "action" ||
+      mode.type === "navigate"
+        ? mode.interceptSourceUrl
+        : undefined;
+
+    // When leaving intercept, filter out intercept-specific segments
+    let segments: string[];
+    if (mode.type === "leave-intercept") {
+      const currentSegments = segmentIds ?? segmentState.currentSegmentIds;
+      const currentCached = getCurrentCachedSegments();
+      const interceptIds = new Set(
+        currentCached
+          .filter((s) => s.namespace?.startsWith("intercept:"))
+          .map((s) => s.id),
+      );
+      segments = currentSegments.filter((id) => !interceptIds.has(id));
+      debugLog(
+        `[Browser] Leaving intercept - filtered segments: ${segments.join(", ")}`,
+      );
+    } else {
+      segments = segmentIds ?? segmentState.currentSegmentIds;
+    }
+
+    // For intercept revalidation, use the intercept source URL as previousUrl
+    const previousUrl =
+      interceptSourceUrl || tx.currentUrl || segmentState.currentUrl;
+
+    debugLog(`\n[Browser] >>> NAVIGATION`);
+    debugLog(`[Browser] From: ${previousUrl}`);
+    debugLog(`[Browser] To: ${url}`);
+    debugLog(`[Browser] Segments to send: ${segments.join(", ")}`);
+    if (interceptSourceUrl) {
+      debugLog(`[Browser] Intercept context from: ${interceptSourceUrl}`);
+    }
+
+    // Get cached segments for merging with server diff.
+    // When navigating with targetCacheSegments, use those for consistency.
+    // Otherwise fall back to current page's segments (for same-route revalidation).
+    const targetCache =
+      mode.type === "navigate" ? mode.targetCacheSegments : undefined;
+    const cachedSegs =
+      targetCache && targetCache.length > 0
+        ? targetCache
+        : getCurrentCachedSegments();
+
+    // Fetch partial payload (no abort signal - RSC doesn't support it well)
+    let fetchResult: Awaited<ReturnType<NavigationClient["fetchPartial"]>>;
+    fetchResult = await client.fetchPartial({
+      targetUrl: url,
+      segmentIds: segments,
+      previousUrl,
+      // Mark stale when explicitly requested OR when no segments are sent
+      // (action redirect sends empty segments for a fresh render).
+      staleRevalidation:
+        mode.type === "stale-revalidation" || segments.length === 0,
+      version,
+    });
+    // Mark navigation as streaming (response received, now parsing RSC).
+    // Called after fetchPartial so pendingUrl stays set during the network wait,
+    // allowing useLinkStatus to show per-link pending indicators.
+    const streamingToken = tx.startStreaming();
+    const { payload, streamComplete: rawStreamComplete } = fetchResult;
+    debugLog("payload.metadata", payload.metadata);
+
+    const streamComplete = rawStreamComplete.then(() => {
+      streamingToken.end();
+    });
+
+    // Handle server-side redirect with state
+    if (payload.metadata?.redirect) {
+      if (signal?.aborted) {
+        debugLog("[Browser] Ignoring stale redirect (aborted)");
+        return;
+      }
+      const redirectUrl = validateRedirectOrigin(
+        payload.metadata.redirect.url,
+        window.location.origin,
+      );
+      if (!redirectUrl) {
+        debugLog("[Browser] Ignoring blocked redirect payload");
+        return;
+      }
+      const serverState = payload.metadata.locationState;
+      throw new ServerRedirect(redirectUrl, serverState);
+    }
+
+    if (payload.metadata?.isPartial) {
+      const { segments: newSegments, matched, diff } = payload.metadata;
+
+      // Check if this navigation is stale (a newer one started)
+      if (signal?.aborted) {
+        debugLog("[Browser] Ignoring stale navigation (aborted)");
+        return;
+      }
+
+      debugLog(`[Browser] Partial update - matched: ${matched?.join(", ")}`);
+      debugLog(`[Browser] Diff: ${diff?.join(", ")}`);
+
+      // If diff is empty, nothing changed on server side.
+      if (!diff || diff.length === 0) {
+        const matchedIds = matched || [];
+        const cacheMap = new Map(cachedSegs.map((s) => [s.id, s]));
+        const existingSegments = matchedIds
+          .map((id: string) => cacheMap.get(id))
+          .filter(Boolean) as ResolvedSegment[];
+
+        // When navigating with cached segments to a different route, render them.
+        if (mode.type === "navigate" && targetCache && targetCache.length > 0) {
+          debugLog(
+            "[Browser] No diff but navigating with cached segments - rendering target route",
+          );
+
+          const newTree = await renderSegments(existingSegments, {
+            forceAwait: true,
+          });
+
+          tx.commit(matchedIds, existingSegments);
+
+          // Include cachedHandleData in metadata so NavigationProvider can restore
+          // breadcrumbs and other handle data from cache.
+          // Remove `handles` from metadata to prevent NavigationProvider from
+          // processing an empty handles stream, which would clear the cached breadcrumbs.
+          const { handles: _unusedHandles, ...metadataWithoutHandles } =
+            payload.metadata!;
+          const cachedUpdate = {
+            root: newTree,
+            metadata: {
+              ...metadataWithoutHandles,
+              cachedHandleData: mode.targetCacheHandleData,
+            },
+          };
+
+          const cachedHasTransition = existingSegments.some(
+            (s) => s.transition,
+          );
+          if (cachedHasTransition) {
+            startTransition(() => {
+              if (addTransitionType) {
+                addTransitionType("navigation");
+              }
+              onUpdate(cachedUpdate);
+            });
+          } else {
+            onUpdate(cachedUpdate);
+          }
+
+          debugLog("[Browser] Navigation complete (rendered from cache)");
+          return;
+        }
+
+        // When leaving intercept, force re-render even with empty diff
+        if (mode.type === "leave-intercept") {
+          debugLog(
+            "[Browser] Leaving intercept - forcing re-render to remove modal",
+          );
+
+          const newTree = await renderSegments(existingSegments, {
+            forceAwait: true,
+          });
+
+          tx.commit(matchedIds, existingSegments);
+
+          onUpdate({
+            root: newTree,
+            metadata: payload.metadata,
+          });
+
+          debugLog("[Browser] Navigation complete (left intercept)");
+          return;
+        }
+
+        // Same route revalidation with no changes - skip UI update
+        debugLog(
+          "[Browser] No changes - all revalidations returned false, keeping existing UI",
+        );
+        tx.commit(matchedIds, existingSegments);
+        debugLog("[Browser] Navigation complete (no re-render)");
+        return;
+      }
+
+      // Reconcile server segments with cached segments (single source of truth)
+      const matchedIds = matched || [];
+      const actor: ReconcileActor =
+        mode.type === "stale-revalidation" || mode.type === "action"
+          ? "stale-revalidation"
+          : "navigation";
+
+      const reconciled = reconcileSegments({
+        actor,
+        matched: matchedIds,
+        diff: diff || [],
+        serverSegments: newSegments || [],
+        cachedSegments: cachedSegs,
+        insertMissingDiff: true,
+      });
+
+      // HMR RESILIENCE: Check if we're missing any matched segments
+      const reconciledIdSet = new Set(reconciled.segments.map((s) => s.id));
+      const missingIds = matchedIds.filter(
+        (id: string) => !reconciledIdSet.has(id),
+      );
+
+      if (missingIds.length > 0) {
+        const missingCount = missingIds.length;
+
+        if (isRetry) {
+          console.warn("Missing ids", { missingIds });
+          throw new Error(
+            `[Browser] Failed to fetch segments after retry. Missing: [${missingIds.join(", ")}]`,
+          );
+        }
+        if (signal?.aborted) {
+          debugLog(
+            "[Browser] Ignoring stale navigation (aborted during HMR retry)",
+          );
+          return;
+        }
+        if (mode.type === "action") {
+          return;
+        }
+        console.warn(
+          `[Browser] HMR detected: Missing ${missingCount} segments. Refetching all...`,
+        );
+
+        // Refetch with empty segments = server sends everything
+        return fetchPartialUpdate(url, [], true, signal, tx, mode);
+      }
+
+      if (signal?.aborted) {
+        debugLog("[Browser] Ignoring stale navigation (aborted before render)");
+        return;
+      }
+
+      // Rebuild tree on client (await for loader data resolution)
+      const renderOptions = {
+        isAction: mode.type === "action",
+        forceAwait: mode.type === "stale-revalidation",
+        interceptSegments:
+          reconciled.interceptSegments.length > 0
+            ? reconciled.interceptSegments
+            : undefined,
+      };
+      const newTree = await (signal
+        ? Promise.race([
+            renderSegments(reconciled.mainSegments, renderOptions),
+            new Promise<never>((_, reject) => {
+              if (signal.aborted) {
+                reject(new DOMException("Navigation aborted", "AbortError"));
+              }
+              signal.addEventListener("abort", () => {
+                reject(new DOMException("Navigation aborted", "AbortError"));
+              });
+            }),
+          ])
+        : renderSegments(reconciled.mainSegments, renderOptions));
+
+      // Final abort check before committing - another navigation may have started
+      if (signal?.aborted) {
+        debugLog("[Browser] Ignoring stale navigation (aborted before commit)");
+        return;
+      }
+
+      // Check if this is an intercept response (any slot is active)
+      const isInterceptResponse = hasActiveInterceptSlots(
+        payload.metadata?.slots,
+      );
+
+      // Track intercept context (only on navigation, not actions or stale revalidation)
+      // Use the authoritative source from mode/history state when restoring an
+      // intercept via popstate cache miss; fall back to the current URL for fresh
+      // intercept navigations.
+      const effectiveInterceptSource =
+        interceptSourceUrl || segmentState.currentUrl;
+      if (mode.type !== "action" && mode.type !== "stale-revalidation") {
+        if (isInterceptResponse) {
+          store.setInterceptSourceUrl(effectiveInterceptSource);
+        } else {
+          store.setInterceptSourceUrl(null);
+        }
+      }
+
+      // Commit navigation - transaction handles all store mutations atomically
+      const allSegmentIds = reconciled.segments.map((s) => s.id);
+      const serverLocationState = payload.metadata?.locationState;
+      const overrides: CommitOverrides | undefined = isInterceptResponse
+        ? {
+            scroll: false,
+            intercept: true,
+            interceptSourceUrl: effectiveInterceptSource,
+            ...(serverLocationState && { serverState: serverLocationState }),
+          }
+        : serverLocationState
+          ? { serverState: serverLocationState }
+          : undefined;
+      tx.commit(allSegmentIds, reconciled.segments, overrides);
+
+      // For stale revalidation: verify history key hasn't changed before updating UI
+      if (mode.type === "stale-revalidation") {
+        const historyKeyNow = store.getHistoryKey();
+        if (historyKeyNow !== historyKeyAtStart) {
+          debugLog(
+            `[Browser] Stale revalidation: history key changed (${historyKeyAtStart} -> ${historyKeyNow}), skipping UI update`,
+          );
+          return;
+        }
+      }
+
+      debugLog("[partial-update] updating document");
+
+      // Emit update to trigger React render
+      const hasTransition = reconciled.mainSegments.some((s) => s.transition);
+
+      if (mode.type === "action" || mode.type === "stale-revalidation") {
+        startTransition(() => {
+          if (hasTransition && addTransitionType) {
+            addTransitionType("action");
+          }
+          onUpdate({
+            root: newTree,
+            metadata: payload.metadata!,
+          });
+        });
+      } else if (hasTransition) {
+        startTransition(() => {
+          if (addTransitionType) {
+            addTransitionType("navigation");
+          }
+          onUpdate({
+            root: newTree,
+            metadata: payload.metadata!,
+          });
+        });
+      } else {
+        onUpdate({
+          root: newTree,
+          metadata: payload.metadata!,
+        });
+      }
+
+      debugLog("[Browser] Navigation complete");
+      return;
+    } else {
+      // Full update (fallback)
+      console.warn(`[Browser] Full update (fallback)`);
+
+      const segments = payload.metadata?.segments || [];
+
+      if (signal?.aborted) {
+        debugLog("[Browser] Ignoring stale navigation (aborted)");
+        return;
+      }
+
+      const segmentIds = segments.map((s: ResolvedSegment) => s.id);
+
+      const newTree = await renderSegments(segments);
+
+      if (signal?.aborted) {
+        debugLog("[Browser] Ignoring stale navigation (aborted before commit)");
+        return;
+      }
+
+      const fullUpdateServerState = payload.metadata?.locationState;
+      if (fullUpdateServerState) {
+        tx.commit(segmentIds, segments, { serverState: fullUpdateServerState });
+      } else {
+        tx.commit(segmentIds, segments);
+      }
+
+      const fullHasTransition = segments.some(
+        (s: ResolvedSegment) => s.transition,
+      );
+
+      if (mode.type === "stale-revalidation") {
+        await rawStreamComplete;
+        startTransition(() => {
+          if (fullHasTransition && addTransitionType) {
+            addTransitionType("action");
+          }
+          onUpdate({
+            root: newTree,
+            metadata: payload.metadata!,
+          });
+        });
+      } else if (mode.type === "action") {
+        startTransition(async () => {
+          if (fullHasTransition && addTransitionType) {
+            addTransitionType("action");
+          }
+          onUpdate({
+            root: newTree,
+            metadata: payload.metadata!,
+          });
+        });
+      } else if (fullHasTransition) {
+        startTransition(() => {
+          if (addTransitionType) {
+            addTransitionType("navigation");
+          }
+          onUpdate({
+            root: newTree,
+            metadata: payload.metadata!,
+          });
+        });
+      } else {
+        onUpdate({
+          root: newTree,
+          metadata: payload.metadata!,
+        });
+      }
+
+      return;
+    }
+  }
+
+  return fetchPartialUpdate;
+}
+
+export { createPartialUpdater as default };

package/src/browser/prefetch/cache.ts

@@ -0,0 +1,146 @@
+/**
+ * Prefetch Cache
+ *
+ * In-memory cache storing prefetch 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.
+ *
+ * Replaces the previous browser HTTP cache approach which was unreliable
+ * due to response draining race conditions and browser inconsistencies.
+ */
+
+import { cancelAllPrefetches } from "./queue.js";
+import { invalidateRangoState } from "../rango-state.js";
+
+// Default TTL: 5 minutes. Overridden by initPrefetchCache() with
+// the server-configured prefetchCacheTTL from router options.
+// 0 disables the in-memory cache entirely.
+let cacheTTL = 300_000;
+
+/**
+ * Initialize the prefetch cache with the configured TTL.
+ * Called once at app startup with the value from server metadata.
+ * A TTL of 0 disables the in-memory cache.
+ */
+export function initPrefetchCache(ttlMs: number): void {
+  cacheTTL = ttlMs;
+}
+const MAX_PREFETCH_CACHE_SIZE = 50;
+
+interface PrefetchCacheEntry {
+  response: Response;
+  timestamp: number;
+}
+
+const cache = new Map<string, PrefetchCacheEntry>();
+const inflight = new Set<string>();
+
+// Generation counter incremented on each clearPrefetchCache(). Fetches that
+// started before a clear carry a stale generation and must not store their
+// response (the data may be stale due to a server action invalidation).
+let generation = 0;
+
+/**
+ * Build a source-dependent cache key.
+ * Includes the source page href so the same target prefetched from
+ * different pages gets separate entries — the server response varies
+ * based on the source page context (diff-based rendering).
+ */
+export function buildPrefetchKey(sourceHref: string, targetUrl: URL): string {
+  return sourceHref + "\0" + targetUrl.pathname + targetUrl.search;
+}
+
+/**
+ * Check if a prefetch is already cached, in-flight, or queued for the given key.
+ */
+export function hasPrefetch(key: string): boolean {
+  if (inflight.has(key)) return true;
+  if (cacheTTL <= 0) return false;
+  const entry = cache.get(key);
+  if (!entry) return false;
+  if (Date.now() - entry.timestamp > cacheTTL) {
+    cache.delete(key);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Consume a cached prefetch response. Returns null if not found or expired.
+ * One-time consumption: the entry is deleted after retrieval.
+ * Returns null when caching is disabled (TTL <= 0).
+ */
+export function consumePrefetch(key: string): Response | null {
+  if (cacheTTL <= 0) return null;
+  const entry = cache.get(key);
+  if (!entry) return null;
+  if (Date.now() - entry.timestamp > cacheTTL) {
+    cache.delete(key);
+    return null;
+  }
+  cache.delete(key);
+  return entry.response;
+}
+
+/**
+ * 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.
+ *
+ * Skips storage if the generation has changed since the fetch started
+ * (a server action invalidated the cache mid-flight).
+ */
+export function storePrefetch(
+  key: string,
+  response: Response,
+  fetchGeneration: number,
+): void {
+  if (cacheTTL <= 0) return;
+  if (fetchGeneration !== generation) return;
+
+  // Evict expired entries
+  const now = Date.now();
+  for (const [k, entry] of cache) {
+    if (now - entry.timestamp > cacheTTL) {
+      cache.delete(k);
+    }
+  }
+
+  // FIFO eviction if at capacity
+  if (cache.size >= MAX_PREFETCH_CACHE_SIZE) {
+    const oldest = cache.keys().next().value;
+    if (oldest) cache.delete(oldest);
+  }
+
+  cache.set(key, { response, timestamp: now });
+}
+
+/**
+ * Capture the current generation. The returned value is passed to
+ * storePrefetch so it can detect stale completions.
+ */
+export function currentGeneration(): number {
+  return generation;
+}
+
+export function markPrefetchInflight(key: string): void {
+  inflight.add(key);
+}
+
+export function clearPrefetchInflight(key: string): void {
+  inflight.delete(key);
+}
+
+/**
+ * Invalidate all prefetch state. Called when server actions mutate data.
+ * Clears the in-memory cache, cancels in-flight prefetches, and rotates
+ * the Rango state key so CDN-cached responses are also invalidated.
+ */
+export function clearPrefetchCache(): void {
+  generation++;
+  inflight.clear();
+  cache.clear();
+  cancelAllPrefetches();
+  invalidateRangoState();
+}