@rangojs/router 0.0.0-experimental.9 → 0.0.0-experimental.9c87b9aa

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;
@@ -36,6 +36,8 @@ export interface RscMetadata {
   isError?: boolean;
   matched?: string[];
   diff?: 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
@@ -53,6 +55,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.
@@ -65,6 +72,10 @@ export interface RscMetadata {
   initialTheme?: Theme;
   /** 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>;
 }
 
 /**
@@ -115,7 +126,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) */
@@ -172,7 +183,7 @@ 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.
  */
@@ -204,14 +215,25 @@ export interface SegmentState {
 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
@@ -219,6 +241,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.
@@ -226,19 +267,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
 // ============================================================================
@@ -252,15 +341,15 @@ export interface NavigateOptions {
 export interface RscBrowserDependencies {
   createFromFetch: <T>(
     response: Promise<Response>,
-    options?: { temporaryReferences?: any }
+    options?: { temporaryReferences?: any },
   ) => 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;
 }
@@ -312,11 +401,13 @@ export interface NavigationStore {
   cacheSegmentsForHistory(
     historyKey: string,
     segments: ResolvedSegment[],
-    handleData?: HandleData
+    handleData?: HandleData,
   ): void;
   getCachedSegments(
-    historyKey: string
-  ): { segments: ResolvedSegment[]; stale: boolean; handleData?: HandleData } | undefined;
+    historyKey: string,
+  ):
+    | { segments: ResolvedSegment[]; stale: boolean; handleData?: HandleData }
+    | undefined;
   hasHistoryCache(historyKey: string): boolean;
   updateCacheHandleData(historyKey: string, handleData: HandleData): void;
   markCacheAsStale(): void;
@@ -340,39 +431,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
 // ============================================================================
@@ -430,7 +492,6 @@ export interface LinkInterceptorOptions {
  */
 export interface ServerActionBridge {
   register(): void;
-  unregister(): void;
 }
 
 /**
@@ -443,7 +504,7 @@ export interface ServerActionBridgeConfig {
   onUpdate: UpdateSubscriber;
   renderSegments: (
     segments: ResolvedSegment[],
-    options?: RenderSegmentsOptions
+    options?: RenderSegmentsOptions,
   ) => Promise<ReactNode> | ReactNode;
 }
 
@@ -470,9 +531,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/generate-manifest.ts

@@ -43,14 +43,14 @@ export interface GeneratedManifest {
   routeManifest: Record<string, string>;
   /** Route name → trailing slash mode for trie redirect handling */
   routeTrailingSlash?: Record<string, string>;
-  /** Route names using createPrerenderHandler (for dev-mode Node.js delegation) */
+  /** Route names using Prerender (for dev-mode Node.js delegation) */
   prerenderRoutes?: string[];
   /** Route names with passthrough: true (handler kept in bundle for live fallback) */
   passthroughRoutes?: string[];
   /** Route name → response type for non-RSC routes */
   responseTypeRoutes?: Record<string, string>;
-  /** Generation timestamp */
-  generatedAt: string;
+  /** Route name -> search schema descriptor for typed URL helpers */
+  routeSearchSchemas?: Record<string, Record<string, string>>;
 }
 
 /**
@@ -62,7 +62,7 @@ function buildPrefixTreeNode(
   namePrefix: string | undefined,
   patterns: UrlPatterns<any>,
   routeManifest: Record<string, string>,
-  routeAncestry: Record<string, string[]>,  // internal: feeds trie building, not exported
+  routeAncestry: Record<string, string[]>, // internal: feeds trie building, not exported
   mountIndex: number,
   visited: Set<unknown> = new Set(),
   routeTrailingSlash?: Record<string, string>,
@@ -70,10 +70,11 @@ function buildPrefixTreeNode(
   prerenderDefs?: Record<string, any>,
   passthroughRoutes?: string[],
   responseTypeRoutes?: Record<string, string>,
+  routeSearchSchemas?: Record<string, Record<string, string>>,
 ): PrefixTreeNode {
   if (visited.has(patterns)) {
     console.warn(
-      `[@rangojs/router] Circular include detected at prefix "${urlPrefix}". Skipping.`
+      `[@rangojs/router] Circular include detected at prefix "${urlPrefix}". Skipping.`,
     );
     return {
       staticPrefix: extractStaticPrefix(urlPrefix),
@@ -89,6 +90,7 @@ function buildPrefixTreeNode(
   const patternsMap = new Map<string, string>();
   const patternsByPrefix = new Map<string, Map<string, string>>();
   const trailingSlashMap = new Map<string, TrailingSlashMode>();
+  const searchSchemasMap = new Map<string, Record<string, string>>();
   const trackedIncludes: TrackedInclude[] = [];
 
   RSCRouterContext.run(
@@ -97,6 +99,7 @@ function buildPrefixTreeNode(
       patterns: patternsMap,
       patternsByPrefix,
       trailingSlash: trailingSlashMap,
+      searchSchemas: searchSchemasMap,
       namespace: "build",
       parent: null,
       counters: {},
@@ -114,7 +117,7 @@ function buildPrefixTreeNode(
         }
         return patterns.handler() as AllUseItems[];
       });
-    }
+    },
   );
 
   // Collect route names defined in this include (routes have prefixes applied)
@@ -130,6 +133,11 @@ function buildPrefixTreeNode(
       routeTrailingSlash[name] = mode;
     }
   }
+  if (routeSearchSchemas) {
+    for (const [name, schema] of searchSchemasMap.entries()) {
+      routeSearchSchemas[name] = schema;
+    }
+  }
 
   // Capture ancestry from manifest entries' parent chains
   captureAncestry(manifest, routeAncestry);
@@ -142,7 +150,10 @@ function buildPrefixTreeNode(
         if (prerenderDefs && entry.prerenderDef) {
           prerenderDefs[name] = entry.prerenderDef;
         }
-        if (passthroughRoutes && entry.prerenderDef?.options?.passthrough === true) {
+        if (
+          passthroughRoutes &&
+          entry.prerenderDef?.options?.passthrough === true
+        ) {
           passthroughRoutes.push(name);
         }
       }
@@ -177,6 +188,7 @@ function buildPrefixTreeNode(
       prerenderDefs,
       passthroughRoutes,
       responseTypeRoutes,
+      routeSearchSchemas,
     );
 
     const existing = children[include.fullPrefix];
@@ -188,6 +200,11 @@ function buildPrefixTreeNode(
     }
   }
 
+  // Remove from visited so sibling branches can reuse the same patterns
+  // without false circular-include detection. Only ancestors in the current
+  // recursion path should trigger the cycle guard.
+  visited.delete(patterns);
+
   return {
     staticPrefix: extractStaticPrefix(urlPrefix),
     fullPrefix: urlPrefix,
@@ -218,11 +235,20 @@ function captureAncestry(
 }
 
 /**
- * Generate manifest from UrlPatterns
+ * Internal manifest result including build-pipeline-only fields.
+ * Not part of the public API — use generateManifest() for the public surface.
+ */
+export interface FullManifest extends GeneratedManifest {
+  _routeAncestry: Record<string, string[]>;
+  _prerenderDefs?: Record<string, any>;
+}
+
+/**
+ * Generate manifest from UrlPatterns (public API).
  *
- * This runs all patterns (including lazy ones) at build time to extract:
- * - The complete prefix tree for short-circuit optimization
- * - The complete route manifest for href()
+ * Returns only the public GeneratedManifest fields. Internal build pipeline
+ * consumers that need _routeAncestry or _prerenderDefs should use
+ * generateManifestFull() instead.
  *
  * @example
  * ```typescript
@@ -240,7 +266,26 @@ function captureAncestry(
 export function generateManifest<TEnv>(
   urlpatterns: UrlPatterns<TEnv, any>,
   mountIndex: number = 0,
-): GeneratedManifest & { _routeAncestry: Record<string, string[]>; _prerenderDefs?: Record<string, any> } {
+): GeneratedManifest {
+  const {
+    _routeAncestry: _,
+    _prerenderDefs: __,
+    ...publicManifest
+  } = generateManifestFull(urlpatterns, mountIndex);
+  return publicManifest;
+}
+
+/**
+ * Generate manifest with internal build-pipeline fields.
+ *
+ * Used by the Vite plugin (discover-routers via dynamic import through
+ * @rangojs/router/build), manifest-init (direct import), and trie
+ * building. Not intended for external use.
+ */
+export function generateManifestFull<TEnv>(
+  urlpatterns: UrlPatterns<TEnv, any>,
+  mountIndex: number = 0,
+): FullManifest {
   const routeManifest: Record<string, string> = {};
   const routeAncestry: Record<string, string[]> = {};
   const prefixTree: Record<string, PrefixTreeNode> = {};
@@ -250,6 +295,7 @@ export function generateManifest<TEnv>(
   const patternsMap = new Map<string, string>();
   const patternsByPrefix = new Map<string, Map<string, string>>();
   const trailingSlashMap = new Map<string, TrailingSlashMode>();
+  const searchSchemasMap = new Map<string, Record<string, string>>();
   const trackedIncludes: TrackedInclude[] = [];
 
   RSCRouterContext.run(
@@ -258,6 +304,7 @@ export function generateManifest<TEnv>(
       patterns: patternsMap,
       patternsByPrefix,
       trailingSlash: trailingSlashMap,
+      searchSchemas: searchSchemasMap,
       namespace: "build",
       parent: null,
       counters: {},
@@ -270,7 +317,7 @@ export function generateManifest<TEnv>(
       helpers.layout(MapRootLayout, () => {
         return urlpatterns.handler() as AllUseItems[];
       });
-    }
+    },
   );
 
   // Collect root-level routes and trailing slash config
@@ -281,6 +328,10 @@ export function generateManifest<TEnv>(
   for (const [name, mode] of trailingSlashMap.entries()) {
     routeTrailingSlash[name] = mode;
   }
+  const routeSearchSchemas: Record<string, Record<string, string>> = {};
+  for (const [name, schema] of searchSchemasMap.entries()) {
+    routeSearchSchemas[name] = schema;
+  }
 
   // Capture ancestry from manifest entries' parent chains
   captureAncestry(manifest, routeAncestry);
@@ -323,6 +374,7 @@ export function generateManifest<TEnv>(
       prerenderDefs,
       passthroughRoutes,
       responseTypeRoutes,
+      routeSearchSchemas,
     );
 
     const existing = prefixTree[include.fullPrefix];
@@ -337,15 +389,25 @@ export function generateManifest<TEnv>(
   return {
     prefixTree,
     routeManifest,
-    routeTrailingSlash: Object.keys(routeTrailingSlash).length > 0 ? routeTrailingSlash : undefined,
+    routeTrailingSlash:
+      Object.keys(routeTrailingSlash).length > 0
+        ? routeTrailingSlash
+        : undefined,
     prerenderRoutes: prerenderRoutes.length > 0 ? prerenderRoutes : undefined,
-    passthroughRoutes: passthroughRoutes.length > 0 ? passthroughRoutes : undefined,
-    responseTypeRoutes: Object.keys(responseTypeRoutes).length > 0 ? responseTypeRoutes : undefined,
-    generatedAt: new Date().toISOString(),
-    // Internal: routeAncestry is used only for trie building, not exported
+    passthroughRoutes:
+      passthroughRoutes.length > 0 ? passthroughRoutes : undefined,
+    responseTypeRoutes:
+      Object.keys(responseTypeRoutes).length > 0
+        ? responseTypeRoutes
+        : undefined,
+    routeSearchSchemas:
+      Object.keys(routeSearchSchemas).length > 0
+        ? routeSearchSchemas
+        : undefined,
     _routeAncestry: routeAncestry,
     // Internal: prerender handler definitions for build-time getParams() access
-    _prerenderDefs: Object.keys(prerenderDefs).length > 0 ? prerenderDefs : undefined,
+    _prerenderDefs:
+      Object.keys(prerenderDefs).length > 0 ? prerenderDefs : undefined,
   };
 }
 
@@ -359,13 +421,12 @@ export function generateManifest<TEnv>(
  * ```
  */
 export function generateManifestCode<TEnv>(
-  urlpatterns: UrlPatterns<TEnv, any>
+  urlpatterns: UrlPatterns<TEnv, any>,
 ): string {
   const manifest = generateManifest(urlpatterns);
 
   return `/**
  * Auto-generated route manifest
- * Generated at: ${manifest.generatedAt}
  *
  * DO NOT EDIT - This file is generated by @rangojs/router
  */