@rangojs/router 0.0.0-experimental.19 → 0.0.0-experimental.190fb30d

package/src/browser/types.ts

@@ -14,7 +14,6 @@ import type { RenderSegmentsOptions } from "../segment-system.js";
 export interface RscPayload<TMetadata = RscMetadata> {
   metadata?: TMetadata;
   returnValue?: ActionResult;
-  formState?: unknown;
 }
 
 /**
@@ -32,10 +31,21 @@ export type HandleData = Record<string, Record<string, unknown[]>>;
 export interface RscMetadata {
   pathname: string;
   segments: ResolvedSegment[];
+  /** Router instance ID — the current app's identity. A mismatch with the
+   *  client's id (sent as _rsc_rid) is detected server-side and answered with
+   *  X-RSC-Reload (full document load), so the client never swaps apps
+   *  in-session; within a session this always equals the current app. */
+  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>;
   /**
@@ -55,6 +65,27 @@ 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;
+  /**
+   * Max entries in the client-side in-memory prefetch cache (FIFO eviction).
+   * Sent on initial render so the browser can configure its cache capacity.
+   */
+  prefetchCacheSize?: number;
+  /**
+   * Max concurrent speculative prefetch requests on the client.
+   * Sent on initial render so the browser can configure its prefetch queue.
+   */
+  prefetchConcurrency?: number;
+  /**
+   * Server-resolved rango state cookie name (`{prefix}_{routerId}`). The client
+   * reads it verbatim and binds the rango state cookie to it; composition
+   * happens only server-side.
+   */
+  stateCookieName?: string;
   /**
    * Theme configuration from router.
    * Included when theme is enabled in router config.
@@ -65,10 +96,22 @@ export interface RscMetadata {
    * Included when theme is enabled in router config.
    */
   initialTheme?: Theme;
+  /** 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 };
+  /**
+   * Whether the client should hydrate inside React.StrictMode. Carried on the
+   * initial full-render payload only; the browser entry reads it once at
+   * hydration. Defaults to true on the client when omitted.
+   */
+  strictMode?: boolean;
+  /**
+   * Server-side redirect with optional state (for partial requests).
+   * `external: true` (from redirect(url, { external: true })) tells the client
+   * to hard-navigate to an off-host target instead of validating same-origin.
+   */
+  redirect?: { url: string; external?: boolean };
   /** Server-set location state to include in history.pushState */
   locationState?: Record<string, unknown>;
 }
@@ -169,6 +212,15 @@ export interface TrackedActionState {
   result: unknown | null;
 }
 
+/**
+ * The value returned by {@link useAction} when called without a selector.
+ *
+ * This is the stable, public name for the action-state shape; consumers can
+ * name it in their own signatures (e.g. a wrapper hook). It aliases the
+ * internal {@link TrackedActionState}.
+ */
+export type ActionState = TrackedActionState;
+
 /**
  * Listener for action state changes
  *
@@ -210,6 +262,15 @@ 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;
+  };
 }
 
 /**
@@ -227,6 +288,25 @@ export type HistoryState =
 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.
@@ -278,8 +358,14 @@ export interface RouterInstance {
   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;
+  /**
+   * Prefetch a URL for faster client-side transition.
+   *
+   * Pass `{ key: ":source" }` to source-scope the prefetch cache entry (parity
+   * with `<Link prefetchKey=":source">`) when the target's response can differ
+   * by source page.
+   */
+  prefetch(url: string, options?: { key?: ":source" }): void;
   /** Go back in browser history */
   back(): void;
   /** Go forward in browser history */
