@rangojs/router 0.0.0-experimental.32 → 0.0.0-experimental.3232cd17

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

@@ -25,15 +25,18 @@ function parsePathname(pathname: string): string[] {
 }
 
 /**
- * Build segments state from event controller
+ * Build segments state from event controller. `segmentIds` is the
+ * route-only list (parallels and loaders stripped) — distinct from the
+ * controller's `segmentOrder` which drives handle collection and includes
+ * parallel slot ids.
  */
 function buildSegmentsState(
   location: URL,
-  segmentOrder: string[],
+  routeSegmentIds: string[],
 ): SegmentsState {
   return {
     path: parsePathname(location.pathname),
-    segmentIds: segmentOrder,
+    segmentIds: routeSegmentIds,
     location,
   };
 }
@@ -74,7 +77,7 @@ export function useSegments<T>(
     const handleState = ctx.eventController.getHandleState();
     const segmentsState = buildSegmentsState(
       location as URL,
-      handleState.segmentOrder,
+      handleState.routeSegmentIds,
     );
     return selector ? selector(segmentsState) : segmentsState;
   });
@@ -83,47 +86,36 @@ export function useSegments<T>(
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 
-  // Track selector identity to detect when the selector function changes.
-  // Only then do we eagerly recompute during render to avoid staleness.
-  // Without this guard, no-selector mode causes infinite re-renders because
-  // buildSegmentsState creates fresh arrays that fail Object.is checks.
   const prevSelectorIdentity = useRef(selector);
 
-  // Cache SegmentsState to stabilize nested references (path, segmentIds
-  // arrays) so selectors returning composite values don't cause spurious
-  // render-time setState calls.
   const segmentsCache = useRef<{
     location: URL;
-    segmentOrder: string[];
+    routeSegmentIds: string[];
     state: SegmentsState;
   } | null>(null);
 
-  // Recompute selected value from current store state and apply selector.
-  // Shared by the render-time eager check and the subscription callback.
   function recompute(
     sel: ((state: SegmentsState) => T) | undefined,
   ): T | SegmentsState {
     const location = ctx!.eventController.getLocation();
     const handleState = ctx!.eventController.getHandleState();
 
-    // Reuse cached state when inputs haven't changed by reference,
-    // keeping array/object references stable for composite selectors.
     const cache = segmentsCache.current;
     let segmentsState: SegmentsState;
     if (
       cache &&
       cache.location === location &&
-      cache.segmentOrder === handleState.segmentOrder
+      cache.routeSegmentIds === handleState.routeSegmentIds
     ) {
       segmentsState = cache.state;
     } else {
       segmentsState = buildSegmentsState(
         location as URL,
-        handleState.segmentOrder,
+        handleState.routeSegmentIds,
       );
       segmentsCache.current = {
         location: location as URL,
-        segmentOrder: handleState.segmentOrder,
+        routeSegmentIds: handleState.routeSegmentIds,
         state: segmentsState,
       };
     }
@@ -162,8 +154,6 @@ export function useSegments<T>(
       unsubscribeNav();
       unsubscribeHandles();
     };
-    // Stable subscription: selector changes are handled via selectorRef,
-    // state comparison uses prevState ref. No re-subscribe needed.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 

package/src/browser/response-adapter.ts

@@ -24,6 +24,51 @@ export function emptyResponse(): Response {
   return new Response(null, { status: 200 });
 }
 
+/**
+ * Whether an RSC content response carries a server-stamped router identity
+ * (`X-RSC-Router-Id`) that DIFFERS from the id this client expects (its own
+ * routerId, also sent as `_rsc_rid`). Pre-decode integrity check: lets a caller
+ * refuse a foreign app's payload before `createFromFetch` imports its chunks.
+ *
+ * True ONLY when both the header and the expected id are present and differ. An
+ * absent header (control-only reload/redirect responses are not stamped) or an
+ * absent expected id (e.g. before the client is seeded) is a pass-through —
+ * never a false reject.
+ */
+export function isForeignRouterId(
+  response: Response,
+  expectedId: string | undefined,
+): boolean {
+  const got = response.headers.get("X-RSC-Router-Id");
+  if (!got || !expectedId) return false;
+  return got !== expectedId;
+}
+
+/**
+ * Handle the X-RSC-Reload control header (server requests a full page reload on
+ * a version mismatch). Returns a short-circuit response when the header is
+ * present -- emptyResponse() if the URL was blocked by origin validation, or a
+ * never-resolving promise while the page reloads -- and null when absent, so
+ * the caller continues processing (e.g. the X-RSC-Redirect check). Scoped to
+ * X-RSC-Reload only; redirect handling differs between callers.
+ */
+export function handleReloadHeader(
+  response: Response,
+  opts: { onBlocked: () => void; onReload: (url: string) => void },
+): Response | Promise<Response> | null {
+  const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
+  if (reload === "blocked") {
+    opts.onBlocked();
+    return emptyResponse();
+  }
+  if (reload) {
+    opts.onReload(reload.url);
+    window.location.href = reload.url;
+    return new Promise<Response>(() => {});
+  }
+  return null;
+}
+
 /**
  * Tee a response body for RSC parsing and stream completion tracking.
  * Returns a new Response with one branch; the other is consumed to detect
@@ -31,11 +76,17 @@ export function emptyResponse(): Response {
  *
  * If the response has no body, onComplete fires synchronously.
  * If signal is provided, an abort cancels the tracking reader.
+ *
+ * `silent` suppresses the stream-error log. Prefetch passes it: a speculative,
+ * low-priority prefetch that is aborted or never consumed can error its stream
+ * benignly, which is not worth surfacing. The fresh-navigation path keeps the
+ * log (default), where a stream error reflects a real failed navigation.
  */
 export function teeWithCompletion(
   response: Response,
   onComplete: () => void,
   signal?: AbortSignal,
+  silent = false,
 ): Response {
   if (!response.body) {
     onComplete();
@@ -59,7 +110,7 @@ export function teeWithCompletion(
       onComplete();
     }
   })().catch((error) => {
-    if (!signal?.aborted) {
+    if (!silent && !signal?.aborted) {
       console.error("[Browser] Error reading tracking stream:", error);
     }
     onComplete();

package/src/browser/rsc-router.tsx

@@ -8,6 +8,7 @@ import {
   generateHistoryKey,
 } from "./navigation-store.js";
 import { createEventController } from "./event-controller.js";
+import { validateRedirectOrigin } from "./validate-redirect-origin.js";
 import { createNavigationClient } from "./navigation-client.js";
 import { createServerActionBridge } from "./server-action-bridge.js";
 import { createNavigationBridge } from "./navigation-bridge.js";
@@ -22,11 +23,15 @@ import type {
 import type { EventController } from "./event-controller.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 import { initRangoState } from "./rango-state.js";
+import { registerNavigationStore } from "./navigation-store-handle.js";
 import { initPrefetchCache } from "./prefetch/cache.js";
+import { setPrefetchDecoder } from "./prefetch/fetch.js";
+import { setAppVersion } from "./app-version.js";
 import {
   isInterceptSegment,
   splitInterceptSegments,
 } from "./intercept-utils.js";
+import { createAppShellRef } from "./app-shell.js";
 
 // Vite HMR types are provided by vite/client
 
@@ -113,13 +118,22 @@ export interface BrowserAppContext {
   warmupEnabled?: boolean;
   /** App version for prefetch version mismatch detection */
   version?: string;
+  /**
+   * App-shell ref, read through on each render so renderSegments and the
+   * NavigationProvider see rootLayout/basename/version without closing over a
+   * stale snapshot. Set once from the initial payload and not swapped within a
+   * session: a cross-app navigation is a full document load (X-RSC-Reload), so
+   * the target app establishes its own shell on load. Theme, warmup, and
+   * prefetch TTL are document-lifetime too (see AppShell).
+   */
+  appShellRef?: import("./app-shell.js").AppShellRef;
 }
 
 // Module-level state for the initialized app
 let browserAppContext: BrowserAppContext | null = null;
 
 /**
- * Initialize the browser app. Must be called before rendering RSCRouter.
+ * Initialize the browser app. Must be called before rendering Rango.
  *
  * This function:
  * - Loads the initial RSC payload from the stream
@@ -139,7 +153,6 @@ export async function initBrowserApp(
     initialTheme,
   } = options;
 
-  // Load initial payload from SSR-injected __FLIGHT_DATA__
   const initialPayload =
     await deps.createFromReadableStream<RscPayload>(rscStream);
 
@@ -164,6 +177,18 @@ export async function initBrowserApp(
     ...(storeOptions?.cacheSize && { cacheSize: storeOptions.cacheSize }),
   });
 
+  // Register the active store on the module-level handle and wire the
+  // jar-divergence observer before any getRangoState() read can detect a
+  // cross-tab/server rotation. There is no global store singleton, so this
+  // handle is the live reference.
+  registerNavigationStore(store);
+
+  // Seed router identity from the initial SSR payload so the first
+  // cross-app SPA navigation can detect the app switch.
+  if (initialPayload.metadata?.routerId) {
+    store.setRouterId?.(initialPayload.metadata.routerId);
+  }
+
   // Create event controller for reactive state management
   const eventController = createEventController({
     initialLocation: new URL(window.location.href),
@@ -198,13 +223,25 @@ export async function initBrowserApp(
   // Create composable utilities
   const client = createNavigationClient(deps);
 
-  // Extract rootLayout and version from metadata for browser-side re-renders
-  const rootLayout = initialPayload.metadata?.rootLayout;
+  // Capture the per-router app-shell. rootLayout, basename, and version live
+  // here and are read through the ref at call time rather than closed over.
+  // It is set once from the initial payload and not swapped within a session:
+  // a cross-app navigation is a full document load (X-RSC-Reload), so the
+  // target app establishes its own shell on load.
   const version = initialPayload.metadata?.version;
+  const appShellRef = createAppShellRef({
+    routerId: initialPayload.metadata?.routerId,
+    rootLayout: initialPayload.metadata?.rootLayout,
+    basename: initialPayload.metadata?.basename,
+    version,
+  });
 
-  // Initialize the localStorage state key for cache invalidation.
-  // Uses the build version so a new deploy automatically busts all cached prefetches.
-  initRangoState(version ?? "0");
+  // Initialize the rango state cookie for cache invalidation. The build version
+  // busts cached prefetches on deploy; the server-resolved cookie name
+  // namespaces the cookie so sibling apps on the same origin don't collide
+  // (falls back to the bare default prefix if metadata lacks the name).
+  initRangoState(version ?? "0", initialPayload.metadata?.stateCookieName);
+  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.
@@ -213,11 +250,22 @@ export async function initBrowserApp(
     initPrefetchCache(prefetchCacheTTL);
   }
 
-  // Create a bound renderSegments that includes rootLayout
+  // Wire the RSC decoder so prefetches decode eagerly and warm the route's
+  // client chunks (same createFromFetch the navigation client uses).
+  setPrefetchDecoder((response) => deps.createFromFetch<RscPayload>(response));
+
+  // Create a bound renderSegments that reads rootLayout through the shell ref.
+  // The shell is set once at init and not swapped within a session (a cross-app
+  // navigation is a full document load), so this always renders this app's
+  // Document; reading through the ref just avoids closing over a stale value.
   const renderSegments = (
     segments: ResolvedSegment[],
     options?: RenderSegmentsOptions,
-  ) => baseRenderSegments(segments, { ...options, rootLayout });
+  ) =>
+    baseRenderSegments(segments, {
+      ...options,
+      rootLayout: appShellRef.get().rootLayout,
+    });
 
   // Lazy reference for navigation bridge — the action bridge is created first
   // but may need to trigger SPA navigation for action redirects.
@@ -231,10 +279,15 @@ export async function initBrowserApp(
     deps,
     onUpdate: (update) => store.emitUpdate(update),
     renderSegments,
-    version,
     onNavigate: (url, options) => {
       if (!navigateFn) {
-        window.location.href = url;
+        // Navigation bridge not wired yet: hard-navigate, but re-validate
+        // same-origin defensively so this init-window fallback cannot become an
+        // open redirect (the normal path validates inside the navigation bridge).
+        const safe = validateRedirectOrigin(url, window.location.origin);
+        if (safe) {
+          window.location.href = safe;
+        }
         return Promise.resolve();
       }
       return navigateFn(url, options);
@@ -249,7 +302,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)
@@ -263,75 +316,157 @@ export async function initBrowserApp(
   // Build initial tree with rootLayout
   const initialTree = renderSegments(initialPayload.metadata!.segments);
 
-  // Setup HMR
+  // Setup HMR with debounce — burst saves (format-on-save, rapid edits)
+  // fire many rsc:update events in quick succession. Without debouncing,
+  // each event triggers a fetchPartial() which on slow routes can pile up
+  // and overwhelm the worker (cross-request promise issues, 500s).
   if (import.meta.hot) {
-    import.meta.hot.on("rsc:update", async () => {
-      console.log("[RSCRouter] HMR: Server update, refetching RSC");
-
-      const handle = eventController.startNavigation(window.location.href, {
-        replace: true,
-      });
-      const streamingToken = handle.startStreaming();
-
-      const interceptSourceUrl = store.getInterceptSourceUrl();
-
-      try {
-        const { payload, streamComplete } = await client.fetchPartial({
-          targetUrl: window.location.href,
-          segmentIds: [],
-          previousUrl: store.getSegmentState().currentUrl,
-          interceptSourceUrl: interceptSourceUrl || undefined,
-          hmr: true,
+    let hmrTimer: ReturnType<typeof setTimeout> | null = null;
+    let hmrAbort: AbortController | null = null;
+
+    import.meta.hot.on("rsc:update", () => {
+      // Cancel any pending debounce timer
+      if (hmrTimer !== null) {
+        clearTimeout(hmrTimer);
+      }
+
+      // Abort any in-flight HMR fetch so it doesn't race with the next one
+      if (hmrAbort) {
+        hmrAbort.abort();
+        hmrAbort = null;
+      }
+
+      // Debounce: wait 200ms of quiet before fetching
+      hmrTimer = setTimeout(async () => {
+        hmrTimer = null;
+
+        // Don't interrupt an active user navigation — startNavigation()
+        // would abort it and refetch the old URL (window.location.href
+        // hasn't updated yet). The user's navigation will pick up the
+        // new server code when it completes. isNavigating covers the
+        // full lifecycle (fetching + streaming, before commit) without
+        // blocking on server actions.
+        if (eventController.getState().isNavigating) {
+          console.log("[Rango] HMR: Skipping — navigation in progress");
+          return;
+        }
+
+        console.log("[Rango] HMR: Server update, refetching RSC");
+
+        const abort = new AbortController();
+        hmrAbort = abort;
+
+        const handle = eventController.startNavigation(window.location.href, {
+          replace: true,
         });
+        const streamingToken = handle.startStreaming();
+
+        const interceptSourceUrl = store.getInterceptSourceUrl();
+
+        try {
+          const { payload, streamComplete } = await client.fetchPartial({
+            targetUrl: window.location.href,
+            segmentIds: [],
+            previousUrl: store.getSegmentState().currentUrl,
+            interceptSourceUrl: interceptSourceUrl || undefined,
+            routerId: store.getRouterId?.(),
+            hmr: true,
+            signal: abort.signal,
+          });
 
-        if (payload.metadata?.isPartial) {
-          const segments = payload.metadata.segments || [];
-          const matched = payload.metadata.matched || [];
+          if (abort.signal.aborted) return;
 
-          // Derive intercept state from the returned payload, not the
-          // pre-fetch store snapshot. If the HMR edit removed intercept
-          // behavior, the response won't contain intercept segments.
-          const responseIsIntercept = segments.some(isInterceptSegment);
+          // If the server returned a non-RSC response (404, 500 without
+          // error boundary), the payload won't have valid metadata.
+          // Reload to recover rather than leaving the page stale.
+          if (!payload.metadata) {
+            throw new Error("HMR refetch returned invalid payload");
+          }
 
-          // Sync store intercept state with what the server returned
-          if (!responseIsIntercept && interceptSourceUrl) {
-            store.setInterceptSourceUrl(null);
+          // Update version BEFORE rebuilding state so that
+          // clearHistoryCache() runs first, then the fresh segment
+          // cache entry we create below survives.
+          //
+          // Compare against the bridge's live version, not the init-time
+          // `version` const: after the first HMR bump the const is stale, so a
+          // later update with an unchanged version would otherwise re-clear the
+          // cache and re-broadcast across tabs/apps. The live read fires only
+          // on a genuine version change.
+          const newVersion = payload.metadata.version;
+          const currentVersion = navigationBridge.getVersion();
+          if (newVersion && newVersion !== currentVersion) {
+            console.log(
+              "[Rango] HMR: version changed",
+              currentVersion,
+              "→",
+              newVersion,
+              "clearing caches",
+            );
+            navigationBridge.updateVersion(newVersion);
           }
 
-          store.setSegmentIds(matched);
-          store.setCurrentUrl(window.location.href);
+          // Apply only partial segment updates. A non-partial payload during
+          // HMR is transient: the worker route table is still rebuilding after
+          // the edit, so the URL momentarily resolves to not-found/catch-all.
+          // Skip it -- the debounced follow-up refetch returns the settled
+          // route's partial payload and renders it below. We never reload here:
+          // a paramless document GET would run the SSR path and surface the
+          // not-found page during that same transient.
+          if (payload.metadata?.isPartial) {
+            const segments = payload.metadata.segments || [];
+            const matched = payload.metadata.matched || [];
+
+            // Derive intercept state from the returned payload, not the
+            // pre-fetch store snapshot. If the HMR edit removed intercept
+            // behavior, the response won't contain intercept segments.
+            const responseIsIntercept = segments.some(isInterceptSegment);
+
+            // Sync store intercept state with what the server returned
+            if (!responseIsIntercept && interceptSourceUrl) {
+              store.setInterceptSourceUrl(null);
+            }
+
+            store.setSegmentIds(matched);
+            store.setCurrentUrl(window.location.href);
+
+            const historyKey = generateHistoryKey(window.location.href, {
+              intercept: responseIsIntercept,
+            });
+            store.setHistoryKey(historyKey);
+            const currentHandleData = eventController.getHandleState().data;
+            store.cacheSegmentsForHistory(
+              historyKey,
+              segments,
+              currentHandleData,
+            );
+
+            const { main, intercept } = splitInterceptSegments(segments);
+            store.emitUpdate({
+              root: renderSegments(main, {
+                interceptSegments: intercept.length > 0 ? intercept : undefined,
+              }),
+              metadata: payload.metadata,
+            });
+          }
 
-          const historyKey = generateHistoryKey(window.location.href, {
-            intercept: responseIsIntercept,
-          });
-          store.setHistoryKey(historyKey);
-          const currentHandleData = eventController.getHandleState().data;
-          store.cacheSegmentsForHistory(
-            historyKey,
-            segments,
-            currentHandleData,
-          );
-
-          const { main, intercept } = splitInterceptSegments(segments);
-          store.emitUpdate({
-            root: renderSegments(main, {
-              interceptSegments: intercept.length > 0 ? intercept : undefined,
-            }),
-            metadata: payload.metadata,
-          });
+          await streamComplete;
+          handle.complete(new URL(window.location.href));
+          console.log("[Rango] HMR: RSC stream complete");
+        } catch (err) {
+          if (abort.signal.aborted) return;
+          console.warn("[Rango] HMR: Refetch failed, reloading page", err);
+          window.location.reload();
+          return;
+        } finally {
+          if (hmrAbort === abort) hmrAbort = null;
+          streamingToken.end();
+          handle[Symbol.dispose]();
         }
-
-        await streamComplete;
-        handle.complete(new URL(window.location.href));
-        console.log("[RSCRouter] HMR: RSC stream complete");
-      } finally {
-        streamingToken.end();
-        handle[Symbol.dispose]();
-      }
+      }, 200);
     });
   }
 
-  // Store context for RSCRouter component
+  // Store context for Rango component
   const context: BrowserAppContext = {
     store,
     eventController,
@@ -342,6 +477,7 @@ export async function initBrowserApp(
     initialTheme: effectiveInitialTheme,
     warmupEnabled: initialPayload.metadata?.warmupEnabled ?? true,
     version,
+    appShellRef,
   };
   browserAppContext = context;
 
@@ -354,7 +490,7 @@ export async function initBrowserApp(
 export function getBrowserAppContext(): BrowserAppContext {
   if (!browserAppContext) {
     throw new Error(
-      "RSCRouter: initBrowserApp() must be called before rendering RSCRouter",
+      "Rango: initBrowserApp() must be called before rendering Rango",
     );
   }
   return browserAppContext;
@@ -368,18 +504,18 @@ export function resetBrowserAppContext(): void {
 }
 
 /**
- * Props for the RSCRouter component
+ * Props for the Rango component
  */
-export interface RSCRouterProps {}
+export interface RangoProps {}
 
 /**
- * RSCRouter component - renders the RSC router with all internal wiring.
+ * Rango component - renders the RSC router with all internal wiring.
  *
  * Must be called after initBrowserApp() has completed.
  *
  * @example
  * ```tsx
- * import { initBrowserApp, RSCRouter } from "rsc-router/browser";
+ * import { initBrowserApp, Rango } from "rsc-router/browser";
  * import { rscStream } from "rsc-html-stream/client";
  * import * as rscBrowser from "@vitejs/plugin-rsc/browser";
  *
@@ -389,14 +525,14 @@ export interface RSCRouterProps {}
  *   hydrateRoot(
  *     document,
  *     <React.StrictMode>
- *       <RSCRouter />
+ *       <Rango />
  *     </React.StrictMode>
  *   );
  * }
  * main();
  * ```
  */
-export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
+export function Rango(_props: RangoProps): React.ReactElement {
   const {
     store,
     eventController,
@@ -407,6 +543,7 @@ export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
     initialTheme,
     warmupEnabled,
     version,
+    appShellRef,
   } = getBrowserAppContext();
 
   // Signal that the React tree has hydrated. useEffect only fires after
@@ -426,6 +563,8 @@ export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
       initialTheme={initialTheme}
       warmupEnabled={warmupEnabled}
       version={version}
+      basename={initialPayload.metadata?.basename}
+      appShellRef={appShellRef}
     />
   );
 }