vike 0.4.247-commit-903de25 → 0.4.247-commit-c3d567b

package/dist/client/runtime-client-routing/getPageContextFromHooks.js

@@ -0,0 +1,231 @@
+export { getPageContextFromHooksClient };
+export { getPageContextFromHooksClient_firstRender };
+export { getPageContextFromHooksServer };
+export { getPageContextFromHooksServer_firstRender };
+export { setPageContextInitIsPassedToClient };
+import { assert, assertUsage, hasProp, objectAssign, getProjectError, redirectHard, isObject, getGlobalObject, } from './utils.js';
+import { parse } from '@brillout/json-serializer/parse';
+import { getPageContextSerializedInHtml } from '../shared/getJsonSerializedInHtml.js';
+import { analyzePageServerSide } from '../../shared-server-client/getPageFiles/analyzePageServerSide.js';
+import { removeBuiltInOverrides } from './getPageContext/removeBuiltInOverrides.js';
+import { getPageContextRequestUrl } from '../../shared-server-client/getPageContextRequestUrl.js';
+import { getPageConfig } from '../../shared-server-client/page-configs/helpers.js';
+import { getConfigValueRuntime } from '../../shared-server-client/page-configs/getConfigValueRuntime.js';
+import { assertOnBeforeRenderHookReturn } from '../../shared-server-client/assertOnBeforeRenderHookReturn.js';
+import { execHookGuard } from '../../shared-server-client/route/execHookGuard.js';
+import { AbortRender, isAbortPageContext } from '../../shared-server-client/route/abort.js';
+import { pageContextInitIsPassedToClient } from '../../shared-server-client/misc/pageContextInitIsPassedToClient.js';
+import { isServerSideError } from '../../shared-server-client/misc/isServerSideError.js';
+import { execHook } from '../../shared-server-client/hooks/execHook.js';
+import { preparePageContextForPublicUsageClient, } from './preparePageContextForPublicUsageClient.js';
+const globalObject = getGlobalObject('runtime-client-routing/getPageContextFromHooks.ts', {});
+// TO-DO/soon/cumulative-hooks: filter & execute all client-only hooks (see other TO-DO/soon/cumulative-hooks comments)
+// - The client-side needs to know what hooks are client-only
+//   - Possible implementation: new computed prop `clientOnlyHooks: string[]` (list of hook ids) and add `hookId` to serialized config values
+const clientHooks = ['guard', 'data', 'onBeforeRender'];
+// Get `pageContext` values from `<script id="vike_pageContext" type="application/json">`
+function getPageContextFromHooksServer_firstRender() {
+    const pageContextSerialized = getPageContextSerializedInHtml();
+    processPageContextFromServer(pageContextSerialized);
+    objectAssign(pageContextSerialized, {
+        _hasPageContextFromServer: true,
+    });
+    return pageContextSerialized;
+}
+async function getPageContextFromHooksClient_firstRender(pageContext) {
+    for (const hookName of clientHooks) {
+        if (!hookClientOnlyExists(hookName, pageContext))
+            continue;
+        if (hookName === 'guard') {
+            await execHookGuardClient(pageContext);
+        }
+        else {
+            await execHookDataLike(hookName, pageContext);
+        }
+    }
+    return pageContext;
+}
+async function getPageContextFromHooksServer(pageContext, isErrorPage) {
+    const pageContextFromHooksServer = {
+        _hasPageContextFromServer: false,
+    };
+    // If pageContextInit has some client data or if one of the hooks guard(), data() or onBeforeRender() is server-side
+    // only, then we need to fetch pageContext from the server.
+    // We do it before executing any client-side hook, because it contains pageContextInit which may be needed for guard() / data() / onBeforeRender(), for example pageContextInit.user is crucial for guard()
+    if (
+    // For the error page, we cannot fetch pageContext from the server because the pageContext JSON request is based on the URL
+    !isErrorPage &&
+        // true if pageContextInit has some client data or at least one of the data() and onBeforeRender() hooks is server-side only:
+        (await hasPageContextServer(pageContext))) {
+        const res = await fetchPageContextFromServer(pageContext);
+        if ('is404ServerSideRouted' in res)
+            return { is404ServerSideRouted: true };
+        const { pageContextFromServer } = res;
+        pageContextFromHooksServer._hasPageContextFromServer = true;
+        // Already handled
+        assert(!(isServerSideError in pageContextFromServer));
+        assert(!('serverSideError' in pageContextFromServer));
+        objectAssign(pageContextFromHooksServer, pageContextFromServer);
+    }
+    // We cannot return the whole pageContext because this function is used for prefetching `pageContext` (which requires a partial pageContext to be merged with the future pageContext created upon rendering the page in the future).
+    return { pageContextFromHooksServer };
+}
+async function getPageContextFromHooksClient(pageContext, isErrorPage) {
+    let dataHookExecuted = false;
+    // At this point, we need to call the client-side guard(), data() and onBeforeRender() hooks, if they exist on client
+    // env. However if we have fetched pageContext from the server, some of them might have run already on the
+    // server-side, so we run only the client-only ones in this case.
+    // Note: for the error page, we also execute the client-side data() and onBeforeRender() hooks, but maybe we
+    // shouldn't? The server-side does it as well (but maybe it shouldn't).
+    for (const hookName of clientHooks) {
+        if (!hookClientOnlyExists(hookName, pageContext) && pageContext._hasPageContextFromServer)
+            continue;
+        if (hookName === 'guard') {
+            if (isErrorPage)
+                continue;
+            await execHookGuardClient(pageContext);
+        }
+        else {
+            if (hookName === 'data')
+                dataHookExecuted = true;
+            await execHookDataLike(hookName, pageContext);
+        }
+    }
+    // Execute +onData
+    const dataHookEnv = getHookEnv('data', pageContext);
+    if ((dataHookExecuted && dataHookEnv.client) || (pageContext._hasPageContextFromServer && dataHookEnv.server)) {
+        await execHookClient('onData', pageContext);
+    }
+    const pageContextFromHooksClient = pageContext;
+    return pageContextFromHooksClient;
+}
+async function execHookClient(hookName, pageContext) {
+    return await execHook(hookName, pageContext, (p) => preparePageContextForPublicUsageClient(p));
+}
+// It's a no-op if:
+// - No hook has been defined, or
+// - The hook's `env.client` is `false`
+async function execHookDataLike(hookName, pageContext) {
+    let pageContextFromHook;
+    if (hookName === 'data') {
+        pageContextFromHook = await execHookData(pageContext);
+    }
+    else {
+        pageContextFromHook = await execHookOnBeforeRender(pageContext);
+    }
+    Object.assign(pageContext, pageContextFromHook);
+}
+async function execHookData(pageContext) {
+    const res = await execHookClient('data', pageContext);
+    const hook = res[0]; // TO-DO/soon/cumulative-hooks: support cumulative
+    if (!hook)
+        return;
+    const { hookReturn } = hook;
+    const pageContextAddendum = { data: hookReturn };
+    return pageContextAddendum;
+}
+async function execHookOnBeforeRender(pageContext) {
+    const res = await execHookClient('onBeforeRender', pageContext);
+    const hook = res[0]; // TO-DO/soon/cumulative-hooks: support cumulative
+    if (!hook)
+        return;
+    const { hookReturn, hookFilePath } = hook;
+    const pageContextFromHook = {};
+    assertOnBeforeRenderHookReturn(hookReturn, hookFilePath);
+    // Note: hookReturn looks like { pageContext: { ... } }
+    const pageContextFromOnBeforeRender = hookReturn?.pageContext;
+    if (pageContextFromOnBeforeRender) {
+        objectAssign(pageContextFromHook, pageContextFromOnBeforeRender);
+    }
+    return pageContextFromHook;
+}
+// Workaround for the fact that the client-side cannot known whether a pageContext JSON request is needed in order to fetch pageContextInit data passed to the client.
+//  - The workaround is reliable as long as the user sets additional pageContextInit to undefined instead of not defining the property:
+//    ```diff
+//    - // Breaks the workaround:
+//    - const pageContextInit = { urlOriginal: req.url }
+//    - if (user) pageContextInit.user = user
+//    + // Makes the workaround reliable:
+//    + const pageContextInit = { urlOriginal: req.url, user }
+//    ```
+// - We can show a warning to users when the pageContextInit keys aren't always the same. (We didn't implement the waning yet because it would require a new doc page https://vike.dev/pageContextInit#avoid-conditional-properties
+// - Workaround cannot be made completely reliable because the workaround assumes that passToClient is always the same, but the user may set a different passToClient value for another page
+// - Alternatively, we could define a new config `alwaysFetchPageContextFromServer: boolean`
+function setPageContextInitIsPassedToClient(pageContext) {
+    if (pageContext[pageContextInitIsPassedToClient]) {
+        globalObject.pageContextInitIsPassedToClient = true;
+    }
+}
+// TO-DO/next-major-release: make it sync
+async function hasPageContextServer(pageContext) {
+    if (isOldDesign(pageContext)) {
+        const { hasOnBeforeRenderServerSideOnlyHook } = await analyzePageServerSide(pageContext._pageFilesAll, pageContext.pageId);
+        // data() hooks didn't exist in the V0.4 design
+        return hasOnBeforeRenderServerSideOnlyHook;
+    }
+    return !!globalObject.pageContextInitIsPassedToClient || hasServerOnlyHook(pageContext);
+}
+function hasServerOnlyHook(pageContext) {
+    if (isOldDesign(pageContext))
+        return false;
+    const pageConfig = getPageConfig(pageContext.pageId, pageContext._globalContext._pageConfigs);
+    const val = getConfigValueRuntime(pageConfig, `hasServerOnlyHook`)?.value;
+    assert(val === true || val === false);
+    return val;
+}
+function hookClientOnlyExists(hookName, pageContext) {
+    const hookEnv = getHookEnv(hookName, pageContext);
+    return !!hookEnv.client && !hookEnv.server;
+}
+function getHookEnv(hookName, pageContext) {
+    if (isOldDesign(pageContext)) {
+        // Client-only onBeforeRender(), data(), or guard() hooks were never supported for the V0.4 design
+        return { client: false, server: true };
+    }
+    const pageConfig = getPageConfig(pageContext.pageId, pageContext._globalContext._pageConfigs);
+    // No runtime validation to save client-side KBs
+    const hookEnv = (getConfigValueRuntime(pageConfig, `${hookName}Env`)?.value ?? {});
+    return hookEnv;
+}
+async function fetchPageContextFromServer(pageContext) {
+    let pageContextUrl = getPageContextRequestUrl(pageContext._urlRewrite ?? pageContext.urlOriginal);
+    /* TO-DO/soon/once: pass & use previousUrl
+    pageContextUrl = modifyUrlSameOrigin(pageContextUrl, { search: { _vike: JSON.stringify({ previousUrl: pageContext.previousPageContext.urlOriginal }) } })
+    */
+    const response = await fetch(pageContextUrl);
+    {
+        const contentType = response.headers.get('content-type');
+        const contentTypeCorrect = 'application/json';
+        const isCorrect = contentType && contentType.includes(contentTypeCorrect);
+        // Static hosts + page doesn't exist
+        if (!isCorrect && response.status === 404) {
+            redirectHard(pageContext.urlOriginal);
+            return { is404ServerSideRouted: true };
+        }
+        assertUsage(isCorrect, `Wrong Content-Type for ${pageContextUrl}: it should be ${contentTypeCorrect} but it's ${contentType} instead. Make sure to properly use pageContext.httpResponse.headers, see https://vike.dev/renderPage`);
+    }
+    const responseText = await response.text();
+    const pageContextFromServer = parse(responseText);
+    assert(isObject(pageContextFromServer));
+    if (isAbortPageContext(pageContextFromServer)) {
+        throw AbortRender(pageContextFromServer);
+    }
+    // Is there a reason for having two different properties? Can't we use only one property? I guess/think the isServerSideError property was an attempt (a bad idea really) for rendering the error page even though an error occurred on the server-side (which is a bad idea because the added complexity is non-negligible while the added value is minuscule since the error page usually doesn't have any (meaningful / server-side) hooks).
+    if ('serverSideError' in pageContextFromServer || isServerSideError in pageContextFromServer) {
+        throw getProjectError(`pageContext couldn't be fetched because an error occurred on the server-side`);
+    }
+    processPageContextFromServer(pageContextFromServer);
+    return { pageContextFromServer };
+}
+function processPageContextFromServer(pageContext) {
+    assertUsage(!('urlOriginal' in pageContext), "Adding 'urlOriginal' to passToClient is forbidden");
+    assert(hasProp(pageContext, 'pageId', 'string'));
+    removeBuiltInOverrides(pageContext);
+}
+// TO-DO/next-major-release: remove
+function isOldDesign(pageContext) {
+    return pageContext._globalContext._pageConfigs.length === 0;
+}
+async function execHookGuardClient(pageContext) {
+    await execHookGuard(pageContext, (pageContext) => preparePageContextForPublicUsageClient(pageContext));
+}

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

