@ivogt/rsc-router 0.0.0-experimental.1

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/link-interceptor.ts

@@ -0,0 +1,121 @@
+import type { LinkInterceptorOptions, NavigateOptions } from "./types.js";
+
+/**
+ * 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;
+  }
+
+  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 navigateOptions: NavigateOptions = {};
+    if (scrollAttr === "false") {
+      navigateOptions.scroll = false;
+    }
+    if (replaceAttr === "true") {
+      navigateOptions.replace = true;
+    }
+
+    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/lru-cache.ts

@@ -0,0 +1,69 @@
+/**
+ * Simple LRU (Least Recently Used) cache implementation
+ * Used for caching navigation segments to enable instant back/forward
+ */
+export class LRUCache<K, V> {
+  private cache = new Map<K, V>();
+  private maxSize: number;
+
+  constructor(maxSize: number) {
+    this.maxSize = maxSize;
+  }
+
+  get(key: K): V | undefined {
+    if (!this.cache.has(key)) {
+      return undefined;
+    }
+
+    // Move to end (most recently used)
+    const value = this.cache.get(key)!;
+    this.cache.delete(key);
+    this.cache.set(key, value);
+    return value;
+  }
+
+  set(key: K, value: V): void {
+    // If key exists, delete it first to update position
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    }
+
+    this.cache.set(key, value);
+
+    // Evict oldest entries if over capacity
+    while (this.cache.size > this.maxSize) {
+      const oldestKey = this.cache.keys().next().value;
+      if (oldestKey !== undefined) {
+        this.cache.delete(oldestKey);
+      }
+    }
+  }
+
+  has(key: K): boolean {
+    if (!this.cache.has(key)) {
+      return false;
+    }
+
+    // Move to end (most recently used) - same as get()
+    const value = this.cache.get(key)!;
+    this.cache.delete(key);
+    this.cache.set(key, value);
+    return true;
+  }
+
+  delete(key: K): boolean {
+    return this.cache.delete(key);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  keys(): IterableIterator<K> {
+    return this.cache.keys();
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+}

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

@@ -0,0 +1,126 @@
+import type { ResolvedSegment } from "./types.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 || [];
+
+  console.log(
+    `[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;
+
+  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) {
+            // Insert loader segment right after its parent layout
+            allSegments.splice(parentIndex + 1, 0, fromServer);
+            console.log(
+              `[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);
+          console.log(`[Browser] Appended diff segment ${diffId}`);
+        }
+      }
+    }
+  });
+}