@rshono/core 1.0.0-rc.21 → 1.0.0-rc.23

package/README.md

@@ -322,8 +322,11 @@ Every target streams, which is the bar a new one has to clear.
 - **Soft navigation needs the [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API)**
   — Chrome/Edge 135, Firefox 147, Safari 26.2, [Baseline](https://web.dev/blog/baseline-navigation-api) since
   January 2026. Where it is missing there is no interception at all and every link is a real browser load,
-  which a server-rendered app answers correctly; only the soft part is gone. Scroll restoration, the fragment
-  jump and the post-navigation focus reset are all the browser's.
+  which a server-rendered app answers correctly; only the soft part is gone. On a soft navigation the runtime
+  owns the scroll: a push reaches the top or its fragment, a traversal returns to where the entry was left,
+  and focus resets — `history.scrollRestoration` is `manual` for the document and positions are kept per
+  entry, in `sessionStorage` too, so a reload lands where the last document was left. A same-page fragment
+  stays the browser's, since it never changes the payload.
 - **`redirect()` and `notFound()` must be reached before the page shell is sent.** A page streams: the status
   line and the first bytes go out as soon as the shell is ready, and HTTP has no take-backs after that. Called
   from a `<Suspense>` boundary that resolves later, the signal can no longer be a 3xx or a 404 — the response

package/dist/runtime/entry.client.js

@@ -40,6 +40,12 @@ const flightStream = readFlightPayload();
  * never sees. Two URLs that differ only by `#hash` describe the same payload.
  */
 const documentUrl = () => location.pathname + location.search;
+/**
+ * The document URL the payload on screen was rendered for — see {@link documentUrl}. A fragment-only
+ * traversal leaves it unchanged, which is how the `popstate` listener knows there is nothing to fetch.
+ * Updated in the layout effect that commits a payload.
+ */
+let renderedUrl = documentUrl();
 /** 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)
@@ -101,7 +107,7 @@ function showFatal(error, componentStack) {
         reload.textContent = 'Reload page';
         reload.style.cssText =
             'margin-top:1.25rem;padding:0.5rem 1rem;font:inherit;color:#18181b;background:#f4f4f5;border:0;border-radius:4px;cursor:pointer';
-        reload.addEventListener('click', () => loadOutsideRouter(() => window.location.reload()));
+        reload.addEventListener('click', () => loadDocument());
         box.appendChild(reload);
     });
 }
@@ -168,6 +174,101 @@ function requestPayload(href, signal) {
  * would take the whole client runtime down with it rather than degrading anything.
  */
 const canSoftNavigate = typeof navigation !== 'undefined' && typeof NavigateEvent !== 'undefined' && 'sourceElement' in NavigateEvent.prototype;
+/**
+ * The runtime owns a soft navigation's scroll, so the browser's own restoration has to be off: left on, a
+ * traversal restores the destination's offset against the outgoing tree before the payload for that entry
+ * has even been asked for, and the incoming tree overwrites it. `manual` only concerns the entries this
+ * document creates — a navigation to another document creates its own entry `auto` — and it also turns the
+ * browser's reload restoration off, which {@link readStoredScrollPositions} and the first layout effect put
+ * back.
+ *
+ * Gated on the soft router: below the Navigation API floor every navigation is a real document load, which
+ * a server-rendered app answers correctly and the browser restores correctly, and taking that over without
+ * a router to repaint the entry would strand the visitor at the top.
+ */
+if (canSoftNavigate) {
+    try {
+        history.scrollRestoration = 'manual';
+    }
+    catch {
+        // A preference, not a requirement: where it cannot be set, the browser's restoration and the runtime's
+        // own can race on a traversal, and the runtime's runs at commit, after.
+    }
+}
+/**
+ * Where each history entry of this document was left, keyed by its Navigation API key. In memory for the
+ * document's life; {@link persistScrollPositions} also writes it to `sessionStorage` so a reload — which
+ * the `manual` mode above stops the browser restoring — lands where the last document was left.
+ */
+const scrollPositions = new Map();
+/** The `sessionStorage` key holding {@link scrollPositions}. */
+const SCROLL_STORAGE_KEY = 'rshono:scroll';
+/** How many entries are kept in that snapshot; the oldest falls out first — `Map` iteration order. */
+const SCROLL_STORAGE_LIMIT = 50;
+/** The key of the history entry being shown, or `undefined` where the soft router does not exist. */
+function currentEntryKey() {
+    return canSoftNavigate ? navigation.currentEntry?.key : undefined;
+}
+/**
+ * Records where the outgoing entry is being left. Read at `navigate` time — before the browser commits the
+ * new entry — and at `pagehide`, so whatever the navigation turns out to be, the entry it leaves has a
+ * position to come back to.
+ */
+function rememberCurrentScroll() {
+    const key = currentEntryKey();
+    if (key)
+        scrollPositions.set(key, { x: window.scrollX, y: window.scrollY });
+}
+/** The position `key` was left at, or `undefined` when this document never saw it. */
+function scrollPointFor(key) {
+    return key === undefined ? undefined : scrollPositions.get(key);
+}
+/**
+ * Reads the last document's snapshot back into {@link scrollPositions}. Called once, on startup, before the
+ * first payload commits: the in-memory map alone would lose every entry the moment the document is replaced.
+ */
+function readStoredScrollPositions() {
+    try {
+        const raw = sessionStorage.getItem(SCROLL_STORAGE_KEY);
+        if (!raw)
+            return;
+        for (const [key, point] of Object.entries(JSON.parse(raw))) {
+            if (Number.isFinite(point?.x) && Number.isFinite(point?.y))
+                scrollPositions.set(key, point);
+        }
+    }
+    catch {
+        // Blocked site data, or a snapshot written by a different version. Either way there is nothing to restore,
+        // and the page is still correct without it.
+    }
+}
+/** Writes {@link scrollPositions} out, oldest first, bounded — see {@link SCROLL_STORAGE_LIMIT}. */
+function persistScrollPositions() {
+    try {
+        while (scrollPositions.size > SCROLL_STORAGE_LIMIT) {
+            const oldest = scrollPositions.keys().next().value;
+            if (oldest === undefined)
+                break;
+            scrollPositions.delete(oldest);
+        }
+        sessionStorage.setItem(SCROLL_STORAGE_KEY, JSON.stringify(Object.fromEntries(scrollPositions)));
+    }
+    catch {
+        // Blocked site data: the in-memory map still carries this document's navigations.
+    }
+}
+/**
+ * The snapshot starts with the document, not with hydration: the page is visible and clickable while the
+ * initial payload streams, and a reload or a navigation away in that window would otherwise lose the offset
+ * now that `manual` has stopped the browser restoring it. Nothing here depends on the router being mounted,
+ * so it does not wait for {@link listenNavigation}.
+ */
+if (canSoftNavigate) {
+    window.addEventListener('pagehide', () => {
+        rememberCurrentScroll();
+        persistScrollPositions();
+    });
+}
 /**
  * Drops a navigation's result promises. Both reject when a navigation is superseded or cancelled — routine
  * here, since a second click is meant to abandon the first — and unhandled they would be reported as faults.
@@ -177,26 +278,36 @@ function settle(result) {
     void result.committed?.catch(ignore);
     void result.finished?.catch(ignore);
 }
-/** Set by {@link loadOutsideRouter}, read and cleared by the `navigate` listener. */
-let bypassRouter = false;
+/**
+ * The mark {@link loadDocument} puts on its navigations, so the `navigate` listener below recognizes them as
+ * the runtime's own. A symbol because the identity has to survive the trip through the browser intact:
+ * `NavigateEvent.info` hands the value back by reference, so only the navigation that was given it matches.
+ */
+const documentNavigation = Symbol('rshono:document-navigation');
 /**
  * Performs a navigation the router below must **not** intercept, and returns having asked for it.
  *
- * `location.reload()` and `location.assign()` fire a `navigate` event like any other navigation, and
- * `listenNavigation` intercepts a `reload` on purpose — that is what `router.refresh()` is. Every caller here
- * is reaching for a *new document* precisely because the current one cannot be repaired: the React root a
- * soft load would render into is the thing that just failed, or is about to be torn down. Intercepted, the
+ * `listenNavigation` intercepts a `reload` on purpose — that is what `router.refresh()` is — and every caller
+ * here is reaching for a *new document* precisely because the current one cannot be repaired: the React root
+ * a soft load would render into is the thing that just failed, or is about to be torn down. Intercepted, the
  * escape hatch becomes a payload fetch that lands nowhere — which is how a late `notFound()` left the tab on
  * 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.
  *
- * One-shot: the listener clears the flag on the next event it sees. If that event never comes — a navigation
- * the browser refuses — the cost is that the *next* navigation is a full load rather than a soft one, on a
- * document that was on its way out anyway.
+ * 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 loadOutsideRouter(navigate) {
-    bypassRouter = true;
-    navigate();
+function loadDocument(href) {
+    if (!canSoftNavigate) {
+        if (href === undefined)
+            window.location.reload();
+        else
+            window.location.assign(href);
+        return;
+    }
+    settle(href === undefined ? navigation.reload({ info: documentNavigation }) : navigation.navigate(href, { info: documentNavigation }));
 }
 // 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
@@ -272,7 +383,7 @@ function reloadOnceForLateNotFound() {
         showLateNotFound();
         return;
     }
-    loadOutsideRouter(() => window.location.reload());
+    loadDocument();
     // The reload wins this race whenever it happens at all: the document goes away and takes the timer with
     // it. What this covers is a reload that does not happen — swallowed by an interceptor, refused by the
     // browser, held by a `beforeunload` — which used to leave the visitor on a Suspense fallback with nothing
@@ -298,17 +409,79 @@ function handleControlDigest(error, { hard = false } = {}) {
         reloadOnceForLateNotFound();
     }
     else if (hard) {
-        loadOutsideRouter(() => window.location.assign(new URL(redirect.location, window.location.href).href));
+        // 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);
     }
     else {
         push(redirect.location);
     }
     return true;
 }
+/**
+ * Scrolls the document to its start.
+ *
+ * The options form rather than `scrollTo(0, 0)`: the two-argument call is `auto`, which follows a
+ * `scroll-behavior` the app may have set on `html`, and a soft navigation that animates its own reset reads
+ * as a glitch rather than a page change.
+ */
+function scrollToTop() {
+    window.scrollTo({ top: 0, left: 0, behavior: 'instant' });
+}
+/** Puts a saved offset back. Instant for the same reason {@link scrollToTop} passes it. */
+function scrollToPoint(point) {
+    window.scrollTo({ top: point.y, left: point.x, behavior: 'instant' });
+}
+/**
+ * Scrolls to a fragment's target the way the browser's own fragment jump does.
+ *
+ * `scrollIntoView` is the algorithm that honours `scroll-padding-top` on the scrolling box and
+ * `scroll-margin-top` on the target, which `window.scrollTo` does not. The lookup follows the browser's
+ * "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.
+ */
+function jumpToAnchor(hash) {
+    const raw = hash.startsWith('#') ? hash.slice(1) : hash;
+    // No special case for `#top`: the browser only treats it as the top of the document when no element
+    // matches, and the fallback below is that top.
+    if (raw === '') {
+        scrollToTop();
+        return;
+    }
+    let id = raw;
+    try {
+        id = decodeURIComponent(raw);
+    }
+    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)
+        target.scrollIntoView();
+    else
+        scrollToTop();
+}
+/**
+ * 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.
+ */
+function resetFocus() {
+    const autofocus = document.querySelector('[autofocus]');
+    if (autofocus)
+        autofocus.focus({ preventScroll: true });
+    else
+        document.body.focus({ preventScroll: true });
+}
 /**
  * Puts a payload on screen, resolving once React has committed it. Replaced by `BrowserRoot`'s own on mount;
  * the default covers the window before hydration, where `setServerCallback` is already registered but there
  * is no root to update — a reload is the honest answer, and nothing after it needs to run.
+ *
+ * `afterCommit`, when given, runs in the same layout effect that releases the commit: after the new tree is
+ * in the DOM and before the browser paints, which is the only moment a `#hash` target exists and the
+ * pre-scroll position has not been shown.
  */
 let setPayload = () => {
     window.location.reload();
@@ -318,31 +491,48 @@ let setPayload = () => {
 let startNav = (run) => {
     void run();
 };
+/**
+ * The navigation whose payload is allowed to settle the screen. React runs async work concurrently, so two
+ * navigations are two live fetches with no ordering between them; without this a slow first response landing
+ * after a fast second one repaints the page the user already left. The Navigation API aborts an intercepted
+ * navigation when a newer one starts, but a traversal has no `event.signal` to watch — `popstate` arrives
+ * 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;
 /**
  * Fetches the payload for `url` and puts it on screen.
  *
- * Resolves once React has **committed** it rather than when the fetch lands: an intercepted navigation
- * scrolls and moves focus when this promise settles, 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.
+ * Resolves once React has **committed** it rather than when the fetch lands: `afterCommit` runs at that
+ * 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.
  */
-function loadPayload(url, signal) {
+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).
+    const navigation = ++currentNavigation;
+    navigationFetch?.abort();
+    const controller = (navigationFetch = new AbortController());
+    const abort = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
     // 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;
     const run = async () => {
-        const payload = await requestPayload(url, signal);
-        // The browser aborts a navigation the moment a newer one starts. 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 (signal?.aborted)
+        const payload = await requestPayload(url, abort);
+        // 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)
             return;
         if (payload.redirect) {
             push(payload.redirect);
             return;
         }
-        committed = setPayload(payload);
+        committed = setPayload(payload, afterCommit);
     };
     // `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.
@@ -353,11 +543,28 @@ function loadPayload(url, signal) {
     () => 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 (signal?.aborted || handleControlDigest(error))
+        if (abort.aborted || navigation !== currentNavigation || handleControlDigest(error))
             return;
         throw error;
     });
 }
