@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.130

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

@@ -2,25 +2,41 @@ import type {
   ServerActionBridge,
   ServerActionBridgeConfig,
   RscPayload,
-  ResolvedSegment,
-  NavigationStore,
 } from "./types.js";
 import { createPartialUpdater } from "./partial-update.js";
-import { createNavigationTransaction } from "./navigation-bridge.js";
+import { enterActionFence, exitActionFence } from "./action-fence.js";
+import { KEEP_CACHE_HEADER } from "./cookie-name.js";
+import { createNavigationTransaction } from "./navigation-transaction.js";
 import {
-  mergeSegmentLoaders,
-  needsLoaderMerge,
-} from "./merge-segment-loaders.js";
-import { assertSegmentStructure } from "./segment-structure-assert.js";
-import { startTransition, createElement } from "react";
-import type { EventController, ActionHandle } from "./event-controller.js";
-import { NetworkError, isNetworkError } from "../errors.js";
-import { NetworkErrorThrower } from "../network-error-thrower.js";
+  reconcileSegments,
+  reconcileErrorSegments,
+} from "./segment-reconciler.js";
+import { startTransition } from "react";
+import type { EventController } from "./event-controller.js";
+import {
+  toNetworkError,
+  emitNetworkError,
+  isBackgroundSuppressible,
+} from "./network-error-handler.js";
 import {
   browserDebugLog,
   isBrowserDebugEnabled,
   startBrowserTransaction,
 } from "./logging.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") {
@@ -30,26 +46,16 @@ if (typeof Symbol.asyncDispose === "undefined") {
   (Symbol as any).asyncDispose = Symbol("Symbol.asyncDispose");
 }
 
-/**
- * Normalize action ID - returns the ID as-is
- *
- * Server actions have IDs like "hash#actionName" or "src/actions.ts#actionName".
- * The full ID is used for tracking in the event controller. When subscribing
- * via useAction, both exact matching (full ID) and suffix matching (action name
- * only) are supported by the event controller.
- */
-function normalizeActionId(actionId: string): string {
-  return actionId;
-}
-
 /**
  * Extended configuration for server action bridge with event controller
  */
-export interface ServerActionBridgeConfigWithController
-  extends ServerActionBridgeConfig {
+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,
+    options?: { state?: unknown; replace?: boolean; _skipCache?: boolean },
+  ) => Promise<void>;
 }
 
 /**
@@ -66,10 +72,37 @@ export interface ServerActionBridgeConfigWithController
  * @returns ServerActionBridge instance
  */
 export function createServerActionBridge(
-  config: ServerActionBridgeConfigWithController
+  config: ServerActionBridgeConfigWithController,
 ): ServerActionBridge {
-  const { store, client, eventController, deps, onUpdate, renderSegments, version } =
-    config;
+  const {
+    store,
+    client,
+    eventController,
+    deps,
+    onUpdate,
+    renderSegments,
+    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;
 
@@ -78,9 +111,46 @@ export function createServerActionBridge(
     client,
     onUpdate,
     renderSegments,
-    version,
+    getVersion: getAppVersion,
   });
 
+  /**
+   * Refetch current route via a navigation transaction.
+   * Encapsulates the repeated pattern of creating a navTx + fetchPartialUpdate
+   * used by navigated-away, hmr-missing, and consolidation-needed scenarios.
+   */
+  async function refetchRoute(opts?: {
+    segments?: string[];
+    interceptSourceUrl?: string | null;
+  }): Promise<void> {
+    const src = opts?.interceptSourceUrl ?? null;
+    const navTx = createNavigationTransaction(
+      store,
+      eventController,
+      window.location.href,
+      { replace: true, skipLoadingState: true },
+    );
+    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]();
+    }
+  }
+
   /**
    * Server action callback handler
    */
