@rangojs/router 0.0.0-experimental.0b82333f

package/src/browser/history-state.ts

@@ -0,0 +1,80 @@
+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;
+}
+
+/**
+ * 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

@@ -0,0 +1,18 @@
+// ============================================================================
+// Browser Module - Browser entry point for RSC Router
+// ============================================================================
+//
+// Usage:
+//   import { initBrowserApp, RSCRouter } from "rsc-router/browser";
+//
+// For React components (Link, useNavigation, etc.):
+//   import { Link, useNavigation, useAction, href } from "rsc-router/client";
+//
+// ============================================================================
+
+// Browser app initialization
+export {
+  initBrowserApp,
+  RSCRouter,
+  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/link-interceptor.ts

@@ -0,0 +1,141 @@
+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
+ *
+ * Returns true if the link should be intercepted for SPA navigation.
+ * Filters out:
+ * - Cross-origin links
+ * - Links with download attribute
+ * - Links with target other than _self
+ * - Links with data-no-intercept attribute
+ *
+ * @param link - The anchor element to check
+ * @returns true if the link should be intercepted
+ */
+export function defaultShouldIntercept(link: HTMLAnchorElement): boolean {
+  // Only intercept same-origin links
+  if (link.origin !== window.location.origin) {
+    return false;
+  }
+
+  // Don't intercept if it has download attribute
+  if (link.hasAttribute("download")) {
+    return false;
+  }
+
+  // Don't intercept if target is set to something other than _self
+  if (link.target && link.target !== "_self") {
+    return false;
+  }
+
+  // Don't intercept if explicitly disabled
+  if (link.getAttribute("data-no-intercept") === "true") {
+    return false;
+  }
+
+  // Don't intercept Link component anchors - they handle their own navigation
+  if (link.hasAttribute("data-link-component")) {
+    return false;
+  }
+
+  // Don't intercept external links
+  if (link.hasAttribute("data-external")) {
+    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;
+}
+
+/**
+ * Set up link interception for SPA navigation
+ *
+ * Attaches a global click handler to intercept clicks on anchor elements
+ * and call the onNavigate callback instead of performing a full page load.
+ *
+ * @param onNavigate - Callback when a link should navigate via SPA
+ * @param options - Configuration options
+ * @returns Cleanup function to remove the event listener
+ *
+ * @example
+ * ```typescript
+ * const cleanup = setupLinkInterception((url) => {
+ *   window.history.pushState({}, "", url);
+ *   fetchPartialUpdate(url);
+ * });
+ *
+ * // Later, to clean up:
+ * cleanup();
+ * ```
+ */
+export function setupLinkInterception(
+  onNavigate: (url: string, options?: NavigateOptions) => void,
+  options?: LinkInterceptorOptions,
+): () => void {
+  const shouldIntercept = options?.shouldIntercept ?? defaultShouldIntercept;
+
+  const handleClick = (event: MouseEvent) => {
+    // If event was already handled by Link component (or other handler), skip
+    if (event.defaultPrevented) {
+      return;
+    }
+
+    const target = event.target as HTMLElement;
+    const link = target.closest("a");
+
+    if (!link || !shouldIntercept(link)) {
+      return;
+    }
+
+    // Don't intercept if modifier keys are pressed (open in new tab, etc.)
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+      return;
+    }
+
+    event.preventDefault();
+    const href = link.href;
+
+    // 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") {
+      navigateOptions.scroll = false;
+    }
+    if (replaceAttr === "true") {
+      navigateOptions.replace = true;
+    }
+    if (revalidateAttr === "false") {
+      navigateOptions.revalidate = false;
+    }
+
+    onNavigate(href, navigateOptions);
+  };
+
+  document.addEventListener("click", handleClick);
+
+  return () => {
+    document.removeEventListener("click", handleClick);
+  };
+}

package/src/browser/logging.ts

@@ -0,0 +1,55 @@
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
+
+interface BrowserLogContext {
+  requestId: string;
+  txId: string;
+  operation: string;
+}
+
+let txCounter = 0;
+let requestCounter = 0;
+
+export function isBrowserDebugEnabled(): boolean {
+  return INTERNAL_RANGO_DEBUG;
+}
+
+function nextId(prefix: string, counter: number): string {
+  return `${prefix}${counter.toString(36)}`;
+}
+
+export function startBrowserTransaction(operation: string): BrowserLogContext {
+  txCounter += 1;
+  requestCounter += 1;
+  return {
+    operation,
+    txId: nextId("ctx-", txCounter),
+    requestId: nextId("creq-", requestCounter),
+  };
+}
+
+export function browserDebugLog(
+  ctx: BrowserLogContext,
+  message: string,
+  details?: Record<string, unknown>,
+): void {
+  if (!INTERNAL_RANGO_DEBUG) return;
+
+  const prefix = `[Browser][req:${ctx.requestId}][tx:${ctx.operation}-${ctx.txId}]`;
+  if (details) {
+    console.log(`${prefix} ${message}`, details);
+    return;
+  }
+
+  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);
+  }
+}

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

