vike 0.4.220 → 0.4.221-commit-8577456

package/dist/cjs/utils/path.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pathJoin = pathJoin;
+exports.pathIsRelative = pathIsRelative;
+exports.toPosixPath = toPosixPath;
+exports.assertPosixPath = assertPosixPath;
+// Utilites for handling file paths.
+// - Shims `import * from "node:path"` for server runtime.
+//   - Robust shim reference: https://github.com/unjs/pathe
+const assert_js_1 = require("./assert.js");
+const assertIsNotBrowser_js_1 = require("./assertIsNotBrowser.js");
+(0, assertIsNotBrowser_js_1.assertIsNotBrowser)();
+/**********************/
+/****** SHIMS *********/
+/**********************/
+function pathJoin(path1, path2) {
+    (0, assert_js_1.assert)(!path1.includes('\\'));
+    (0, assert_js_1.assert)(!path2.includes('\\'));
+    let joined = [...path1.split('/'), ...path2.split('/')].filter(Boolean).join('/');
+    if (path1.startsWith('/'))
+        joined = '/' + joined;
+    return joined;
+}
+/* https://github.com/brillout/telefunc/blob/0fd44322acbd07857ae29361ba7c998607f17dd5/telefunc/utils/path-shim.ts#L17-L21
+const IS_ABSOLUTE_RE = /^[/\\](?![/\\])|^[/\\]{2}(?!\.)|^[A-Za-z]:[/\\]/
+function pathIsAbsolute(filePath: string) {
+  return IS_ABSOLUTE_RE.test(filePath)
+}
+//*/
+/**********************/
+/****** UTILS *********/
+/**********************/
+function toPosixPath(path) {
+    const pathPosix = path.split('\\').join('/');
+    assertPosixPath(pathPosix);
+    return pathPosix;
+}
+function assertPosixPath(path) {
+    const errMsg = (msg) => `Not a posix path: ${msg}`;
+    (0, assert_js_1.assert)(path !== null, errMsg('null'));
+    (0, assert_js_1.assert)(typeof path === 'string', errMsg(`typeof path === ${JSON.stringify(typeof path)}`));
+    (0, assert_js_1.assert)(path !== '', errMsg('(empty string)'));
+    (0, assert_js_1.assert)(path);
+    (0, assert_js_1.assert)(!path.includes('\\'), errMsg(path));
+}
+function pathIsRelative(importPath) {
+    return importPath.startsWith('./') || importPath.startsWith('../');
+}

package/dist/cjs/utils/requireResolve.js

@@ -4,7 +4,7 @@ exports.requireResolve = requireResolve;
 const assert_js_1 = require("./assert.js");
 const assertIsNotBrowser_js_1 = require("./assertIsNotBrowser.js");
 const assertSetup_js_1 = require("./assertSetup.js");
-const filesystemPathHandling_js_1 = require("./filesystemPathHandling.js");
+const path_js_1 = require("./path.js");
 const isScriptFile_js_1 = require("./isScriptFile.js");
 const module_1 = require("module");
 // @ts-ignore Shimmed by dist-cjs-fixup.js for CJS build.
@@ -15,7 +15,7 @@ const require_ = (0, module_1.createRequire)(importMetaUrl);
 // We still can't use import.meta.resolve() as of 23.1.0 (November 2024) because `parent` argument requires an experimental flag.
 // - https://stackoverflow.com/questions/54977743/do-require-resolve-for-es-modules#comment139581675_62272600
 function requireResolve(importPath, cwd) {
-    (0, filesystemPathHandling_js_1.assertPosixPath)(cwd);
+    (0, path_js_1.assertPosixPath)(cwd);
     const clean = addFileExtensionsToRequireResolve();
     importPath = removeFileExtention(importPath);
     let importedFile;
@@ -29,7 +29,7 @@ function requireResolve(importPath, cwd) {
         clean();
     }
     if (importedFile) {
-        importedFile = (0, filesystemPathHandling_js_1.toPosixPath)(importedFile);
+        importedFile = (0, path_js_1.toPosixPath)(importedFile);
     }
     return importedFile;
 }

package/dist/esm/__internal/index.d.ts

@@ -1,12 +1,13 @@
 export { setGlobalContext_buildEntry } from '../node/runtime/globalContext.js';
 export { route, getPagesAndRoutes };
 export type { PageRoutes, PageFile, PageConfigRuntime as PageConfig };