@@ -88,291 +158,428 @@ export function createServerActionBridge(
     const tx = isBrowserDebugEnabled()
       ? startBrowserTransaction("action")
       : null;
-    // Normalize action ID to just the function name for store tracking
+    const log = (msg: string, details?: Record<string, unknown>) => {
+      if (tx) browserDebugLog(tx, msg, details);
+    };
+
     const locationKey = window.history.state?.key;
-    const actionId = normalizeActionId(id);
-    if (tx) {
-      browserDebugLog(tx, "action start", { id, actionId, argsCount: args.length });
-    }
+    log("action start", { id, argsCount: args.length });
 
     // Start action in event controller - handles lifecycle tracking
-    using handle = eventController.startAction(actionId, args);
-
-    const segmentState = store.getSegmentState();
-    if (tx) {
-      browserDebugLog(tx, "action args prepared");
-    }
-
-    // Mark cache as stale immediately when action starts
-    // This ensures SWR pattern kicks in if user navigates away during action
-    store.markCacheAsStaleAndBroadcast();
-
-    // 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
-    if (version) {
-      url.searchParams.set("_rsc_v", version);
-    }
+    const handle = eventController.startAction(id, args);
+    // 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);
+      }
 
-    // Encode arguments
-    const encodedBody = await deps.encodeReply(args, { temporaryReferences });
+      // Encode arguments
+      const encodedBody = await deps.encodeReply(args, { temporaryReferences });
 
-    if (tx) {
-      browserDebugLog(tx, "sending action request", {
+      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;
-
-    // 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,
-    }).then(async (response) => {
-      // Check for version mismatch - server wants us to reload
-      const reloadUrl = response.headers.get("X-RSC-Reload");
-      if (reloadUrl) {
-        if (tx) {
-          browserDebugLog(tx, "version mismatch on action, reloading", { reloadUrl });
-        }
-        window.location.href = reloadUrl;
-        // Return a never-resolving promise to prevent further processing
-        return new Promise<Response>(() => {});
-      }
 
-      // Start streaming immediately when response arrives
-      if (!handle.signal.aborted) {
-        streamingToken = handle.startStreaming();
-      }
-
-      if (!response.body) {
-        // No body means stream is already complete
-        streamingToken?.end();
-        resolveStreamComplete();
-        return response;
-      }
+      // Track when the stream completes
+      let resolveStreamComplete: () => void;
+      const streamComplete = new Promise<void>((resolve) => {
+        resolveStreamComplete = resolve;
+      });
 
-      // Tee the stream: one for RSC runtime, one for tracking completion
-      const [rscStream, trackingStream] = response.body.tee();
+      // 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();
+        }
 
-      // Consume the tracking stream to detect when it closes
-      (async () => {
-        const reader = trackingStream.getReader();
-        try {
-          while (true) {
-            const { done } = await reader.read();
-            if (done) break;
-          }
-        } finally {
-          reader.releaseLock();
-          if (tx) {
-            browserDebugLog(tx, "stream complete");
-          }
-          streamingToken?.end();
+        // 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>(() => {});
         }
-      })().catch((error) => {
-        console.error("[STREAMING] Error reading tracking stream:", error);
-        streamingToken?.end();
-      });
 
-      // Return response with the RSC stream
-      return new Response(rscStream, {
-        headers: response.headers,
-        status: response.status,
-        statusText: response.statusText,
-      });
-    });
+        // Start streaming immediately when response arrives
+        if (!handle.signal.aborted) {
+          streamingToken = handle.startStreaming();
+        }
 
-    // Deserialize response (MUST use same temporaryReferences)
-    let payload: RscPayload;
-    try {
-      payload = await deps.createFromFetch<RscPayload>(responsePromise, {
-        temporaryReferences,
+        return teeWithCompletion(response, () => {
+          log("stream complete");
+          streamingToken?.end();
+          resolveStreamComplete();
+        });
       });
-    } 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!();
-
-      // Convert network-level errors to NetworkError for proper handling
-      if (isNetworkError(error)) {
-        const networkError = new NetworkError(
-          "Unable to connect to server. Please check your connection.",
-          {
-            cause: error,
-            url: url.toString(),
-            operation: "action",
-          }
-        );
 
-        // Mark action as failed
-        handle.fail(networkError);
-
-        // Emit the network error so the root error boundary can catch it
-        // NetworkErrorThrower throws during render to trigger the error boundary
-        startTransition(() => {
-          onUpdate({
-            root: createElement(NetworkErrorThrower, { error: networkError }),
-            metadata: {
-              pathname: segmentState.currentUrl,
-              segments: [],
-              isError: true,
-            },
-          });
+      // 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;
+        }
 
-        throw networkError;
+        // 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;
       }
-      throw error;
-    }
 