@@ -0,0 +1,134 @@
+import type { ResolvedSegment } from "./types.js";
+import { debugLog } from "./logging.js";
+
+/**
+ * Merge partial loader data from server with cached loader data.
+ *
+ * During partial revalidation (stale or action), the server may return only
+ * some loaders that pass the revalidation check. The component still needs
+ * all loader data, so we merge fresh data with cached data.
+ *
+ * @param fromServer - Segment returned from server with partial loaders
+ * @param fromCache - Cached segment with full loader data
+ * @returns Merged segment with complete loader data
+ */
+export function mergeSegmentLoaders(
+  fromServer: ResolvedSegment,
+  fromCache: ResolvedSegment,
+): ResolvedSegment {
+  const serverLoaderIds = fromServer.loaderIds || [];
+  const cachedLoaderIds = fromCache.loaderIds || [];
+
+  debugLog(
+    `[Browser] Merging partial loaders: server has ${serverLoaderIds.join(", ")}, cache has ${cachedLoaderIds.join(", ")}`,
+  );
+
+  return {
+    ...fromCache,
+    // Keep cached component (server's might be a fresh Promise that needs the loaders)
+    component: fromCache.component,
+    // Merge loader data - await both and combine
+    loaderDataPromise: Promise.all([
+      fromServer.loaderDataPromise!,
+      fromCache.loaderDataPromise!,
+    ]).then(([newData, cachedData]) => {
+      // Build merged array: use new data for updated loaders, cached for rest
+      return cachedLoaderIds.map((id: string, i: number) => {
+        const newIndex = serverLoaderIds.indexOf(id);
+        if (newIndex !== -1) {
+          return (newData as any[])[newIndex]; // Use fresh data
+        }
+        return (cachedData as any[])[i]; // Use cached data
+      });
+    }),
+    // Keep all loader IDs from cache
+    loaderIds: fromCache.loaderIds,
+  };
+}
+
+/**
+ * Check if segments need loader merging during partial revalidation.
+ *
+ * Returns true when:
+ * - Server returned fewer loaders than cached (partial revalidation)
+ * - Both segments have loader data promises
+ */
+export function needsLoaderMerge(
+  fromServer: ResolvedSegment,
+  fromCache: ResolvedSegment | undefined,
+): fromCache is ResolvedSegment {
+  return !!(
+    fromCache &&
+    fromServer.loaderIds &&
+    fromCache.loaderIds &&
+    fromServer.loaderIds.length < fromCache.loaderIds.length &&
+    fromServer.loaderDataPromise &&
+    fromCache.loaderDataPromise
+  );
+}
+
+/**
+ * Insert diff segments that aren't in the matched array into allSegments.
+ *
+ * During consolidation fetch for concurrent actions, loader segments may be
+ * excluded from the request. The server returns them in the diff but not in
+ * the matched array. This function inserts them at the correct position
+ * (after their parent layout segment).
+ *
+ * Loader segment IDs follow the pattern: {parentLayoutId}D{index}.{loaderId}
+ * Example: M9L0L1D0.actionCounter has parent layout M9L0L1
+ *
+ * @param allSegments - Mutable array of segments to insert into
+ * @param diff - Array of segment IDs that changed (from server response)
+ * @param matchedIdSet - Set of segment IDs from matched array
+ * @param newSegmentMap - Map of segment ID to segment data from server
+ */
+export function insertMissingDiffSegments(
+  allSegments: ResolvedSegment[],
+  diff: string[] | undefined,
+  matchedIdSet: Set<string>,
+  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);
+      if (fromServer) {
+        // Loader segment IDs have pattern like M9L0L1D0.actionCounter
+        // Parent layout ID is the prefix before D\d+ (e.g., M9L0L1)
+        const loaderMatch = diffId.match(/^(.+?)D\d+\./);
+        if (loaderMatch) {
+          const parentLayoutId = loaderMatch[1];
+          const parentIndex = allSegments.findIndex(
+            (s) => s.id === parentLayoutId,
+          );
+          if (parentIndex !== -1) {
+            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)`,
+            );
+          }
+        } else {
+          // Non-loader diff segment not in matched - append to end
+          allSegments.push(fromServer);
+          debugLog(`[Browser] Appended diff segment ${diffId}`);
+        }
+      }
+    }
+  });
+}