@@ -0,0 +1,196 @@
+export { pushHistoryState };
+export { replaceHistoryStateOriginal };
+export { onPopStateBegin };
+export { saveScrollPosition };
+export { initHistory };
+import { getCurrentUrl } from '../shared/getCurrentUrl.js';
+import { assert, assertUsage, getGlobalObject, isObject, deepEqual, cast, redirectHard } from './utils.js';
+const globalObject = getGlobalObject('history.ts', {
+    monkeyPatched: false,
+    previous: undefined,
+});
+initHistory(); // we redundantly call initHistory() to ensure it's called early
+globalObject.previous = getHistoryInfo();
+// `window.history.state === null` when:
+// - The very first render
+// - Click on `<a href="#some-hash" />`
+// - `location.hash = 'some-hash'`
+function enhanceHistoryState() {
+    if (isVikeEnhanced(window.history.state))
+        return;
+    const stateVikeEnhanced = enhance(window.history.state);
+    replaceHistoryState(stateVikeEnhanced);
+}
+function enhance(stateNotEnhanced) {
+    const timestamp = getTimestamp();
+    const scrollPosition = getScrollPosition();
+    const triggeredBy = 'browser';
+    let stateVikeEnhanced;
+    if (!stateNotEnhanced) {
+        stateVikeEnhanced = {
+            timestamp,
+            scrollPosition,
+            triggeredBy,
+            _isVikeEnhanced: true,
+        };
+    }
+    else {
+        // State information may be incomplete if `window.history.state` is set by an old Vike version. (E.g. `state.timestamp` was introduced for `pageContext.isBackwardNavigation` in `0.4.19`.)
+        cast(stateNotEnhanced);
+        stateVikeEnhanced = {
+            timestamp: stateNotEnhanced.timestamp ?? timestamp,
+            scrollPosition: stateNotEnhanced.scrollPosition ?? scrollPosition,
+            triggeredBy: stateNotEnhanced.triggeredBy ?? triggeredBy,
+            _isVikeEnhanced: true,
+        };
+    }
+    assertIsVikeEnhanced(stateVikeEnhanced);
+    return stateVikeEnhanced;
+}
+function getState() {
+    const state = window.history.state;
+    // *Every* state added to the history needs to go through Vike.
+    // - Otherwise Vike's `popstate` listener won't work. (Because, for example, if globalObject.previous is outdated => isHashNavigation faulty => client-side navigation is wrongfully skipped.)
+    // - Therefore, we have to monkey patch history.pushState() and history.replaceState()
+    // - Therefore, we need the assert() below to ensure history.state has been enhanced by Vike
+    //   - If users stumble upon this assert() then let's make it a assertUsage()
+    assertIsVikeEnhanced(state);
+    return state;
+}
+function getScrollPosition() {
+    const scrollPosition = { x: window.scrollX, y: window.scrollY };
+    return scrollPosition;
+}
+function getTimestamp() {
+    return new Date().getTime();
+}
+function saveScrollPosition() {
+    const scrollPosition = getScrollPosition();
+    // Don't overwrite history.state if it was set by a non-Vike history.pushState() call.
+    // https://github.com/vikejs/vike/issues/2801#issuecomment-3490431479
+    if (!isVikeEnhanced(window.history.state))
+        return;
+    const state = getState();
+    replaceHistoryState({ ...state, scrollPosition });
+}
+function pushHistoryState(url, overwriteLastHistoryEntry) {
+    if (!overwriteLastHistoryEntry) {
+        const state = {
+            timestamp: getTimestamp(),
+            // I don't remember why I set it to `null`, maybe because setting it now would be too early? (Maybe there is a delay between renderPageClient() is finished and the browser updating the scroll position.) Anyways, it seems like autoSaveScrollPosition() is enough.
+            scrollPosition: null,
+            triggeredBy: 'vike',
+            _isVikeEnhanced: true,
+        };
+        // Calling the monkey patched history.pushState() (and not the original) so that other tools (e.g. user tracking) can listen to Vike's pushState() calls.
+        // - https://github.com/vikejs/vike/issues/1582
+        window.history.pushState(state, '', url);
+    }
+    else {
+        replaceHistoryState(getState(), url);
+    }
+}
+function replaceHistoryState(state, url) {
+    const url_ = url ?? null; // Passing `undefined` chokes older Edge versions.
+    window.history.replaceState(state, '', url_);
+    assertIsVikeEnhanced(window.history.state);
+}
+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()
+function monkeyPatchHistoryAPI() {
+    if (globalObject.monkeyPatched)
+        return;
+    globalObject.monkeyPatched = true;
+    ['pushState', 'replaceState'].forEach((funcName) => {
+        const funcOriginal = window.history[funcName].bind(window.history);
+        window.history[funcName] = (stateOriginal = {}, ...rest) => {
+            assertUsage(stateOriginal === undefined || stateOriginal === null || isObject(stateOriginal), `history.${funcName}(state) argument state must be an object`);
+            const stateEnhanced = isVikeEnhanced(stateOriginal)
+                ? stateOriginal
+                : {
+                    _isVikeEnhanced: true,
+                    scrollPosition: getScrollPosition(),
+                    timestamp: getTimestamp(),
+                    triggeredBy: 'user',
+                    ...stateOriginal,
+                };
+            assertIsVikeEnhanced(stateEnhanced);
+            funcOriginal(stateEnhanced, ...rest);
+            assert(deepEqual(stateEnhanced, window.history.state));
+            globalObject.previous = getHistoryInfo();
+            // Workaround https://github.com/vikejs/vike/issues/2504#issuecomment-3149764736
+            queueMicrotask(() => {
+                if (deepEqual(stateEnhanced, window.history.state))
+                    return;
+                Object.assign(stateEnhanced, window.history.state);
+                assertIsVikeEnhanced(stateEnhanced);
+                replaceHistoryStateOriginal(stateEnhanced, rest[1]);
+                assert(deepEqual(stateEnhanced, window.history.state));
+            });
+        };
+    });
+}
+function isVikeEnhanced(state) {
+    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 assertIsVikeEnhanced(state) {
+    if (isVikeEnhanced(state))
+        return;
+    assert(false, { state });
+}
+function getHistoryInfo() {
+    return {
+        url: getCurrentUrl(),
+        state: getState(),
+    };
+}
+function onPopStateBegin() {
+    const { previous } = globalObject;
+    const isHistoryStateEnhanced = isVikeEnhanced(window.history.state);
+    // Either:
+    // - `window.history.pushState(null, '', '/some-path')` , or
+    // - hash navigation
+    //   - Click on `<a href="#some-hash">`
+    //   - Using the `location` API (only hash navigation)
+    // See comments a the top of the ./initOnPopState.ts file.
+    const isHistoryStatePristine = window.history.state === null;
+    if (!isHistoryStateEnhanced && !isHistoryStatePristine) {
+        // Going to a history entry not created by Vike — entering another "SPA realm" => hard reload
+        // https://github.com/vikejs/vike/issues/2801#issuecomment-3490431479
+        redirectHard(getCurrentUrl());
+        return { skip: true };
+    }
+    if (!isHistoryStateEnhanced)
+        enhanceHistoryState();
+    assertIsVikeEnhanced(window.history.state);
+    const current = getHistoryInfo();
+    globalObject.previous = current;
+    // Let the browser handle hash navigations.
+    // - Upon hash navigation: `isHistoryStatePristine===true` (see comment above).
+    if (isHistoryStatePristine) {
+        return { skip: true };
+    }
+    return { previous, current };
+}
+function initHistory() {
+    monkeyPatchHistoryAPI(); // the earlier we call it the better (Vike can workaround erroneous library monkey patches if Vike is the last one in the monkey patch chain)
+    enhanceHistoryState(); // enhance very first window.history.state which is `null`
+}

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

@@ -0,0 +1,20 @@
+export { navigate, reload } from './navigate.js';
+export { prefetch } from './prefetch.js';
+export { getPageContextClient } from './renderPageClient.js';
+export { PROJECT_VERSION as version } from './utils.js';
+import type { PageContextBuiltInClientWithClientRouting } from '../../types/PageContext.js';
+/** @deprecated
+ * Replace:
+ *   ```
+ *   import type { PageContextBuiltInClient } from 'vite-plugin/client/router'
+ *   ```
+ * With:
+ *   ```
+ *   import type {
+ *     PageContextBuiltInClientWithClientRouting as
+ *     PageContextBuiltInClient
+ *   } from 'vike/types'
+ *   ```
+ */
+type PageContextBuiltInClient<Page = any> = PageContextBuiltInClientWithClientRouting<Page>;
+export type { PageContextBuiltInClient };

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

@@ -0,0 +1,9 @@
+// TO-DO/next-major-release: move
+//   import { navigate, prefetch } from 'vike/client/router'
+// to:
+//   import { navigate, prefetch } from 'vike'
+// Use package.json#exports to make the imports isomorphic.
+export { navigate, reload } from './navigate.js';
+export { prefetch } from './prefetch.js';
+export { getPageContextClient } from './renderPageClient.js';
+export { PROJECT_VERSION as version } from './utils.js';

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

@@ -0,0 +1,35 @@
+export { initClientRouter };
+import { assert } from './utils.js';
+import { getRenderCount, renderPageClient } from './renderPageClient.js';
+import { initOnPopState } from './initOnPopState.js';
+import { initOnLinkClick } from './initOnLinkClick.js';
+import { scrollRestoration_init } from './scrollRestoration.js';
+import { autoSaveScrollPosition } from './setScrollPosition.js';
+import { initLinkPrefetchHandlers } from './prefetch.js';
+import { initHistory } from './history.js';
+async function initClientRouter() {
+    // Init navigation history and scroll restoration
+    initHistoryAndScroll();
+    // Render/hydrate
+    const renderFirstPagePromise = renderFirstPage();
+    // Intercept <a> clicks
+    initOnLinkClick();
+    // Add <a> prefetch handlers
+    initLinkPrefetchHandlers();
+    // Preserve stack track
+    await renderFirstPagePromise;
+}
+async function renderFirstPage() {
+    assert(getRenderCount() === 0);
+    await renderPageClient({
+        scrollTarget: { preserveScroll: true },
+        isClientSideNavigation: false,
+    });
+}
+function initHistoryAndScroll() {
+    scrollRestoration_init();
+    initHistory(); // we redundantly call initHistory() to ensure it's called early
+    autoSaveScrollPosition();
+    // Handle back-/forward navigation
+    initOnPopState();
+}

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

@@ -0,0 +1,55 @@
+export { initOnLinkClick };
+import { isLinkIgnored, isHrefCurrentUrl, isLinkSkipped } from './isLinkSkipped.js';
+import { renderPageClient } from './renderPageClient.js';
+import { scrollToHashOrTop } from './setScrollPosition.js';
+function initOnLinkClick() {
+    document.addEventListener('click', onLinkClick);
+}
+async function onLinkClick(ev) {
+    if (!isNormalLeftClick(ev))
+        return;
+    const linkTag = findLinkTag(ev.target);
+    if (!linkTag)
+        return;
+    const href = linkTag.getAttribute('href');
+    if (href === null)
+        return;
+    if (isLinkIgnored(linkTag))
+        return;
+    // 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
+    if (href.includes('#') && isHrefCurrentUrl(href)) {
+        // Prevent Firefox from setting `window.history.state` to `null`
+        ev.preventDefault();
+        // Replicate the browser's native behavior
+        scrollToHashOrTop(href.split('#')[1]);
+        return;
+    }
+    if (isLinkSkipped(linkTag))
+        return;
+    ev.preventDefault();
+    let scrollTarget;
+    {
+        const v = linkTag.getAttribute('keep-scroll-position');
+        if (v !== null)
+            scrollTarget = { preserveScroll: v === 'false' ? false : true };
+    }
+    await renderPageClient({
+        scrollTarget,
+        urlOriginal: href,
+    });
+}
+function isNormalLeftClick(ev) {
+    return ev.button === 0 && !ev.ctrlKey && !ev.shiftKey && !ev.altKey && !ev.metaKey;
+}
+function findLinkTag(target) {
+    while (target.tagName !== 'A') {
+        const { parentNode } = target;
+        if (!parentNode) {
+            return null;
+        }
+        target = parentNode;
+    }
+    return target;
+}

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

@@ -0,0 +1,54 @@
+export { initOnPopState };
+import { onPopStateBegin } from './history.js';
+import { renderPageClient } from './renderPageClient.js';
+import { setScrollPosition } from './setScrollPosition.js';
+import { catchInfiniteLoop } from './utils.js';
+// The 'popstate' event is triggered 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 `isLinkSkipped()`) 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.
+// - No 'popstate' event is fired upon Server Routing — when the user clicks on a link before the page's JavaScript loaded.
+// - On a pristine page without JavaScript such as https://brillout.com we have `window.history.state === null`.
+function initOnPopState() {
+    window.addEventListener('popstate', onPopState);
+}
+async function onPopState() {
+    catchInfiniteLoop('onPopState()');
+    const res = onPopStateBegin();
+    if (res.skip)
+        return;
+    const { previous, current } = res;
+    await handleHistoryNavigation(previous, current);
+}
+async function handleHistoryNavigation(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 renderPageClient({ scrollTarget, isBackwardNavigation, doNotRenderIfSamePage, isHistoryNavigation: true });
+}
+function removeHash(url) {
+    return url.split('#')[0];
+}

package/dist/client/runtime-client-routing/isClientSideRoutable.d.ts

@@ -0,0 +1,7 @@
+export { isClientSideRoutable };
+import type { GlobalContextClientInternal } from './getGlobalContextClientInternal.js';
+import type { PageFile } from '../../shared-server-client/getPageFiles.js';
+declare function isClientSideRoutable(pageId: string, pageContext: {
+    _globalContext: GlobalContextClientInternal;
+    _pageFilesAll: PageFile[];
+}): Promise<boolean>;

package/dist/client/runtime-client-routing/isClientSideRoutable.js

@@ -0,0 +1,13 @@
+export { isClientSideRoutable };
+import { analyzePageClientSideInit } from '../../shared-server-client/getPageFiles/analyzePageClientSide.js';
+import { findPageConfig } from '../../shared-server-client/page-configs/findPageConfig.js';
+import { analyzeClientSide } from '../../shared-server-client/getPageFiles/analyzeClientSide.js';
+// TO-DO/next-major-release: make it sync
+async function isClientSideRoutable(pageId, pageContext) {
+    await analyzePageClientSideInit(pageContext._pageFilesAll, pageId, {
+        sharedPageFilesAlreadyLoaded: false,
+    });
+    const pageConfig = findPageConfig(pageContext._globalContext._pageConfigs, pageId);
+    const { isClientRuntimeLoaded, isClientRouting } = analyzeClientSide(pageConfig, pageContext._pageFilesAll, pageId);
+    return isClientRuntimeLoaded && isClientRouting;
+}

package/dist/client/runtime-client-routing/navigate.js

@@ -0,0 +1,34 @@
+export { navigate };
+export { reload };
+// import { modifyUrlSameOrigin, ModifyUrlSameOriginOptions } from '../../shared/modifyUrlSameOrigin.js'
+import { getCurrentUrl } from '../shared/getCurrentUrl.js';
+import { normalizeUrlArgument } from './normalizeUrlArgument.js';
+import { firstRenderStartPromise, renderPageClient } from './renderPageClient.js';
+import { assertClientRouting } from './utils.js';
+assertClientRouting();
+/** Programmatically navigate to a new page.
+ *
+ * https://vike.dev/navigate
+ *
+ * @param url - The URL of the new page.
+ * @param keepScrollPosition - Don't scroll to the top of the page, instead keep the current scroll position.
+ * @param overwriteLastHistoryEntry - Don't create a new entry in the browser's history, instead let the new URL replace the current URL. (This effectively removes the current URL from the browser history).
+ */
+async function navigate(url, options) {
+    // let url = normalizeUrlArgument(options.url ?? getCurrentUrl(), 'navigate')
+    // url = modifyUrlSameOrigin(url, options)
+    normalizeUrlArgument(url, 'navigate');
+    // If `hydrationCanBeAborted === false` (e.g. Vue) then we can apply navigate() only after hydration is done
+    await firstRenderStartPromise;
+    const { keepScrollPosition, overwriteLastHistoryEntry, pageContext } = options ?? {};
+    const scrollTarget = { preserveScroll: keepScrollPosition ?? false };
+    await renderPageClient({
+        scrollTarget,
+        urlOriginal: url,
+        overwriteLastHistoryEntry,
+        pageContextInitClient: pageContext,
+    });
+}
+async function reload() {
+    await navigate(getCurrentUrl());
+}