@rangojs/router 0.0.0-experimental.15 → 0.0.0-experimental.151

package/src/browser/history-state.ts

@@ -0,0 +1,101 @@
+import {
+  isLocationStateEntry,
+  resolveLocationStateEntries,
+} from "./react/location-state-shared.js";
+
+/**
+ * Check if state is from typed LocationStateEntry[] (has __rsc_ls_ keys)
+ */
+function isTypedLocationState(
+  state: unknown,
+): state is Record<string, unknown> {
+  if (state === null || typeof state !== "object") return false;
+  return Object.keys(state).some((key) => key.startsWith("__rsc_ls_"));
+}
+
+/**
+ * Resolve navigation state - handles both LocationStateEntry[] and plain formats
+ */
+export function resolveNavigationState(state: unknown): unknown {
+  if (
+    Array.isArray(state) &&
+    state.length > 0 &&
+    isLocationStateEntry(state[0])
+  ) {
+    return resolveLocationStateEntries(state);
+  }
+  return state;
+}
+
+/**
+ * Build history state object from user state
+ * - Typed state: spread directly into history.state
+ * - Plain state: store in history.state.state
+ */
+export function buildHistoryState(
+  userState: unknown,
+  routerState?: { intercept?: boolean; sourceUrl?: string },
+  serverState?: Record<string, unknown>,
+): Record<string, unknown> | null {
+  const result: Record<string, unknown> = {};
+
+  if (routerState?.intercept) {
+    result.intercept = true;
+    if (routerState.sourceUrl) {
+      result.sourceUrl = routerState.sourceUrl;
+    }
+  }
+
+  if (userState !== undefined) {
+    if (isTypedLocationState(userState)) {
+      Object.assign(result, userState);
+    } else {
+      result.state = userState;
+    }
+  }
+
+  if (serverState) {
+    Object.assign(result, serverState);
+  }
+
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+/**
+ * Stamp an `idx` on the next history entry's state and call push/replaceState.
+ * Push increments the current idx; replace keeps it. Initial entry idx is 0.
+ * Used by useRouter().back() to detect "first entry in this session" without
+ * relying on the Navigation API.
+ */
+export function pushHistoryWithIdx(
+  state: Record<string, unknown> | null,
+  url: string,
+  replace: boolean,
+): void {
+  const oldIdx = (window.history.state as { idx?: number } | null)?.idx ?? 0;
+  const newIdx = replace ? oldIdx : oldIdx + 1;
+  const finalState = { ...(state ?? {}), idx: newIdx };
+  if (replace) {
+    window.history.replaceState(finalState, "", url);
+  } else {
+    window.history.pushState(finalState, "", url);
+  }
+}
+
+/**
+ * Merge server-set location state into the current history entry.
+ * Replaces the current history state and dispatches notification event
+ * so useLocationState hooks re-read from history.state.
+ */
+export function mergeLocationState(
+  locationState: Record<string, unknown>,
+): void {
+  const merged = {
+    ...window.history.state,
+    ...locationState,
+  };
+  window.history.replaceState(merged, "", window.location.href);
+  if (Object.keys(locationState).some((k) => k.startsWith("__rsc_ls_"))) {
+    window.dispatchEvent(new Event("__rsc_locationstate"));
+  }
+}

package/src/browser/index.ts

@@ -1,9 +1,9 @@
 // ============================================================================
-// Browser Module - Browser entry point for RSC Router
+// Browser Module - Browser entry point for Rango
 // ============================================================================
 //
 // Usage:
-//   import { initBrowserApp, RSCRouter } from "rsc-router/browser";
+//   import { initBrowserApp, Rango } from "rsc-router/browser";
 //
 // For React components (Link, useNavigation, etc.):
 //   import { Link, useNavigation, useAction, href } from "rsc-router/client";
@@ -13,6 +13,6 @@
 // Browser app initialization
 export {
   initBrowserApp,
-  RSCRouter,
+  Rango,
   type InitBrowserAppOptions,
 } from "./rsc-router.js";

package/src/browser/intercept-utils.ts

@@ -0,0 +1,52 @@
+import type { ResolvedSegment } from "./types.js";
+import type { SlotState } from "../types.js";
+
+/**
+ * Check if a segment is an intercept segment.
+ * Intercept segments have namespace starting with "intercept:" — both the
+ * parallel container (@modal) and its content children receive this namespace
+ * from intercept-resolution.ts. Regular parallel segments like @sidebar do not.
+ */
+export function isInterceptSegment(s: ResolvedSegment): boolean {
+  return s.namespace?.startsWith("intercept:") === true;
+}
+
+/**
+ * Split an array of segments into main and intercept groups.
+ * Intercept segments are separated for explicit injection into the render tree
+ * via the interceptSegments render option.
+ */
+export function splitInterceptSegments(segments: ResolvedSegment[]): {
+  main: ResolvedSegment[];
+  intercept: ResolvedSegment[];
+} {
+  const main: ResolvedSegment[] = [];
+  const intercept: ResolvedSegment[] = [];
+  for (const s of segments) {
+    if (isInterceptSegment(s)) {
+      intercept.push(s);
+    } else {
+      main.push(s);
+    }
+  }
+  return { main, intercept };
+}
+
+/**
+ * Check if any slot is currently active (has content to render).
+ * Active slots indicate an intercept response where a parallel segment
+ * (e.g., @modal) has matched and should be rendered.
+ */
+export function hasActiveIntercept(slots?: Record<string, SlotState>): boolean {
+  if (!slots) return false;
+  return Object.values(slots).some((slot) => slot.active);
+}
+
+/**
+ * Check if cached segments contain any intercept segments.
+ * Intercept caches shouldn't be used for cached SWR rendering since
+ * whether interception happens depends on the current page context.
+ */
+export function isInterceptOnlyCache(segments: ResolvedSegment[]): boolean {
+  return segments.some(isInterceptSegment);
+}

package/src/browser/invalidate-client-cache.ts

@@ -0,0 +1,52 @@
+/**
+ * Client seat of `invalidateClientCache()` (the `default` export condition).
+ *
+ * Makes the current client behave as if a server action had just completed:
+ * the history cache is marked stale (SWR), the prefetch map is flushed, the
+ * state rotates, and sibling tabs are broadcast to — the same
+ * `markCacheAsStaleAndBroadcast()` path the server-action bridge uses. This is
+ * the gentler mark-stale (not hard-clear) behavior, so Back renders the cached
+ * entry instantly and revalidates.
+ */
+
+import { getRegisteredStore } from "./navigation-store-handle.js";
+import { clearPrefetchCache } from "./prefetch/cache.js";
+
+export function invalidateClientCache(): void {
+  if (typeof document === "undefined") {
+    // SSR pass of a client component also resolves the default condition. A
+    // render-time call must not take down the page; no-op with a dev warning.
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(
+        "[rango] invalidateClientCache() was called during a server render; " +
+          "it is a no-op outside the browser.",
+      );
+    }
+    return;
+  }
+
+  const store = getRegisteredStore();
+  if (store) {
+    store.markCacheAsStaleAndBroadcast();
+    return;
+  }
+
+  // Pre-boot: no store registered yet. clearPrefetchCache() (which rotates the
+  // state) is complete at this point — there is no history cache to mark and no
+  // sibling state worth broadcasting.
+  clearPrefetchCache();
+}
+
+/**
+ * Client no-op for `keepClientCache()`. It is a server action directive (the
+ * `react-server` condition sets a response header the action bridge reads);
+ * there is nothing to suppress from the client side.
+ */
+export function keepClientCache(): void {
+  if (process.env.NODE_ENV !== "production") {
+    console.warn(
+      "[rango] keepClientCache() has no effect on the client; it is a server " +
+        "action directive. Call it from inside a server action.",
+    );
+  }
+}