+/**
+ * Whether a destination names a file rather than a page. `public/`, `/_static` and an endpoint route that
+ * serves a document (`/llms.txt`, `/sitemap.xml`) answer an RSC fetch with the file itself, not a flight
+ * payload — so intercepting one buys nothing: the payload never arrives, and the only recovery left is the
+ * document load the browser would have made directly. Handing it that navigation up front also gives the
+ * entry the file loads into the browser's own history, so Back is an ordinary cross-document traversal. An
+ * intercepted entry is same-document by construction, and traversing one with nothing to repaint it changes
+ * the URL and nothing else — which is what a Back press out of an opened file was doing.
+ *
+ * A dot in the last path segment rather than a list of extensions: a list is never complete, and every miss
+ * is the failed round trip above. A page route whose last segment carries a dot (`/release-1.0`) therefore
+ * costs a document load — the direction to err in, and what a `data-native` link already asks for by hand.
+ */
+function namesAFile(href) {
+    const lastSegment = new URL(href).pathname.split('/').pop() ?? '';
+    return lastSegment.includes('.');
+}
 /**
  * Navigations the browser can hand over but shouldn't:
  *
@@ -366,10 +573,15 @@ function loadPayload(url, signal) {
  * - a download, which is not a navigation of this page at all;
  * - a `POST` form, which is a submission and the server's to answer (a `GET` form carries its fields in the
  *   URL, has no `formData`, and soft-navigates like any other link);
- * - a link marked `data-native`, the documented opt-out.
+ * - a link marked `data-native`, the documented opt-out;
+ * - a destination that names a file — see {@link namesAFile}.
  */
 function leaveToBrowser(event) {
-    return event.hashChange || event.downloadRequest !== null || event.formData !== null || event.sourceElement?.hasAttribute('data-native') === true;
+    return (event.hashChange ||
+        event.downloadRequest !== null ||
+        event.formData !== null ||
+        event.sourceElement?.hasAttribute('data-native') === true ||
+        namesAFile(event.destination.url));
 }
 /**
  * The whole router, in one listener.
@@ -384,29 +596,81 @@ function listenNavigation() {
     if (!canSoftNavigate)
         return () => { };
     const onNavigate = (event) => {
-        // Cleared as it is consumed, whatever this event turns out to be: the flag names one navigation, and the
-        // one it named is the one that just arrived.
-        if (bypassRouter) {
-            bypassRouter = false;
+        // 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;
-        }
+        // 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))
             return;
-        // A push or a traversal lands on a new page, so the browser resets the scroll offset — or restores the
-        // one it remembers — and moves focus, which is what makes a soft navigation announce itself to a screen
-        // reader. A replace or a refresh stays where it is, so neither should move. Both wait on the handler,
-        // which is the point of resolving it at commit rather than at fetch.
+        // 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')
+            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
+        // `after-transition` reset at all for an intercepted push (bugs.webkit.org/304593). Chromium skips it
+        // too, and a fragment jump rides the same code path. Passing `manual` here makes the browser hand the
+        // 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);
+        }
         event.intercept({
-            scroll: inPlace ? 'manual' : 'after-transition',
+            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).catch(() => loadOutsideRouter(() => window.location.reload())),
+            handler: () => loadPayload(event.destination.url, event.signal, afterCommit).catch(() => loadDocument()),
         });
     };
+    /**
+     * Repaints a traversal the listener above deliberately left to the browser, and moves the viewport back
+     * where the entry was left. `popstate` fires after the browser has committed the entry, so the destination
+     * is `navigation.currentEntry` and its saved offset is in {@link scrollPositions}.
+     */
+    const onPopState = () => {
+        const stored = scrollPointFor(currentEntryKey());
+        const hash = location.hash;
+        const apply = () => {
+            if (stored)
+                scrollToPoint(stored);
+            else if (hash !== '')
+                jumpToAnchor(hash);
+            else
+                scrollToTop();
+        };
+        // 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
+        // is off, so the offset comes from what `onNavigate` saved when the anchor was followed; no focus reset,
+        // which is what leaving those navigations to the browser has always meant.
+        if (documentUrl() === renderedUrl) {
+            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());
+    };
     navigation.addEventListener('navigate', onNavigate);