-    if (tx) {
-      browserDebugLog(tx, "action response received", {
+      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;
+
+      // 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;
+      }
 
-    // Process response
-    const { metadata, returnValue } = payload;
-    const { matched, diff, segments, isPartial, isError } = metadata || {};
+      // 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 || {};
 
-    // Log action result
-    if (returnValue) {
-      console.log(`[Browser] Action result:`, returnValue);
-      if (!returnValue.ok) {
+      // 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) {
-      console.log(`[Browser] Processing error boundary response`);
+      // Handle error responses with error boundary UI
+      if (isError && isPartial && segments && diff) {
+        log("processing error boundary response");
 
-      // Abort all other pending action requests - error takes precedence
-      // This prevents other actions from completing and overwriting the error UI
-      eventController.abortAllActions();
+        // 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);
+        }
 
-      // Clear concurrent action tracking - no consolidation needed when showing error
-      handle.clearConsolidation();
+        // Abort all other pending action requests - error takes precedence
+        // This prevents other actions from completing and overwriting the error UI
+        eventController.abortAllActions();
 
-      // Get current page's cached segments
-      const currentKey = store.getHistoryKey();
-      const cached = store.getCachedSegments(currentKey);
-      const cachedSegments = cached?.segments || [];
+        // Clear concurrent action tracking - no consolidation needed when showing error
+        handle.clearConsolidation();
 
-      // Create lookup for error segment from server
-      const errorSegmentMap = new Map<string, ResolvedSegment>();
-      segments.forEach((s: ResolvedSegment) => errorSegmentMap.set(s.id, s));
-
-      // For error responses, use ALL cached segments but replace the errored one
-      // This preserves sibling layouts that aren't in the parent chain
-      const fullSegments = cachedSegments.map((cached) => {
-        // Replace the error segment with the one from server
-        const fromServer = errorSegmentMap.get(cached.id);
-        if (fromServer) return fromServer;
-        return cached;
-      });
+        // 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,
+        });
 
-      // INTERCEPT HANDLING: Separate intercept segments for explicit injection
-      const isInterceptSegment = (s: ResolvedSegment) =>
-        s.namespace?.startsWith("intercept:") ||
-        (s.type === "parallel" && s.id.includes(".@"));
-
-      const interceptSegments = fullSegments.filter(isInterceptSegment);
-      const mainSegments = fullSegments.filter((s) => !isInterceptSegment(s));
-
-      // Render the full tree with error segment merged with parent layouts
-      const errorRenderOptions = {
-        isAction: true,
-        interceptSegments:
-          interceptSegments.length > 0 ? interceptSegments : undefined,
-      };
-      const errorTree = await renderSegments(mainSegments, errorRenderOptions);
-
-      // Update UI with error boundary
-      startTransition(() => {
-        onUpdate({ root: errorTree, metadata: metadata! });
-      });
+        // 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;
+        }
 
-      console.log(`[Browser] Error boundary UI rendered`);
+        // Update UI with error boundary
+        startTransition(() => {
+          onUpdate({ root: errorTree, metadata: metadata! });
+        });
 
-      // Update segment tracking to exclude error segment IDs
-      const errorSegmentIds = new Set(diff);
-      const segmentIdsAfterError = segmentState.currentSegmentIds.filter(
-        (id) => !errorSegmentIds.has(id)
-      );
+        // Update segment tracking to exclude error segment IDs
+        const errorSegmentIds = new Set(diff);
+        const segmentIdsAfterError = segmentState.currentSegmentIds.filter(
+          (id) => !errorSegmentIds.has(id),
+        );
 
-      // Update store state
-      store.setSegmentIds(segmentIdsAfterError);
-      const currentHandleData = eventController.getHandleState().data;
-      store.cacheSegmentsForHistory(currentKey, fullSegments, currentHandleData);
+        // Update store state
+        store.setSegmentIds(segmentIdsAfterError);
+        const currentHandleData = eventController.getHandleState().data;
+        store.cacheSegmentsForHistory(
+          currentKey,
+          errorResult.segments,
+          currentHandleData,
+        );
 
-      console.log(
-        `[Browser] Segment IDs updated (excluding error segments):`,
-        segmentIdsAfterError
-      );
+        // Throw the error so the action promise rejects
+        if (returnValue && !returnValue.ok) {
+          throw 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;
       }
 
-      // No error in returnValue (shouldn't happen with isError: true)
-      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.`,
+        );
+      }
 
-    if (isPartial) {
-      console.log(`[Browser] Processing partial update`);
-      console.log(
-        `[Browser] Server sent ${segments?.length || 0} segments in diff:`,
-        diff
-      );
-      console.log(`[Browser] Server expects client to have:`, matched);
+      log("processing partial update", {
+        serverSegments: segments?.length ?? 0,
+        diff: diff?.join(", ") ?? "",
+        matched: matched?.join(", ") ?? "",
+      });
 
       // Record revalidated segments for concurrent action tracking
       if (diff) {
@@ -383,375 +590,188 @@ export function createServerActionBridge(
       const currentKey = store.getHistoryKey();
       const cached = store.getCachedSegments(currentKey);
       const cachedSegments = cached?.segments || [];
-      const currentSegmentMap = new Map<string, ResolvedSegment>();
-      cachedSegments.forEach((s) => currentSegmentMap.set(s.id, s));
-
-      console.log(
-        `[Browser] Client cache has ${currentSegmentMap.size} entries:`,
-        Array.from(currentSegmentMap.keys())
-      );
-
-      // Create lookup for new segments from server
-      const newSegmentMap = new Map<string, ResolvedSegment>();
-      (segments || []).forEach((s: ResolvedSegment) =>
-        newSegmentMap.set(s.id, s)
-      );
 
       if (!matched) {
-        console.log(`[Browser] Matched segments: ${matched}`);
         throw new Error("No matched segments in response");
       }
 
-      // Rebuild from matched: merge server segments with cached, or use cached as fallback
-      const fullSegments = matched
-        .map((segId: string) => {
-          const fromServer = newSegmentMap.get(segId);
-          const fromCache = currentSegmentMap.get(segId);
-
-          if (fromServer) {
-            // Server returned this segment - check if we need to merge partial loaders
-            if (needsLoaderMerge(fromServer, fromCache)) {
-              return mergeSegmentLoaders(fromServer, fromCache);
-            }
-            // When server returns component: null for a layout segment, it means
-            // "this segment doesn't need re-rendering" - preserve the cached component
-            // to maintain the outlet chain and prevent React tree changes
-            const cached = currentSegmentMap.get(segId); // Re-fetch to avoid type narrowing issues
-            if (
-              fromServer.component === null &&
-              fromServer.type === "layout" &&
-              cached?.component != null
-            ) {
-              console.log(
-                `[Browser] Preserving cached component for layout ${segId} (server returned null)`
-              );
-              return { ...fromServer, component: cached.component };
-            }
-            // Dev-mode assertion: warn if tree structure would change
-            if (cached) {
-              assertSegmentStructure(cached, fromServer, "action-bridge");
-            }
-            // Preserve cached loading value to maintain consistent tree structure.
-            // SSR may set loading=false for skipSSR routes, but actions set
-            // loading=<skeleton> (isSSR=false). Changing loading between renders
-            // alters the React tree (with/without RouteContentWrapper), causing
-            // remounts that destroy useActionState.
-            if (
-              cached &&
-              cached.loading !== undefined &&
-              fromServer.loading !== cached.loading
-            ) {
-              return { ...fromServer, loading: cached.loading };
-            }
-            return fromServer;
-          }
-
-          // Fall back to current page's cached segments
-          if (!fromCache) {
-            console.error(`[Browser] MISSING SEGMENT: ${segId} not in cache!`);
-          }
-          return fromCache;
-        })
-        .filter(Boolean) as ResolvedSegment[];
-
-      console.log(
-        `[Browser] Rebuilt ${fullSegments.length} segments from matched array`
-      );
+      // 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;
 
-      console.log(
-        `[Browser] Action complete - UI updated (after action state committed)`
-      );
-
       if (returnValue && !returnValue.ok) {
         handle.fail(returnValue.data);
         throw returnValue.data;
       }
 
-      // Check if user navigated away during the action
-      const currentPathname = window.location.pathname;
-      const currentLocationKey = window.history.state?.key;
-      const userNavigatedAway =
-        currentPathname !== actionStartPathname ||
-        currentLocationKey !== locationKey;
-
-      if (userNavigatedAway) {
-        console.log(
-          `[Browser] User navigated away during action (${actionStartPathname} -> ${currentPathname})`
-        );
-        // Clear concurrent action tracking - don't consolidate for old route's segments
-        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(),
+      });
 
-        // Check if the history key changed (different cache entry)
-        // This happens when navigating between intercept and non-intercept routes
-        if (currentLocationKey !== locationKey) {
-          console.log(
-            `[Browser] History key changed (${locationKey} -> ${currentLocationKey}), triggering background revalidation`
-          );
+      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;
+          }
 
-          // The action completed on the server, but the user navigated to a different route.
-          // The navigation fetch may have gotten stale data (before action committed).
-          // Trigger a background revalidation of the CURRENT route to get fresh data.
-          // User navigated to a different history entry.
-          // Check if we should do background revalidation:
-          // - YES if user is on a non-intercept route (safe to revalidate)
-          // - NO if user is on an intercept route (would lose background segments)
-          const currentInterceptSource = store.getInterceptSourceUrl();
-          if (currentInterceptSource) {
-            // User is on an intercept route - skip revalidation to preserve background
-            console.log(
-              `[Browser] Skipping background revalidation - user on intercept route`
-            );
-          } else {
-            // User is on a non-intercept route - safe to revalidate
-            console.log(
-              `[Browser] History key changed, triggering background revalidation`
-            );
-            store.markCacheAsStaleAndBroadcast();
-            using navTx = createNavigationTransaction(
-              store,
-              eventController,
-              window.location.href,
-              { replace: true, skipLoadingState: true }
-            );
-            fetchPartialUpdate(
-              window.location.href,
-              [],
-              false,
-              navTx.handle.signal,
-              navTx.with({
-                url: window.location.href,
-                storeOnly: true,
-              }),
-              {
-                isAction: true,
-              }
-            ).then(() => {
-              console.log(`[Browser] Background revalidation complete`);
+          // 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(),
             });
           }
-
-          handle.complete(returnData);
-          return returnData;
+          break;
         }
 
-        // Same history key but different pathname (e.g., same-page navigation)
-        // Safe to refetch current route
-        console.log(`[Browser] Same history key, refetching current route`);
-        store.markCacheAsStaleAndBroadcast();
-        using navTx = createNavigationTransaction(
-          store,
-          eventController,
-          window.location.href,
-          { replace: true, skipLoadingState: true }
-        );
-        // Preserve intercept context
-        const currentInterceptSource = store.getInterceptSourceUrl();
-        await fetchPartialUpdate(
-          window.location.href,
-          [], // Empty array = refetch all segments for current route
-          false,
-          navTx.handle.signal,
-          navTx.with({
-            url: window.location.href,
-            storeOnly: true,
-            intercept: !!currentInterceptSource,
-            interceptSourceUrl: currentInterceptSource ?? undefined,
-          }),
-          {
-            isAction: true,
-            interceptSourceUrl: currentInterceptSource ?? undefined,
-          }
-        );
-        console.log(`[Browser] Refetch after navigation complete`);
-        handle.complete(returnData);
-        return returnData;
-      }
-
-      // HMR resilience check - only runs if user DIDN'T navigate away
-      if (fullSegments.length < matched.length) {
-        console.warn(
-          `[Browser] Missing segments after action (HMR detected), refetching...`
-        );
-
-        using navTx = createNavigationTransaction(
-          store,
-          eventController,
-          window.location.href,
-          { replace: true, skipLoadingState: true }
-        );
-        await fetchPartialUpdate(
-          window.location.href,
-          [],
-          false,
-          navTx.handle.signal,
-          navTx.with({
-            url: window.location.href,
-            storeOnly: true,
-            intercept: !!interceptSourceUrl,
-            interceptSourceUrl: interceptSourceUrl ?? undefined,
-          }),
-          {
-            isAction: true,
-            interceptSourceUrl: interceptSourceUrl ?? undefined,
-          }
-        );
-        console.log(
-          `[Browser] Refetch complete (HMR), now returning action result`
-        );
+        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;
+        }
 
-        // Broadcast to other tabs
-        store.broadcastCacheInvalidation();
-        handle.complete(returnData);
-        return returnData;
-      }
+        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),
+          );
 
-      // Check if we need a consolidation fetch due to concurrent actions
-      const consolidationSegments = handle.getConsolidationSegments();
+          // Clear consolidation tracking before fetch
+          handle.clearConsolidation();
 
-      if (consolidationSegments && consolidationSegments.length > 0) {
-        // This is the last concurrent action - do consolidation fetch
-        console.log(
-          `[Browser] Concurrent actions detected - consolidation fetch needed for:`,
-          consolidationSegments
-        );
-        // Calculate segments to send (exclude the ones we want fresh)
-        const currentSegmentIds = store.getSegmentState().currentSegmentIds;
-        const segmentsToSend = currentSegmentIds.filter(
-          (id) => !consolidationSegments.includes(id)
-        );
+          // Ungated on keepCache, same as hmr-missing above (see the keep row).
+          await refetchRoute({
+            segments: segmentsToSend,
+            interceptSourceUrl,
+          });
+          break;
+        }
 
-        console.log(
-          `[Browser] Sending segments (excluding revalidated):`,
-          segmentsToSend
-        );
+        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) {
+            store.setSegmentIds(matched);
+            const currentHandleData = eventController.getHandleState().data;
+            store.cacheSegmentsForHistory(
+              currentKey,
+              fullSegments,
+              currentHandleData,
+            );
+          }
+          break;
+        }
 
-        // Clear consolidation tracking before fetch
-        handle.clearConsolidation();
+        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,
+          });
 
-        using navTx = createNavigationTransaction(
-          store,
-          eventController,
-          window.location.href,
-          { replace: true, skipLoadingState: true }
-        );
+          // Re-check if user navigated away (could happen during async renderSegments)
+          if (window.location.pathname !== actionStartPathname) {
+            log("user navigated during render, skipping");
+            break;
+          }
 
-        console.warn("Fetch partial", id);
-        await fetchPartialUpdate(
-          window.location.href,
-          segmentsToSend,
-          false,
-          navTx.handle.signal,
-          navTx.with({
-            url: window.location.href,
-            storeOnly: true,
-            intercept: !!interceptSourceUrl,
-            interceptSourceUrl: interceptSourceUrl ?? undefined,
-          }),
-          {
-            isAction: true,
-            interceptSourceUrl: interceptSourceUrl ?? undefined,
+          // 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;
           }
-        );
 
-        console.log(`[Browser] Consolidation fetch complete`);
-        // Broadcast to other tabs
-        store.broadcastCacheInvalidation();
-        console.log(
-          `[Browser] Consolidate/Reconcile - Returning to React:`,
-          returnData
-        );
+          startTransition(() => {
+            onUpdate({ root: newTree, metadata: metadata! });
+          });
 
-        handle.complete(returnData);
-        return returnData;
-      }
+          // Apply server-set location state to history.state (non-redirect flow)
+          const actionLocationState = metadata?.locationState;
+          if (actionLocationState) {
+            mergeLocationState(actionLocationState);
+          }
 
-      // Check if there are OTHER actions still fetching (waiting for server response)
-      // Exclude the current action since we already have our response
-      // We don't need to wait for streaming to complete - just for the response to arrive
-      const otherFetchingActions = [...eventController.getInflightActions().values()].filter(
-        (a) => a.phase === "fetching" && a.id !== handle.id
-      );
-      if (otherFetchingActions.length > 0) {
-        console.log(
-          `[Browser] Skipping UI update - ${otherFetchingActions.length} other action(s) still fetching`
-        );
-        console.log(
-          `[Browser] Multi actions - Returning to React (no cache clear):`,
-          returnData
-        );
-        // Only update store if history key hasn't changed (user didn't navigate away)
-        const currentKeyNow = store.getHistoryKey();
-        if (currentKeyNow === currentKey) {
+          // Update store state
           store.setSegmentIds(matched);
           const currentHandleData = eventController.getHandleState().data;
-          store.cacheSegmentsForHistory(currentKey, fullSegments, currentHandleData);
-        } else {
-          console.log(
-            `[Browser] History key changed during multi-action (${currentKey} -> ${currentKeyNow}), skipping cache update`
+          store.cacheSegmentsForHistory(
+            currentKey,
+            fullSegments,
+            currentHandleData,
           );
+          // Invalidation deferred to finalizeAction() (runs after this caches
+          // the fresh segments), suppressed when the action called
+          // keepClientCache().
+          break;
         }
-        handle.complete(returnData);
-        return returnData;
-      }
-
-      // No concurrent actions - normal flow with single action
-      // INTERCEPT HANDLING: Separate intercept segments for explicit injection
-      const isInterceptSegment = (s: ResolvedSegment) =>
-        s.namespace?.startsWith("intercept:") ||
-        (s.type === "parallel" && s.id.includes(".@"));
-
-      const interceptSegments = fullSegments.filter(isInterceptSegment);
-      const mainSegments = fullSegments.filter((s) => !isInterceptSegment(s));
-
-      // Prepare new tree (await loader data resolution)
-      const renderOptions = {
-        isAction: true,
-        interceptSegments:
-          interceptSegments.length > 0 ? interceptSegments : undefined,
-      };
-      const newTree = await renderSegments(mainSegments, renderOptions);
-
-      // Re-check if user navigated away (could happen during async wait)
-      const currentPathnameNow = window.location.pathname;
-      if (currentPathnameNow !== actionStartPathname) {
-        console.log(
-          `[Browser] User navigated during UI update scheduling, skipping`
-        );
-        handle.complete(returnData);
-        return returnData;
-      }
-
-      // 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) {
-        console.log(
-          `[Browser] History key changed during action (${currentKey} -> ${currentKeyNow}), skipping cache update`
-        );
-        handle.complete(returnData);
-        return returnData;
       }
 
-      startTransition(() => {
-        onUpdate({ root: newTree, metadata: metadata! });
-      });
-
-      // Update store state
-      store.setSegmentIds(matched);
-      const currentHandleData = eventController.getHandleState().data;
-      store.cacheSegmentsForHistory(currentKey, fullSegments, currentHandleData);
-      store.markCacheAsStaleAndBroadcast();
-
-      console.log(`[Browser] Normal - Returning to React:`, returnData);
       handle.complete(returnData);
       return returnData;
-    } else {
-      // Full update not supported for actions
-      throw new Error(
-        `[Browser] Full update after action is not supported yet`
-      );
+    } 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]();
     }
   }
 
@@ -766,18 +786,6 @@ export function createServerActionBridge(
       }
       deps.setServerCallback(handleServerAction);
       isRegistered = true;
-      console.log("[Browser] Server action callback registered");
-    },
-
-    /**
-     * Unregister the server action callback
-     */
-    unregister(): void {
-      if (!isRegistered) {
-        return;
-      }
-      isRegistered = false;
-      console.log("[Browser] Server action bridge unregistered");
     },
   };
 }