package/src/browser/link-interceptor.ts

@@ -1,5 +1,18 @@
 import type { LinkInterceptorOptions, NavigateOptions } from "./types.js";
 
+/**
+ * Check if an anchor points to the same page with only a hash change.
+ * Used by both Link component and link-interceptor to let the browser
+ * handle anchor scrolling natively.
+ */
+export function isHashOnlyNavigation(anchor: HTMLAnchorElement): boolean {
+  return (
+    anchor.pathname === window.location.pathname &&
+    anchor.search === window.location.search &&
+    !!anchor.hash
+  );
+}
+
 /**
  * Default link interception predicate
  *
@@ -44,6 +57,12 @@ export function defaultShouldIntercept(link: HTMLAnchorElement): boolean {
     return false;
   }
 
+  // Don't intercept hash-only navigation (same path, only fragment changes).
+  // Let the browser handle anchor scrolling natively.
+  if (isHashOnlyNavigation(link)) {
+    return false;
+  }
+
   return true;
 }
 
@@ -70,7 +89,7 @@ export function defaultShouldIntercept(link: HTMLAnchorElement): boolean {
  */
 export function setupLinkInterception(
   onNavigate: (url: string, options?: NavigateOptions) => void,
-  options?: LinkInterceptorOptions
+  options?: LinkInterceptorOptions,
 ): () => void {
   const shouldIntercept = options?.shouldIntercept ?? defaultShouldIntercept;
 
@@ -98,6 +117,7 @@ export function setupLinkInterception(
     // Read navigation options from data attributes (set by Link component)
     const scrollAttr = link.getAttribute("data-scroll");
     const replaceAttr = link.getAttribute("data-replace");
+    const revalidateAttr = link.getAttribute("data-revalidate");
 
     const navigateOptions: NavigateOptions = {};
     if (scrollAttr === "false") {
@@ -106,16 +126,16 @@ export function setupLinkInterception(
     if (replaceAttr === "true") {
       navigateOptions.replace = true;
     }
+    if (revalidateAttr === "false") {
+      navigateOptions.revalidate = false;
+    }
 
     onNavigate(href, navigateOptions);
   };
 
   document.addEventListener("click", handleClick);
 
-  console.log("[Browser] Link interception enabled");
-
   return () => {
     document.removeEventListener("click", handleClick);
-    console.log("[Browser] Link interception disabled");
   };
 }

package/src/browser/logging.ts

@@ -1,5 +1,15 @@
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 
+/**
+ * Module-level debug flag for guarding call sites whose debug arguments do
+ * non-trivial work (joins, maps, spreads, object literals). Because the Vite
+ * transform folds INTERNAL_RANGO_DEBUG to a literal, an `if (IS_BROWSER_DEBUG)`
+ * guard is minifier-DCE-able — the whole block drops from the production bundle.
+ * Prefer this over isBrowserDebugEnabled() at hot call sites: a const guard folds
+ * where a function call may not.
+ */
+export const IS_BROWSER_DEBUG: boolean = INTERNAL_RANGO_DEBUG;
+
 interface BrowserLogContext {
   requestId: string;
   txId: string;
@@ -42,3 +52,32 @@ export function browserDebugLog(
 
   console.log(`${prefix} ${message}`);
 }
+
+/**
+ * Simple gated console.log for browser-side debug output.
+ * Unlike browserDebugLog, this doesn't require a transaction context -
+ * use it for standalone debug messages in partial-update, navigation-bridge, etc.
+ */
+export function debugLog(msg: string, ...args: unknown[]): void {
+  if (INTERNAL_RANGO_DEBUG) {
+    console.log(msg, ...args);
+  }
+}
+
+/**
+ * Boot-sequence debug log: one line per initial-document step (flight decode,
+ * handle stream, bridge wiring, initial tree build, hydration commit), each
+ * stamped with performance.now() so the gap BEFORE hydrateRoot is visible.
+ * The initial document path was otherwise silent — FE debug only started
+ * talking at the first soft navigation, so a boot stall (e.g. an await that
+ * holds initBrowserApp, and with it hydrateRoot) was invisible.
+ */
+export function bootLog(step: string, details?: Record<string, unknown>): void {
+  if (!INTERNAL_RANGO_DEBUG) return;
+  const prefix = `[Browser][boot] ${step} @ ${Math.round(performance.now())}ms`;
+  if (details) {
+    console.log(prefix, details);
+    return;
+  }
+  console.log(prefix);
+}

package/src/browser/merge-segment-loaders.ts

@@ -1,4 +1,5 @@
 import type { ResolvedSegment } from "./types.js";
+import { debugLog, IS_BROWSER_DEBUG } from "./logging.js";
 
 /**
  * Merge partial loader data from server with cached loader data.
@@ -13,14 +14,16 @@ import type { ResolvedSegment } from "./types.js";
  */
 export function mergeSegmentLoaders(
   fromServer: ResolvedSegment,
-  fromCache: ResolvedSegment
+  fromCache: ResolvedSegment,
 ): ResolvedSegment {
   const serverLoaderIds = fromServer.loaderIds || [];
   const cachedLoaderIds = fromCache.loaderIds || [];
 
-  console.log(
-    `[Browser] Merging partial loaders: server has ${serverLoaderIds.join(", ")}, cache has ${cachedLoaderIds.join(", ")}`
-  );
+  if (IS_BROWSER_DEBUG) {
+    debugLog(
+      `[Browser] Merging partial loaders: server has ${serverLoaderIds.join(", ")}, cache has ${cachedLoaderIds.join(", ")}`,
+    );
+  }
 
   return {
     ...fromCache,
@@ -54,7 +57,7 @@ export function mergeSegmentLoaders(
  */
 export function needsLoaderMerge(
   fromServer: ResolvedSegment,
-  fromCache: ResolvedSegment | undefined
+  fromCache: ResolvedSegment | undefined,
 ): fromCache is ResolvedSegment {
   return !!(
     fromCache &&
@@ -86,10 +89,15 @@ export function insertMissingDiffSegments(
   allSegments: ResolvedSegment[],
   diff: string[] | undefined,
   matchedIdSet: Set<string>,
-  newSegmentMap: Map<string, ResolvedSegment>
+  newSegmentMap: Map<string, ResolvedSegment>,
 ): void {
   if (!diff || diff.length === 0) return;
 
+  // Track how many siblings have been inserted per parent so each new
+  // sibling goes after the last one rather than always at parentIndex + 1
+  // (which would reverse the server order).
+  const insertedPerParent = new Map<string, number>();
+
   diff.forEach((diffId: string) => {
     if (!matchedIdSet.has(diffId)) {
       const fromServer = newSegmentMap.get(diffId);
@@ -100,25 +108,27 @@ export function insertMissingDiffSegments(
         if (loaderMatch) {
           const parentLayoutId = loaderMatch[1];
           const parentIndex = allSegments.findIndex(
-            (s) => s.id === parentLayoutId
+            (s) => s.id === parentLayoutId,
           );
           if (parentIndex !== -1) {
-            // Insert loader segment right after its parent layout
-            allSegments.splice(parentIndex + 1, 0, fromServer);
-            console.log(
-              `[Browser] Inserted diff segment ${diffId} after ${parentLayoutId}`
+            const alreadyInserted = insertedPerParent.get(parentLayoutId) ?? 0;
+            const insertAt = parentIndex + 1 + alreadyInserted;
+            allSegments.splice(insertAt, 0, fromServer);
+            insertedPerParent.set(parentLayoutId, alreadyInserted + 1);
+            debugLog(
+              `[Browser] Inserted diff segment ${diffId} after ${parentLayoutId}`,
             );
           } else {
             // Fallback: append to end if parent not found
             allSegments.push(fromServer);
             console.warn(
-              `[Browser] Appended diff segment ${diffId} (parent ${parentLayoutId} not found)`
+              `[Browser] Appended diff segment ${diffId} (parent ${parentLayoutId} not found)`,
             );
           }
         } else {
           // Non-loader diff segment not in matched - append to end
           allSegments.push(fromServer);
-          console.log(`[Browser] Appended diff segment ${diffId}`);
+          debugLog(`[Browser] Appended diff segment ${diffId}`);
         }
       }
     }