@rangojs/router 0.0.0-experimental.dfdb0387 → 0.0.0-experimental.e9c0b2f2

package/src/browser/scroll-restoration.ts

@@ -191,10 +191,15 @@ export function saveCurrentScrollPosition(): void {
 
 /**
  * Persist scroll positions to sessionStorage.
- * If the write fails due to quota exceeded, progressively evict the oldest
- * entries and retry until it succeeds or the store is empty.
+ * If the write fails (typically QuotaExceededError), evict the oldest ~1/4 of
+ * entries ONCE and retry the write a single time; if that still fails, remove
+ * our storage key entirely so we don't block other sessionStorage consumers.
+ * This is a single evict-then-retry-then-clear ladder, not a loop.
+ *
+ * Exported so that single eviction/retry/clear ladder is unit-testable directly.
+ * The browser drives it from the `pagehide` handler.
  */
-function persistToSessionStorage(): void {
+export function persistToSessionStorage(): void {
   try {
     sessionStorage.setItem(
       SCROLL_STORAGE_KEY,
@@ -332,6 +337,8 @@ export function scrollToHash(): boolean {
  * Scroll to top of page
  */
 export function scrollToTop(): void {
+  if (typeof window === "undefined") return;
+  if (typeof window.scrollTo !== "function") return;
   window.scrollTo(0, 0);
 }
 
@@ -374,20 +381,26 @@ export function handleNavigationEnd(options: {
     // Fall through to hash or top if no saved position
   }
 
-  // Defer hash and scroll-to-top to after React paints the new content,
-  // so the user doesn't see the current page jump before the new route appears.
-  deferToNextPaint(() => {
-    // Re-check: the deferred callback may fire after environment teardown
-    if (typeof window === "undefined") return;
-
-    // Try hash scrolling first
-    if (scrollToHash()) {
-      return;
-    }
-
-    // Default: scroll to top
-    scrollToTop();
-  });
+  // scrollToHash / scrollToTop run synchronously here.
+  // handleNavigationEnd is invoked from NavigationProvider's
+  // useLayoutEffect (post-commit, pre-paint), so a sync scrollTo is
+  // captured by the upcoming paint AND by startViewTransition's snapshot.
+  // Deferring via rAF here pushed the call past the snapshot capture,
+  // making forward navigations wrapped in a layout/route view transition
+  // skip scroll-to-top — the live DOM scrolled but the captured snapshot
+  // was at the previous scroll position, so the user-facing page stayed
+  // visually clamped at the source page's scrollY (often the new tree's
+  // max scroll for tall→short navs). Y=0 / a hash element are robust
+  // against unmeasured layout, so sync scroll is correct here even
+  // before the new tree's scrollHeight settles.
+  //
+  // (The restore branch above keeps deferToNextPaint because savedY
+  // depends on the new tree's max scroll; sync scrollTo against an
+  // unmeasured DOM would clamp savedY to whatever the old/zero max was.)
+  if (scrollToHash()) {
+    return;
+  }
+  scrollToTop();
 }
 
 /**

package/src/browser/segment-reconciler.ts

@@ -184,20 +184,16 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
         `[reconcile] ${segId}: CACHE only (not from server, type=${fromCache.type}, component=${fromCache.component != null ? "yes" : "null"})`,
       );
 
-      // For non-action actors: cached segments the server decided not to re-render.
-      // - Preserve loading=false (suppressed boundary) to maintain tree structure
-      // - Preserve parallel segment loading so renderSegments can reconstruct
-      //   parallel-owned loader markers from the cached slot metadata
-      // - Clear other truthy loading values to prevent suspense on cached content
-      if (actor !== "action") {
-        if (fromCache.type === "parallel" && fromCache.loading !== undefined) {
-          return fromCache;
-        }
-        if (fromCache.loading !== undefined && fromCache.loading !== false) {
-          return { ...fromCache, loading: undefined };
-        }
-      }
-
+      // Return the cached segment as-is, regardless of actor. We used to clear
+      // truthy `loading` here to prevent a stale Suspense fallback from
+      // committing against cached content, but that swapped the render tree
+      // from the LoaderBoundary branch to the plain OutletProvider branch
+      // inside renderSegments, causing React to unmount the entire chain
+      // (LoaderBoundary > Suspense > LoaderResolver > RouteContentWrapper >
+      // Suspender) every time the user opened an intercept or navigated back
+      // to a cached page. The flicker is now prevented by renderSegments'
+      // promise memoization keeping React's use() in "known fulfilled" state,
+      // so preserving `loading` keeps the element tree stable.
       return fromCache;
     })
     .filter(Boolean) as ResolvedSegment[];

package/src/browser/segment-structure-assert.ts

@@ -48,7 +48,7 @@ export function assertSegmentStructure(
 
   if (cachedCategory !== incomingCategory) {
     console.warn(
-      `[RSC Router] Tree structure mismatch detected in ${context} ` +
+      `[Rango] Tree structure mismatch detected in ${context} ` +
         `for segment "${cached.id}": loading category changed from ` +
         `"${cachedCategory}" (${describeLoading(cached.loading)}) to ` +
         `"${incomingCategory}" (${describeLoading(incoming.loading)}). ` +
@@ -64,7 +64,7 @@ export function assertSegmentStructure(
   const incomingHasMount = !!incoming.mountPath;
   if (cachedHasMount !== incomingHasMount) {
     console.warn(
-      `[RSC Router] MountContextProvider mismatch detected in ${context} ` +
+      `[Rango] MountContextProvider mismatch detected in ${context} ` +
         `for segment "${cached.id}": mountPath changed from ` +
         `${cachedHasMount ? `"${cached.mountPath}"` : "undefined"} to ` +
         `${incomingHasMount ? `"${incoming.mountPath}"` : "undefined"}. ` +

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

@@ -4,13 +4,15 @@ import type {
   RscPayload,
 } from "./types.js";
 import { createPartialUpdater } from "./partial-update.js";
+import { enterActionFence, exitActionFence } from "./action-fence.js";
+import { KEEP_CACHE_HEADER } from "./cookie-name.js";
 import { createNavigationTransaction } from "./navigation-transaction.js";
 import {
   reconcileSegments,
   reconcileErrorSegments,
 } from "./segment-reconciler.js";
 import { startTransition } from "react";
-import type { EventController } from "./event-controller.js";
+import type { EventController, ActionHandle } from "./event-controller.js";
 import {
   toNetworkError,
   emitNetworkError,
@@ -21,11 +23,16 @@ import {
   isBrowserDebugEnabled,
   startBrowserTransaction,
 } from "./logging.js";
-import { validateRedirectOrigin } from "./validate-redirect-origin.js";
+import {
+  validateRedirectOrigin,
+  validateExternalRedirect,
+} from "./validate-redirect-origin.js";
 import {
   extractRscHeaderUrl,
   emptyResponse,
+  handleReloadHeader,
   teeWithCompletion,
+  isForeignRouterId,
 } from "./response-adapter.js";
 import { mergeLocationState } from "./history-state.js";
 import { classifyActionOutcome } from "./action-coordinator.js";
@@ -51,6 +58,27 @@ export interface ServerActionBridgeConfigWithController extends ServerActionBrid
   ) => Promise<void>;
 }
 
+/**
+ * Merge an action's location-state payload into history.state, restricted to
+ * the keys this action is entitled to write. claimLocationState enforces
+ * last-initiated-wins for same-key concurrent writes (a later-initiated sibling
+ * keeps its value even if this action's response settles afterward); distinct
+ * keys from every concurrent action survive. Arbitration is scoped to the
+ * action's cohort (captured at startAction), so a newer action on another entry
+ * cannot suppress this one. No-op when nothing was set or all keys were already
+ * claimed by a later-initiated sibling in the cohort.
+ */
+function applyActionLocationState(
+  handle: ActionHandle,
+  locationState: Record<string, unknown> | undefined,
+): void {
+  if (!locationState) return;
+  const winning = handle.claimLocationState(locationState);
+  if (Object.keys(winning).length > 0) {
+    mergeLocationState(winning);
+  }
+}
+
 /**
  * Create a server action bridge for handling RSC server actions
  *
@@ -77,6 +105,26 @@ export function createServerActionBridge(
     onNavigate,
   } = config;
 
+  // SPA-navigate when onNavigate is set, else hard-reload. state is omitted (not
+  // passed as undefined) to match the header path's prior call shape.
+  // Callers pass an already same-origin-validated url; the hard-reload fallback
+  // re-validates defensively so this leaf cannot become an open redirect if a
+  // future caller forgets (the SPA path validates inside the navigation bridge).
+  async function dispatchRedirect(url: string, state?: unknown): Promise<void> {
+    if (onNavigate) {
+      await onNavigate(url, {
+        ...(state !== undefined ? { state } : {}),
+        replace: true,
+        _skipCache: true,
+      });
+    } else {
+      const safe = validateRedirectOrigin(url, window.location.origin);
+      if (safe) {
+        window.location.href = safe;
+      }
+    }
+  }
+
   let isRegistered = false;
 
   const fetchPartialUpdate = createPartialUpdater({
@@ -138,14 +186,57 @@ export function createServerActionBridge(
     const locationKey = window.history.state?.key;
     log("action start", { id, argsCount: args.length });
 
-    // Start action in event controller - handles lifecycle tracking
-    const handle = eventController.startAction(id, args);
+    // Start action in event controller - handles lifecycle tracking. The
+    // current history key is the action's cohort: location-state arbitration is
+    // scoped to it so a later action on a different entry cannot suppress this
+    // one (and vice versa).
+    const handle = eventController.startAction(id, args, locationKey);
+    // Whether the action's response carried the keepClientCache() directive.
+    // Set when the response arrives; gates the deferred invalidation below.
+    let keepCache = false;
+    // Whether a Response actually settled from the network (the server saw the
+    // request). Set true as the first statement in the fetch .then() below.
+    // Gates the automatic invalidation: a pre-dispatch failure (encodeReply
+    // throw or a fetch rejection — server unreachable/DNS/connection refused)
+    // leaves this false, so finalizeAction() must NOT invalidate or broadcast —
+    // nothing reached the server, so nothing could have mutated. A failed Flight
+    // DECODE after the response arrived keeps it true (the mutation may have
+    // committed, so invalidating the now-possibly-stale client cache is correct).
+    let responseReceived = false;
+    // Single deferred invalidation + fence release, run exactly ONCE however the
+    // action terminates (normal, redirect, error, abort, intercept, concurrent).
+    // This replaces main's eager clear at action start: every directive-free
+    // action invalidates once; keepClientCache() suppresses only the automatic
+    // invalidation, so a concurrent directive-free action still invalidates via
+    // its own latch. Latched so the finally AND the early SPA-redirect returns
+    // (whose Flight stream never settles) can both call it safely.
+    let actionFinalized = false;
+    // skipInvalidation: the version-mismatch reload terminal released nothing
+    // server-side, so it releases the fence without invalidating.
+    const finalizeAction = (skipInvalidation = false): void => {
+      if (actionFinalized) return;
+      actionFinalized = true;
+      // finally so a throw in invalidation cannot leak the fence (latch is set).
+      try {
+        // responseReceived gates the automatic invalidation: a pre-dispatch
+        // failure (serialize throw / fetch reject) never reached the server, so
+        // marking the cache stale + broadcasting cross-tab would be spurious.
+        if (responseReceived && !keepCache && !skipInvalidation) {
+          store.markCacheAsStaleAndBroadcast();
+        }
+      } finally {
+        exitActionFence();
+      }
+    };
     try {
       const segmentState = store.getSegmentState();
 
-      // Mark cache as stale immediately when action starts
-      // This ensures SWR pattern kicks in if user navigates away during action
-      store.markCacheAsStaleAndBroadcast();
+      // Raise the action fence (replaces the old eager clear). Nothing is wiped,
+      // rotated, or broadcast yet: navigations during the flight fetch fresh
+      // (no-store) and popstate is treated as SWR, but the decision to
+      // invalidate is deferred to the response so a no-op action (keepClientCache)
+      // can leave the caches and the jar untouched.
+      enterActionFence();
 
       // Create temporary references for serialization
       const temporaryReferences = deps.createTemporaryReferenceSet();
@@ -217,23 +308,34 @@ export function createServerActionBridge(
         body: encodedBody,
         signal: fetchAbort.signal,
       }).then(async (response) => {
+        // A settled fetch promise means the request reached the server and a
+        // Response came back (true for 2xx, 4xx, AND 5xx — fetch only rejects
+        // on network-layer failure, never on HTTP status). Record it as the
+        // first statement so every downstream terminal can invalidate; a
+        // pre-dispatch failure never gets here and stays gated out.
+        responseReceived = true;
         // Response arrived — disconnect fetch abort from handle abort so
         // abortAllActions() doesn't disrupt the in-progress Flight stream.
         handle.signal.removeEventListener("abort", onHandleAbort);
 
+        // Did the action call keepClientCache()? If so the deferred invalidation
+        // below is suppressed for THIS action (a concurrent directive-free
+        // action still invalidates via its own response).
+        keepCache = response.headers.get(KEEP_CACHE_HEADER) === "1";
+
         // Check for version mismatch - server wants us to reload
-        const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
-        if (reload === "blocked") {
-          resolveStreamComplete();
-          return emptyResponse();
-        }
-        if (reload) {
-          log("version mismatch on action, reloading", {
-            reloadUrl: reload.url,
-          });
-          window.location.href = reload.url;
-          return new Promise<Response>(() => {});
-        }
+        const reloadResult = handleReloadHeader(response, {
+          onBlocked: resolveStreamComplete,
+          onReload: (url) => {
+            log("version mismatch on action, reloading", { reloadUrl: url });
+            // Never-settling terminal (navigates away), so the finally never
+            // runs: release the fence here. skipInvalidation — the mismatch
+            // short-circuits the action server-side, so nothing mutated and a
+            // broadcast would only risk hard-reloading a sibling mid-task.
+            finalizeAction(true);
+          },
+        });
+        if (reloadResult) return reloadResult;
 
         // Simple redirect from action (no state, no RSC payload).
         // Short-circuits before createFromFetch — no Flight deserialization needed.
@@ -243,14 +345,11 @@ export function createServerActionBridge(
         if (redirect && redirect !== "blocked" && !handle.signal.aborted) {
           log("action simple redirect", { url: redirect.url });
           handle.complete(undefined);
-          if (onNavigate) {
-            await onNavigate(redirect.url, {
-              replace: true,
-              _skipCache: true,
-            });
-          } else {
-            window.location.href = redirect.url;
-          }
+          // This path returns a never-settling promise, so the finally never
+          // runs: invalidate + release the fence here (the mutation committed
+          // and we're navigating away). Latched, so the finally is a no-op.
+          finalizeAction();
+          await dispatchRedirect(redirect.url);
           return new Promise<Response>(() => {});
         }
         if (redirect === "blocked") {
@@ -258,6 +357,29 @@ export function createServerActionBridge(
           return emptyResponse();
         }
 
+        // Integrity check (pre-decode): a foreign app's action response must
+        // not be decoded + applied here. This is the one decode-and-apply path
+        // the post-decode partial-update guard does NOT cover (the action
+        // bridge has its own createFromFetch -> onUpdate). Ordered after the
+        // reload/redirect handlers, which steer control responses first.
+        // Reloads via window.location.reload() rather than navigating to a
+        // target (as the navigation-client guard does): an action has no
+        // navigation target, so reloading the current URL re-syncs the
+        // document against the server-applied action effect.
+        if (
+          !handle.signal.aborted &&
+          isForeignRouterId(response, store.getRouterId?.())
+        ) {
+          log("action router id mismatch, reloading to re-sync");
+          handle.complete(undefined);
+          resolveStreamComplete();
+          // Never-settling return: release the fence before the reload (the
+          // reload resets module state anyway, but stay balanced). Latched.
+          finalizeAction();
+          window.location.reload();
+          return new Promise<Response>(() => {});
+        }
+
         // Start streaming immediately when response arrives
         if (!handle.signal.aborted) {
           streamingToken = handle.startStreaming();
@@ -328,6 +450,27 @@ export function createServerActionBridge(
       // Check handle.signal.aborted to avoid redirecting from a stale action
       // when the user has already navigated away.
       if (metadata?.redirect && !handle.signal.aborted) {
+        // Explicit off-host redirect (redirect(url, { external: true })):
+        // hard-navigate, but still scheme-validate (http/https only). external
+        // waives the same-origin check, NOT scheme safety, so a forged payload
+        // carrying a javascript:/data: URL cannot script via location.assign.
+        if (metadata.redirect.external) {
+          const externalUrl = validateExternalRedirect(
+            metadata.redirect.url,
+            window.location.origin,
+          );
+          if (!externalUrl) {
+            log("blocked external action redirect payload", {
+              url: metadata.redirect.url,
+            });
+            handle.complete(returnValue?.data);
+            return returnValue?.data;
+          }
+          log("external action redirect", { url: externalUrl });
+          handle.complete(returnValue?.data);
+          window.location.assign(externalUrl);
+          return returnValue?.data;
+        }
         const redirectUrl = validateRedirectOrigin(
           metadata.redirect.url,
           window.location.origin,
@@ -339,18 +482,9 @@ export function createServerActionBridge(
           handle.complete(returnValue?.data);
           return returnValue?.data;
         }
-        const redirectState = metadata.locationState;
         log("action redirect", { url: redirectUrl });
         handle.complete(returnValue?.data);
-        if (onNavigate) {
-          await onNavigate(redirectUrl, {
-            state: redirectState,
-            replace: true,
-            _skipCache: true,
-          });
-        } else {
-          window.location.href = redirectUrl;
-        }
+        await dispatchRedirect(redirectUrl, metadata.locationState);
         return returnValue?.data;
       }
 
@@ -517,6 +651,20 @@ export function createServerActionBridge(
         currentInterceptSource: store.getInterceptSourceUrl(),
       });
 
+      // Apply server-set location state exhaustively here, as a successful-
+      // response effect — the terminal switch below decides rendering/refetch,
+      // not whether this metadata survives (every refetch path is storeOnly and
+      // never writes history.state). Gated on NOT navigated-away: the classifier
+      // treats either a pathname OR history-key change as diversion, so this
+      // both honors the "diverted state is dropped" contract AND prevents a
+      // cross-entry write (mergeLocationState writes the CURRENT entry, which a
+      // navigated-away action no longer owns). Done before the switch (and
+      // before the normal branch's async renderSegments) so a slow render racing
+      // a navigation cannot drop it.
+      if (scenario.type !== "navigated-away") {
+        applyActionLocationState(handle, metadata?.locationState);
+      }
+
       switch (scenario.type) {
         case "navigated-away": {
           log("user navigated away during action", {
@@ -528,8 +676,9 @@ export function createServerActionBridge(
           handle.clearConsolidation();
 
           if (scenario.historyKeyChanged) {
-            if (!scenario.onInterceptRoute) {
-              store.markCacheAsStaleAndBroadcast();
+            // Invalidation is deferred to finalizeAction(); here we only trigger
+            // the revalidation refetch of the new route (suppressed on keep).
+            if (!scenario.onInterceptRoute && !keepCache) {
               refetchRoute().catch((error) => {
                 if (isBackgroundSuppressible(error)) return;
                 console.error(
@@ -541,11 +690,14 @@ export function createServerActionBridge(
             break;
           }
 
-          // Same history key but different pathname - safe to refetch current route
-          store.markCacheAsStaleAndBroadcast();
-          await refetchRoute({
-            interceptSourceUrl: store.getInterceptSourceUrl(),
-          });
+          // Same history key but different pathname - safe to refetch current
+          // route. Invalidation is deferred to finalizeAction(); here we only
+          // trigger the revalidation refetch (suppressed on keep).
+          if (!keepCache) {
+            await refetchRoute({
+              interceptSourceUrl: store.getInterceptSourceUrl(),
+            });
+          }
           break;
         }
 
@@ -553,8 +705,11 @@ export function createServerActionBridge(
           console.warn(
             `[Browser] Missing segments after action (HMR detected), refetching...`,
           );
+          // Repair (not revalidation), so ungated on keepCache: a keep action
+          // resolving last must discharge a directive-free sibling's repair.
+          // See the keep row in docs/design/rango-state-cookie.md (the all-keep
+          // edge, and the benign re-mark-stale-after-refetch end-state delta).
           await refetchRoute({ interceptSourceUrl });
-          store.broadcastCacheInvalidation();
           break;
         }
 
@@ -562,7 +717,8 @@ export function createServerActionBridge(
           log("consolidation fetch needed", {
             segmentIds: scenario.segmentIds,
           });
-          // Calculate segments to send (exclude the ones we want fresh)
+          // Location state already applied above (pre-switch). Calculate
+          // segments to send (exclude the ones we want fresh).
           const currentSegmentIds = store.getSegmentState().currentSegmentIds;
           const segmentsToSend = currentSegmentIds.filter(
             (sid) => !scenario.segmentIds.includes(sid),
@@ -571,11 +727,11 @@ export function createServerActionBridge(
           // Clear consolidation tracking before fetch
           handle.clearConsolidation();
 
+          // Ungated on keepCache, same as hmr-missing above (see the keep row).
           await refetchRoute({
             segments: segmentsToSend,
             interceptSourceUrl,
           });
-          store.broadcastCacheInvalidation();
           break;
         }
 
@@ -586,6 +742,8 @@ export function createServerActionBridge(
           // Only update store if history key hasn't changed (user didn't navigate away)
           const currentKeyNow = store.getHistoryKey();
           if (currentKeyNow === currentKey) {
+            // Location state already applied above (pre-switch); this action's
+            // UI render is skipped because a later sibling consolidates.
             store.setSegmentIds(matched);
             const currentHandleData = eventController.getHandleState().data;
             store.cacheSegmentsForHistory(
@@ -625,13 +783,7 @@ export function createServerActionBridge(
             onUpdate({ root: newTree, metadata: metadata! });
           });
 
-          // Apply server-set location state to history.state (non-redirect flow)
-          const actionLocationState = metadata?.locationState;
-          if (actionLocationState) {
-            mergeLocationState(actionLocationState);
-          }
-
-          // Update store state
+          // Location state already applied above (pre-switch). Update store.
           store.setSegmentIds(matched);
           const currentHandleData = eventController.getHandleState().data;
           store.cacheSegmentsForHistory(
@@ -639,7 +791,9 @@ export function createServerActionBridge(
             fullSegments,
             currentHandleData,
           );
-          store.markCacheAsStaleAndBroadcast();
+          // Invalidation deferred to finalizeAction() (runs after this caches
+          // the fresh segments), suppressed when the action called
+          // keepClientCache().
           break;
         }
       }
@@ -647,6 +801,11 @@ export function createServerActionBridge(
       handle.complete(returnData);
       return returnData;
     } finally {
+      // The single deferred invalidation + fence release for this action. Runs
+      // for every terminal that settles (normal, navigated-away, error, abort,
+      // intercept, concurrent); the SPA-redirect paths above already ran it.
+      // Latched, so it fires exactly once.
+      finalizeAction();
       handle[Symbol.dispose]();
     }
   }

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,13 +31,21 @@ export type HandleData = Record<string, Record<string, unknown[]>>;
 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). */
+  /** 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>;
   /**
@@ -63,6 +70,12 @@ export interface RscMetadata {
    * Sent on initial render so the browser can configure its cache duration.
    */
   prefetchCacheTTL?: 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.
@@ -77,8 +90,18 @@ export interface RscMetadata {
   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>;
 }
@@ -179,6 +202,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
  *
@@ -316,8 +348,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 */
@@ -425,9 +463,9 @@ export interface NavigationStore {
   hasHistoryCache(historyKey: string): boolean;
   updateCacheHandleData(historyKey: string, handleData: HandleData): void;
   markCacheAsStale(): void;
+  markHistoryCacheStale(): void;
   markCacheAsStaleAndBroadcast(): void;
   clearHistoryCache(): void;
-  broadcastCacheInvalidation(): void;
 
   // Cross-tab refresh callback (set by navigation bridge)
   setCrossTabRefreshCallback(callback: () => void): void;
@@ -540,6 +578,8 @@ 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;
 }