-    return () => navigation.removeEventListener('navigate', onNavigate);
+    window.addEventListener('popstate', onPopState);
+    return () => {
+        navigation.removeEventListener('navigate', onNavigate);
+        window.removeEventListener('popstate', onPopState);
+    };
 }
 async function main() {
     // The assertion is load-bearing under the compiler that builds this: TypeScript 7 declares `nonce` on
@@ -433,26 +697,46 @@ async function main() {
             // Blocked site data. `reloadOnceForLateNotFound` already treats that as the terminating case.
         }
     }
+    // Everything the last document saved, read before any payload commits: the in-memory map alone would not
+    // survive the reload that `history.scrollRestoration = 'manual'` just stopped the browser restoring. The
+    // entry's key is stable across a reload, and the offset is applied by `BrowserRoot`'s first layout effect,
+    // before the first paint of the new tree.
+    if (canSoftNavigate)
+        readStoredScrollPositions();
+    const restored = scrollPointFor(currentEntryKey());
     function BrowserRoot() {
         const [payload, setPayloadState] = React.useState(initialPayload);
         const [pending, startTransition] = React.useTransition();
         // 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);
         React.useEffect(() => {
-            setPayload = (next) => new Promise((resolve) => {
+            setPayload = (next, afterCommit) => 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);
             });
             startNav = (run) => startTransition(run);
         }, [startTransition]);
         /**
-         * Releases the navigation waiting on this payload, which is what lets the browser scroll and move focus
-         * now that their target exists. A layout effect, so the pre-scroll position is never painted.
+         * 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.
          */
         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?.();
@@ -549,7 +833,7 @@ function initDevRefresh() {
     let targetHash;
     function reload(reason, error) {
         console.warn(`[rshono] ${reason} — reloading`, ...(error === undefined ? [] : [error]));
-        loadOutsideRouter(() => window.location.reload());
+        loadDocument();
     }
     async function applyClientUpdate() {
         const giveUp = await walkHotUpdates(hot, () => __webpack_hash__, () => targetHash);
@@ -562,7 +846,7 @@ function initDevRefresh() {
                 targetHash = message.hash ?? targetHash;
                 if (connectedOnce) {
                     await applyClientUpdate();
-                    await loadPayload(window.location.href).catch(() => loadOutsideRouter(() => window.location.reload()));
+                    await loadPayload(window.location.href).catch(() => loadDocument());
                 }
                 connectedOnce = true;
                 break;
@@ -572,7 +856,7 @@ function initDevRefresh() {
                 break;
             case 'rsc-update':
                 console.log('[rshono] server components updated');
-                await loadPayload(window.location.href).catch(() => loadOutsideRouter(() => window.location.reload()));
+                await loadPayload(window.location.href).catch(() => loadDocument());
                 break;
         }
     }