@rangojs/router 0.5.1 → 0.6.0

package/src/browser/react/use-search-params.ts

@@ -1,34 +1,129 @@
 "use client";
 
-import { useContext, useState, useEffect, useRef } from "react";
+import {
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import { NavigationStoreContext } from "./context.js";
 import type { ReadonlyURLSearchParams } from "../types.js";
 
 /**
- * Hook to access the current URL search params.
+ * Accepted shapes for the setter: a full replacement for the search string.
+ * Record values are stringified; array values append one entry per element;
+ * null/undefined values are skipped (ergonomic conditional spreads).
+ */
+export type SearchParamsInit =
+  | string
+  | URLSearchParams
+  | ReadonlyURLSearchParams
+  | Record<
+      string,
+      | string
+      | number
+      | boolean
+      | readonly (string | number | boolean)[]
+      | null
+      | undefined
+    >;
+
+export interface SetSearchParamsOptions {
+  /** Replace the current history entry instead of pushing (default false). */
+  replace?: boolean;
+  /** Scroll behavior for the navigation (default: router default, scroll). */
+  scroll?: boolean;
+  /**
+   * Set false to skip the server fetch and only update the URL (default
+   * true). Purely client-derived search state (open accordions, view modes)
+   * needs no loader re-run; all location-aware hooks still update. Same
+   * contract as NavigateOptions.revalidate — it only applies because the
+   * setter never changes the pathname.
+   */
+  revalidate?: boolean;
+}
+
+export type SetSearchParams = (
+  init: SearchParamsInit | ((prev: URLSearchParams) => SearchParamsInit),
+  options?: SetSearchParamsOptions,
+) => Promise<void>;
+
+function normalizeInit(init: SearchParamsInit): URLSearchParams {
+  if (typeof init === "string") return new URLSearchParams(init);
+  if (init instanceof URLSearchParams) return new URLSearchParams(init);
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(init)) {
+    if (value == null) continue;
+    if (Array.isArray(value)) {
+      for (const entry of value) params.append(key, String(entry));
+    } else {
+      params.append(key, String(value));
+    }
+  }
+  return params;
+}
+
+/**
+ * Hook to read and write the current URL search params
+ * (React Router-style tuple).
  *
- * Returns a read-only URLSearchParams object from the committed location.
- * Updates when navigation completes, not during pending navigation.
+ * The first element is a read-only URLSearchParams from the COMMITTED
+ * location — it updates when navigation completes, not during a pending
+ * navigation. During document SSR it carries the LIVE request's search (the
+ * SSR store is seeded from SSRRenderOptions.search), and the browser's
+ * first render seeds from its own store location (window.location) — the
+ * same URL, so hydration matches. Ppr capture/resume renders seed the SHELL
+ * KEY's search (sorted, cache.searchParams filter applied — search is part
+ * of shell identity like every other ppr key), so static-part reads bake
+ * markup consistent with the shell's own key. Two edges: a param EXCLUDED
+ * by cache.searchParams is absent in shell renders but present in the
+ * browser (exclusion declares "does not affect markup" — reading one
+ * anyway hydration-mismatches), and toString() renders sorted order while
+ * the browser holds the raw URL order.
  *
- * Note: During SSR the search params are not available (the server only sends
- * the pathname). The hook returns empty params during SSR and syncs from
- * the browser URL on mount.
+ * The setter REPLACES the whole search string (React Router semantics) and
+ * navigates to the current pathname with the new params — a same-route
+ * navigation, so route loaders re-evaluate per their revalidate() contract
+ * and the commit holds previous content (the same-structure transition
+ * lane). Pass a function to merge with the current params: it receives a
+ * MUTABLE copy read at call time. The hash is dropped, like React Router.
  *
  * @example
  * ```tsx
- * const searchParams = useSearchParams();
- * const query = searchParams.get("q"); // "react"
- * const page = searchParams.get("page"); // "2"
+ * const [searchParams, setSearchParams] = useSearchParams();
+ * const category = searchParams.get("category");
+ *
+ * // Replace the whole search string
+ * setSearchParams({ category: "electronics" });
+ *
+ * // Merge with what's there now
+ * setSearchParams((prev) => {
+ *   prev.set("page", "2");
+ *   return prev;
+ * });
+ *
+ * // Filter UIs usually want replace + preserved scroll
+ * setSearchParams({ category: "home" }, { replace: true, scroll: false });
  * ```
  */
