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

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,
   });
 
   /**
@@ -99,27 +145,31 @@ export function createServerActionBridge(
     interceptSourceUrl?: string | null;
   }): Promise<void> {
     const src = opts?.interceptSourceUrl ?? null;
-    using navTx = createNavigationTransaction(
+    const navTx = createNavigationTransaction(
       store,
       eventController,
       window.location.href,
       { replace: true, skipLoadingState: true },
     );
-    await fetchPartialUpdate(
-      window.location.href,
-      opts?.segments ?? [],
-      false,
-      navTx.handle.signal,
-      navTx.with({
-        url: window.location.href,
-        storeOnly: true,
-        ...(src ? { intercept: true, interceptSourceUrl: src } : {}),
-      }),
-      {
-        type: "action" as const,
-        ...(src ? { interceptSourceUrl: src } : {}),
-      },
-    );
+    try {
+      await fetchPartialUpdate(
+        window.location.href,
+        opts?.segments ?? [],
+        false,
+        navTx.handle.signal,
+        navTx.with({
+          url: window.location.href,
+          storeOnly: true,
+          ...(src ? { intercept: true, interceptSourceUrl: src } : {}),
+        }),
+        {
+          type: "action" as const,
+          ...(src ? { interceptSourceUrl: src } : {}),
+        },
+      );
+    } finally {
+      navTx[Symbol.dispose]();
+    }
   }
 
   /**
@@ -136,441 +186,612 @@ export function createServerActionBridge(
     const locationKey = window.history.state?.key;
     log("action start", { id, argsCount: args.length });
 
-    // Start action in event controller - handles lifecycle tracking
-    using 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();
+
+      // 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();
+
+      // Capture URL pathname at action start to detect navigation during action
+      // Must use window.location (not store.path) because intercepts change URL
+      // without changing store.path (e.g., /kanban -> /kanban/card/1)
+      const actionStartPathname = window.location.pathname;
+
+      // Build action request URL with current segments
+      const url = new URL(window.location.href);
+      url.searchParams.set("_rsc_action", id);
+      url.searchParams.set(
+        "_rsc_segments",
+        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);
+      }
 
-    const segmentState = store.getSegmentState();
+      // Encode arguments
+      const encodedBody = await deps.encodeReply(args, { temporaryReferences });
 
-    // Mark cache as stale immediately when action starts
-    // This ensures SWR pattern kicks in if user navigates away during action
-    store.markCacheAsStaleAndBroadcast();
+      log("sending action request", {
+        url: url.href,
+        bodyType: typeof encodedBody,
+        isFormData: encodedBody instanceof FormData,
+        segmentCount: segmentState.currentSegmentIds.length,
+      });
 
-    // Create temporary references for serialization
-    const temporaryReferences = deps.createTemporaryReferenceSet();
+      // Track when the stream completes
+      let resolveStreamComplete: () => void;
+      const streamComplete = new Promise<void>((resolve) => {
+        resolveStreamComplete = resolve;
+      });
 
-    // Capture URL pathname at action start to detect navigation during action
-    // Must use window.location (not store.path) because intercepts change URL
-    // without changing store.path (e.g., /kanban -> /kanban/card/1)
-    const actionStartPathname = window.location.pathname;
+      // Get intercept source URL if in intercept context
+      const interceptSourceUrl = store.getInterceptSourceUrl();
+
+      // Track streaming token - will be set when response arrives
+      let streamingToken: { end(): void } | null = null;
+
+      // Use a dedicated abort controller for the fetch so we can cancel network
+      // I/O without disrupting the Flight stream once the response has arrived.
+      // Aborting a response mid-stream causes React's Flight decoder to throw
+      // asynchronous unhandled errors (BodyStreamBuffer was aborted).
+      const fetchAbort = new AbortController();
+      const onHandleAbort = () => fetchAbort.abort();
+      handle.signal.addEventListener("abort", onHandleAbort, { once: true });
+
+      // Send action request with stream tracking
+      const responsePromise = fetch(url, {
+        method: "POST",
+        headers: {
+          "rsc-action": id,
+          "X-RSC-Router-Client-Path": segmentState.currentUrl,
+          ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
+          ...(interceptSourceUrl && {
+            "X-RSC-Router-Intercept-Source": interceptSourceUrl,
+          }),
+        },
+        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 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.
+        // Check handle.signal.aborted to avoid redirecting from a stale action
+        // when the user has already navigated away.
+        const redirect = extractRscHeaderUrl(response, "X-RSC-Redirect");
+        if (redirect && redirect !== "blocked" && !handle.signal.aborted) {
+          log("action simple redirect", { url: redirect.url });
+          handle.complete(undefined);
+          // 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") {
+          resolveStreamComplete();
+          return emptyResponse();
+        }
 
-    // Build action request URL with current segments
-    const url = new URL(window.location.href);
-    url.searchParams.set("_rsc_action", id);
-    url.searchParams.set(
-      "_rsc_segments",
-      segmentState.currentSegmentIds.join(","),
-    );
-    // Add version param for version mismatch detection
-    if (version) {
-      url.searchParams.set("_rsc_v", version);
-    }
+        // 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>(() => {});
+        }
 
-    // Encode arguments
-    const encodedBody = await deps.encodeReply(args, { temporaryReferences });
-
-    log("sending action request", {
-      url: url.href,
-      bodyType: typeof encodedBody,
-      isFormData: encodedBody instanceof FormData,
-      segmentCount: segmentState.currentSegmentIds.length,
-    });
-
-    // Track when the stream completes
-    let resolveStreamComplete: () => void;
-    const streamComplete = new Promise<void>((resolve) => {
-      resolveStreamComplete = resolve;
-    });
-
-    // Get intercept source URL if in intercept context
-    const interceptSourceUrl = store.getInterceptSourceUrl();
-
-    // Track streaming token - will be set when response arrives
-    let streamingToken: { end(): void } | null = null;
-
-    // Use a dedicated abort controller for the fetch so we can cancel network
-    // I/O without disrupting the Flight stream once the response has arrived.
-    // Aborting a response mid-stream causes React's Flight decoder to throw
-    // asynchronous unhandled errors (BodyStreamBuffer was aborted).
-    const fetchAbort = new AbortController();
-    const onHandleAbort = () => fetchAbort.abort();
-    handle.signal.addEventListener("abort", onHandleAbort, { once: true });
-
-    // Send action request with stream tracking
-    const responsePromise = fetch(url, {
-      method: "POST",
-      headers: {
-        "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,
-        }),
-      },
-      body: encodedBody,
-      signal: fetchAbort.signal,
-    }).then(async (response) => {
-      // Response arrived — disconnect fetch abort from handle abort so
-      // abortAllActions() doesn't disrupt the in-progress Flight stream.
-      handle.signal.removeEventListener("abort", onHandleAbort);
-
-      // 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>(() => {});
-      }
+        // Start streaming immediately when response arrives
+        if (!handle.signal.aborted) {
+          streamingToken = handle.startStreaming();
+        }
 
-      // Simple redirect from action (no state, no RSC payload).
-      // Short-circuits before createFromFetch — no Flight deserialization needed.
-      // Check handle.signal.aborted to avoid redirecting from a stale action
-      // when the user has already navigated away.
-      const redirect = extractRscHeaderUrl(response, "X-RSC-Redirect");
-      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;
+        return teeWithCompletion(response, () => {
+          log("stream complete");
+          streamingToken?.end();
+          resolveStreamComplete();
+        });
+      });
+
+      // Deserialize response (MUST use same temporaryReferences)
+      let payload: RscPayload;
+      try {
+        payload = await deps.createFromFetch<RscPayload>(responsePromise, {
+          temporaryReferences,
+        });
+      } catch (error) {
+        // Clean up streaming token on error (may be null if fetch failed before .then() ran)
+        // The token is assigned in .then() callback which runs before this catch block,
+        // but TypeScript doesn't track cross-async assignments, so use type assertion
+        (streamingToken as { end(): void } | null)?.end();
+        // resolveStreamComplete is assigned in the Promise constructor so it's safe to call
+        resolveStreamComplete!();
+
+        // Silently swallow abort errors — the action was intentionally cancelled
+        // (e.g., user navigated away or abortAllActions was called).
+        // Return undefined instead of throwing to avoid surfacing as a page error.
+        // Check both DOMException AbortError and stream-level abort messages
+        // (BodyStreamBuffer was aborted) that propagate from the aborted fetch.
+        if (handle.signal.aborted) {
+          return undefined;
         }
-        return new Promise<Response>(() => {});
-      }
-      if (redirect === "blocked") {
-        resolveStreamComplete();
-        return emptyResponse();
-      }
 
-      // Start streaming immediately when response arrives
-      if (!handle.signal.aborted) {
-        streamingToken = handle.startStreaming();
+        // Convert network-level errors to NetworkError for proper handling
+        const networkError = toNetworkError(error, {
+          url: url.toString(),
+          operation: "action",
+        });
+        if (networkError) {
+          handle.fail(networkError);
+          emitNetworkError(onUpdate, networkError, segmentState.currentUrl);
+          throw networkError;
+        }
+        throw error;
       }
 
-      return teeWithCompletion(response, () => {
-        log("stream complete");
-        streamingToken?.end();
-        resolveStreamComplete();
-      });
-    });
-
-    // Deserialize response (MUST use same temporaryReferences)
-    let payload: RscPayload;
-    try {
-      payload = await deps.createFromFetch<RscPayload>(responsePromise, {
-        temporaryReferences,
+      log("action response received", {
+        isPartial: payload.metadata?.isPartial,
+        isError: payload.metadata?.isError,
+        matchedCount: payload.metadata?.matched?.length ?? 0,
+        diffCount: payload.metadata?.diff?.length ?? 0,
       });
-    } catch (error) {
-      // Clean up streaming token on error (may be null if fetch failed before .then() ran)
-      // The token is assigned in .then() callback which runs before this catch block,
-      // but TypeScript doesn't track cross-async assignments, so use type assertion
-      (streamingToken as { end(): void } | null)?.end();
-      // resolveStreamComplete is assigned in the Promise constructor so it's safe to call
-      resolveStreamComplete!();
-
-      // Silently swallow abort errors — the action was intentionally cancelled
-      // (e.g., user navigated away or abortAllActions was called).
-      // Return undefined instead of throwing to avoid surfacing as a page error.
-      // Check both DOMException AbortError and stream-level abort messages
-      // (BodyStreamBuffer was aborted) that propagate from the aborted fetch.
+      // 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.
       if (handle.signal.aborted) {
+        log("action aborted after response, skipping reconciliation");
         return undefined;
       }
 
-      // Convert network-level errors to NetworkError for proper handling
-      const networkError = toNetworkError(error, {
-        url: url.toString(),
-        operation: "action",
-      });
-      if (networkError) {
-        handle.fail(networkError);
-        emitNetworkError(onUpdate, networkError, segmentState.currentUrl);
-        throw networkError;
-      }
-      throw error;
-    }
-
-    log("action response received", {
-      isPartial: payload.metadata?.isPartial,
-      isError: payload.metadata?.isError,
-      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.
-    if (handle.signal.aborted) {
-      log("action aborted after response, skipping reconciliation");
-      return undefined;
-    }
+      // Process response
+      const { metadata, returnValue } = payload;
 
-    // Process response
-    const { metadata, returnValue } = payload;
-
-    // Handle action redirect: server converted the redirect to a Flight payload
-    // so we can perform SPA navigation instead of a full page reload.
-    // Check handle.signal.aborted to avoid redirecting from a stale action
-    // when the user has already navigated away.
-    if (metadata?.redirect && !handle.signal.aborted) {
-      const redirectUrl = validateRedirectOrigin(
-        metadata.redirect.url,
-        window.location.origin,
-      );
-      if (!redirectUrl) {
-        log("blocked action redirect payload", { url: metadata.redirect.url });
+      // Handle action redirect: server converted the redirect to a Flight payload
+      // so we can perform SPA navigation instead of a full page reload.
+      // 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,
+        );
+        if (!redirectUrl) {
+          log("blocked action redirect payload", {
+            url: metadata.redirect.url,
+          });
+          handle.complete(returnValue?.data);
+          return returnValue?.data;
+        }
+        log("action redirect", { url: redirectUrl });
         handle.complete(returnValue?.data);
+        await dispatchRedirect(redirectUrl, metadata.locationState);
         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;
+
+      // Bail out if the action was aborted after deserialization (e.g. user
+      // navigated away or abortAllActions was called while the Flight stream
+      // was being consumed). Without this check the code below would mutate
+      // the store / UI for a stale action.
+      if (handle.signal.aborted) {
+        log("action aborted after deserialization, skipping mutations");
+        return returnValue?.data;
       }
-      return returnValue?.data;
-    }
 
-    // Bail out if the action was aborted after deserialization (e.g. user
-    // navigated away or abortAllActions was called while the Flight stream
-    // was being consumed). Without this check the code below would mutate
-    // the store / UI for a stale action.
-    if (handle.signal.aborted) {
-      log("action aborted after deserialization, skipping mutations");
-      return returnValue?.data;
-    }
+      const { matched, diff, segments, isPartial, isError } = metadata || {};
 
-    const { matched, diff, segments, isPartial, isError } = metadata || {};
+      // Log action result
+      if (returnValue && !returnValue.ok) {
+        console.error(`[Browser] Action failed:`, returnValue.data);
+      }
 
-    // Log action result
-    if (returnValue && !returnValue.ok) {
-      console.error(`[Browser] Action failed:`, returnValue.data);
-    }
+      // Handle error responses with error boundary UI
+      if (isError && isPartial && segments && diff) {
+        log("processing error boundary response");
 
-    // Handle error responses with error boundary UI
-    if (isError && isPartial && segments && diff) {
-      log("processing error boundary response");
+        // Fail current handle BEFORE aborting all actions so the event controller
+        // records the error state (abortAllActions clears inflight entries)
+        if (returnValue && !returnValue.ok) {
+          handle.fail(returnValue.data);
+        }
 
-      // Fail current handle BEFORE aborting all actions so the event controller
-      // records the error state (abortAllActions clears inflight entries)
-      if (returnValue && !returnValue.ok) {
-        handle.fail(returnValue.data);
-      }
+        // Abort all other pending action requests - error takes precedence
+        // This prevents other actions from completing and overwriting the error UI
+        eventController.abortAllActions();
 
-      // Abort all other pending action requests - error takes precedence
-      // This prevents other actions from completing and overwriting the error UI
-      eventController.abortAllActions();
+        // Clear concurrent action tracking - no consolidation needed when showing error
+        handle.clearConsolidation();
 
-      // Clear concurrent action tracking - no consolidation needed when showing error
-      handle.clearConsolidation();
+        // Get current page's cached segments
+        const currentKey = store.getHistoryKey();
+        const cached = store.getCachedSegments(currentKey);
+        const cachedSegments = cached?.segments || [];
 
-      // Get current page's cached segments
-      const currentKey = store.getHistoryKey();
-      const cached = store.getCachedSegments(currentKey);
-      const cachedSegments = cached?.segments || [];
+        // Reconcile error segments with cached tree
+        const errorResult = reconcileErrorSegments(cachedSegments, segments);
+
+        // Render the full tree with error segment merged with parent layouts
+        const errorTree = await renderSegments(errorResult.mainSegments, {
+          isAction: true,
+          interceptSegments:
+            errorResult.interceptSegments.length > 0
+              ? errorResult.interceptSegments
+              : undefined,
+        });
 
-      // Reconcile error segments with cached tree
-      const errorResult = reconcileErrorSegments(cachedSegments, segments);
+        // Re-check route stability after async renderSegments — user may have
+        // navigated away while the error tree was being prepared.
+        if (window.location.pathname !== actionStartPathname) {
+          log("user navigated during error render, skipping");
+          if (returnValue && !returnValue.ok) {
+            throw returnValue.data;
+          }
+          handle.complete(undefined);
+          return undefined;
+        }
+        const currentKeyNow = store.getHistoryKey();
+        if (currentKeyNow !== currentKey) {
+          log("history key changed during error render, skipping cache update");
+          if (returnValue && !returnValue.ok) {
+            throw returnValue.data;
+          }
+          handle.complete(undefined);
+          return undefined;
+        }
 
-      // Render the full tree with error segment merged with parent layouts
-      const errorTree = await renderSegments(errorResult.mainSegments, {
-        isAction: true,
-        interceptSegments:
-          errorResult.interceptSegments.length > 0
-            ? errorResult.interceptSegments
-            : undefined,
-      });
+        // Update segment tracking to exclude error segment IDs
+        const errorSegmentIds = new Set(diff);
+        const segmentIdsAfterError = segmentState.currentSegmentIds.filter(
+          (id) => !errorSegmentIds.has(id),
+        );
 
-      // Re-check route stability after async renderSegments — user may have
-      // navigated away while the error tree was being prepared.
-      if (window.location.pathname !== actionStartPathname) {
-        log("user navigated during error render, skipping");
+        // Cache (and bump the nav instance) BEFORE the UI update so a deferred
+        // handle pushed by the error-boundary render still applies — see the
+        // "normal" case below for why caching after onUpdate dropped it.
+        store.setSegmentIds(segmentIdsAfterError);
+        const currentHandleData = eventController.getHandleState().data;
+        store.cacheSegmentsForHistory(
+          currentKey,
+          errorResult.segments,
+          currentHandleData,
+        );
+
+        // Update UI with error boundary
+        startTransition(() => {
+          onUpdate({ root: errorTree, metadata: metadata! });
+        });
+
+        // Throw the error so the action promise rejects
         if (returnValue && !returnValue.ok) {
           throw returnValue.data;
         }
+
+        // No error in returnValue (shouldn't happen with isError: true)
         handle.complete(undefined);
         return undefined;
       }
-      const currentKeyNow = store.getHistoryKey();
-      if (currentKeyNow !== currentKey) {
-        log("history key changed during error render, skipping cache update");
-        if (returnValue && !returnValue.ok) {
-          throw returnValue.data;
-        }
-        handle.complete(undefined);
-        return undefined;
+
+      if (!isPartial) {
+        // Protocol invariant: action revalidation responses MUST be partial.
+        // The server always sends isPartial: true for successful revalidation
+        // and isPartial: true + isError: true for error boundary responses.
+        // A non-partial payload here indicates a server-side bug.
+        throw new Error(
+          `[Browser] Action response missing isPartial — the server must ` +
+            `always send partial payloads for action revalidation.`,
+        );
       }
 
-      // Update UI with error boundary
-      startTransition(() => {
-        onUpdate({ root: errorTree, metadata: metadata! });
+      log("processing partial update", {
+        serverSegments: segments?.length ?? 0,
+        diff: diff?.join(", ") ?? "",
+        matched: matched?.join(", ") ?? "",
       });
 
-      // Update segment tracking to exclude error segment IDs
-      const errorSegmentIds = new Set(diff);
-      const segmentIdsAfterError = segmentState.currentSegmentIds.filter(
-        (id) => !errorSegmentIds.has(id),
-      );
+      // Record revalidated segments for concurrent action tracking
+      if (diff) {
+        handle.recordRevalidatedSegments(diff);
+      }
 
-      // Update store state
-      store.setSegmentIds(segmentIdsAfterError);
-      const currentHandleData = eventController.getHandleState().data;
-      store.cacheSegmentsForHistory(
-        currentKey,
-        errorResult.segments,
-        currentHandleData,
-      );
+      // Get current page's cached segments for merging
+      const currentKey = store.getHistoryKey();
+      const cached = store.getCachedSegments(currentKey);
+      const cachedSegments = cached?.segments || [];
+
+      if (!matched) {
+        throw new Error("No matched segments in response");
+      }
+
+      // Reconcile server segments with cached segments (single source of truth)
+      const reconciled = reconcileSegments({
+        actor: "action",
+        matched,
+        diff: diff || [],
+        serverSegments: segments || [],
+        cachedSegments,
+      });
+      const fullSegments = reconciled.segments;
+
+      const returnData = returnValue?.data;
 
-      // Throw the error so the action promise rejects
       if (returnValue && !returnValue.ok) {
+        handle.fail(returnValue.data);
         throw returnValue.data;
       }
 
-      // No error in returnValue (shouldn't happen with isError: true)
-      handle.complete(undefined);
-      return undefined;
-    }
+      // Classify the post-reconciliation scenario
+      const scenario = classifyActionOutcome({
+        handleId: handle.id,
+        inflightActions: eventController.getInflightActions(),
+        hadAnyConcurrentActions: eventController.hadAnyConcurrentActions(),
+        revalidatedSegments: handle.getRevalidatedSegments(),
+        actionStartPathname,
+        currentPathname: window.location.pathname,
+        actionStartLocationKey: locationKey,
+        currentLocationKey: window.history.state?.key,
+        reconciledSegmentCount: fullSegments.length,
+        matchedCount: matched.length,
+        currentInterceptSource: store.getInterceptSourceUrl(),
+      });
 
-    if (!isPartial) {
-      // Protocol invariant: action revalidation responses MUST be partial.
-      // The server always sends isPartial: true for successful revalidation
-      // and isPartial: true + isError: true for error boundary responses.
-      // A non-partial payload here indicates a server-side bug.
-      throw new Error(
-        `[Browser] Action response missing isPartial — the server must ` +
-          `always send partial payloads for action revalidation.`,
-      );
-    }
+      // 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);
+      }
 
-    log("processing partial update", {
-      serverSegments: segments?.length ?? 0,
-      diff: diff?.join(", ") ?? "",
-      matched: matched?.join(", ") ?? "",
-    });
+      switch (scenario.type) {
+        case "navigated-away": {
+          log("user navigated away during action", {
+            from: actionStartPathname,
+            to: window.location.pathname,
+            historyKeyChanged: scenario.historyKeyChanged,
+          });
+          // Clear concurrent action tracking - don't consolidate for old route's segments
+          handle.clearConsolidation();
+
+          if (scenario.historyKeyChanged) {
+            // 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(
+                  "[Browser] Background revalidation failed:",
+                  error,
+                );
+              });
+            }
+            break;
+          }
 
-    // Record revalidated segments for concurrent action tracking
-    if (diff) {
-      handle.recordRevalidatedSegments(diff);
-    }
+          // 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;
+        }
 
-    // Get current page's cached segments for merging
-    const currentKey = store.getHistoryKey();
-    const cached = store.getCachedSegments(currentKey);
-    const cachedSegments = cached?.segments || [];
+        case "hmr-missing": {
+          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 });
+          break;
+        }
 
-    if (!matched) {
-      throw new Error("No matched segments in response");
-    }
+        case "consolidation-needed": {
+          log("consolidation fetch needed", {
+            segmentIds: scenario.segmentIds,
+          });
+          // 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),
+          );
 
-    // Reconcile server segments with cached segments (single source of truth)
-    const reconciled = reconcileSegments({
-      actor: "action",
-      matched,
-      diff: diff || [],
-      serverSegments: segments || [],
-      cachedSegments,
-    });
-    const fullSegments = reconciled.segments;
-
-    const returnData = returnValue?.data;
-
-    if (returnValue && !returnValue.ok) {
-      handle.fail(returnValue.data);
-      throw returnValue.data;
-    }
+          // Clear consolidation tracking before fetch
+          handle.clearConsolidation();
 
-    // Classify the post-reconciliation scenario
-    const scenario = classifyActionOutcome({
-      handleId: handle.id,
-      inflightActions: eventController.getInflightActions(),
-      hadAnyConcurrentActions: eventController.hadAnyConcurrentActions(),
-      revalidatedSegments: handle.getRevalidatedSegments(),
-      actionStartPathname,
-      currentPathname: window.location.pathname,
-      actionStartLocationKey: locationKey,
-      currentLocationKey: window.history.state?.key,
-      reconciledSegmentCount: fullSegments.length,
-      matchedCount: matched.length,
-      currentInterceptSource: store.getInterceptSourceUrl(),
-    });
-
-    switch (scenario.type) {
-      case "navigated-away": {
-        log("user navigated away during action", {
-          from: actionStartPathname,
-          to: window.location.pathname,
-          historyKeyChanged: scenario.historyKeyChanged,
-        });
-        // Clear concurrent action tracking - don't consolidate for old route's segments
-        handle.clearConsolidation();
+          // Ungated on keepCache, same as hmr-missing above (see the keep row).
+          await refetchRoute({
+            segments: segmentsToSend,
+            interceptSourceUrl,
+          });
+          break;
+        }
 
-        if (scenario.historyKeyChanged) {
-          if (!scenario.onInterceptRoute) {
-            store.markCacheAsStaleAndBroadcast();
-            refetchRoute().catch((error) => {
-              if (isBackgroundSuppressible(error)) return;
-              console.error("[Browser] Background revalidation failed:", error);
-            });
+        case "concurrent-skip": {
+          log("skipping UI update, other actions fetching", {
+            otherCount: scenario.otherFetchingCount,
+          });
+          // 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(
+              currentKey,
+              fullSegments,
+              currentHandleData,
+            );
           }
           break;
         }
 
-        // Same history key but different pathname - safe to refetch current route
-        store.markCacheAsStaleAndBroadcast();
-        await refetchRoute({
-          interceptSourceUrl: store.getInterceptSourceUrl(),
-        });
-        break;
-      }
-
-      case "hmr-missing": {
-        console.warn(
-          `[Browser] Missing segments after action (HMR detected), refetching...`,
-        );
-        await refetchRoute({ interceptSourceUrl });
-        store.broadcastCacheInvalidation();
-        break;
-      }
-
-      case "consolidation-needed": {
-        log("consolidation fetch needed", { segmentIds: scenario.segmentIds });
-        // Calculate segments to send (exclude the ones we want fresh)
-        const currentSegmentIds = store.getSegmentState().currentSegmentIds;
-        const segmentsToSend = currentSegmentIds.filter(
-          (sid) => !scenario.segmentIds.includes(sid),
-        );
+        case "normal": {
+          // Prepare new tree (await loader data resolution)
+          const newTree = await renderSegments(reconciled.mainSegments, {
+            isAction: true,
+            interceptSegments:
+              reconciled.interceptSegments.length > 0
+                ? reconciled.interceptSegments
+                : undefined,
+          });
 
-        // Clear consolidation tracking before fetch
-        handle.clearConsolidation();
+          // Re-check if user navigated away (could happen during async renderSegments)
+          if (window.location.pathname !== actionStartPathname) {
+            log("user navigated during render, skipping");
+            break;
+          }
 
-        await refetchRoute({
-          segments: segmentsToSend,
-          interceptSourceUrl,
-        });
-        store.broadcastCacheInvalidation();
-        break;
-      }
+          // Verify the store's current key still matches what we captured at action start
+          // If they differ, user navigated away and we should NOT cache under the old key
+          const currentKeyNow = store.getHistoryKey();
+          if (currentKeyNow !== currentKey) {
+            log("history key changed during action, skipping cache update");
+            break;
+          }
 
-      case "concurrent-skip": {
-        log("skipping UI update, other actions fetching", {
-          otherCount: scenario.otherFetchingCount,
-        });
-        // Only update store if history key hasn't changed (user didn't navigate away)
-        const currentKeyNow = store.getHistoryKey();
-        if (currentKeyNow === currentKey) {
+          // Cache (and bump the nav instance) BEFORE the UI update, matching the
+          // navigation commit order (navigation-transaction.ts:157). processHandles
+          // is spawned by onUpdate and captures the current nav instance up front;
+          // a deferred handle value resolves asynchronously and is only applied
+          // while stillLive() (its captured instance still owns the page). Caching
+          // AFTER onUpdate bumped the instance out from under that in-flight
+          // resolve, so stillLive() turned false and the resolved handle snapshot
+          // was dropped on the action-revalidation path (sync siblings sharing the
+          // yield are held atomically, so they were dropped too).
+          //
+          // Location state already applied above (pre-switch). Update store.
           store.setSegmentIds(matched);
           const currentHandleData = eventController.getHandleState().data;
           store.cacheSegmentsForHistory(
@@ -578,59 +799,27 @@ export function createServerActionBridge(
             fullSegments,
             currentHandleData,
           );
-        }
-        break;
-      }
-
-      case "normal": {
-        // Prepare new tree (await loader data resolution)
-        const newTree = await renderSegments(reconciled.mainSegments, {
-          isAction: true,
-          interceptSegments:
-            reconciled.interceptSegments.length > 0
-              ? reconciled.interceptSegments
-              : undefined,
-        });
-
-        // Re-check if user navigated away (could happen during async renderSegments)
-        if (window.location.pathname !== actionStartPathname) {
-          log("user navigated during render, skipping");
-          break;
-        }
 
-        // Verify the store's current key still matches what we captured at action start
-        // If they differ, user navigated away and we should NOT cache under the old key
-        const currentKeyNow = store.getHistoryKey();
-        if (currentKeyNow !== currentKey) {
-          log("history key changed during action, skipping cache update");
+          startTransition(() => {
+            onUpdate({ root: newTree, metadata: metadata! });
+          });
+          // Invalidation deferred to finalizeAction() (runs after this caches
+          // the fresh segments), suppressed when the action called
+          // keepClientCache().
           break;
         }
-
-        startTransition(() => {
-          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
-        store.setSegmentIds(matched);
-        const currentHandleData = eventController.getHandleState().data;
-        store.cacheSegmentsForHistory(
-          currentKey,
-          fullSegments,
-          currentHandleData,
-        );
-        store.markCacheAsStaleAndBroadcast();
-        break;
       }
-    }
 
-    handle.complete(returnData);
-    return returnData;
+      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]();
+    }
   }
 
   return {