@rangojs/router 0.0.0-experimental.ce770c9a → 0.0.0-experimental.d5d3070a

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,14 +23,20 @@ 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";
+import { getAppVersion } from "./app-version.js";
 
 // Polyfill Symbol.dispose/asyncDispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -43,8 +51,6 @@ if (typeof Symbol.asyncDispose === "undefined") {
  */
 export interface ServerActionBridgeConfigWithController extends ServerActionBridgeConfig {
   eventController: EventController;
-  /** RSC version from initial payload metadata */
-  version?: string;
   /** Callback to trigger SPA navigation (for action redirects) */
   onNavigate?: (
     url: string,
@@ -52,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
  *
@@ -75,10 +102,29 @@ export function createServerActionBridge(
     deps,
     onUpdate,
     renderSegments,
-    version,
     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({
@@ -86,7 +132,7 @@ export function createServerActionBridge(
     client,
     onUpdate,
     renderSegments,
-    version,
+    getVersion: getAppVersion,
   });
 
   /**
@@ -140,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();
@@ -165,9 +254,15 @@ export function createServerActionBridge(
         segmentState.currentSegmentIds.join(","),
       );
       // Add version param for version mismatch detection
+      const version = getAppVersion();
       if (version) {
         url.searchParams.set("_rsc_v", version);
       }
+      // Add router ID for app switch detection
+      const rid = store.getRouterId?.();
+      if (rid) {
+        url.searchParams.set("_rsc_rid", rid);
+      }
 
       // Encode arguments
       const encodedBody = await deps.encodeReply(args, { temporaryReferences });
@@ -206,7 +301,6 @@ export function createServerActionBridge(
           "rsc-action": id,
           "X-RSC-Router-Client-Path": segmentState.currentUrl,
           ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
-          // Send intercept source URL so server can maintain intercept context
           ...(interceptSourceUrl && {
             "X-RSC-Router-Intercept-Source": interceptSourceUrl,
           }),
@@ -214,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.
@@ -240,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") {
@@ -255,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();
@@ -309,7 +434,6 @@ export function createServerActionBridge(
         matchedCount: payload.metadata?.matched?.length ?? 0,
         diffCount: payload.metadata?.diff?.length ?? 0,
       });
-
       // Guard: if the action was aborted while streaming (e.g., user navigated
       // away or abortAllActions fired), bail out before any reconcile/render/cache
       // writes to avoid overwriting the current UI with stale action results.
@@ -326,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,
@@ -337,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;
       }
 
@@ -515,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", {
@@ -526,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(
@@ -539,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;
         }
 
@@ -551,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;
         }
 
@@ -560,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),
@@ -569,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;
         }
 
@@ -584,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(
@@ -623,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(
@@ -637,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;
         }
       }
@@ -645,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,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>;
   /**
@@ -60,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.
@@ -70,10 +86,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>;
 }
@@ -174,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
  *
@@ -311,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 */
@@ -341,7 +384,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: (
@@ -403,17 +452,20 @@ export interface NavigationStore {
     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;
+      }
     | undefined;
   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;
@@ -422,6 +474,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;
@@ -452,6 +508,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;
 }
@@ -463,6 +521,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;
 }
 
 /**
@@ -520,6 +587,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;
 }
 
 /**