-export function useSearchParams(): ReadonlyURLSearchParams {
+export function useSearchParams(): [ReadonlyURLSearchParams, SetSearchParams] {
   const ctx = useContext(NavigationStoreContext);
 
-  const [searchParams, setSearchParams] = useState<ReadonlyURLSearchParams>(
-    () => new URLSearchParams(),
-  );
+  // Seed from the store location on BOTH sides (mirrors usePathname): the
+  // SSR store carries the live request's search, the browser store carries
+  // window.location — same URL, so the hydration renders agree. No ctx
+  // (no provider) seeds empty.
+  const [searchParams, setSearchParamsState] =
+    useState<ReadonlyURLSearchParams>(() => {
+      const location = ctx?.eventController.getState().location as
+        | URL
+        | undefined;
+      return new URLSearchParams(location?.searchParams);
+    });
 
-  const prevSearch = useRef("");
+  const prevSearch = useRef(searchParams.toString());
 
   useEffect(() => {
     if (!ctx) return;
@@ -38,7 +133,7 @@ export function useSearchParams(): ReadonlyURLSearchParams {
       const nextSearch = location.searchParams.toString();
       if (nextSearch !== prevSearch.current) {
         prevSearch.current = nextSearch;
-        setSearchParams(new URLSearchParams(nextSearch));
+        setSearchParamsState(new URLSearchParams(nextSearch));
       }
     };
 
@@ -47,5 +142,33 @@ export function useSearchParams(): ReadonlyURLSearchParams {
     return ctx.eventController.subscribe(update);
   }, []);
 
-  return searchParams;
+  // Reads the committed location at CALL time (not the render closure), so a
+  // functional init always merges against fresh params even when the caller's
+  // closure is stale.
+  const setSearchParams = useCallback<SetSearchParams>((init, options) => {
+    if (!ctx) {
+      throw new Error(
+        "useSearchParams setter must be used within NavigationProvider",
+      );
+    }
+    const location = ctx.eventController.getState().location as URL;
+    const resolved =
+      typeof init === "function"
+        ? init(new URLSearchParams(location.searchParams))
+        : init;
+    const search = normalizeInit(resolved).toString();
+    const url = search ? `${location.pathname}?${search}` : location.pathname;
+    return ctx.navigate(url, {
+      replace: options?.replace ?? false,
+      ...(options?.scroll !== undefined ? { scroll: options.scroll } : {}),
+      ...(options?.revalidate !== undefined
+        ? { revalidate: options.revalidate }
+        : {}),
+    });
+  }, []);
+
+  return useMemo(
+    () => [searchParams, setSearchParams],
+    [searchParams, setSearchParams],
+  );
 }

package/src/browser/rsc-router.tsx

@@ -8,6 +8,7 @@ import {
   generateHistoryKey,
 } from "./navigation-store.js";
 import { createEventController } from "./event-controller.js";
+import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
 import { validateRedirectOrigin } from "./validate-redirect-origin.js";
 import { createNavigationClient } from "./navigation-client.js";
 import { createServerActionBridge } from "./server-action-bridge.js";
@@ -38,6 +39,7 @@ import {
 } from "./intercept-utils.js";
 import { createAppShellRef } from "./app-shell.js";
 import { bootLog, IS_BROWSER_DEBUG } from "./logging.js";
+import { setActiveInterceptTargets } from "../client-urls/navigation.js";
 
 // Vite HMR types are provided by vite/client
 
@@ -205,6 +207,11 @@ export async function initBrowserApp(
   const version = initialPayload.metadata?.version;
   initRangoState(version ?? "0", initialPayload.metadata?.stateCookieName);
 
+  // Seed the intercept-target set for the initial location so the FIRST
+  // clientUrls navigation already declines intercepted targets (refreshed on
+  // every commit in partial-update.ts).
+  setActiveInterceptTargets(initialPayload.metadata?.interceptTargets);
+
   // Create navigation store with history-based caching
   const store = createNavigationStore({
     initialLocation: window.location,
@@ -268,6 +275,43 @@ export async function initBrowserApp(
     // Update the initial cache entry with the processed handleData
     // The cache entry was created by createNavigationStore but without handleData
     store.updateCacheHandleData(initialHistoryKey, lastHandleData);
+
+    // Late handle channel: pushes from streaming loader bodies that missed the
+    // handler barrier (ctx.handle() writes mid-body). Consumed NON-BLOCKING —
+    // hydration must not wait on loader bodies — and applied through the same
+    // controller/cache path as the initial snapshot, so useHandle readers
+    // re-render as meta/breadcrumbs stream in.
+    const lateGenerator = initialPayload.metadata?.handlesLate;
+    if (lateGenerator) {
+      void (async () => {
+        try {
+          // Never apply before React commits hydration — a pre-commit
+          // application mutates the state useHandle initializers read during
+          // the hydration render (mismatch). Yields buffer in the generator
+          // meanwhile; nothing is lost.
+          await hydrationCommitted;
+          for await (const rawLateData of lateGenerator) {
+            // Handles are async by design: a push(promise) value resolves
+            // whenever it resolves — only SSR'd handles are awaited server-
+            // side. The main document snapshot arrives server-resolved
+            // (resolvedHandleStream); this late channel is raw, so resolve
+            // deferred values here exactly like the nav lane's processHandles
+            // does before applying.
+            const lateData = await resolveDeferredHandleValues(rawLateData);
+            bootLog("handles: late push applied", {
+              segments: Object.keys(lateData),
+            });
+            eventController.setHandleData(
+              lateData,
+              initialPayload.metadata?.matched,
+            );
+            store.updateCacheHandleData(initialHistoryKey, lateData);
+          }
+        } catch (err) {
+          console.error("[rsc-router] Error consuming late handles:", err);
+        }
+      })();
+    }
   } else {
     bootLog("handles: none in payload");
   }
@@ -568,6 +612,18 @@ export async function initBrowserApp(
 // re-runs the root effect; the second flush is not a second hydration).
 let hydrationCommitLogged = false;
 
+// Hydration-commit barrier for the late handle channel. useHandle's useState
+// initializer reads the eventController's LIVE state during the hydration
+// render, so applying a late handle update BEFORE hydration commits changes
+// that state out from under React — the classic "external changing data"
+// hydration mismatch (seen when a loader's push lost the handler-barrier race
+// by milliseconds and its late yield landed mid-hydration). The root effect
+// below resolves this; the late consumer awaits it before applying anything.
+let resolveHydrationCommitted!: () => void;
+const hydrationCommitted: Promise<void> = new Promise((resolve) => {
+  resolveHydrationCommitted = resolve;
+});
+
 /**
  * Get the browser app context. Throws if initBrowserApp hasn't been called.
  */
@@ -643,6 +699,9 @@ export function Rango(_props: RangoProps): React.ReactElement {
       hydrationCommitLogged = true;
       bootLog("hydration commit (root effect flushed)");
     }
+    // Release the late handle channel (see hydrationCommitted above).
+    // StrictMode double-invoke: resolving twice is a no-op.
+    resolveHydrationCommitted();
     return cleanupPrefetch;
   }, [bridge, linkInterceptionEnabled]);
 

package/src/browser/server-action-bridge.ts

@@ -37,6 +37,8 @@ import {
 import { mergeLocationState } from "./history-state.js";
 import { classifyActionOutcome } from "./action-coordinator.js";
 import { getAppVersion } from "./app-version.js";
+import { collectClientRevalidationDecisions } from "../client-urls/navigation.js";
+import { CLIENT_REVALIDATION_HEADER } from "../client-urls/revalidation-protocol.js";
 
 // Polyfill Symbol.dispose/asyncDispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -294,12 +296,36 @@ export function createServerActionBridge(
       const onHandleAbort = () => fetchAbort.abort();
       handle.signal.addEventListener("abort", onHandleAbort, { once: true });
 
+      // Client-run per-loader revalidation for the action follow-up render:
+      // run the held clientUrls route's revalidate() predicates with the
+      // action context and ship their decisions. Fails soft to null (locked
+      // server defaults).
+      let clientRevalidation: string | null = null;
+      try {
+        const actionPageUrl = new URL(
+          segmentState.currentUrl,
+          window.location.origin,
+        );
+        clientRevalidation = collectClientRevalidationDecisions({
+          currentUrl: actionPageUrl,
+          nextUrl: actionPageUrl,
+          isAction: true,
+          actionId: id,
+          stale: false,
+        });
+      } catch {
+        clientRevalidation = null;
+      }
+
       // Send action request with stream tracking
       const responsePromise = fetch(url, {
         method: "POST",
         headers: {
           "rsc-action": id,
           "X-RSC-Router-Client-Path": segmentState.currentUrl,
+          ...(clientRevalidation && {
+            [CLIENT_REVALIDATION_HEADER]: clientRevalidation,
+          }),
           ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
           ...(interceptSourceUrl && {
             "X-RSC-Router-Intercept-Source": interceptSourceUrl,

package/src/browser/types.ts

@@ -54,10 +54,25 @@ export interface RscMetadata {
    * Slots are used for intercepting routes during soft navigation
    */
   slots?: Record<string, SlotState>;
+  /**
+   * Intercept TARGET route names reachable from this location as a
+   * navigation origin. The browser-local clientUrls matcher declines its
+   * optimistic presentation for these targets (the canonical response would
+   * commit the intercept over the ORIGIN page, so destination loading would
+   * flash and revert). Missing/empty means no targets.
+   */
+  interceptTargets?: string[];
   /** Root layout component for browser-side re-renders */
   rootLayout?: ComponentType<{ children: ReactNode }>;
   /** Handle data accumulated across route segments (async generator that yields on each push) */
   handles?: AsyncGenerator<HandleData, void, unknown>;
+  /**
+   * Document-lane late handle channel: pushes landing after the handler
+   * barrier (streaming loader ctx.use(Handle) writes). Consumed non-blocking
+   * post-hydration (rsc-router.tsx); `handles` above is drained in blocking
+   * positions and must complete at the handler barrier.
+   */
+  handlesLate?: AsyncGenerator<HandleData, void, unknown>;
   /** Cached handle data (for back/forward navigation from cache) */
   cachedHandleData?: HandleData;
   /**
@@ -531,6 +546,13 @@ export interface FetchPartialOptions {
   signal?: AbortSignal;
   /** If true, this is a stale cache revalidation request - server should force revalidators */
   staleRevalidation?: boolean;
+  /**
+   * Encoded client-run per-loader revalidation decisions
+   * (clientUrls revalidate() predicates executed in the browser); sent as
+   * X-Rango-Client-Reval and honored only by materialized client-urls loader
+   * stubs. Null/absent = locked server defaults.
+   */
+  clientRevalidation?: string | null;
   interceptSourceUrl?: string;
   /** RSC version for cache invalidation detection */
   version?: string;

package/src/build/merge-full-manifests.ts

@@ -0,0 +1,161 @@
+import type { FullManifest, PrefixTreeNode } from "./generate-manifest.js";
+
+function clonePrefixNode(node: PrefixTreeNode): PrefixTreeNode {
+  return {
+    staticPrefix: node.staticPrefix,
+    fullPrefix: node.fullPrefix,
+    ...(node.namePrefix === undefined ? {} : { namePrefix: node.namePrefix }),
+    children: clonePrefixTree(node.children),
+    routes: [...node.routes],
+  };
+}
+
+function clonePrefixTree(
+  tree: Record<string, PrefixTreeNode>,
+): Record<string, PrefixTreeNode> {
+  return Object.fromEntries(
+    Object.entries(tree).map(([prefix, node]) => [
+      prefix,
+      clonePrefixNode(node),
+    ]),
+  );
+}
+
+function removeRoutesFromPrefixTree(
+  tree: Record<string, PrefixTreeNode>,
+  routeNames: ReadonlySet<string>,
+): Record<string, PrefixTreeNode> {
+  return Object.fromEntries(
+    Object.entries(tree).map(([prefix, node]) => [
+      prefix,
+      {
+        staticPrefix: node.staticPrefix,
+        fullPrefix: node.fullPrefix,
+        ...(node.namePrefix === undefined
+          ? {}
+          : { namePrefix: node.namePrefix }),
+        children: removeRoutesFromPrefixTree(node.children, routeNames),
+        routes: node.routes.filter((name) => !routeNames.has(name)),
+      },
+    ]),
+  );
+}
+
+function mergePrefixTrees(
+  earlier: Record<string, PrefixTreeNode>,
+  later: Record<string, PrefixTreeNode>,
+): Record<string, PrefixTreeNode> {
+  const merged = clonePrefixTree(earlier);
+  for (const [prefix, laterNode] of Object.entries(later)) {
+    const earlierNode = merged[prefix];
+    if (!earlierNode) {
+      merged[prefix] = clonePrefixNode(laterNode);
+      continue;
+    }
+
+    merged[prefix] = {
+      staticPrefix: laterNode.staticPrefix,
+      fullPrefix: laterNode.fullPrefix,
+      ...(laterNode.namePrefix === undefined
+        ? {}
+        : { namePrefix: laterNode.namePrefix }),
+      children: mergePrefixTrees(earlierNode.children, laterNode.children),
+      routes: [...new Set([...earlierNode.routes, ...laterNode.routes])],
+    };
+  }
+  return merged;
+}
+
+function mergeRouteRecord<T>(
+  earlier: Record<string, T> | undefined,
+  later: Record<string, T> | undefined,
+  overwrittenRoutes: ReadonlySet<string>,
+  cloneValue: (value: T) => T,
+): Record<string, T> | undefined {
+  const merged: Record<string, T> = {};
+  for (const [name, value] of Object.entries(earlier ?? {})) {
+    if (!overwrittenRoutes.has(name)) merged[name] = cloneValue(value);
+  }
+  for (const [name, value] of Object.entries(later ?? {})) {
+    merged[name] = cloneValue(value);
+  }
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
+function mergeRouteList(
+  earlier: readonly string[] | undefined,
+  later: readonly string[] | undefined,
+  overwrittenRoutes: ReadonlySet<string>,
+): string[] | undefined {
+  const merged = [
+    ...(earlier ?? []).filter((name) => !overwrittenRoutes.has(name)),
+    ...(later ?? []),
+  ];
+  const unique = [...new Set(merged)];
+  return unique.length > 0 ? unique : undefined;
+}
+
+/** Merge ordered per-mount manifests without mutating any input manifest. */
+export function mergeFullManifests(
+  manifests: readonly FullManifest[],
+): FullManifest {
+  let merged: FullManifest = {
+    prefixTree: {},
+    routeManifest: {},
+  };
+
+  for (const manifest of manifests) {
+    const overwrittenRoutes = new Set(Object.keys(manifest.routeManifest));
+    const prefixTreeWithoutOverwrites = removeRoutesFromPrefixTree(
+      merged.prefixTree,
+      overwrittenRoutes,
+    );
+
+    merged = {
+      prefixTree: mergePrefixTrees(
+        prefixTreeWithoutOverwrites,
+        manifest.prefixTree,
+      ),
+      routeManifest: {
+        ...merged.routeManifest,
+        ...manifest.routeManifest,
+      },
+      routeTrailingSlash: mergeRouteRecord(
+        merged.routeTrailingSlash,
+        manifest.routeTrailingSlash,
+        overwrittenRoutes,
+        (value) => value,
+      ),
+      prerenderRoutes: mergeRouteList(
+        merged.prerenderRoutes,
+        manifest.prerenderRoutes,
+        overwrittenRoutes,
+      ),
+      passthroughRoutes: mergeRouteList(
+        merged.passthroughRoutes,
+        manifest.passthroughRoutes,
+        overwrittenRoutes,
+      ),
+      responseTypeRoutes: mergeRouteRecord(
+        merged.responseTypeRoutes,
+        manifest.responseTypeRoutes,
+        overwrittenRoutes,
+        (value) => value,
+      ),
+      routeSearchSchemas: mergeRouteRecord(
+        merged.routeSearchSchemas,
+        manifest.routeSearchSchemas,
+        overwrittenRoutes,
+        (value) => ({ ...value }),
+      ),
+      _prerenderDefs: mergeRouteRecord(
+        merged._prerenderDefs,
+        manifest._prerenderDefs,
+        overwrittenRoutes,
+        (value) => value,
+      ),
+    };
+  }
+
+  return merged;
+}