@@ -308,7 +394,13 @@ export type ReadonlyURLSearchParams = Omit<
 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: (
@@ -365,22 +457,59 @@ export interface NavigationStore {
   // History-based segment cache (for back/forward navigation and partial merging)
   getHistoryKey(): string;
   setHistoryKey(key: string): void;
+  /** Monotonic token of the most recently committed navigation. */
+  getNavInstance(): number;
+  /** Nav-instance token recorded on a cache entry (undefined if absent). */
+  getCacheEntryInstance(historyKey: string): number | undefined;
   cacheSegmentsForHistory(
     historyKey: string,
     segments: ResolvedSegment[],
     handleData?: HandleData,
   ): void;
-  getCachedSegments(
-    historyKey: string,
-  ):
-    | { segments: ResolvedSegment[]; stale: boolean; handleData?: HandleData }
+  getCachedSegments(historyKey: string):
+    | {
+        segments: ResolvedSegment[];
+        stale: boolean;
+        handleData?: HandleData;
+        routerId?: string;
+        /**
+         * True when the entry's handle data is incomplete (a deferred Meta was
+         * still pending at navigate-away). A popstate return must revalidate with
+         * a FULL re-render so the server re-streams handles.
+         */
+        handlesPending?: boolean;
+      }
     | undefined;
   hasHistoryCache(historyKey: string): boolean;
-  updateCacheHandleData(historyKey: string, handleData: HandleData): void;
+  /**
+   * Update only the handleData (and optionally the stale / handlesPending flags)
+   * of an existing cache entry. When a flag is omitted the entry's current value
+   * is preserved. `stale=true` marks a single entry stale so a popstate return
+   * revalidates it; `handlesPending=true` additionally forces that revalidation
+   * to be a full re-render (so a deferred Meta re-streams).
+   */
+  updateCacheHandleData(
+    historyKey: string,
+    handleData: HandleData,
+    stale?: boolean,
+    handlesPending?: boolean,
+  ): void;
+  /**
+   * Owner-guarded variant of updateCacheHandleData: writes only when the entry
+   * is still owned by `ownerInstance`. Folds the caller's separate ownership
+   * probe and write into one historyCache scan for the per-yield streaming path.
+   */
+  updateCacheHandleDataIfOwned(
+    historyKey: string,
+    handleData: HandleData,
+    ownerInstance: number,
+    stale?: boolean,
+    handlesPending?: boolean,
+  ): void;
   markCacheAsStale(): void;
+  markHistoryCacheStale(): void;
   markCacheAsStaleAndBroadcast(): void;
   clearHistoryCache(): void;
-  broadcastCacheInvalidation(): void;
 
   // Cross-tab refresh callback (set by navigation bridge)
   setCrossTabRefreshCallback(callback: () => void): void;
@@ -389,6 +518,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;
@@ -419,6 +552,8 @@ 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;
 }
@@ -430,6 +565,15 @@ export interface FetchPartialResult {
   payload: RscPayload;
   /** Promise that resolves when the response stream is fully consumed */
   streamComplete: Promise<void>;
+  /**
+   * True only when this payload came from a prefetch-cache hit whose stream had
+   * ALREADY fully drained at fetch time (the route was fully prefetched). The
+   * commit then runs in a startTransition so loading()/Suspense content — already
+   * resolved — swaps in directly without flashing a fallback. A partially-warmed
+   * (still-streaming) prefetch hit and a cold fetch leave this false so their
+   * fallbacks stream as usual.
+   */
+  fullyPrefetched?: boolean;
 }
 
 /**
@@ -487,6 +631,10 @@ 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;
 }
 
 /**

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

@@ -1,29 +1,56 @@
+import {
+  resolveSameOriginRedirect,
+  resolveExternalRedirect,
+} from "../redirect-origin.js";
+
 /**
  * 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.
  *
+ * Thin wrapper over the shared {@link resolveSameOriginRedirect} rule (also used
+ * by the server guard in `rsc/redirect-guard.ts`) so client and server enforce
+ * the identical same-origin contract. Adds the client-side `console.error` on a
+ * block; the resolver itself stays pure.
+ *
  * @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;
+  const resolved = resolveSameOriginRedirect(url, currentOrigin);
+  if (resolved === null) {
+    console.error(
+      `[rango] Redirect blocked: cross-origin or invalid target "${url}"`,
+    );
+  }
+  return resolved;
+}
+
+/**
+ * Validate an explicit off-origin redirect (`redirect(url, { external: true })`)
+ * the client is about to hard-navigate to via `window.location.assign()`.
+ *
+ * Thin wrapper over the shared {@link resolveExternalRedirect} rule (also used by
+ * the server guard in `rsc/redirect-guard.ts`) so client and server enforce the
+ * identical contract: `external` allows an off-origin target but only an
+ * http(s) scheme. This stops a forged or mistaken external payload carrying a
+ * `javascript:`/`data:` URL from turning `location.assign` into a scriptable
+ * navigation. Adds the client-side `console.error` on a block; the resolver
+ * itself stays pure.
+ *
+ * @returns The normalized URL string on success, or null if blocked.
+ */
+export function validateExternalRedirect(
+  url: string,
+  currentOrigin: string,
+): string | null {
+  const resolved = resolveExternalRedirect(url, currentOrigin);
+  if (resolved === null) {
+    console.error(
+      `[rango] External redirect blocked: non-http(s) target "${url}"`,
+    );
   }
+  return resolved;
 }

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.
+  }
+}