@rangojs/router 0.0.0-experimental.54 → 0.0.0-experimental.55

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.54",
+  version: "0.0.0-experimental.55",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.54",
+  "version": "0.0.0-experimental.55",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/src/browser/app-version.ts

@@ -0,0 +1,14 @@
+/**
+ * Mutable app version — updated after HMR revalidation.
+ * Read by prefetch, navigation, and context code.
+ */
+
+let currentVersion: string | undefined;
+
+export function getAppVersion(): string | undefined {
+  return currentVersion;
+}
+
+export function setAppVersion(version: string | undefined): void {
+  currentVersion = version;
+}

package/src/browser/navigation-bridge.ts

@@ -4,6 +4,7 @@ import type {
   NavigateOptionsInternal,
   ResolvedSegment,
 } from "./types.js";
+import { setAppVersion } from "./app-version.js";
 import * as React from "react";
 import { startTransition } from "react";
 import {
@@ -67,8 +68,8 @@ export interface NavigationBridgeConfigWithController extends NavigationBridgeCo
 export function createNavigationBridge(
   config: NavigationBridgeConfigWithController,
 ): NavigationBridge {
-  const { store, client, eventController, onUpdate, renderSegments, version } =
-    config;
+  const { store, client, eventController, onUpdate, renderSegments } = config;
+  let version = config.version;
 
   // Create shared partial updater
   const fetchPartialUpdate = createPartialUpdater({
@@ -76,7 +77,7 @@ export function createNavigationBridge(
     client,
     onUpdate,
     renderSegments,
-    version,
+    getVersion: () => version,
   });
 
   return {
@@ -632,6 +633,12 @@ export function createNavigationBridge(
         window.removeEventListener("pageshow", handlePageShow);
       };
     },
+
+    updateVersion(newVersion: string): void {
+      version = newVersion;
+      setAppVersion(newVersion);
+      store.clearHistoryCache();
+    },
   };
 }
 

package/src/browser/navigation-client.ts

@@ -107,6 +107,54 @@ export function createNavigationClient(
         resolveStreamComplete = resolve;
       });
 
