@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.204030a9

package/src/browser/shallow.ts

@@ -26,7 +26,12 @@ export function shallow<T>(a: T, b: T): boolean {
 
   // Check each key's value with Object.is
   for (const key of keysA) {
-    if (!Object.is((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])) {
+    if (
+      !Object.is(
+        (a as Record<string, unknown>)[key],
+        (b as Record<string, unknown>)[key],
+      )
+    ) {
       return false;
     }
   }

package/src/browser/types.ts

@@ -8,10 +8,10 @@ import type { RenderSegmentsOptions } from "../segment-system.js";
 // ============================================================================
 
 /**
- * RSC payload received from server
+ * RSC payload received from server.
+ * The tree is reconstructed from metadata.segments by the browser bridges.
  */
 export interface RscPayload<TMetadata = RscMetadata> {
-  root: ReactNode | Promise<ReactNode> | null;
   metadata?: TMetadata;
   returnValue?: ActionResult;
   formState?: unknown;
@@ -19,19 +19,34 @@ export interface RscPayload<TMetadata = RscMetadata> {
 
 /**
  * Handle data structure: handleName -> segmentId -> entries[]
+ *
+ * @internal This type is an implementation detail and may change without notice.
  */
 export type HandleData = Record<string, Record<string, unknown[]>>;
 
 /**
  * Metadata included in RSC responses
+ *
+ * @internal This type is an implementation detail and may change without notice.
  */
 export interface RscMetadata {
   pathname: string;
   segments: ResolvedSegment[];
+  /** Router instance ID. When this changes between navigations, the client
+   *  forces a full tree replacement (app switch via host router). */
+  routerId?: string;
   isPartial?: boolean;
   isError?: boolean;
   matched?: string[];
   diff?: string[];
+  /**
+   * All segment ids re-resolved on the server, including null-component
+   * ones excluded from `segments`/`diff`. Drives client-side handle-bucket
+   * cleanup. Superset of `diff`. See MatchResult.resolvedIds.
+   */
+  resolvedIds?: string[];
+  /** Merged route params from the matched route */
+  params?: Record<string, string>;
   /**
    * State of named slots for this route match
    * Key is slot name (e.g., "@modal"), value is slot state
@@ -49,6 +64,11 @@ export interface RscMetadata {
    * Used to detect version mismatches after HMR/deployment.
    */
   version?: string;
+  /**
+   * TTL in milliseconds for the client-side in-memory prefetch cache.
+   * Sent on initial render so the browser can configure its cache duration.
+   */
+  prefetchCacheTTL?: number;
   /**
    * Theme configuration from router.
    * Included when theme is enabled in router config.
@@ -59,20 +79,20 @@ export interface RscMetadata {
    * Included when theme is enabled in router config.
    */
   initialTheme?: Theme;
-  /**
-   * Route map for useHref() - maps route names to URL patterns.
-   * Used for type-safe URL generation on the client.
-   */
-  routeMap?: Record<string, string>;
-  /**
-   * Current matched route name (for local name resolution in useHref).
-   * When using include() with name prefix, this contains the full prefixed name.
-   */
-  routeName?: string;
+  /** URL prefix for all routes (from createRouter({ basename })). */
+  basename?: string;
+  /** Whether connection warmup is enabled */
+  warmupEnabled?: boolean;
+  /** Server-side redirect with optional state (for partial requests) */
+  redirect?: { url: string };
+  /** Server-set location state to include in history.pushState */
+  locationState?: Record<string, unknown>;
 }
 
 /**
  * Result from server action execution
+ *
+ * @internal This type is an implementation detail and may change without notice.
  */
 export interface ActionResult {
   ok: boolean;
@@ -91,6 +111,8 @@ export type NavigationLocation = URL;
 
 /**
  * Inflight server action being tracked
+ *
+ * @internal This type is an implementation detail and may change without notice.
  */
 export interface InflightAction {
   /** Unique identifier for this action invocation */
@@ -105,6 +127,8 @@ export interface InflightAction {
 
 /**
  * Internal navigation state (includes inflight actions for store use)
+ *
+ * @internal This type is an implementation detail. Use PublicNavigationState instead.
  */
 export interface NavigationState {
   /** Navigation lifecycle state (idle or loading during navigation) */
@@ -113,7 +137,7 @@ export interface NavigationState {
   /** Whether RSC data is currently streaming (initial load or navigation) */
   isStreaming: boolean;
 
-  /** Current location (updated optimistically) */
+  /** Current location */
   location: NavigationLocation;
 
   /** URL being navigated to (null when idle) */
@@ -141,6 +165,8 @@ export type ActionLifecycleState = "idle" | "loading" | "streaming";
 /**
  * State for a tracked server action
  * Used by useAction hook to observe action lifecycle
+ *
+ * @internal This type is an implementation detail and may change without notice.
  */
 export interface TrackedActionState {
   /** Current lifecycle state of the action */
@@ -161,12 +187,16 @@ export interface TrackedActionState {
 
 /**
  * Listener for action state changes
+ *
+ * @internal This type is an implementation detail and may change without notice.
  */
 export type ActionStateListener = (state: TrackedActionState) => void;
 
 /**
  * Cache interface for storing segments
- * Compatible with both Map and LRUCache
+ * Compatible with Map
+ *
+ * @internal This type is an implementation detail and may change without notice.
  */
 export interface SegmentCache {
   get(key: string): ResolvedSegment | undefined;
@@ -179,6 +209,8 @@ export interface SegmentCache {
 
 /**
  * Internal segment state managed by the store
+ *
+ * @internal This type is an implementation detail and may change without notice.
  */
 export interface SegmentState {
   path: string;
@@ -188,18 +220,31 @@ export interface SegmentState {
 
 /**
  * Navigation update emitted when UI should re-render
+ *
+ * @internal This type is an implementation detail and may change without notice.
  */
 export interface NavigationUpdate {
   root: ReactNode | Promise<ReactNode>;
   metadata: RscMetadata;
+  /** Scroll behavior to apply after React commits this update */
+  scroll?: {
+    /** For back/forward: restore saved position */
+    restore?: boolean;
+    /** Set to false to disable scrolling entirely */
+    enabled?: boolean;
+    /** Function to check if streaming is in progress */
+    isStreaming?: () => boolean;
+  };
 }
 
 /**
  * State value for navigate/Link
  * - LocationStateEntry[]: Type-safe state entries (recommended)
- * - unknown: Legacy format for backwards compatibility
+ * - unknown: Plain state format (object or getter function)
  */
-export type HistoryState = import("./react/location-state-shared.js").LocationStateEntry[] | unknown;
+export type HistoryState =
+  | import("./react/location-state-shared.js").LocationStateEntry[]
+  | unknown;
 
 /**
  * Options for navigation operations
@@ -207,6 +252,25 @@ export type HistoryState = import("./react/location-state-shared.js").LocationSt
 export interface NavigateOptions {
   replace?: boolean;
   scroll?: boolean;
+  /**
+   * Whether to revalidate server data on navigation.
+   * Set to `false` to skip the RSC server fetch and only update the URL.
+   *
+   * Only takes effect when the pathname stays the same (search param / hash changes).
+   * If the pathname changes, this option is ignored and a full navigation occurs.
+   *
+   * All location-aware hooks (`useSearchParams`, `useNavigation`, etc.) still update.
+   * Server components do not re-render.
+   *
+   * @default true
+   *
+   * @example
+   * ```tsx
+   * router.push("/products?color=blue", { revalidate: false });
+   * router.replace("/products?page=3", { revalidate: false });
+   * ```
+   */
+  revalidate?: boolean;
   /**
    * State to pass to history.pushState/replaceState
    * Accessible via useLocationState() hook.
@@ -214,19 +278,67 @@ export interface NavigateOptions {
    * @example
    * ```tsx
    * // Type-safe state (recommended)
-   * const ProductState = createLocationState<{ name: string }>("product");
+   * const ProductState = createLocationState<{ name: string }>();
    * navigate("/product/123", { state: [ProductState({ name: "Widget" })] });
    *
+   * // Type-safe just-in-time state (getter called at navigation time)
+   * navigate("/product/123", {
+   *   state: [ProductState(() => ({ name: computeName() }))],
+   * });
+   *
    * // Multiple states
    * navigate("/checkout", { state: [ProductState(p), CartState(c)] });
    *
-   * // Legacy format (backwards compatible)
+   * // Plain static state
    * navigate("/product", { state: { from: "list" } });
+   *
+   * // Plain just-in-time state
+   * navigate("/product", { state: () => ({ from: window.location.pathname }) });
    * ```
    */
   state?: HistoryState;
 }
 
+/** @internal Extended options used only within the navigation bridge */
+export interface NavigateOptionsInternal extends NavigateOptions {
+  /** Skip segment cache (used by redirect-with-state to force re-render) */
+  _skipCache?: boolean;
+}
+
+/**
+ * Options for useRouter push/replace methods.
+ * Same as NavigateOptions but without `replace` (implicit in push vs replace).
+ */
+export type RouterNavigateOptions = Omit<NavigateOptions, "replace">;
+
+/**
+ * Router instance returned by useRouter hook.
+ * Provides stable action methods that never cause re-renders.
+ */
+export interface RouterInstance {
+  /** Navigate to a URL, pushing a new entry to the history stack */
+  push(url: string, options?: RouterNavigateOptions): Promise<void>;
+  /** Navigate to a URL, replacing the current history entry */
+  replace(url: string, options?: RouterNavigateOptions): Promise<void>;
+  /** Refresh the current route (re-fetch server data, preserve client state) */
+  refresh(): Promise<void>;
+  /** Prefetch a URL for faster client-side transition */
+  prefetch(url: string): void;
+  /** Go back in browser history */
+  back(): void;
+  /** Go forward in browser history */
+  forward(): void;
+}
+
+/**
+ * URLSearchParams without mutation methods.
+ * Matches Next.js convention for useSearchParams return type.
+ */
+export type ReadonlyURLSearchParams = Omit<
+  URLSearchParams,
+  "append" | "delete" | "set" | "sort"
+>;
+
 // ============================================================================
 // RSC Browser Dependencies
 // ============================================================================
@@ -240,15 +352,21 @@ export interface NavigateOptions {
 export interface RscBrowserDependencies {
   createFromFetch: <T>(
     response: Promise<Response>,
-    options?: { temporaryReferences?: any }
+    options?: {
+      temporaryReferences?: any;
+      findSourceMapURL?: (
+        filename: string,
+        environmentName: string,
+      ) => string | null;
+    },
   ) => Promise<T>;
   createFromReadableStream: <T>(stream: ReadableStream) => Promise<T>;
   encodeReply: (
     args: any[],
-    options?: { temporaryReferences?: any }
+    options?: { temporaryReferences?: any },
   ) => Promise<FormData | string>;
   setServerCallback: (
-    callback: (id: string, args: any[]) => Promise<any>
+    callback: (id: string, args: any[]) => Promise<any>,
   ) => void;
   createTemporaryReferenceSet: () => any;
 }
@@ -300,16 +418,27 @@ export interface NavigationStore {
   cacheSegmentsForHistory(
     historyKey: string,
     segments: ResolvedSegment[],
-    handleData?: HandleData
+    handleData?: HandleData,
   ): void;
-  getCachedSegments(
-    historyKey: string
-  ): { segments: ResolvedSegment[]; stale: boolean; handleData?: HandleData } | undefined;
+  getCachedSegments(historyKey: string):
+    | {
+        segments: ResolvedSegment[];
+        stale: boolean;
+        handleData?: HandleData;
+        routerId?: string;
+      }
+    | undefined;
   hasHistoryCache(historyKey: string): boolean;
   updateCacheHandleData(historyKey: string, handleData: HandleData): void;
   markCacheAsStale(): void;
   markCacheAsStaleAndBroadcast(): void;
   clearHistoryCache(): void;
+  /**
+   * Clear this tab's nav + prefetch caches without broadcasting or rotating
+   * shared state. Intended for app-switch transitions that affect only this
+   * tab's session.
+   */
+  clearHistoryCacheLocal(): void;
   broadcastCacheInvalidation(): void;
 
   // Cross-tab refresh callback (set by navigation bridge)
@@ -319,6 +448,10 @@ export interface NavigationStore {
   getInterceptSourceUrl(): string | null;
   setInterceptSourceUrl(url: string | null): void;
 
+  // Router identity tracking (for cross-app navigation detection)
+  getRouterId?(): string | undefined;
+  setRouterId?(id: string): void;
+
   // UI update notifications
   onUpdate(callback: UpdateSubscriber): () => void;
   emitUpdate(update: NavigationUpdate): void;
@@ -328,39 +461,10 @@ export interface NavigationStore {
   setActionState(actionId: string, state: Partial<TrackedActionState>): void;
   subscribeToAction(
     actionId: string,
-    listener: ActionStateListener
+    listener: ActionStateListener,
   ): () => void;
 }
 
-// ============================================================================
-// Request Controller Types
-// ============================================================================
-
-/**
- * Disposable abort controller with automatic cleanup
- */
-export interface DisposableAbortController extends Disposable {
-  controller: AbortController;
-}
-
-/**
- * Request controller for managing concurrent requests
- *
- * Separates navigation requests (aborted on new navigation) from
- * action requests (complete independently of navigation).
- */
-export interface RequestController {
-  create(): AbortController;
-  createDisposable(): DisposableAbortController;
-  /** Create a disposable controller for actions (not aborted by navigation) */
-  createActionDisposable(): DisposableAbortController;
-  /** Abort all navigation requests (not actions) */
-  abortAll(): void;
-  /** Abort all action requests (used for error handling) */
-  abortAllActions(): void;
-  remove(controller: AbortController): void;
-}
-
 // ============================================================================
 // Navigation Client Types
 // ============================================================================
@@ -378,6 +482,10 @@ export interface FetchPartialOptions {
   interceptSourceUrl?: string;
   /** RSC version for cache invalidation detection */
   version?: string;
+  /** Current router ID — server detects app switch and returns full response */
+  routerId?: string;
+  /** If true, this is an HMR refetch - server should invalidate manifest cache */
+  hmr?: boolean;
 }
 
 /**
@@ -416,7 +524,6 @@ export interface LinkInterceptorOptions {
  */
 export interface ServerActionBridge {
   register(): void;
-  unregister(): void;
 }
 
 /**
@@ -429,7 +536,7 @@ export interface ServerActionBridgeConfig {
   onUpdate: UpdateSubscriber;
   renderSegments: (
     segments: ResolvedSegment[],
-    options?: RenderSegmentsOptions
+    options?: RenderSegmentsOptions,
   ) => Promise<ReactNode> | ReactNode;
 }
 
@@ -445,6 +552,17 @@ export interface NavigationBridge {
   refresh(): Promise<void>;
   handlePopstate(): Promise<void>;
   registerLinkInterception(): () => void;
+  /** Current RSC version (live, reflects the latest updateVersion). */
+  getVersion(): string | undefined;
+  /** Update the RSC version (e.g. after HMR). Clears prefetch cache. */
+  updateVersion(newVersion: string): void;
+  /**
+   * Replace the active app-shell snapshot (rootLayout, basename, version)
+   * atomically. Used on cross-app navigations when the response's routerId
+   * indicates the user entered a different app. Theme, warmup, and prefetch
+   * TTL are document-lifetime and not part of the shell.
+   */
+  updateAppShell(next: import("./app-shell.js").AppShell): void;
 }
 
 /**
@@ -456,9 +574,17 @@ export interface NavigationBridgeConfig {
   onUpdate: UpdateSubscriber;
   renderSegments: (
     segments: ResolvedSegment[],
-    options?: RenderSegmentsOptions
+    options?: RenderSegmentsOptions,
   ) => Promise<ReactNode> | ReactNode;
 }
 
 // Re-export ResolvedSegment for convenience
 export type { ResolvedSegment };
+
+/**
+ * Token for tracking an active stream.
+ * Call end() when the stream completes.
+ */
+export interface StreamingToken {
+  end(): void;
+}

package/src/browser/validate-redirect-origin.ts

@@ -0,0 +1,29 @@
+/**
+ * Validate that a client-consumed redirect URL (from headers or Flight payload)
+ * targets the same origin as the current page. Prevents open-redirect attacks
+ * via crafted responses.
+ *
+ * @returns The canonical (normalized) URL string on success, or null if blocked.
+ */
+export function validateRedirectOrigin(
+  url: string,
+  currentOrigin: string,
+): string | null {
+  try {
+    const target = new URL(url, currentOrigin);
+    if (target.origin !== currentOrigin) {
+      console.error(
+        `[rango] Redirect blocked: origin mismatch (${target.origin})`,
+      );
+      return null;
+    }
+    // Return pathname+search+hash for relative inputs, full href for absolute.
+    // This normalizes protocol-relative and other ambiguous forms.
+    return target.href.startsWith(currentOrigin)
+      ? target.href
+      : target.pathname + target.search + target.hash;
+  } catch {
+    console.error(`[rango] Redirect blocked: invalid URL "${url}"`);
+    return null;
+  }
+}

package/src/build/collect-fallback-refs.ts

@@ -0,0 +1,107 @@
+// Collect the `"use client"` client-reference keys reachable from an error /
+// notFound boundary registration, for routing them into the dedicated
+// `app-fallback` chunk (see vite/utils/client-chunks.ts).
+//
+// A boundary registration is not always a bare client element. The common,
+// load-bearing pattern wraps the client boundary in providers a thrown handler
+// needs (the layout that would normally supply them did not mount):
+//
+//   defaultErrorBoundary: ({ error }) => (
+//     <FallbackIntl locales={...}>
+//       <ThemedError error={error} />   // <- the real "use client" boundary
+//     </FallbackIntl>
+//   )
+//
+// So the value may be (a) a handler FUNCTION returning a tree, or (b) an element
+// tree with the client boundary nested below server wrappers. We:
+//   1. If it's a function, CALL it with synthetic props to get the returned tree.
+//      This only constructs JSX — the inner components are element `type`s, never
+//      invoked — so no hooks run. Guarded: a boundary that needs a real render
+//      context (request globals, etc.) throws and is skipped (graceful: it simply
+//      stays on the default grouping, as before).
+//   2. Walk the resulting tree and report every element whose `.type` is a
+//      plugin-rsc client reference.
+//
+// Limit: a boundary that *conditionally* renders different client components based
+// on the runtime error cannot be resolved statically — only the branch taken with
+// the synthetic error is seen. Such cases fall back to the default chunk; the
+// custom `clientChunks` function is the escape hatch.
+
+const CLIENT_REF = Symbol.for("react.client.reference");
+const MAX_DEPTH = 40;
+
+// Synthetic props covering the error-boundary (`{ error, reset }`) and notFound
+// (`{ pathname }`) handler shapes. The handler destructures what it needs.
+const SYNTHETIC_PROPS = {
+  error: new Error("rango: build-time fallback-chunk discovery"),
+  reset: () => {},
+  pathname: "/",
+  info: { componentStack: "" },
+};
+
+interface MaybeElement {
+  type?: { $$typeof?: symbol; $$id?: string };
+  props?: Record<string, unknown>;
+}
+
+function isReactNodeLike(v: unknown): boolean {
+  return (
+    Array.isArray(v) ||
+    (typeof v === "object" && v !== null && "$$typeof" in (v as object))
+  );
+}
+
+function walkElementTree(
+  node: unknown,
+  report: (refKey: string) => void,
+  depth: number,
+): void {
+  if (node == null || depth > MAX_DEPTH) return;
+  if (Array.isArray(node)) {
+    for (const child of node) walkElementTree(child, report, depth + 1);
+    return;
+  }
+  if (typeof node !== "object") return;
+
+  const el = node as MaybeElement;
+  const type = el.type;
+  if (type?.$$typeof === CLIENT_REF && typeof type.$$id === "string") {
+    // $$id is `<referenceKey>#<exportName>` in build mode — keep the referenceKey.
+    report(type.$$id.split("#")[0]);
+  }
+
+  const props = el.props;
+  if (props && typeof props === "object") {
+    // Children are always nodes; other props are followed only when they look
+    // like React nodes (slots/icons), never arbitrary data objects.
+    walkElementTree(props.children, report, depth + 1);
+    for (const key in props) {
+      if (key === "children") continue;
+      const value = props[key];
+      if (isReactNodeLike(value)) walkElementTree(value, report, depth + 1);
+    }
+  }
+}
+
+/**
+ * Report every `"use client"` client-reference key reachable from a single
+ * error/notFound boundary registration (handler function or element tree).
+ */
+export function collectFallbackClientRefs(
+  boundary: unknown,
+  report: (refKey: string) => void,
+): void {
+  try {
+    let node = boundary;
+    if (typeof node === "function") {
+      node = (node as (props: unknown) => unknown)(SYNTHETIC_PROPS);
+    }
+    walkElementTree(node, report, 0);
+  } catch {
+    // The boundary needs a real render context (request globals, hooks at the
+    // top level) or its tree has hostile getters. Its client refs can't be
+    // resolved statically — skip. It stays on the default grouping (no
+    // regression vs. not collecting), and the custom clientChunks fn is the
+    // escape hatch for such cases.
+  }
+}