@rshono/core 1.0.0-rc.27 → 1.0.0-rc.29

package/dist/runtime/entry.client.js

@@ -2,12 +2,14 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import React from 'react';
 import { hydrateRoot } from 'react-dom/client';
 import { createFromFetch, createFromReadableStream, createTemporaryReferenceSet, encodeReply, setServerCallback, } from 'react-server-dom-rspack/client.browser';
+import { cancelNavigationPreparation, isPreparedNavigation, listenNavigationPreparation, useNavigationPreparation, } from './navigation-preparation.js';
 import { isControlDigest, parseRedirectDigest } from './control.js';
 // Dev-only: its one caller sits behind `import.meta.webpackHot`, which a production build compiles to
 // `false` — so this module is dropped there.
 import { walkHotUpdates } from './hot-update.js';
 import { RouterContext } from './navigation.js';
 import { createRscRequest } from './request.js';
+import { startNavigationPayload, useNavigationTransition } from './navigation-transition.js';
 const isDev = process.env.NODE_ENV === 'development';
 /** The flight payload the document carried, read back out of `__FLIGHT_DATA` — see `flight-inject.ts`. */
 function readFlightPayload() {
@@ -46,6 +48,8 @@ const documentUrl = () => location.pathname + location.search;
  * Updated in the layout effect that commits a payload.
  */
 let renderedUrl = documentUrl();
+let renderedModel;
+const navigationModels = new WeakMap();
 /** Guarantees somewhere to attach the fatal overlay: the root container is `document`, so a teardown can take `<body>` with it. */
 function overlayHost() {
     if (!document.documentElement)
@@ -134,6 +138,41 @@ function showLateNotFound() {
 }
 /** What every flight response is typed as. The charset and any other parameters follow it. */
 const FLIGHT_CONTENT_TYPE = 'text/x-component';
+/** How much of a body that is not a payload is quoted back in the error. */
+const REFUSAL_BODY_LIMIT = 200;
+/**
+ * The first {@link REFUSAL_BODY_LIMIT} characters of a response body, without buffering the rest.
+ *
+ * `response.text()` reads the whole body first, so a proxy's multi-megabyte error page would be buffered and
+ * decoded before the 200 characters that are kept — on a path that exists to say what answered instead of a
+ * payload. Reading one chunk at a time and cancelling stops paying for bytes nothing will look at.
+ */
+async function refusalBody(response) {
+    if (!response.body)
+        return '';
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let text = '';
+    try {
+        while (text.length < REFUSAL_BODY_LIMIT) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            // `stream: true` so a multi-byte character split across two reads is not replaced by U+FFFD.
+            text += decoder.decode(value, { stream: true });
+        }
+        // Flush a trailing partial multi-byte sequence, so a body cut mid-character reads as U+FFFD rather than
+        // dropping the bytes that were already read.
+        text += decoder.decode();
+    }
+    catch {
+        // A body that failed mid-read says no more than the status already did.
+    }
+    finally {
+        void reader.cancel().catch(() => { });
+    }
+    return text.slice(0, REFUSAL_BODY_LIMIT).trim();
+}
 /**
  * Fetches a payload, refusing a response that is not one.
  *
@@ -151,7 +190,7 @@ async function payloadResponse(request) {
         return response;
     // Read for the message: a plain-text refusal says what it refused only in its body, and HTTP/2 has no
     // `statusText` at all. Bounded, because this is an error path and the body is not ours to trust.
-    const body = await response.text().then((text) => text.trim().slice(0, 200), () => '');
+    const body = await refusalBody(response);
     const status = `${response.status}${response.statusText ? ` ${response.statusText}` : ''}`;
     throw new Error(`[rshono] the server answered ${status} (${contentType ?? 'no content type'}) instead of a payload${body ? `: ${body}` : ''}`);
 }
@@ -308,60 +347,149 @@ const documentNavigation = Symbol('rshono:document-navigation');
  * its Suspense fallback with no second document ever arriving, and how a late `redirect()` moved the address
  * bar to a page it then failed to render.
  *
+ * `replace` puts the loaded document in place of the current entry rather than after it, which is what a
+ * redirect recovery owes: the entry being left is the URL that raised the redirect, and a 30x would have
+ * replaced it, so Back must reach whatever preceded it rather than the URL that redirects again.
+ *
  * The mark rides the navigation itself, through `info`, so the listener recognizes the event that owns it
  * instead of consuming a flag set in advance. There is no state to clear and none to leak: a navigation the
  * browser refuses cannot make the next one a full load. Below the Navigation API there is no interception to
  * opt out of, and `location.*` is already a document load.
  */
-function loadDocument(href) {
+function loadDocument(href, { replace = false } = {}) {
+    finishAttempt(activeAttempt, { kind: 'document-navigation' });
     if (!canSoftNavigate) {
         if (href === undefined)
             window.location.reload();
+        else if (replace)
+            window.location.replace(href);
         else
             window.location.assign(href);
         return;
     }
-    settle(href === undefined ? navigation.reload({ info: documentNavigation }) : navigation.navigate(href, { info: documentNavigation }));
+    try {
+        settle(href === undefined
+            ? navigation.reload({ info: documentNavigation })
+            : navigation.navigate(href, { history: replace ? 'replace' : 'auto', info: documentNavigation }));
+    }
+    catch {
+        // The Navigation API refuses a document that is not fully active — it is unloading — and a URL it cannot
+        // parse. Both callers are recovery paths, where a throw here becomes an unhandled rejection rather than
+        // the document load they asked for. `location.*` is the same load without the interception, and its own
+        // refusal (the same unparseable URL) is swallowed because there is then no load left to make.
+        try {
+            if (href === undefined)
+                window.location.reload();
+            else if (replace)
+                window.location.replace(href);
+            else
+                window.location.assign(href);
+        }
+        catch {
+            // Nothing to navigate to. The caller is already recovering from a failure, and the address bar still
+            // describes the document on screen.
+        }
+    }
 }
 // The imperative actions behind `useNavigation().router`. Each one only *asks*: the browser turns it into a
 // `navigate` event, which is where `listenNavigation` answers it — so a `router.push` and a link click reach
 // the same code by the same route, and inherit the same fetch, scroll and `pending` flag.
+// Carry each caller's completion through its browser event, fetch, and DOM commit.
+const attemptMark = Symbol('rshono:navigation-attempt');
+let activeAttempt;
+let traversalAttempt;
+function finishAttempt(attempt, outcome) {
+    if (!attempt || attempt.done)
+        return;
+    attempt.done = true;
+    attempt.resolve(outcome);
+    if (activeAttempt === attempt)
+        activeAttempt = undefined;
+}
+function rejectAttempt(attempt, error) {
+    if (!attempt || attempt.done)
+        return;
+    attempt.done = true;
+    attempt.reject(error);
+    if (activeAttempt === attempt)
+        activeAttempt = undefined;
+}
+function newAttempt() {
+    const { promise, resolve, reject } = Promise.withResolvers();
+    // Ignoring a router call must not create an unhandled rejection; awaiting this original promise still rejects.
+    void promise.catch(() => { });
+    return { mark: attemptMark, hop: 0, done: false, browserOnlyRendered: false, promise, resolve, reject };
+}
+function requestNavigation(attempt, run) {
+    const hop = attempt.hop;
+    try {
+        const result = run();
+        settle(result);
+        void result.finished?.then(() => {
+            if (attempt.hop === hop && attempt.browserOnlyRendered) {
+                finishAttempt(attempt, { kind: 'rendered', url: new URL(location.href) });
+            }
+        }, (error) => {
+            if (attempt.hop === hop)
+                rejectAttempt(attempt, error);
+        });
+    }
+    catch (error) {
+        rejectAttempt(attempt, error);
+    }
+    return attempt.promise;
+}
+function navigateAttempt(href, history, attempt = newAttempt()) {
+    if (!canSoftNavigate) {
+        if (history === 'replace')
+            window.location.replace(href);
+        else
+            window.location.assign(href);
+        finishAttempt(attempt, { kind: 'document-navigation' });
+        return attempt.promise;
+    }
+    return requestNavigation(attempt, () => navigation.navigate(href, { history, info: attempt }));
+}
 function push(href) {
-    if (canSoftNavigate)
-        settle(navigation.navigate(href, { history: 'push' }));
-    else
-        window.location.assign(href);
+    return navigateAttempt(href, 'push');
 }
 function replace(href) {
-    if (canSoftNavigate)
-        settle(navigation.navigate(href, { history: 'replace' }));
-    else
-        window.location.replace(href);
+    return navigateAttempt(href, 'replace');
 }
-// A traversal is the browser's to perform either way — `navigation` only hands it back as an interceptable
-// event first. Nothing to go back to is a rejection there and a no-op here; both amount to the same thing.
 function back() {
-    if (canSoftNavigate)
-        settle(navigation.back());
-    else
+    if (!canSoftNavigate) {
         window.history.back();
+        return Promise.resolve({ kind: 'document-navigation' });
+    }
+    if (!navigation.canGoBack)
+        return Promise.resolve({ kind: 'no-op' });
+    const attempt = newAttempt();
+    return requestNavigation(attempt, () => navigation.back({ info: attempt }));
 }
 function forward() {
-    if (canSoftNavigate)
-        settle(navigation.forward());
-    else
+    if (!canSoftNavigate) {
         window.history.forward();
+        return Promise.resolve({ kind: 'document-navigation' });
+    }
+    if (!navigation.canGoForward)
+        return Promise.resolve({ kind: 'no-op' });
+    const attempt = newAttempt();
+    return requestNavigation(attempt, () => navigation.forward({ info: attempt }));
 }
-// A refresh keeps the URL, and is still a navigation: it arrives as `navigationType: 'reload'`, which is what
-// tells the listener to leave scroll and focus where the user left them.
 function refresh() {
-    if (canSoftNavigate)
-        settle(navigation.reload());
-    else
+    if (!canSoftNavigate) {
         window.location.reload();
+        return Promise.resolve({ kind: 'document-navigation' });
+    }
+    const attempt = newAttempt();
+    return requestNavigation(attempt, () => navigation.reload({ info: attempt }));
 }
-/** How long the recovery reload is given to replace this document before the panel is painted instead. */
-const RELOAD_GRACE_MS = 2000;
+/**
+ * How long a recovery document load is given to replace this one before the framework paints the panel the
+ * load stands in for. Both recoveries — a late `notFound()` and a payload whose render tore the root down —
+ * ask the browser for a real document, and this timer is all that is left when one is refused or swallowed.
+ */
+const RECOVERY_GRACE_MS = 2000;
 /** The `sessionStorage` key bounding the recovery reload for one URL. Spent here, released in {@link main}. */
 const lateNotFoundKey = () => `rshono:late-not-found:${documentUrl()}`;
 /**
@@ -405,7 +533,7 @@ function reloadOnceForLateNotFound() {
     setTimeout(() => {
         if (!document.querySelector('[data-rshono-fatal]'))
             showLateNotFound();
-    }, RELOAD_GRACE_MS);
+    }, RECOVERY_GRACE_MS);
 }
 /**
  * Turns a control-signal digest — how `redirect()` / `notFound()` reach the browser — into a real
@@ -413,8 +541,13 @@ function reloadOnceForLateNotFound() {
  *
  * `hard` forces a full document load, for signals that surfaced *through React*: it unmounts the root on
  * an uncaught error, leaving no live tree to soft-navigate with.
+ *
+ * A redirect is followed *replacing* the entry that raised it, the way a 30x replaces the URL that answered
+ * with one. `history` lets the action-reply paths that must not — the fetch catch, and a digest surfacing
+ * through React during the reply's render — keep the push they have always had. `notFound()` has nowhere to
+ * go but a reload, and a reload is its own entry already.
  */
-function handleControlDigest(error, { hard = false } = {}) {
+function handleControlDigest(error, { hard = false, history = 'replace' } = {}) {
     const digest = error?.digest;
     if (!isControlDigest(digest))
         return false;
@@ -424,10 +557,14 @@ function handleControlDigest(error, { hard = false } = {}) {
     }
     else if (hard) {
         // The URL is resolved first: a malformed location then throws here, before any navigation is asked for.
-        loadDocument(new URL(redirect.location, window.location.href).href);
+        // Replacing is what keeps the URL that raised the redirect from becoming an entry Back bounces through.
+        loadDocument(new URL(redirect.location, window.location.href).href, { replace: history === 'replace' });
+    }
+    else if (history === 'replace') {
+        void replace(redirect.location);
     }
     else {
-        push(redirect.location);
+        void push(redirect.location);
     }
     return true;
 }
@@ -445,6 +582,58 @@ function scrollToTop() {
 function scrollToPoint(point) {
     window.scrollTo({ top: point.y, left: point.x, behavior: 'instant' });
 }
+/**
+ * How long a commit waits for a fragment target or `autofocus` element that a boundary has not streamed in
+ * yet. Past it the fallback stands — the top of the document, or body focus — and the watch is dropped, so a
+ * fragment that names nothing leaves no observer running behind it.
+ */
+const ELEMENT_WATCH_TIMEOUT_MS = 5_000;
+const pendingElementWatches = new Set();
+let elementObserver = null;
+function stopElementWatch(watch) {
+    clearTimeout(watch.timer);
+    if (!pendingElementWatches.delete(watch))
+        return;
+    if (pendingElementWatches.size === 0) {
+        elementObserver?.disconnect();
+        elementObserver = null;
+    }
+}
+/** Drops every watch; a new navigation owns the screen from here. */
+function cancelElementWatches() {
+    for (const watch of [...pendingElementWatches])
+        stopElementWatch(watch);
+}
+/**
+ * Runs `run` as soon as `find` finds an element, or gives up after {@link ELEMENT_WATCH_TIMEOUT_MS}. When
+ * the element is already there, `run` happens synchronously. `find` and `run` are always passed as a matching
+ * pair; the type-erasure here is what lets one observer serve watches of different element shapes.
+ */
+function watchForElement(find, run) {
+    const present = find();
+    if (present) {
+        run(present);
+        return;
+    }
+    if (elementObserver === null) {
+        elementObserver = new MutationObserver(() => {
+            for (const watch of [...pendingElementWatches]) {
+                const element = watch.find();
+                if (element) {
+                    stopElementWatch(watch);
+                    watch.run(element);
+                }
+            }
+        });
+        elementObserver.observe(document.documentElement, { childList: true, subtree: true });
+    }
+    const watch = {
+        find,
+        run: run,
+        timer: setTimeout(() => stopElementWatch(watch), ELEMENT_WATCH_TIMEOUT_MS),
+    };
+    pendingElementWatches.add(watch);
+}
 /**
  * Scrolls to a fragment's target the way the browser's own fragment jump does.
  *
@@ -453,6 +642,9 @@ function scrollToPoint(point) {
  * "find a potential indicated element": the id first, then the name. A malformed percent-escape falls back
  * to the literal fragment, and a fragment nothing matches gets the top of the document — what a browser
  * gives a missing anchor on a real load.
+ *
+ * A streamed payload commits its shell before a target inside a suspended boundary exists, so a miss is not
+ * final: the top is applied right away, and the watch follows the fragment in when its element arrives.
  */
 function jumpToAnchor(hash) {
     const raw = hash.startsWith('#') ? hash.slice(1) : hash;
@@ -469,24 +661,37 @@ function jumpToAnchor(hash) {
     catch {
         // Malformed escape — the literal fragment is the better guess at the id than nothing.
     }
-    const target = document.getElementById(id) ?? document.getElementsByName(id)[0];
-    if (target)
+    const find = () => document.getElementById(id) ?? document.getElementsByName(id)[0] ?? null;
+    const target = find();
+    if (target) {
         target.scrollIntoView();
-    else
-        scrollToTop();
+        return;
+    }
+    scrollToTop();
+    watchForElement(find, (element) => element.scrollIntoView());
 }
 /**
  * Moves focus the way the browser's `focusReset: 'after-transition'` does: the first `autofocus` element,
  * else the document body. A traversal is no longer intercepted, so the browser performs no focus reset for
  * it; without this, Back would leave focus on the link that was clicked on the page being left, and the next
  * Tab would resume there. `preventScroll` because the traversal's own offset has just been restored.
+ *
+ * The page may still be streaming — a traversal into a page whose `autofocus` element sits in a suspended
+ * boundary — and the browser's own reset follows the element in, so this watches for it with the same bound
+ * as a fragment.
  */
 function resetFocus() {
     const autofocus = document.querySelector('[autofocus]');
-    if (autofocus)
+    if (autofocus) {
         autofocus.focus({ preventScroll: true });
-    else
-        document.body.focus({ preventScroll: true });
+        return;
+    }
+    document.body.focus({ preventScroll: true });
+    watchForElement(() => document.querySelector('[autofocus]'), (element) => {
+        // Only if focus is still where this reset left it: a user who has since focused something else keeps it.
+        if (document.activeElement === document.body)
+            element.focus({ preventScroll: true });
+    });
 }
 /**
  * Puts a payload on screen, resolving once React has committed it. Replaced by `BrowserRoot`'s own on mount;
@@ -501,13 +706,46 @@ let setPayload = () => {
     window.location.reload();
     return new Promise(() => { });
 };
+/**
+ * The payload {@link setPayload} handed React that is still waiting to commit, or `undefined` once it has.
+ *
+ * Read by `onUncaughtError`, where React has decided to unmount the root. A navigation payload that never
+ * committed is the one case a document load can still repair: the URL already names its destination, and
+ * every recovery the runtime has — `popstate`, a link click, `setPayload` — writes into a root that no longer
+ * exists. The server answers that document request with the app's error page, which is a root of its own. An
+ * action reply is not: a GET of the URL it was called from does not re-run the action, so the page renders as
+ * if nothing had happened and the panel is the answer. Deliberately `undefined` for the initial payload and
+ * cleared as soon as a render commits: a deterministic client fault must reach the fatal panel rather than
+ * reload the tab forever.
+ *
+ * Failing the render rejects the commit promise rather than settling it as a success, so every waiter —
+ * `loadPayload`'s caller, the prepared handler — learns the render it asked for has failed and can take its
+ * recovery branch. A render React is only suspending is not failed: it has not given up on it, and neither
+ * may the navigation.
+ */
+let pendingRender;
+/**
+ * The history mode for a `redirect()` that surfaced through React, where {@link pendingRender} is the render
+ * that raised it. A navigation payload names the URL that raised the redirect, so the redirect replaces that
+ * entry. An action reply re-renders the page the visitor is already on — a GET of it does not re-run the
+ * action — so its redirect keeps the push the action's other redirect paths have, and Back returns to the
+ * page that submitted the form. `undefined` — the initial payload, or a render past its commit — is not an
+ * action reply and replaces.
+ */
+function controlDigestHistory() {
+    return pendingRender?.recoversByLoad === false ? 'push' : 'replace';
+}
 /**
  * Re-dispatches the payload already waiting to commit, for {@link loadPayload}'s lost-ping retry. Unlike
  * {@link setPayload} it creates and releases no commit promise, so re-rendering the same payload cannot
  * resolve the navigation's commit early. Assigned with {@link setPayload} by `BrowserRoot`.
  */
 let reapplyPayload = () => { };
-/** Runs work inside the nav transition so `useNavigation().pending` stays true across the round-trip. */
+/**
+ * Runs a navigation's work through `useNavigationTransition`'s runner, which tracks the promise it returns so
+ * `useNavigation().pending` stays true across the whole round-trip rather than only inside a React transition.
+ * The default covers the window before hydration, where no root observes `pending`.
+ */
 let startNav = (run) => {
     void run();
 };
@@ -519,8 +757,23 @@ let startNav = (run) => {
  * after the browser has already committed it — so ordering is the runtime's own for those.
  */
 let currentNavigation = 0;
-/** The in-flight navigation's fetch, so a newer one can stop paying for it. */
-let navigationFetch = null;
+/** An urgent traversal releases a suspended destination in favor of the last committed payload. */
+function restoreCommittedPayload(payload) {
+    currentNavigation++;
+    // The payload has rendered before, but an uncaught error would still tear the root down. Nothing awaits
+    // this commit, so the rejection needs a consumer of its own to reach the document-load recovery.
+    void setPayload(payload).catch(() => loadDocument());
+}
+let navigationFetches = [];
+/** Stop only the requests whose streams no longer belong to a retained render. */
+function abortNavigationFetches(shouldAbort) {
+    navigationFetches = navigationFetches.filter((fetch) => {
+        if (!shouldAbort(fetch))
+            return true;
+        fetch.controller.abort();
+        return false;
+    });
+}
 /**
  * Fetches the payload for `url` and puts it on screen.
  *
@@ -528,41 +781,107 @@ let navigationFetch = null;
  * point, and a `#hash` target does not exist until the new tree does. Rejects only on a genuine failure —
  * being superseded is not one, and resolves quietly, because the navigation that replaced this one owns the
  * screen from then on.
+ *
+ * `prepared`, when given, is a fetch that was started before the URL committed: this call takes over its
+ * abort wiring, so from here it follows the same applied-fetch rules as one this function started.
  */
-function loadPayload(url, signal, afterCommit) {
-    // This navigation's place in the queue, and its own abort switch: a fetch is abandoned by whichever comes
-    // first, the browser superseding it (an intercepted navigation carries `event.signal`) or a newer runtime
-    // fetch starting (a traversal, an action, a dev refresh).
+function loadPayload(url, { signal, afterCommit, attempt, prepared } = {}) {
+    // This navigation's place in the queue, and its own abort switch: the navigation stops being applied by
+    // whichever comes first, the browser superseding it (an intercepted navigation carries `event.signal`) or a
+    // newer runtime fetch starting (a traversal, an action, a dev refresh). The fetch itself runs on until its
+    // payload is on screen and a newer one commits — see {@link navigationFetches}.
     const navigation = ++currentNavigation;
-    navigationFetch?.abort();
-    const controller = (navigationFetch = new AbortController());
-    const abort = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+    const controller = new AbortController();
+    const entry = { navigation, controller, applied: false };
+    navigationFetches.push(entry);
+    // A newer navigation owns the screen now, and an older fetch whose payload never reached React is reading
+    // into a tree that does not exist — stopping it cannot reject a chunk anything holds. One that did reach
+    // React waits for this payload's commit; see {@link navigationFetches}.
+    abortNavigationFetches((fetch) => fetch !== entry && !fetch.applied);
+    // The browser supersedes an intercepted navigation the moment a newer one starts, and `signal` is how it
+    // says so. A fetch React has been handed keeps running (see {@link navigationFetches}), but one that never
+    // reached React stops here: the navigation taking over may be one the runtime does not intercept (a
+    // fragment jump, a download), leaving no commit to stop it later.
+    let abandoned = signal?.aborted ?? false;
+    const abandon = () => {
+        abandoned = true;
+        if (!entry.applied)
+            controller.abort();
+    };
+    if (abandoned)
+        abandon();
+    else
+        signal?.addEventListener('abort', abandon, { once: true });
+    /** Whether this navigation has lost the screen to the browser or to a newer runtime fetch. */
+    const stale = () => abandoned || navigation !== currentNavigation || controller.signal.aborted;
     // Deliberately not awaited inside the transition: the scope ends once the payload is handed to React, and
     // React holds `pending` until the update it scheduled commits. Awaiting the commit *inside* the scope would
     // work too, but only because React happens not to gate a commit on its async scope settling — an internal
     // this has no reason to depend on across the whole `^19.1.0` peer range.
     let committed;
-    // Whether the payload update has committed. A streamed transition can suspend on a flight chunk whose later
-    // resolution React never pings the lane back for; the retry below re-schedules the update once the stream
-    // has closed, but only while this is still false.
     let committedSettled = false;
     const run = async () => {
-        const { payload, settled } = requestPayload(url, abort);
-        const nextPayload = await payload;
+        let fetched;
+        if (prepared) {
+            // The payload is already on the wire and its abort switch belonged to the navigation event up to the
+            // commit. Take over here so the runtime's ownership rules apply from now on: a superseded fetch that
+            // never reached React stops at once, while one React is reading waits for a newer commit.
+            const owned = prepared;
+            const abortPrepared = () => owned.controller.abort(controller.signal.reason);
+            if (controller.signal.aborted)
+                abortPrepared();
+            else
+                controller.signal.addEventListener('abort', abortPrepared, { once: true });
+            void owned.fetched.settled.then(() => controller.signal.removeEventListener('abort', abortPrepared));
+            fetched = owned.fetched;
+        }
+        else {
+            fetched = requestPayload(url, controller.signal);
+        }
+        const nextPayload = await fetched.payload;
         // Checked again after the await because the fetch may already have resolved by then, and applying it
         // would repaint a page the user has left.
-        if (abort.aborted || navigation !== currentNavigation)
+        if (stale())
             return;
         if (nextPayload.redirect) {
-            push(nextPayload.redirect);
+            // Replacing for the same reason as {@link handleControlDigest}: the URL whose payload carried the
+            // redirect is the entry being left, and a push would make Back bounce through it into the same redirect.
+            if (attempt) {
+                attempt.hop++;
+                void navigateAttempt(nextPayload.redirect, 'replace', attempt);
+            }
+            else
+                void replace(nextPayload.redirect);
             return;
         }
         // The fetch crossed an await, so its payload update needs a new synchronous transition scope.
         // Keep the commit promise outside the async Action; React tracks the scheduled update until commit.
-        React.startTransition(() => {
+        startNavigationPayload(() => {
+            // From here React holds this payload's stream, so a superseded fetch may not be stopped until a newer
+            // payload commits — see {@link navigationFetches}.
+            navigationModels.set(controller, nextPayload);
+            entry.applied = true;
             committed = setPayload(nextPayload, afterCommit);
-            void committed.then(() => (committedSettled = true));
+            // Either way this render is settled, so the lost-ping retry below must not wait for it or re-apply it:
+            // a failed render would re-enter a root React has already torn down.
+            void committed.then(() => (committedSettled = true), () => (committedSettled = true));
         });
+        // This payload is on screen, so every fetch it superseded is reading into a tree React has replaced.
+        // Stopping them now cannot reject a chunk the committed tree holds — see {@link navigationFetches}.
+        // Only the older ones: a newer navigation may have started while this payload was in flight, and its
+        // fetch is the one the screen is waiting for.
+        void committed?.then(() => {
+            if (renderedModel !== nextPayload)
+                return;
+            navigationFetches = navigationFetches.filter((fetch) => {
+                if (fetch.navigation >= navigation)
+                    return true;
+                fetch.controller.abort();
+                return false;
+            });
+        }, 
+        // A rejected commit is the caller's to report; this chain only exists to reap older fetches.
+        () => { });
         // A streamed payload can suspend a transition on a flight chunk that resolves after the shell without
         // React ever pinging the suspended lane back, which strands the navigation on the previous tree. The
         // chunks have all landed by the time the stream closes, so one re-application — still a transition, so a
@@ -570,18 +889,18 @@ function loadPayload(url, signal, afterCommit) {
         // lost ping stranded. It goes through `reapplyPayload` rather than `setPayload`: the payload is not
         // replaced, so the commit the navigation waits on has to stay attached to it. The macrotask lets the
         // decoder process the last chunk and React's own retry run first, so the normal path is not interrupted.
-        void settled.then(() => {
-            if (abort.aborted || navigation !== currentNavigation || committedSettled)
+        void fetched.settled.then(() => {
+            if (stale() || committedSettled)
                 return;
             setTimeout(() => {
-                if (abort.aborted || navigation !== currentNavigation || committedSettled)
-                    return;
-                React.startTransition(reapplyPayload);
+                if (!stale() && !committedSettled)
+                    React.startTransition(reapplyPayload);
             }, 0);
         });
     };
-    // `startTransition` runs the work but hands nothing back, so the promise carrying a failure is caught here
-    // instead. Assigned synchronously: React invokes the callback before `startNav` returns.
+    // `startTransition` runs the work but hands nothing back, so the promise carrying a failure is caught by
+    // the rejection handler on `work` below instead. Assigned synchronously: React invokes the callback before
+    // `startNav` returns.
     let work;
     startNav(() => (work = run()));
     return work.then(
@@ -589,7 +908,7 @@ function loadPayload(url, signal, afterCommit) {
     () => committed, (error) => {
         // Checked before the error is read: an abort is this navigation being replaced, and the one that
         // replaced it owns the outcome.
-        if (abort.aborted || navigation !== currentNavigation || handleControlDigest(error))
+        if (stale() || handleControlDigest(error))
             return;
         throw error;
     });
@@ -629,6 +948,30 @@ function leaveToBrowser(event) {
         event.sourceElement?.hasAttribute('data-native') === true ||
         namesAFile(event.destination.url));
 }
+/**
+ * The scroll a committing navigation owes: a push reaches its own fragment or the top, an in-place change
+ * stays where it is. Read at commit rather than at dispatch, so a redirect the preparation followed lands
+ * on the fragment it actually committed.
+ */
+function afterCommitFor(event) {
+    if (event.navigationType !== 'push')
+        return undefined;
+    const { hash } = new URL(event.destination.url);
+    return hash === '' ? scrollToTop : () => jumpToAnchor(hash);
+}
+/** Applies a prepared payload and resolves after React commits it, keeping native `finished` pending until then. */
+function applyPrepared(event, prepared) {
+    const info = event.info;
+    const attempt = info?.mark === attemptMark ? info : undefined;
+    const hop = attempt?.hop;
+    return loadPayload(event.destination.url, { signal: event.signal, afterCommit: afterCommitFor(event), attempt, prepared }).then(() => {
+        if (attempt?.hop === hop && !event.signal.aborted)
+            finishAttempt(attempt, { kind: 'rendered', url: new URL(location.href) });
+    }, (error) => {
+        rejectAttempt(attempt, error);
+        loadDocument();
+    });
+}
 /**
  * The whole router, in one listener.
  *
@@ -641,24 +984,55 @@ function leaveToBrowser(event) {
 function listenNavigation() {
     if (!canSoftNavigate)
         return () => { };
+    const disposePreparation = listenNavigationPreparation({
+        fetchPayload: requestPayload,
+        shouldIntercept: (event) => event.info !== documentNavigation && event.canIntercept && !leaveToBrowser(event),
+        canCommitInPlace: (href) => !namesAFile(href),
+        apply: applyPrepared,
+        fallbackToDocument: loadDocument,
+    });
     const onNavigate = (event) => {
         // A document navigation the runtime asked for itself, marked through `info`. Checked before the scroll
         // snapshot: the document is going away, so where its entry was left does not matter, and an unrelated
         // later navigation can never be mistaken for this one.
         if (event.info === documentNavigation)
             return;
+        const info = event.info;
+        const attempt = info?.mark === attemptMark ? info : undefined;
+        if (activeAttempt && activeAttempt !== attempt)
+            rejectAttempt(activeAttempt, new DOMException('Navigation superseded', 'AbortError'));
+        activeAttempt = attempt;
+        traversalAttempt = undefined;
+        // A commit for the destination being left is no longer the screen's; its pending fragment target (or
+        // `autofocus` element) must not scroll or focus the page that replaces it.
+        cancelElementWatches();
         // Whatever the browser is about to do with this navigation, the entry it is leaving is about to lose the
         // offset it was at, and nothing else in this document will put it back. Saved before the branches below
         // return, so a fragment the browser performs itself is covered too.
         rememberCurrentScroll();
-        if (!event.canIntercept || leaveToBrowser(event))
+        if (!event.canIntercept || leaveToBrowser(event)) {
+            if (attempt) {
+                if (event.hashChange) {
+                    attempt.browserOnlyRendered = true;
+                }
+                else
+                    finishAttempt(attempt, { kind: 'document-navigation' });
+            }
             return;
+        }
         // A traversal is repainted by the `popstate` listener below, not intercepted. `intercept`ing one is what
         // makes WebKit stall the rendered viewport for about three seconds on a back swipe
         // (bugs.webkit.org/319414): the view gesture's snapshot is only removed once the navigation finishes, and
         // React's root attaches the wheel listener the bug also needs. Letting the traversal through means the
         // browser commits the entry straight away, and the runtime puts the payload on screen when it arrives.
-        if (event.navigationType === 'traverse')
+        if (event.navigationType === 'traverse') {
+            if (attempt)
+                traversalAttempt = { attempt, key: event.destination.key };
+            return;
+        }
+        // The preparation listener claimed this push or replace: it set the scroll and focus options and will
+        // apply the prepared payload from its own precommit, so there is no handler to register here.
+        if (isPreparedNavigation(event))
             return;
         // A replace or a refresh stays where it is, so neither should move. A push starts at the top of the
         // page, or at its fragment — and that scroll is the runtime's own now: WebKit performs no
@@ -667,17 +1041,21 @@ function listenNavigation() {
         // handler over without scrolling; the `afterCommit` callback reaches the target once the new tree is on
         // screen. Focus stays the browser's, reset after the transition.
         const inPlace = event.navigationType === 'replace' || event.navigationType === 'reload';
-        let afterCommit;
-        if (event.navigationType === 'push') {
-            const { hash } = new URL(event.destination.url);
-            afterCommit = hash === '' ? scrollToTop : () => jumpToAnchor(hash);
-        }
+        const hop = attempt?.hop;
         event.intercept({
             scroll: 'manual',
             focusReset: inPlace ? 'manual' : 'after-transition',
-            // The URL commits before the handler runs, so a failure leaves the address bar describing a page the
-            // document is not showing. A real load is the only way back to agreement.
-            handler: () => loadPayload(event.destination.url, event.signal, afterCommit).catch(() => loadDocument()),
+            // The URL has committed by the time this runs, so a failure leaves the address bar describing a page
+            // the document is not showing. That is the whole path for a reload, and the fallback path for a push
+            // or replace on a browser without precommit support — see `listenNavigationPreparation`. A real load
+            // is the only way back to agreement.
+            handler: () => loadPayload(event.destination.url, { signal: event.signal, afterCommit: afterCommitFor(event), attempt }).then(() => {
+                if (attempt?.hop === hop && !event.signal.aborted)
+                    finishAttempt(attempt, { kind: 'rendered', url: new URL(location.href) });
+            }, (error) => {
+                rejectAttempt(attempt, error);
+                loadDocument();
+            }),
         });
     };
     /**
@@ -686,6 +1064,11 @@ function listenNavigation() {
      * is `navigation.currentEntry` and its saved offset is in {@link scrollPositions}.
      */
     const onPopState = () => {
+        const traversal = traversalAttempt;
+        const attempt = traversal && traversal.key === currentEntryKey() ? traversal.attempt : undefined;
+        traversalAttempt = undefined;
+        // Same ownership as `onNavigate`: this traversal's commit replaces whatever the last one was waiting for.
+        cancelElementWatches();
         const stored = scrollPointFor(currentEntryKey());
         const hash = location.hash;
         const apply = () => {
@@ -695,6 +1078,7 @@ function listenNavigation() {
                 jumpToAnchor(hash);
             else
                 scrollToTop();
+            finishAttempt(attempt, { kind: 'rendered', url: new URL(location.href) });
         };
         // A fragment-only traversal never changed the payload: the address bar is back at an anchor of the page
         // already on screen, so there is nothing to fetch and nothing to wait for. The browser's own restoration
@@ -704,16 +1088,28 @@ function listenNavigation() {
             apply();
             return;
         }
-        void loadPayload(location.href, undefined, () => {
-            apply();
-            // The browser performs this for an intercepted navigation; a traversal is no longer intercepted, so
-            // without it Back would leave focus on the link that was clicked on the page being left.
-            resetFocus();
-        }).catch(() => loadDocument());
+        // A root redirect transfers completion to the next navigation, just as for push/replace.
+        const hop = attempt?.hop;
+        void loadPayload(location.href, {
+            afterCommit: () => {
+                apply();
+                // The browser performs this for an intercepted navigation; a traversal is no longer intercepted, so
+                // without it Back would leave focus on the link that was clicked on the page being left.
+                resetFocus();
+            },
+            attempt,
+        }).then(() => {
+            if (attempt?.hop === hop)
+                finishAttempt(attempt, { kind: 'rendered', url: new URL(location.href) });
+        }, (error) => {
+            rejectAttempt(attempt, error);
+            loadDocument();
+        });
     };
     navigation.addEventListener('navigate', onNavigate);
     window.addEventListener('popstate', onPopState);
     return () => {
+        disposePreparation();
         navigation.removeEventListener('navigate', onNavigate);
         window.removeEventListener('popstate', onPopState);
     };
@@ -750,58 +1146,92 @@ async function main() {
     if (canSoftNavigate)
         readStoredScrollPositions();
     const restored = scrollPointFor(currentEntryKey());
+    /**
+     * Creates a one-shot completion for this render. Superseding it releases its waiter without
+     * running scroll/focus work; committing runs that work before the browser paints; failing
+     * releases the waiter with the reason the render never will do either.
+     */
+    function createRender(payload, href, afterCommit, recoversByLoad = true) {
+        const { promise, resolve, reject } = Promise.withResolvers();
+        let finished = false;
+        return {
+            payload,
+            href,
+            recoversByLoad,
+            committed: promise,
+            commit: () => {
+                if (finished)
+                    return;
+                finished = true;
+                afterCommit?.();
+                resolve();
+            },
+            // Supersession releases the old waiter, but never runs its scroll/focus callback.
+            supersede: () => {
+                finished = true;
+                resolve();
+            },
+            // React tore the tree down, so this render never commits. Rejecting is what settles the navigation's
+            // `finished` and the prepared handler; see {@link pendingRender}.
+            fail: (error) => {
+                if (finished)
+                    return;
+                finished = true;
+                reject(error);
+            },
+        };
+    }
+    const initialRender = createRender(initialPayload, documentUrl(), restored ? () => scrollToPoint(restored) : undefined);
     function BrowserRoot() {
         const [payload, setPayloadState] = React.useState(initialPayload);
-        const [pending, startTransition] = React.useTransition();
+        const [pending, startTransition] = useNavigationTransition(payload, restoreCommittedPayload);
         // The payload the last `setPayload` put on screen or on its way there, so `reapplyPayload` re-renders
         // that one rather than a payload a later navigation or action has already replaced.
         const currentPayload = React.useRef(initialPayload);
-        // The resolver the payload on screen still owes — see {@link loadPayload}.
-        const pendingCommit = React.useRef(null);
-        // The scroll the payload about to commit owes, set with it so a payload that supersedes another takes
-        // its predecessor's scroll out of the queue along with its commit. Initialised with the reload's offset:
-        // the first layout effect below applies it with the first payload, before the new tree is painted.
-        const pendingScroll = React.useRef(restored ? () => scrollToPoint(restored) : null);
-        // Descendant passive effects can start a navigation before the root's passive effects run.
-        // Install the live payload setter and transition runner before any such navigation starts.
+        const [renders] = React.useState(() => new WeakMap([[initialPayload, initialRender]]));
+        const scheduledRender = React.useRef(initialRender);
+        const [revision, reviseCommit] = React.useState(0);
         React.useLayoutEffect(() => {
-            setPayload = (next, afterCommit) => {
+            setPayload = (next, afterCommit, { recoversByLoad = true } = {}) => {
+                const scheduled = createRender(next, documentUrl(), afterCommit, recoversByLoad);
+                scheduledRender.current.supersede();
+                scheduledRender.current = scheduled;
                 currentPayload.current = next;
-                return new Promise((resolve) => {
-                    // A payload replaced before it ever painted still has a navigation waiting on it. React commits
-                    // only the newest, so the effect below never runs for the one it skipped: release it here.
-                    pendingCommit.current?.();
-                    pendingCommit.current = resolve;
-                    // Replaced rather than kept: a server action's payload carries no `afterCommit`, and the
-                    // navigation it superseded must not scroll the page the action is about to replace it with.
-                    pendingScroll.current = afterCommit ?? null;
-                    setPayloadState(next);
-                });
+                renders.set(next, scheduled);
+                pendingRender = scheduled;
+                setPayloadState(next);
+                // A restoration to the same payload still owns a new commit and post-commit callback.
+                reviseCommit((value) => value + 1);
+                return scheduled.committed;
+            };
+            reapplyPayload = () => {
+                setPayloadState(currentPayload.current);
+                reviseCommit((value) => value + 1);
             };
-            // A re-dispatch of the payload above, for the retry in `loadPayload`: keeping `pendingCommit` and
-            // `pendingScroll` in place means the navigation already waiting resolves when this render commits,
-            // not when the retry runs.
-            reapplyPayload = () => setPayloadState(currentPayload.current);
             startNav = (run) => startTransition(run);
-        }, [startTransition]);
-        /**
-         * Performs the pending scroll and releases the navigation waiting on this payload. A layout effect, so
-         * the new tree is in the DOM and the pre-scroll position is never painted.
-         */
+        }, [renders, startTransition]);
         React.useLayoutEffect(() => {
-            const scroll = pendingScroll.current;
-            pendingScroll.current = null;
-            scroll?.();
-            // What the payload that just committed was rendered for — see {@link renderedUrl}. A redirect never
-            // reaches here, and an action or a dev refresh keeps the URL it was fetched for.
-            renderedUrl = documentUrl();
-            const commit = pendingCommit.current;
-            pendingCommit.current = null;
-            commit?.();
-        }, [payload]);
+            const render = renders.get(payload);
+            if (!render)
+                return;
+            renderedUrl = render.href;
+            renderedModel = payload;
+            // Only this render's own completion clears it: an older record can commit late (a re-apply or a bailed
+            // transition), and it must not drop the newer render `onUncaughtError` would have to fail.
+            if (pendingRender === render)
+                pendingRender = undefined;
+            render.commit();
+            navigationFetches = navigationFetches.filter((fetch) => {
+                if (fetch.navigation >= currentNavigation || navigationModels.get(fetch.controller) === payload)
+                    return true;
+                fetch.controller.abort();
+                return false;
+            });
+        }, [payload, revision, renders]);
         // A descendant may navigate from its first passive effect. Intercept it before that effect runs.
         React.useLayoutEffect(() => listenNavigation(), []);
-        const router = React.useMemo(() => ({ push, replace, back, forward, refresh, pending }), [pending]);
+        const preparing = useNavigationPreparation();
+        const router = React.useMemo(() => ({ push, replace, back, forward, refresh, pending: pending || preparing }), [pending, preparing]);
         return _jsx(RouterContext.Provider, { value: router, children: payload.root });
     }
     setServerCallback(async (id, args) => {
@@ -818,18 +1248,37 @@ async function main() {
         let payload;
         try {
             payload = await createFromFetch(payloadResponse(request), { temporaryReferences });
+            if (documentUrl() === calledFrom)
+                cancelNavigationPreparation();
         }
         catch (error) {
-            if (handleControlDigest(error))
+            // The current entry is the page the action was called from, not a redirecting one, so its redirect
+            // pushes the target after it — the entry a Back is owed is the page that submitted the form.
+            if (handleControlDigest(error, { history: 'push' }))
                 return undefined;
             throw error;
         }
         if (payload.redirect) {
-            push(payload.redirect);
+            void push(payload.redirect);
             return undefined;
         }
-        if (documentUrl() === calledFrom)
-            React.startTransition(() => void setPayload(payload));
+        if (documentUrl() === calledFrom) {
+            // An action response contains the page after the mutation. Any older navigation snapshot must
+            // lose ownership before it can replace that newer data. Applied streams stay alive until commit.
+            const actionGeneration = ++currentNavigation;
+            rejectAttempt(activeAttempt, new DOMException('Navigation superseded by server action', 'AbortError'));
+            abortNavigationFetches((fetch) => !fetch.applied);
+            React.startTransition(() => {
+                const committed = setPayload(payload, undefined, { recoversByLoad: false });
+                void committed.then(() => {
+                    abortNavigationFetches((fetch) => fetch.navigation < actionGeneration);
+                }, 
+                // An action reply that tears the tree down has no caller awaiting the commit, so the rejection is
+                // consumed here rather than left unhandled. The panel `onUncaughtError` painted is the recovery:
+                // the page a document load would render does not re-run the action that failed.
+                () => { });
+            });
+        }
         if (payload.notFound)
             return undefined;
         const result = payload.returnValue;
@@ -861,17 +1310,33 @@ async function main() {
     hydrateRoot(document, _jsx(BrowserRoot, {}), {
         formState: initialPayload.formState,
         onCaughtError: (error, errorInfo) => {
-            if (handleControlDigest(error, { hard: true }))
+            if (handleControlDigest(error, { hard: true, history: controlDigestHistory() }))
                 return;
             // A boundary handled it and the tree is intact, so no overlay over the app's own fallback.
             console.error(error, errorInfo.componentStack ?? '');
         },
         onUncaughtError: (error, errorInfo) => {
-            if (handleControlDigest(error, { hard: true }))
+            if (handleControlDigest(error, { hard: true, history: controlDigestHistory() }))
                 return;
             // Nothing caught it, so React tears the root down — and the root is `document`.
             globalThis.reportError(error);
-            showFatal(error, errorInfo.componentStack);
+            const recover = pendingRender;
+            // A navigation payload is the case a document load can still repair: the URL already names its
+            // destination, and the server answers that document request with the app's error page. An action reply
+            // is not — a GET of the URL it was called from does not re-run the action, so the page would render as
+            // if nothing had happened and the load would silently discard the error. The panel is the answer, and it
+            // is painted now because no load is coming to replace it. See {@link pendingRender}.
+            if (!recover?.recoversByLoad) {
+                showFatal(error, errorInfo.componentStack);
+                recover?.fail(error);
+                return;
+            }
+            // The panel waits for that load to arrive. Painted now, it flashes over the error page on its way and
+            // vanishes when the page commits; the timer dies with the document a successful load replaces, so the
+            // panel only appears when the recovery was never made. A render React is only suspending is not failed;
+            // see {@link pendingRender}.
+            setTimeout(() => showFatal(error, errorInfo.componentStack), RECOVERY_GRACE_MS);
+            recover.fail(error);
         },
     });
     if (import.meta.webpackHot) {