@rangojs/router 0.5.2 → 0.7.0

package/skills/theme/SKILL.md

@@ -33,16 +33,15 @@ const router = createRouter<Env>({
 });
 ```
 
-## Server (in loaders/middleware)
+## Server (in handlers/middleware)
 
 ```typescript
-import { createLoader } from "@rangojs/router";
 import type { Middleware } from "@rangojs/router";
 
-// In a loader
-export const SettingsLoader = createLoader(async (ctx) => {
+// In a handler
+path("/settings", (ctx) => {
   const currentTheme = ctx.theme; // read from cookie
-  return { theme: currentTheme };
+  return <SettingsPage theme={currentTheme} />;
 });
 
 // In middleware
@@ -53,6 +52,10 @@ export const themeMiddleware: Middleware = async (ctx, next) => {
 };
 ```
 
+Theme accessors are handler/middleware-only — the loader context has no
+`ctx.theme`/`ctx.setTheme`. A loader that needs the theme reads the cookie
+directly via `cookies()` (loaders always run fresh, so the read is safe).
+
 ## Client
 
 ```tsx

package/src/bin/rango.ts

@@ -144,7 +144,10 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
       if (/\bcreateRouter\s*[<(]/.test(source)) {
         routerFiles.push(filePath);
       }
-      if (source.includes("urls(")) {
+      // Both spellings, matching the writer's own gate: "clientUrls(" does
+      // NOT contain the lowercase "urls(" token (capital U), so a
+      // clientUrls-only module fails the server-token sniff alone.
+      if (source.includes("urls(") || source.includes("clientUrls(")) {
         urlsFiles.push(filePath);
       }
     } catch (err) {
@@ -255,8 +258,9 @@ async function runRuntimeDiscovery(args: string[], configFile?: string) {
       if (/\bcreateRouter\s*[<(]/.test(source)) {
         routerEntries.push(filePath);
       }
-      // Also generate per-module types for urls files
-      if (source.includes("urls(")) {
+      // Also generate per-module types for urls files. Both spellings — a
+      // clientUrls-only module has no lowercase "urls(" token (capital U).
+      if (source.includes("urls(") || source.includes("clientUrls(")) {
         writePerModuleRouteTypesForFile(filePath);
       }
     } catch {

package/src/browser/navigation-bridge.ts

@@ -48,6 +48,7 @@ import {
   schedulePrefetchWhenRouterIdle,
 } from "./prefetch/loader.js";
 import type { PrefetchStrategy } from "../router/prefetch-default.js";
+import { beginClientUrlNavigation } from "../client-urls/navigation.js";
 
 // Polyfill Symbol.dispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -342,6 +343,10 @@ export function createNavigationBridge(
         state: resolvedState,
         skipLoadingState: false,
       });
+      const clientUrlPresentation = beginClientUrlNavigation(
+        targetUrl,
+        tx.handle.signal,
+      );
 
       // REVALIDATE: Fetch fresh data from server
       try {
@@ -422,6 +427,7 @@ export function createNavigationBridge(
         console.error("[Browser] Unprocessable navigation response:", error);
         emitNavigationError(onUpdate, error, url);
       } finally {
+        clientUrlPresentation?.clear();
         tx[Symbol.dispose]();
       }
     },

package/src/browser/navigation-client.ts

@@ -14,6 +14,7 @@ import {
 } from "./logging.js";
 import { getRangoState } from "./rango-state.js";
 import { isActionFenceActive } from "./action-fence.js";
+import { CLIENT_REVALIDATION_HEADER } from "../client-urls/revalidation-protocol.js";
 import {
   expandPayloadFragments,
   SEGMENT_FRAGMENT_CAPABILITY_HEADER,
@@ -79,6 +80,7 @@ export function createNavigationClient(
         previousUrl,
         signal,
         staleRevalidation,
+        clientRevalidation,
         interceptSourceUrl,
         version,
         routerId,
@@ -261,6 +263,9 @@ export function createNavigationClient(
             ...(fragmentRecovery && {
               [SEGMENT_FRAGMENT_RECOVERY_HEADER]: "1",
             }),
+            ...(clientRevalidation && {
+              [CLIENT_REVALIDATION_HEADER]: clientRevalidation,
+            }),
             ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
             ...(interceptSourceUrl && {
               "X-RSC-Router-Intercept-Source": interceptSourceUrl,

package/src/browser/partial-update.ts

@@ -30,6 +30,10 @@ import {
   validateExternalRedirect,
 } from "./validate-redirect-origin.js";
 import type { NavigationUpdate } from "./types.js";
+import {
+  collectClientRevalidationDecisions,
+  setActiveInterceptTargets,
+} from "../client-urls/navigation.js";
 
 function toScrollPayload(
   scroll: boolean | undefined,
@@ -187,6 +191,22 @@ export function createPartialUpdater(
       );
     }
 
+    // Client-run per-loader revalidation: execute the held clientUrls route's
+    // revalidate() predicates now and ship their decisions with the request.
+    // Fails soft to null (locked server defaults) when no group is active or
+    // URLs do not parse.
+    let clientRevalidation: string | null = null;
+    try {
+      clientRevalidation = collectClientRevalidationDecisions({
+        currentUrl: new URL(previousUrl, window.location.origin),
+        nextUrl: new URL(url, window.location.origin),
+        isAction: false,
+        stale: mode.type === "stale-revalidation",
+      });
+    } catch {
+      clientRevalidation = null;
+    }
+
     let fetchResult: Awaited<ReturnType<NavigationClient["fetchPartial"]>>;
     fetchResult = await client.fetchPartial({
       targetUrl: url,
@@ -194,6 +214,7 @@ export function createPartialUpdater(
       previousUrl,
       staleRevalidation:
         mode.type === "stale-revalidation" || segments.length === 0,
+      clientRevalidation,
       version: getVersion(),
       routerId: store.getRouterId?.(),
     });
@@ -467,6 +488,23 @@ export function createPartialUpdater(
         payload.metadata?.slots,
       );
 
+      // Same-structure revalidation: every segment this commit will render
+      // already exists on screen (by id) — the navigation mounts nothing new,
+      // it only refreshes what the user is looking at. The hold this enables
+      // manifests on SEARCH-only navs (filters, tabs — search is never in the
+      // segment key, so the subtree reconciles); a PARAM nav outside a
+      // transition() scope still remounts via its param-bearing key
+      // (segment-system.tsx) and reveals its fresh skeleton inside the
+      // transition, unchanged. Compared against the CURRENT page's cache, not
+      // cachedSegs: for a popstate restore cachedSegs is the TARGET's history
+      // cache, which says nothing about what is visible now. Restricted to
+      // plain navigations — leave-intercept must close its modal urgently,
+      // and action/stale modes have their own transition branch.
+      const onScreenIds = new Set(getCurrentCachedSegments().map((s) => s.id));
+      const isSameStructureNav =
+        mode.type === "navigate" &&
+        reconciled.segments.every((s) => onScreenIds.has(s.id));
+
       const effectiveInterceptSource =
         interceptSourceUrl || segmentState.currentUrl;
       if (mode.type !== "action" && mode.type !== "stale-revalidation") {
@@ -523,6 +561,13 @@ export function createPartialUpdater(
           all: reconciled.segments.map((s) => s.id),
         });
       }
+      // Refresh the browser-local intercept-target set for the location being
+      // committed — the clientUrls matcher declines optimistic presentation
+      // for targets an intercept would claim from here. Back/forward commits
+      // served purely from the history cache keep the previous set (no fresh
+      // metadata); popstate navigations get no optimistic presentation anyway.
+      setActiveInterceptTargets(payload.metadata?.interceptTargets);
+
       const scrollPayload = toScrollPayload(navScroll);
 
       if (mode.type === "action" || mode.type === "stale-revalidation") {
@@ -547,15 +592,22 @@ export function createPartialUpdater(
             scroll: scrollPayload,
           });
         });
-      } else if (fullyPrefetched) {
-        // Fully-prefetched nav: the payload is fully resolved (forceAwait
-        // above), so commit inside a transition to hold the current UI across
-        // the synchronous resolution — no fallback flash. No addTransitionType:
-        // this is the React content-hold, not a view transition. Deliberate
-        // trade-off (#622 introduced, #624 reverted, then reinstated): a client
-        // component that suspends during its FIRST render (use() of a promise
-        // created at mount — see ClientMountSuspense in the e2e test-app) under
-        // an ALREADY-REVEALED boundary holds the old content until it resolves
+      } else if (fullyPrefetched || isSameStructureNav) {
+        // Content-hold commit, two triggers. Fully-prefetched nav: the payload
+        // is fully resolved (forceAwait above), so the transition commits
+        // synchronously — no fallback flash. Same-structure nav: the re-run
+        // loaders are still streaming, and an urgent commit would re-suspend
+        // the ALREADY-REVEALED boundaries — replacing visible content with its
+        // own fallback for the loader's full duration (the PLP filter-change
+        // flash). Inside a transition React holds the current UI until the
+        // suspended data lands, the action treatment; nothing new mounts (by
+        // the isSameStructureNav definition), so no fallback is being withheld
+        // from a first paint. No addTransitionType: this is the React
+        // content-hold, not a view transition. Deliberate trade-off (#622
+        // introduced, #624 reverted, then reinstated): a client component that
+        // suspends during its FIRST render (use() of a promise created at
+        // mount — see ClientMountSuspense in the e2e test-app) under an
+        // ALREADY-REVEALED boundary holds the old content until it resolves
         // instead of revealing that boundary's fallback; its render happens
         // pre-commit inside the transition, so userland effects cannot run
         // first. Boundaries newly mounted by this nav still reveal their
@@ -568,10 +620,10 @@ export function createPartialUpdater(
           });
         });
       } else {
-        // Cold/partially-prefetched nav: normal commit so fallbacks stream
-        // like a first load and the click has visible feedback. Explicit
-        // transition() routes keep the content-hold via the hasTransition
-        // branch above (the opt-in).
+        // Cold/partially-prefetched nav that mounts NEW segments: normal
+        // commit so fallbacks stream like a first load and the click has
+        // visible feedback. Explicit transition() routes keep the
+        // content-hold via the hasTransition branch above (the opt-in).
         onUpdate({
           root: newTree,
           metadata: payload.metadata!,

package/src/browser/react/use-router.ts

@@ -2,6 +2,7 @@
 
 import { useContext, useMemo } from "react";
 import { NavigationStoreContext } from "./context.js";
+import { useMount } from "./use-mount.js";
 import { prefetchDirect } from "../prefetch/loader.js";
 import { getAppVersion } from "../app-version.js";
 import type { RouterInstance, RouterNavigateOptions } from "../types.js";
@@ -9,8 +10,8 @@ import type { RouterInstance, RouterNavigateOptions } from "../types.js";
 /**
  * Hook to access router actions (push, replace, refresh, prefetch, back, forward).
  *
- * Returns a STABLE reference that never changes, so components using
- * useRouter() do not re-render on navigation state changes.
+ * Returns a STABLE reference per component, so components using useRouter()
+ * do not re-render on navigation state changes.
  * For reactive navigation state, use useNavigation() instead.
  *
  * Methods read `basename` from the context on each call. It is set once from
@@ -18,10 +19,17 @@ import type { RouterInstance, RouterNavigateOptions } from "../types.js";
  * is a full document load (X-RSC-Reload), so the target app mounts fresh with
  * its own basename.
  *
+ * RELATIVE paths (no leading `/`, no scheme/query/hash) resolve against the
+ * current include() mount: `router.push("cart")` inside `include("/shop")`
+ * navigates to `/shop/cart`. Absolute paths stay APP-absolute — unlike
+ * basename, the mount is scoped, and absolute pushes legitimately target
+ * outside it, so they are never auto-prefixed.
+ *
  * @example
  * ```tsx
  * const router = useRouter();
- * router.push("/products");
+ * router.push("/products");   // app-absolute
+ * router.push("cart");        // mount-relative
  * router.replace("/login", { scroll: false });
  * router.prefetch("/dashboard");
  * router.back();
@@ -29,15 +37,17 @@ import type { RouterInstance, RouterNavigateOptions } from "../types.js";
  */
 export function useRouter(): RouterInstance {
   const ctx = useContext(NavigationStoreContext);
+  const mount = useMount();
 
   if (!ctx) {
     throw new Error("useRouter must be used within NavigationProvider");
   }
 
-  // Stable reference: ctx itself is stable, and reads on each method call
-  // pick up live basename values from the context (backed by a live ref
-  // in NavigationProvider), so app-switch transitions are reflected without
-  // recreating this object.
+  // Stable reference per component: ctx is stable and mount is a static
+  // property of the component's position in the tree; reads on each method
+  // call pick up live basename values from the context (backed by a live
+  // ref in NavigationProvider), so app-switch transitions are reflected
+  // without recreating this object.
   return useMemo<RouterInstance>(() => {
     /** Prefix a root-relative path with basename if not already prefixed. */
     function withBasename(url: string): string {
@@ -47,13 +57,32 @@ export function useRouter(): RouterInstance {
       return url === "/" ? bn : bn + url;
     }
 
+    /**
+     * Resolve a navigation/prefetch target. RELATIVE paths — a leading word
+     * character or `./`, never a scheme (`http:`, `mailto:`), query, or
+     * hash form — join onto the include mount and then take the basename
+     * pass like any root-relative path. Everything else passes through
+     * unchanged.
+     */
+    function resolveTarget(url: string): string {
+      const relative = url.startsWith("./") ? url.slice(2) : url;
+      if (
+        !/^[A-Za-z0-9]/.test(relative) ||
+        /^[a-z][a-z0-9+.-]*:/i.test(relative)
+      ) {
+        return withBasename(url);
+      }
+      const base = mount === "/" ? "" : mount.replace(/\/$/, "");
+      return withBasename(`${base}/${relative}`);
+    }
+
     return {
       push(url: string, options?: RouterNavigateOptions): Promise<void> {
-        return ctx.navigate(withBasename(url), { ...options, replace: false });
+        return ctx.navigate(resolveTarget(url), { ...options, replace: false });
       },
 
       replace(url: string, options?: RouterNavigateOptions): Promise<void> {
-        return ctx.navigate(withBasename(url), { ...options, replace: true });
+        return ctx.navigate(resolveTarget(url), { ...options, replace: true });
       },
 
       refresh(): Promise<void> {
@@ -64,7 +93,7 @@ export function useRouter(): RouterInstance {
         const segmentState = ctx.store?.getSegmentState();
         if (segmentState) {
           prefetchDirect(
-            withBasename(url),
+            resolveTarget(url),
             segmentState.currentSegmentIds,
             getAppVersion(),
             ctx.store?.getRouterId?.(),
@@ -94,5 +123,5 @@ export function useRouter(): RouterInstance {
         window.history.forward();
       },
     };
-  }, []);
+  }, [mount]);
 }

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]);