+      /**
+       * Validate RSC control headers on any response (fresh, cached, or
+       * in-flight). Handles version-mismatch reloads and server redirects.
+       * Returns the response unchanged when no control header is present.
+       */
+      const validateRscHeaders = (
+        response: Response,
+        source: string,
+      ): Response | Promise<Response> => {
+        // Version mismatch — server wants a full page reload
+        const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
+        if (reload === "blocked") {
+          resolveStreamComplete();
+          return emptyResponse();
+        }
+        if (reload) {
+          if (tx) {
+            browserDebugLog(tx, `version mismatch, reloading (${source})`, {
+              reloadUrl: reload.url,
+            });
+          }
+          window.location.href = reload.url;
+          // Block further processing — page is reloading
+          return new Promise<Response>(() => {});
+        }
+
+        // Server-side redirect without state: the server returned 204 with
+        // X-RSC-Redirect instead of a 3xx (which fetch would auto-follow
+        // to a URL rendering full HTML). Throw ServerRedirect so the
+        // navigation bridge catches it and re-navigates with _skipCache.
+        const redirect = extractRscHeaderUrl(response, "X-RSC-Redirect");
+        if (redirect === "blocked") {
+          resolveStreamComplete();
+          return emptyResponse();
+        }
+        if (redirect) {
+          if (tx) {
+            browserDebugLog(tx, `server redirect (${source})`, {
+              redirectUrl: redirect.url,
+            });
+          }
+          resolveStreamComplete();
+          throw new ServerRedirect(redirect.url, undefined);
+        }
+
+        return response;
+      };
+
       /** Start a fresh navigation fetch (no cache / inflight hit). */
       const doFreshFetch = (): Promise<Response> => {
         if (tx) {
@@ -127,43 +175,11 @@ export function createNavigationClient(
           },
           signal,
         }).then((response) => {
-          // Check for version mismatch - server wants us to reload
-          const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
-          if (reload === "blocked") {
-            resolveStreamComplete();
-            return emptyResponse();
-          }
-          if (reload) {
-            if (tx) {
-              browserDebugLog(tx, "version mismatch, reloading", {
-                reloadUrl: reload.url,
-              });
-            }
-            window.location.href = reload.url;
-            return new Promise<Response>(() => {});
-          }
-
-          // Server-side redirect without state: the server returned 204 with
-          // X-RSC-Redirect instead of a 3xx (which fetch would auto-follow
-          // to a URL rendering full HTML). Throw ServerRedirect so the
-          // navigation bridge catches it and re-navigates with _skipCache.
-          const redirect = extractRscHeaderUrl(response, "X-RSC-Redirect");
-          if (redirect === "blocked") {
-            resolveStreamComplete();
-            return emptyResponse();
-          }
-          if (redirect) {
-            if (tx) {
-              browserDebugLog(tx, "server redirect", {
-                redirectUrl: redirect.url,
-              });
-            }
-            resolveStreamComplete();
-            throw new ServerRedirect(redirect.url, undefined);
-          }
+          const validated = validateRscHeaders(response, "fetch");
+          if (validated instanceof Promise) return validated;
 
           return teeWithCompletion(
-            response,
+            validated,
             () => {
               if (tx) browserDebugLog(tx, "stream complete");
               resolveStreamComplete();
@@ -179,11 +195,12 @@ export function createNavigationClient(
         if (tx) {
           browserDebugLog(tx, "prefetch cache hit", { key: cacheKey });
         }
-        // Cached response body is already fully buffered (arrayBuffer),
-        // so stream completion is immediate.
         responsePromise = Promise.resolve(cachedResponse).then((response) => {
+          const validated = validateRscHeaders(response, "prefetch cache");
+          if (validated instanceof Promise) return validated;
+
           return teeWithCompletion(
-            response,
+            validated,
             () => {
               if (tx) browserDebugLog(tx, "stream complete (from cache)");
               resolveStreamComplete();
@@ -203,8 +220,11 @@ export function createNavigationClient(
             return doFreshFetch();
           }
 
+          const validated = validateRscHeaders(response, "inflight prefetch");
+          if (validated instanceof Promise) return validated;
+
           return teeWithCompletion(
-            response,
+            validated,
             () => {
               if (tx) {
                 browserDebugLog(tx, "stream complete (from inflight prefetch)");

package/src/browser/partial-update.ts

@@ -39,8 +39,8 @@ export interface PartialUpdateConfig {
     segments: ResolvedSegment[],
     options?: RenderSegmentsOptions,
   ) => Promise<ReactNode> | ReactNode;
-  /** RSC version received from server (from initial payload metadata) */
-  version?: string;
+  /** RSC version getter — returns the current version (may change after HMR) */
+  getVersion?: () => string | undefined;
 }
 
 /**
@@ -104,7 +104,13 @@ export type PartialUpdater = (
 export function createPartialUpdater(
   config: PartialUpdateConfig,
 ): PartialUpdater {
-  const { store, client, onUpdate, renderSegments, version } = config;
+  const {
+    store,
+    client,
+    onUpdate,
+    renderSegments,
+    getVersion = () => undefined,
+  } = config;
 
   /**
    * Get current page's cached segments as an array
@@ -193,7 +199,7 @@ export function createPartialUpdater(
       // (action redirect sends empty segments for a fresh render).
       staleRevalidation:
         mode.type === "stale-revalidation" || segments.length === 0,
-      version,
+      version: getVersion(),
     });
     // Mark navigation as streaming (response received, now parsing RSC).
     // Called after fetchPartial so pendingUrl stays set during the network wait,

package/src/browser/react/Link.tsx

@@ -32,6 +32,7 @@ export type LinkState =
   | StateOrGetter<Record<string, unknown>>;
 
 import { prefetchDirect, prefetchQueued } from "../prefetch/fetch.js";
+import { getAppVersion } from "../app-version.js";
 import {
   observeForPrefetch,
   unobserveForPrefetch,
@@ -289,7 +290,7 @@ export const Link: ForwardRefExoticComponent<
       // prefetch — prefetchDirect bypasses the queue, and hasPrefetch
       // deduplicates if the viewport prefetch already completed.
       const segmentState = ctx.store.getSegmentState();
-      prefetchDirect(to, segmentState.currentSegmentIds, ctx.version);
+      prefetchDirect(to, segmentState.currentSegmentIds, getAppVersion());
     }
   }, [resolvedStrategy, to, isExternal, ctx]);
 
@@ -308,7 +309,7 @@ export const Link: ForwardRefExoticComponent<
     const triggerPrefetch = () => {
       if (cancelled) return;
       const segmentState = ctx.store.getSegmentState();
-      prefetchQueued(to, segmentState.currentSegmentIds, ctx.version);
+      prefetchQueued(to, segmentState.currentSegmentIds, getAppVersion());
     };
 
     // Schedule prefetch only when the app is idle (no navigation/streaming).

package/src/browser/react/NavigationProvider.tsx

@@ -134,7 +134,7 @@ export interface NavigationProviderProps {
 
   /**
    * App version from server payload (stable, immutable).
-   * Forwarded to prefetch requests for version mismatch detection.
+   * Forwarded to context for cache key building.
    */
   version?: string;
 }

package/src/browser/react/context.ts

@@ -43,8 +43,7 @@ export interface NavigationStoreContextValue {
   refresh: () => Promise<void>;
 
   /**
-   * App version from server payload (stable, immutable).
-   * Used in prefetch requests for version mismatch detection.
+   * App version from the initial server payload.
    */
   version: string | undefined;
 }

package/src/browser/react/use-router.ts

@@ -3,6 +3,7 @@
 import { useContext, useMemo } from "react";
 import { NavigationStoreContext } from "./context.js";
 import { prefetchDirect } from "../prefetch/fetch.js";
+import { getAppVersion } from "../app-version.js";
 import type { RouterInstance, RouterNavigateOptions } from "../types.js";
 
 /**
@@ -46,7 +47,7 @@ export function useRouter(): RouterInstance {
       prefetch(url: string): void {
         const segmentState = ctx.store?.getSegmentState();
         if (segmentState) {
-          prefetchDirect(url, segmentState.currentSegmentIds, ctx.version);
+          prefetchDirect(url, segmentState.currentSegmentIds, getAppVersion());
         }
       },
 

package/src/browser/rsc-router.tsx

@@ -23,6 +23,7 @@ import type { EventController } from "./event-controller.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 import { initRangoState } from "./rango-state.js";
 import { initPrefetchCache } from "./prefetch/cache.js";
+import { setAppVersion } from "./app-version.js";
 import {
   isInterceptSegment,
   splitInterceptSegments,
@@ -204,6 +205,7 @@ export async function initBrowserApp(
   // Initialize the localStorage state key for cache invalidation.
   // Uses the build version so a new deploy automatically busts all cached prefetches.
   initRangoState(version ?? "0");
+  setAppVersion(version);
 
   // Initialize the in-memory prefetch cache TTL from server config.
   // A value of 0 disables the cache; undefined falls back to the module default.
@@ -230,7 +232,6 @@ export async function initBrowserApp(
     deps,
     onUpdate: (update) => store.emitUpdate(update),
     renderSegments,
-    version,
     onNavigate: (url, options) => {
       if (!navigateFn) {
         window.location.href = url;
@@ -248,7 +249,7 @@ export async function initBrowserApp(
     client,
     onUpdate: (update) => store.emitUpdate(update),
     renderSegments,
-    version,
+    version: version,
   });
 
   // Connect action redirect → navigation bridge (now that both are initialized)
@@ -328,6 +329,21 @@ export async function initBrowserApp(
             throw new Error("HMR refetch returned invalid payload");
           }
 
+          // Update version BEFORE rebuilding state so that
+          // clearHistoryCache() runs first, then the fresh segment
+          // cache entry we create below survives.
+          const newVersion = payload.metadata.version;
+          if (newVersion && newVersion !== version) {
+            console.log(
+              "[RSCRouter] HMR: version changed",
+              version,
+              "→",
+              newVersion,
+              "clearing caches",
+            );
+            navigationBridge.updateVersion(newVersion);
+          }
+
           if (payload.metadata?.isPartial) {
             const segments = payload.metadata.segments || [];
             const matched = payload.metadata.matched || [];

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

@@ -29,6 +29,7 @@ import {
 } from "./response-adapter.js";
 import { mergeLocationState } from "./history-state.js";
 import { classifyActionOutcome } from "./action-coordinator.js";
+import { getAppVersion } from "./app-version.js";
 
 // Polyfill Symbol.dispose/asyncDispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -43,8 +44,6 @@ if (typeof Symbol.asyncDispose === "undefined") {
  */
 export interface ServerActionBridgeConfigWithController extends ServerActionBridgeConfig {
   eventController: EventController;
-  /** RSC version from initial payload metadata */
-  version?: string;
   /** Callback to trigger SPA navigation (for action redirects) */
   onNavigate?: (
     url: string,
@@ -75,7 +74,6 @@ export function createServerActionBridge(
     deps,
     onUpdate,
     renderSegments,
-    version,
     onNavigate,
   } = config;
 
@@ -86,7 +84,7 @@ export function createServerActionBridge(
     client,
     onUpdate,
     renderSegments,
-    version,
+    getVersion: getAppVersion,
   });
 
   /**
@@ -165,6 +163,7 @@ export function createServerActionBridge(
         segmentState.currentSegmentIds.join(","),
       );
       // Add version param for version mismatch detection
+      const version = getAppVersion();
       if (version) {
         url.searchParams.set("_rsc_v", version);
       }

package/src/browser/types.ts

@@ -526,6 +526,8 @@ export interface NavigationBridge {
   refresh(): Promise<void>;
   handlePopstate(): Promise<void>;
   registerLinkInterception(): () => void;
+  /** Update the RSC version (e.g. after HMR). Clears prefetch cache. */
+  updateVersion(newVersion: string): void;
 }
 
 /**

package/src/router/match-middleware/cache-lookup.ts

@@ -316,7 +316,10 @@ export function withCacheLookup<TEnv>(
 
     // Prerender lookup: check build-time cached data before runtime cache.
     // Prerender data is available regardless of runtime cache configuration.
-    if (!ctx.isAction && ctx.matched.pr) {
+    // Skip for HMR requests — the dev prerender endpoint reads from a stale
+    // RouterRegistry snapshot; rendering fresh ensures edits are visible.
+    const isHmr = !!ctx.request.headers.get("X-RSC-HMR");
+    if (!ctx.isAction && !isHmr && ctx.matched.pr) {
       await ensurePrerenderDeps();
       if (prerenderStoreInstance) {
         const paramHash = _hashParams!(ctx.matched.params);