-export { getMiddlewares };
 import { route as routeInternal, type PageRoutes } from '../shared/route/index.js';
 import type { PageFile } from '../shared/getPageFiles/getPageFileObject.js';
 import { PageConfigRuntime } from '../shared/page-configs/PageConfig.js';
 /**
  * Used by {@link https://github.com/magne4000/vite-plugin-vercel|vite-plugin-vercel} to compute some rewrite rules and extract { isr } configs.
+ *
+ * TODO/eventually: remove
  */
 declare function getPagesAndRoutes(): Promise<{
     pageRoutes: PageRoutes;
@@ -14,7 +15,6 @@ declare function getPagesAndRoutes(): Promise<{
     pageConfigs: PageConfigRuntime[];
     allPageIds: string[];
 }>;
-declare function getMiddlewares(): Promise<unknown[]>;
 declare function route(pageContext: Parameters<typeof routeInternal>[0]): Promise<{
     pageContextAddendum: import("../shared/route/index.js").PageContextFromRoute;
 }>;

package/dist/esm/__internal/index.js

@@ -1,19 +1,19 @@
-// Internals needed by Vike
+// Needed by Vike
 export { setGlobalContext_buildEntry } from '../node/runtime/globalContext.js';
-// Internals needed by vite-plugin-vercel
+// Needed by vite-plugin-vercel
 export { route, getPagesAndRoutes };
-// Internals needed by experimental implementation of vike-telefunc
-export { getMiddlewares };
 import { route as routeInternal } from '../shared/route/index.js';
-import { getPageFilesAll } from '../shared/getPageFiles/getPageFiles.js';
-import { getGlobalContext, initGlobalContext_getGlobalContextAsync } from '../node/runtime/globalContext.js';
+import { getGlobalContextInternal, initGlobalContext_getPagesAndRoutes } from '../node/runtime/globalContext.js';
 import { setNodeEnvProduction } from '../utils/assertSetup.js';
 /**
  * Used by {@link https://github.com/magne4000/vite-plugin-vercel|vite-plugin-vercel} to compute some rewrite rules and extract { isr } configs.
+ *
+ * TODO/eventually: remove
  */
 async function getPagesAndRoutes() {
     setNodeEnvProduction();
-    const globalContext = getGlobalContext();
+    await initGlobalContext_getPagesAndRoutes();
+    const globalContext = await getGlobalContextInternal();
     const { 
     //
     pageRoutes, pageFilesAll, pageConfigs, allPageIds } = globalContext;
@@ -24,25 +24,6 @@ async function getPagesAndRoutes() {
         allPageIds
     };
 }
-// TODO/eventually:
-//  - Remove the need for `isProduction` after Vike's CLI is implemented
-//  - Remove it in favor of https://vike.dev/getGlobalContext
-async function getMiddlewares() {
-    const isProduction = process.env.NODE_ENV === 'production';
-    const { pageConfigs } = await getPageFilesAllSafe(isProduction);
-    const middlewares = pageConfigs[0].configValues.middleware.value.flat(Infinity);
-    return middlewares;
-}
-// TODO/eventually:
-//  - Make it cleaner once the internal refactoring about global configs is done.
-//  - Remove it in favor of https://vike.dev/getGlobalContext
-// Demo usage: https://github.com/vikejs/vike/pull/1823
-async function getPageFilesAllSafe(isProduction) {
-    await initGlobalContext_getGlobalContextAsync(isProduction);
-    const globalContext = getGlobalContext();
-    const pageFilesAll = await getPageFilesAll(false, globalContext.isProduction);
-    return pageFilesAll;
-}
 async function route(pageContext) {
     const pageContextFromRoute = await routeInternal(pageContext);
     // Old interface

package/dist/esm/client/client-routing-runtime/createPageContext.js

@@ -1,18 +1,14 @@
 export { createPageContext };
+import { getPageConfigsRuntime } from '../../shared/getPageConfigsRuntime.js';
 import { getPageContextUrlComputed } from '../../shared/getPageContextUrlComputed.js';
-import { getPageFilesAll, setPageFiles } from '../../shared/getPageFiles/getPageFiles.js';
 import { loadPageRoutes } from '../../shared/route/loadPageRoutes.js';
 import { getBaseServer } from './getBaseServer.js';
-import { assert, isBaseServer, getGlobalObject, objectAssign } from './utils.js';
+import { assert, isBaseServer, objectAssign } from './utils.js';
+// TODO/now: can we avoid optimizeDeps.exclude of client runtime?
 // @ts-ignore
-import * as pageFilesExports from 'virtual:vike:importUserCode:client:client-routing';
-const globalObject = getGlobalObject('createPageContext.ts', {});
-setPageFiles(pageFilesExports);
+import * as virtualFileExports from 'virtual:vike:importUserCode:client:client-routing';
+const { pageFilesAll, allPageIds, pageConfigs, pageConfigGlobal } = getPageConfigsRuntime(virtualFileExports);
 async function createPageContext(urlOriginal) {
-    if (!globalObject.pageFilesData) {
-        globalObject.pageFilesData = await getPageFilesAll(true);
-    }
-    const { pageFilesAll, allPageIds, pageConfigs, pageConfigGlobal } = globalObject.pageFilesData;
     const { pageRoutes, onBeforeRouteHook } = await loadPageRoutes(pageFilesAll, pageConfigs, pageConfigGlobal, allPageIds);
     const baseServer = getBaseServer();
     assert(isBaseServer(baseServer));

package/dist/esm/client/client-routing-runtime/history.d.ts

@@ -1,4 +1,5 @@
 export { pushHistoryState };
+export { replaceHistoryStateOriginal };
 export { onPopStateBegin };
 export { saveScrollPosition };
 export { initHistoryState };
@@ -17,13 +18,14 @@ type ScrollPosition = {
 };
 declare function saveScrollPosition(): void;
 declare function pushHistoryState(url: string, overwriteLastHistoryEntry: boolean): void;
+declare function replaceHistoryStateOriginal(state: unknown, url: string): void;
 declare function monkeyPatchHistoryAPI(): void;
 type HistoryInfo = {
     url: `/${string}`;
     state: StateEnhanced;
 };
 declare function onPopStateBegin(): {
-    isNewState: boolean;
+    isHistoryStateEnhanced: boolean;
     previous: HistoryInfo;
     current: HistoryInfo;
 };

package/dist/esm/client/client-routing-runtime/history.js

@@ -1,10 +1,11 @@
 export { pushHistoryState };
+export { replaceHistoryStateOriginal };
 export { onPopStateBegin };
 export { saveScrollPosition };
 export { initHistoryState };
 export { monkeyPatchHistoryAPI };
 import { getCurrentUrl } from '../shared/getCurrentUrl.js';
-import { assert, assertUsage, getGlobalObject, hasProp, isObject } from './utils.js';
+import { assert, assertUsage, getGlobalObject, isObject } from './utils.js';
 initHistoryState(); // we redundantly call initHistoryState() to ensure it's called early
 const globalObject = getGlobalObject('history.ts', { previous: getHistoryInfo() });
 // `window.history.state === null` when:
@@ -90,6 +91,11 @@ function replaceHistoryState(state, url) {
     const url_ = url ?? null; // Passing `undefined` chokes older Edge versions.
     window.history.replaceState(state, '', url_);
 }
+function replaceHistoryStateOriginal(state, url) {
+    // Bypass all monkey patches.
+    // - Useful, for example, to avoid other tools listening to history.replaceState() calls
+    History.prototype.replaceState.bind(window.history)(state, '', url);
+}
 // Monkey patch:
 // - history.pushState()
 // - history.replaceState()
@@ -116,21 +122,19 @@ function monkeyPatchHistoryAPI() {
     });
 }
 function isVikeEnhanced(state) {
-    const yes = isObject(state) && '_isVikeEnhanced' in state;
-    if (yes)
-        assertStateVikeEnhanced(state);
-    return yes;
-}
-function assertStateVikeEnhanced(state) {
-    assert(isObject(state));
-    assert(hasProp(state, '_isVikeEnhanced', 'true'));
-    // TODO/eventually: remove assert() below to save client-side KBs
-    assert(hasProp(state, 'timestamp', 'number'));
-    assert(hasProp(state, 'scrollPosition'));
-    if (state.scrollPosition !== null) {
-        assert(hasProp(state, 'scrollPosition', 'object'));
-        assert(hasProp(state.scrollPosition, 'x', 'number') && hasProp(state.scrollPosition, 'y', 'number'));
+    if (isObject(state) && '_isVikeEnhanced' in state) {
+        /* We don't use the assert() below to save client-side KBs.
+        assert(hasProp(state, '_isVikeEnhanced', 'true'))
+        assert(hasProp(state, 'timestamp', 'number'))
+        assert(hasProp(state, 'scrollPosition'))
+        if (state.scrollPosition !== null) {
+          assert(hasProp(state, 'scrollPosition', 'object'))
+          assert(hasProp(state.scrollPosition, 'x', 'number') && hasProp(state.scrollPosition, 'y', 'number'))
+        }
+        //*/
+        return true;
     }
+    return false;
 }
 function getHistoryInfo() {
     return {
@@ -140,12 +144,13 @@ function getHistoryInfo() {
 }
 function onPopStateBegin() {
     const { previous } = globalObject;
-    const isNewState = window.history.state === null;
-    if (isNewState)
+    const isHistoryStateEnhanced = window.history.state !== null;
+    if (!isHistoryStateEnhanced)
         enhanceHistoryState();
+    assert(isVikeEnhanced(window.history.state));
     const current = getHistoryInfo();
     globalObject.previous = current;
-    return { isNewState, previous, current };
+    return { isHistoryStateEnhanced, previous, current };
 }
 function initHistoryState() {
     enhanceHistoryState();

package/dist/esm/client/client-routing-runtime/index.d.ts

@@ -1,6 +1,5 @@
 export { navigate, reload } from './navigate.js';
 export { prefetch } from './prefetch.js';
-export { onPopState } from './initOnPopState.js';
 export { PROJECT_VERSION as version } from './utils.js';
 import type { PageContextBuiltInClientWithClientRouting } from '../../shared/types.js';
 /** @deprecated

package/dist/esm/client/client-routing-runtime/index.js

@@ -5,5 +5,4 @@
 // Use package.json#exports to make the imports isomorphic.
 export { navigate, reload } from './navigate.js';
 export { prefetch } from './prefetch.js';
-export { onPopState } from './initOnPopState.js';
 export { PROJECT_VERSION as version } from './utils.js';

package/dist/esm/client/client-routing-runtime/initClientRouter.js

@@ -3,7 +3,7 @@ import { assert } from './utils.js';
 import { getRenderCount, renderPageClientSide } from './renderPageClientSide.js';
 import { initOnPopState } from './initOnPopState.js';
 import { initOnLinkClick } from './initOnLinkClick.js';
-import { setupNativeScrollRestoration } from './scrollRestoration.js';
+import { scrollRestoration_init } from './scrollRestoration.js';
 import { autoSaveScrollPosition } from './setScrollPosition.js';
 import { initLinkPrefetchHandlers } from './prefetch.js';
 import { initHistoryState, monkeyPatchHistoryAPI } from './history.js';
@@ -28,9 +28,9 @@ async function renderFirstPage() {
     });
 }
 function initHistoryAndScroll() {
+    scrollRestoration_init();
     monkeyPatchHistoryAPI();
     initHistoryState(); // we redundantly call initHistoryState() to ensure it's called early
-    setupNativeScrollRestoration();
     autoSaveScrollPosition();
     // Handle back-/forward navigation
     initOnPopState();

package/dist/esm/client/client-routing-runtime/initOnLinkClick.d.ts

@@ -1,6 +1,2 @@
 export { initOnLinkClick };
-export { getCurrentLinkClick };
 declare function initOnLinkClick(): void;
-declare function getCurrentLinkClick(): {
-    href: string;
-} | undefined;

package/dist/esm/client/client-routing-runtime/initOnLinkClick.js

@@ -1,11 +1,7 @@
-// Code adapted from https://github.com/HenrikJoreteg/internal-nav-helper/blob/5199ec5448d0b0db7ec63cf76d88fa6cad878b7d/src/index.js#L11-L29
 export { initOnLinkClick };
-export { getCurrentLinkClick };
-import { getGlobalObject } from './utils.js';
 import { isSameAsCurrentUrl, skipLink } from './skipLink.js';
 import { renderPageClientSide } from './renderPageClientSide.js';
 import { scrollToHashOrTop } from './setScrollPosition.js';
-const globalObject = getGlobalObject('initOnLinkClick.ts', {});
 function initOnLinkClick() {
     document.addEventListener('click', onClick);
 }
@@ -18,10 +14,6 @@ async function onClick(ev) {
     const href = linkTag.getAttribute('href');
     if (href === null)
         return;
-    globalObject.currentLinkClick = { href };
-    setTimeout(() => {
-        delete globalObject.currentLinkClick;
-    }, 0);
     // Workaround for Firefox bug: clicking on a hash link that doesn't change the current URL causes Firefox to erroneously set `window.history.state = null` without firing any signal that we can detect.
     // - https://github.com/vikejs/vike/issues/1962
     // - https://github.com/sveltejs/kit/issues/8725
@@ -60,6 +52,3 @@ function findLinkTag(target) {
     }
     return target;
 }
-function getCurrentLinkClick() {
-    return globalObject.currentLinkClick;
-}

package/dist/esm/client/client-routing-runtime/initOnPopState.d.ts

@@ -1,12 +1,2 @@
 export { initOnPopState };
-export { onPopState };
-import { type HistoryInfo } from './history.js';
 declare function initOnPopState(): void;
-type Listener = (arg: {
-    previous: HistoryInfo;
-}) => void | boolean;
-/** Control back-/forward navigation.
- *
- * https://vike.dev/onPopState
- */
-declare function onPopState(listener: Listener): void;

package/dist/esm/client/client-routing-runtime/initOnPopState.js

@@ -1,79 +1,59 @@
 export { initOnPopState };
-export { onPopState };
-import { assertWarning, getGlobalObject } from './utils.js';
 import { onPopStateBegin } from './history.js';
 import { renderPageClientSide } from './renderPageClientSide.js';
 import { setScrollPosition } from './setScrollPosition.js';
-import { getCurrentLinkClick } from './initOnLinkClick.js';
-import { isSamePageHashLink } from './skipLink.js';
-const globalObject = getGlobalObject('initOnPopState.ts', { listeners: [] });
+import { catchInfiniteLoop } from './utils.js';
+// The 'popstate' event is trigged when the browser doesn't fully load the new URL, for example:
+// - `location.hash='#foo'` triggers the popstate event while `location.href='/foo'` doesn't.
+// - Clicking on the browser's back-/forward button triggers a popstate event only if the history entry was generated with history.pushState() — no popstate event is fired upon Server Routing.
+// Concretely, 'popstate' is fired when:
+// 1. Back-/forward navigation:
+//    - By the user using the browser's back-/forward navigation
+//    - By the app using `history.back()` / `history.forward()` / `history.go()`
+//    > Except of history entries triggered by Server Routing, see comment above.
+// 2. URL hash changes:
+//    - By the user clicking on `<a href="#some-hash">`
+//      - The popstate event is *only* triggered if `href` starts with '#' (even if `href==='/foo#bar'` and the current URL has the same pathname '/foo' then popstate isn't triggered)
+//      - Vike doesn't intercept hash links (see `skipLink()`) and let's the browser handle them.
+//    - By the app using a `location` API such as `location.hash = 'some-hash'`
+//      - Only upon hash navigation: setting `location.href='/foo'` triggers a full page reload and no popstate event is fired.
+//      - Also upon `location.href='/foo#bar'` while the current URL is '/foo' (unlike <a> clicks).
+// Notes:
+// - The 'hashchange' event is fired after popstate, so we cannot use it to distinguish between hash and non-hash navigations.
+// - It isn't possible to monkey patch the `location` APIs. (Chrome throws `TypeError: Cannot redefine property` when attempt to overwrite any `location` property.)
+// - Text links aren't supported: https://github.com/vikejs/vike/issues/2114
+// - docs/ is a good playground to test all this.
 function initOnPopState() {
-    // - The popstate event is trigged upon:
-    //   - Back-/forward navigation.
-    //     - By user clicking on his browser's back-/forward navigation (or using a shortcut)
-    //     - By JavaScript: `history.back()` / `history.forward()`
-    //   - URL hash change.
-    //     - Click on `<a href="#some-hash" />`
-    //       - The popstate event is *only* triggered if `href` starts with '#' (even if `href` is '/#some-hash' while the current URL's pathname is '/' then the popstate still isn't triggered)
-    //     - `location.hash = 'some-hash'`
-    // - The `event` argument of `window.addEventListener('popstate', (event) => /*...*/)` is useless: the History API doesn't provide the previous state (the popped state), see https://stackoverflow.com/questions/48055323/is-history-state-always-the-same-as-popstate-event-state
-    window.addEventListener('popstate', async () => {
-        const currentLinkClick = getCurrentLinkClick();
-        const { isNewState, previous, current } = onPopStateBegin();
-        // We use currentLinkClick.href instead of current.url because current.url missing text links such as #:~:text=With%20frontmatter-,Global%20metadata,-What%20is%20global (e.g. Chrome strips the `#:~:text=` part from the URL before the popstate event).
-        if (currentLinkClick && isSamePageHashLink(currentLinkClick.href)) {
-            // Let the browser handle hash links
-            return;
-        }
-        const scrollTarget = current.state.scrollPosition || undefined;
-        const isUserPushStateNavigation = current.state.triggeredBy === 'user' || previous.state.triggeredBy === 'user';
-        const isHashNavigation = removeHash(current.url) === removeHash(previous.url) && current.url !== previous.url;
-        // - `isNewState === true` when:
-        //   - Click on `<a href="#some-hash" />` (note that Vike's `initOnLinkClick()` handler skips hash links)
-        //   - `location.hash = 'some-hash'`
-        // - `isNewState === false` when `popstate` was triggered by the user clicking on his browser's forward/backward history button.
-        const isHashNavigationNew = isHashNavigation && isNewState;
-        const isBackwardNavigation = !current.state.timestamp || !previous.state.timestamp ? null : current.state.timestamp < previous.state.timestamp;
-        // We have to scroll ourselves because we use `window.history.scrollRestoration = 'manual'`. So far this seems to work. Alternatives in case it doesn't work:
-        // - Alternative: we use `window.history.scrollRestoration = 'auto'`
-        //   - Problem: I don't think it's possbible to set `window.history.scrollRestoration = 'auto'` only for hash navigation and not for non-hash navigations?
-        //   - Problem: inconsistencies between browsers? For example specification says that setting `window.history.scrollRestoration` only affects the current entry in the session history but this contradicts what people are experiencing in practice.
-        //     - Specification: https://html.spec.whatwg.org/multipage/history.html#the-history-interface
-        //     - Practice: https://stackoverflow.com/questions/70188241/history-scrollrestoration-manual-doesnt-prevent-safari-from-restoring-scrol
-        // - Alternative: we completely take over hash navigation and reproduce the browser's native behavior upon hash navigation.
-        //   - By using the `hashchange` event.
-        //   - Problem: conflict if user wants to override the browser's default behavior? E.g. for smooth scrolling, or when using hashes for saving states of some fancy animations.
-        if (isHashNavigation) {
-            if (!isHashNavigationNew) {
-                setScrollPosition(scrollTarget);
-            }
-            else {
-                // The browser already scrolled to `#${hash}` => the current scroll position is the right one => we saved it with `enhanceHistoryState()`.
-            }
-            return;
-        }
-        let doNotRenderIfSamePage = isUserPushStateNavigation;
-        let abort;
-        globalObject.listeners.forEach((listener) => {
-            abort || (abort = listener({ previous }));
-        });
-        if (abort) {
-            return;
-        }
-        if (abort === false) {
-            doNotRenderIfSamePage = false;
-        }
-        await renderPageClientSide({ scrollTarget, isBackwardNavigation, doNotRenderIfSamePage });
-    });
+    window.addEventListener('popstate', onPopState);
 }
-// TODO/eventually: deprecate this onPopState(listener) function and let the user define +onPopState.js instead?
-/** Control back-/forward navigation.
- *
- * https://vike.dev/onPopState
- */
-function onPopState(listener) {
-    assertWarning(false, 'onPopState() is experimental', { onlyOnce: true });
-    globalObject.listeners.push(listener);
+async function onPopState() {
+    catchInfiniteLoop('onPopState()');
+    const { isHistoryStateEnhanced, previous, current } = onPopStateBegin();
+    // - `isHistoryStateEnhanced===false` <=> new hash navigation:
+    //   - Click on `<a href="#some-hash">`
+    //   - Using the `location` API (only hash navigation, see comments above).
+    // - `isHistoryStateEnhanced===true` <=> back-/forward navigation (including back-/forward hash navigation).
+    //   > Only back-/forward client-side navigation: no 'popstate' event is fired upon Server Routing (when the user clicks on a link before the page's JavaScript loaded), see comments above.
+    if (!isHistoryStateEnhanced) {
+        // Let the browser handle it
+        return;
+    }
+    else {
+        await handleBackForwardNavigation(previous, current);
+    }
+}
+async function handleBackForwardNavigation(previous, current) {
+    const scrollTarget = current.state.scrollPosition || undefined;
+    const isHashNavigation = removeHash(current.url) === removeHash(previous.url) && current.url !== previous.url;
+    if (isHashNavigation) {
+        // We have to scroll ourselves because we have set `window.history.scrollRestoration = 'manual'`
+        setScrollPosition(scrollTarget);
+        return;
+    }
+    const isUserPushStateNavigation = current.state.triggeredBy === 'user' || previous.state.triggeredBy === 'user';
+    const doNotRenderIfSamePage = isUserPushStateNavigation;
+    const isBackwardNavigation = !current.state.timestamp || !previous.state.timestamp ? null : current.state.timestamp < previous.state.timestamp;
+    await renderPageClientSide({ scrollTarget, isBackwardNavigation, doNotRenderIfSamePage });
 }
 function removeHash(url) {
     return url.split('#')[0];

package/dist/esm/client/client-routing-runtime/renderPageClientSide.js

@@ -2,7 +2,7 @@ export { renderPageClientSide };
 export { getRenderCount };
 export { disableClientRouting };
 export { firstRenderStartPromise };
-import { assert, isSameErrorMessage, objectAssign, redirectHard, getGlobalObject, executeHook, hasProp, augmentType, genPromise, isCallable } from './utils.js';
+import { assert, isSameErrorMessage, objectAssign, redirectHard, getGlobalObject, executeHook, hasProp, augmentType, genPromise, isCallable, catchInfiniteLoop } from './utils.js';
 import { getPageContextFromClientHooks, getPageContextFromServerHooks, getPageContextFromHooks_isHydration, getPageContextFromHooks_serialized, setPageContextInitIsPassedToClient } from './getPageContextFromHooks.js';
 import { createPageContext } from './createPageContext.js';
 import { addLinkPrefetchHandlers, addLinkPrefetchHandlers_unwatch, addLinkPrefetchHandlers_watch, getPageContextPrefetched, populatePageContextPrefetchCache } from './prefetch.js';
@@ -15,7 +15,7 @@ import { assertNoInfiniteAbortLoop, getPageContextFromAllRewrites, isAbortError,
 import { route } from '../../shared/route/index.js';
 import { isClientSideRoutable } from './isClientSideRoutable.js';
 import { setScrollPosition } from './setScrollPosition.js';
-import { browserNativeScrollRestoration_disable, setInitialRenderIsDone } from './scrollRestoration.js';
+import { scrollRestoration_initialRenderIsDone } from './scrollRestoration.js';
 import { getErrorPageId } from '../../shared/error-page.js';
 import { setPageContextCurrent } from './getPageContextCurrent.js';
 import { getRouteStringParameterList } from '../../shared/route/resolveRouteString.js';
@@ -31,6 +31,7 @@ const globalObject = getGlobalObject('renderPageClientSide.ts', (() => {
 })());
 const { firstRenderStartPromise } = globalObject;
 async function renderPageClientSide(renderArgs) {
+    catchInfiniteLoop('renderPageClientSide()');
     const { urlOriginal = getCurrentUrl(), overwriteLastHistoryEntry = false, isBackwardNavigation, pageContextsFromRewrite = [], redirectCount = 0, doNotRenderIfSamePage, isClientSideNavigation = true, pageContextInitClient } = renderArgs;
     let { scrollTarget } = renderArgs;
     const { previousPageContext } = globalObject;
@@ -391,18 +392,18 @@ async function renderPageClientSide(renderArgs) {
                 }
             }
         };
-        // We use globalObject.onRenderClientPromise in order to ensure that there is never two concurrent onRenderClient() calls
-        if (globalObject.onRenderClientPromise) {
+        // We use globalObject.onRenderClientPreviousPromise in order to ensure that there is never two concurrent onRenderClient() calls
+        if (globalObject.onRenderClientPreviousPromise) {
             // Make sure that the previous render has finished
-            await globalObject.onRenderClientPromise;
-            assert(globalObject.onRenderClientPromise === undefined);
+            await globalObject.onRenderClientPreviousPromise;
+            assert(globalObject.onRenderClientPreviousPromise === undefined);
             if (isRenderOutdated())
                 return;
         }
         changeUrl(urlOriginal, overwriteLastHistoryEntry);
         globalObject.previousPageContext = pageContext;
-        assert(globalObject.onRenderClientPromise === undefined);
-        globalObject.onRenderClientPromise = (async () => {
+        assert(globalObject.onRenderClientPreviousPromise === undefined);
+        const onRenderClientPromise = (async () => {
             let onRenderClientError;
             try {
                 await executeOnRenderClientHook(pageContext, true);
@@ -410,12 +411,13 @@ async function renderPageClientSide(renderArgs) {
             catch (err) {
                 onRenderClientError = err;
             }
-            globalObject.onRenderClientPromise = undefined;
+            globalObject.onRenderClientPreviousPromise = undefined;
             globalObject.isFirstRenderDone = true;
             return onRenderClientError;
         })();
-        const onRenderClientError = await globalObject.onRenderClientPromise;
-        assert(globalObject.onRenderClientPromise === undefined);
+        globalObject.onRenderClientPreviousPromise = onRenderClientPromise;
+        const onRenderClientError = await onRenderClientPromise;
+        assert(globalObject.onRenderClientPreviousPromise === undefined);
         if (onRenderClientError) {
             await onError(onRenderClientError);
             if (!isErrorPage)
@@ -475,9 +477,8 @@ async function renderPageClientSide(renderArgs) {
             }
         }
         // Page scrolling
-        setScrollPosition(scrollTarget);
-        browserNativeScrollRestoration_disable();
-        setInitialRenderIsDone();
+        setScrollPosition(scrollTarget, urlOriginal);
+        scrollRestoration_initialRenderIsDone();
         if (pageContext._hasPageContextFromServer)
             setPageContextInitIsPassedToClient(pageContext);
         // Add link prefetch handlers
@@ -488,7 +489,6 @@ async function renderPageClientSide(renderArgs) {
 function changeUrl(url, overwriteLastHistoryEntry) {
     if (getCurrentUrl() === url)
         return;
-    browserNativeScrollRestoration_disable();
     pushHistoryState(url, overwriteLastHistoryEntry);
 }
 function handleErrorFetchingStaticAssets(err, pageContext, isFirstRender) {

package/dist/esm/client/client-routing-runtime/scrollRestoration.d.ts

@@ -1,6 +1,4 @@
-export { browserNativeScrollRestoration_disable };
-export { setupNativeScrollRestoration };
-export { setInitialRenderIsDone };
-declare function setupNativeScrollRestoration(): void;
-declare function setInitialRenderIsDone(): void;
-declare function browserNativeScrollRestoration_disable(): void;
+export { scrollRestoration_init };
+export { scrollRestoration_initialRenderIsDone };
+declare function scrollRestoration_init(): void;
+declare function scrollRestoration_initialRenderIsDone(): void;

package/dist/esm/client/client-routing-runtime/scrollRestoration.js

@@ -1,25 +1,30 @@
-// Handle the browser's native scroll restoration mechanism
-export { browserNativeScrollRestoration_disable };
-export { setupNativeScrollRestoration };
-export { setInitialRenderIsDone };
+export { scrollRestoration_init };
+export { scrollRestoration_initialRenderIsDone };
+// Using `window.history.scrollRestoration` to recover scroll position when user reloads the page or Cmd-Shift-T back to it.
+// We let the browser do it because it's fast.
+// - Alternatively we could inject an inline script `<script>scrollTo(history.state.scrollPosition)</script>` early, which seems to be equally fast. (See for example https://vike.dev/usePageContext which sets the main scroll position and the navigation scroll position equally fast.)
+// - Firefox doesn't restore the scroll position upon page reload but does upon Cmd-Shift-T
+// See also: https://github.com/cyco130/knave/blob/e9e1bc7687848504293197f1b314b7d12ad0d228/design.md#scroll-restoration
 import { getGlobalObject, onPageHide, onPageShow } from './utils.js';
 const globalObject = getGlobalObject('scrollRestoration.ts', {});
-// We use the browser's native scroll restoration mechanism only for the first render
-function setupNativeScrollRestoration() {
-    browserNativeScrollRestoration_enable();
-    onPageHide(browserNativeScrollRestoration_enable);
-    onPageShow(() => globalObject.initialRenderIsDone && browserNativeScrollRestoration_disable());
+function scrollRestoration_init() {
+    // Use the native scroll restoration mechanism only for the first render
+    scrollRestoration_enable();
+    onPageHide(scrollRestoration_enable);
+    onPageShow(() => globalObject.initialRenderIsDone && scrollRestoration_disable());
 }
-function setInitialRenderIsDone() {
+function scrollRestoration_initialRenderIsDone() {
     globalObject.initialRenderIsDone = true;
+    scrollRestoration_disable();
 }
-function browserNativeScrollRestoration_disable() {
+function scrollRestoration_disable() {
     if ('scrollRestoration' in window.history) {
         window.history.scrollRestoration = 'manual';
     }
 }
-function browserNativeScrollRestoration_enable() {
+function scrollRestoration_enable() {
     if ('scrollRestoration' in window.history) {
+        // Use the browser's native scroll restoration mechanism
         window.history.scrollRestoration = 'auto';
     }
 }