@vesk/runtime 0.1.1 → 0.2.8

package/dist/router.js

@@ -2,7 +2,9 @@ import { get, set, scope, set_active_block } from '@vesk/runtime/src/ripple-runt
 import { root } from '@vesk/runtime/src/ripple-blocks';
 import { createHydrateWalker, hydrateViewport, hydrateIdle, hydrateOnInteraction } from '@vesk/runtime/src/hydrate';
 import { matchRoute, flattenLayoutChain, buildTreeFromMap } from '@vesk/runtime/src/router-match';
-import { setIsHydrating, _state, _scrollPositions, _isPopStateNavigation, setIsPopStateNavigation, setCurrentRouter, showLoadingInContainer, handleScroll, applyHead, findLoadingComponent, findErrorComponent, findNotFoundComponent, Outlet, Link, NavLink, useNavigate, useParams, usePathname, useSearchParams, useRouter, Redirect, redirect, permanentRedirect, NotFoundError, notFound, } from '@vesk/runtime/src/router-components';
+import { setIsHydrating, _state, _scrollPositions, _isPopStateNavigation, setIsPopStateNavigation, setCurrentRouter, showLoadingInContainer, handleScroll, applyHead, findLoadingComponent, findErrorComponent, findNotFoundComponent, findOfflineComponent, findNetworkComponent, Outlet, Link, NavLink, useNavigate, useParams, usePathname, useSearchParams, useRouter, Redirect, redirect, permanentRedirect, NotFoundError, notFound, } from '@vesk/runtime/src/router-components';
+import { getNetworkState, watchNetwork } from '@vesk/runtime/src/network';
+import { loadingStart, loadingFinish, getLoadingState } from '@vesk/runtime/src/loading-indicator';
 export { Outlet, Link, NavLink, useNavigate, useParams, usePathname, useSearchParams, useRouter, Redirect, redirect, permanentRedirect, NotFoundError, notFound, ensureChunk, };
 export { matchRoute } from '@vesk/runtime/src/router-match';
 const loadedChunks = new Set();
@@ -35,7 +37,18 @@ function ensureChunk(chunkUrl) {
 }
 /** Loads pending chunks without letting a single failed chunk abort the flow. */
 function loadChunksQuietly(urls) {
-    return Promise.all(urls.map((u) => ensureChunk(u).catch(() => undefined))).then(() => undefined);
+    navDebug('loadChunks start', urls);
+    return Promise.all(urls.map((u) => ensureChunk(u).catch(() => undefined))).then(() => {
+        navDebug('loadChunks done', urls);
+    });
+}
+// Set window.__veskNavDebug = [] in the page to capture router breadcrumbs.
+function navDebug(...parts) {
+    if (typeof window === 'undefined')
+        return;
+    const log = window.__veskNavDebug;
+    if (log)
+        log.push(parts.map(p => Array.isArray(p) ? p.join(',') : String(p)).join(' '));
 }
 function hasPendingChunks(nodes) {
     const urls = [];
@@ -48,6 +61,17 @@ function hasPendingChunks(nodes) {
     nodes.forEach(walk);
     return urls;
 }
+/**
+ * Classifies a data-fetch failure as a connectivity problem rather than a
+ * server problem: fetch rejects with TypeError on network failure, and
+ * `navigator.onLine === false` confirms it even where the error shape is
+ * environment-specific.
+ */
+function isConnectivityFailure(err) {
+    if (typeof navigator !== 'undefined' && navigator && navigator.onLine === false)
+        return true;
+    return err instanceof TypeError;
+}
 const _dataPromises = new Map();
 async function fetchRouteData(path) {
     try {
@@ -83,7 +107,13 @@ async function fetchRouteData(path) {
             return null;
         return (await res.json());
     }
-    catch {
+    catch (err) {
+        if (isConnectivityFailure(err))
+            return { offline: true };
+        // Passive signals can miss (proxies, emulation) — actively probe
+        // before classifying as a plain failure.
+        if (await looksOffline())
+            return { offline: true };
         return null;
     }
 }
@@ -129,7 +159,27 @@ function chunkErrorForNode(node) {
         return new Error(String(node._chunkError));
     return undefined;
 }
+/**
+ * Active connectivity check for failure paths where passive signals
+ * (`navigator.onLine`) are unreliable (proxies, CDP emulation, some
+ * browsers lag the flag). Any HTTP response — even 404/500 — proves the
+ * origin is reachable; only a fetch-level rejection counts as offline.
+ */
+async function looksOffline() {
+    if (typeof navigator !== 'undefined' && navigator && navigator.onLine === false)
+        return true;
+    if (typeof fetch !== 'function')
+        return false;
+    try {
+        await fetch('/__vesk_connectivity_' + Date.now(), { method: 'HEAD', cache: 'no-store' });
+        return false;
+    }
+    catch (err) {
+        return err instanceof TypeError;
+    }
+}
 async function renderNotFound(router, match, container) {
+    clearOfflineFlag(router, container);
     const chain = match.matchChain;
     const paramValues = match.params;
     const notFoundFn = findNotFoundComponent(chain);
@@ -158,7 +208,142 @@ async function renderNotFound(router, match, container) {
     container.innerHTML = '<h1>404 — Not Found</h1>';
     router._currentMatch = match;
 }
+function defaultOfflineHtml(url) {
+    return '<div data-vesk-offline style="all:initial;display:flex;flex-direction:column;align-items:center;justify-content:center;min-height:60vh;font-family:system-ui,-apple-system,sans-serif;color:#1f2937;text-align:center;padding:24px">' +
+        '<div style="font-size:40px;line-height:1;margin-bottom:16px" aria-hidden="true">📡</div>' +
+        '<h1 style="font-size:22px;font-weight:700;margin:0 0 8px">You\u2019re offline</h1>' +
+        '<p style="margin:0 0 20px;color:#6b7280;max-width:34em">Check your connection. <span style="color:#9ca3af">' + escapeOfflineUrl(url) + '</span> will load automatically once you\u2019re back online.</p>' +
+        '<button type="button" data-vesk-offline-retry style="all:unset;cursor:pointer;background:#2563eb;color:#fff;padding:10px 22px;border-radius:8px;font-size:14px;font-weight:600">Retry now</button>' +
+        '</div>';
+}
+function escapeOfflineUrl(url) {
+    return String(url).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+/**
+ * Renders the connectivity experience for a navigation that failed due to
+ * loss of (or degraded) network. Precedence:
+ *   1. nearest route `offline.vsk` — dedicated offline UI (when offline)
+ *   2. nearest route `network.vsk` — state-aware UI receiving
+ *      `{ url, params, retry, online, effectiveType, downlink, rtt, saveData }`
+ *   3. router `offline` option (component or HTML string)
+ *   4. nearest route `error.vsk`, invoked with an `offline: true` error so
+ *      existing error boundaries can style the offline case themselves
+ *   5. built-in default panel
+ *
+ * A network failure never renders the not-found page. While a boundary from
+ * steps 1–3 or 5 is displayed it re-renders on connectivity changes
+ * (3g→4g→offline…), and the router re-navigates automatically when the
+ * browser comes back online.
+ */
+async function renderOfflinePage(router, match, container) {
+    const url = match.pathname || (typeof window !== 'undefined' ? window.location.pathname : '');
+    const chain = match.matchChain;
+    const navTokenAtRender = router._navToken;
+    // Debounced retry: a component that calls retry() while rendering must
+    // not trigger a navigate→fail→render→retry microtask loop.
+    const safeRetry = () => {
+        const r = router;
+        const now = Date.now();
+        if (now - (r._lastOfflineRetry || 0) < 300)
+            return;
+        r._lastOfflineRetry = now;
+        router.navigate(url, { replace: true });
+    };
+    const mountComponent = async (entry) => {
+        if (typeof entry === 'string') {
+            container.innerHTML = entry;
+            return true;
+        }
+        const tempRoot = document.createDocumentFragment();
+        const walker = createHydrateWalker(tempRoot, []);
+        const props = { url, params: match.params, retry: safeRetry, ...getNetworkState() };
+        const dom = await runInBlockWindow(() => entry(props, new Map(), walker));
+        if (dom && typeof dom === 'object' && dom.nodeType) {
+            if (container.replaceChildren)
+                container.replaceChildren(dom);
+            else {
+                container.innerHTML = '';
+                container.appendChild(dom);
+            }
+            return true;
+        }
+        if (typeof dom === 'string') {
+            container.innerHTML = dom;
+            return true;
+        }
+        return false;
+    };
+    let mounted = false;
+    let reactive = false; // re-render on connectivity change
+    const offlineEntry = findOfflineComponent(chain);
+    if (!mounted && offlineEntry && !(getNetworkState().online)) {
+        mounted = await mountComponent(offlineEntry);
+        reactive = mounted;
+    }
+    const networkEntry = findNetworkComponent(chain);
+    if (!mounted && networkEntry) {
+        mounted = await mountComponent(networkEntry);
+        reactive = mounted;
+    }
+    const optionUI = router._offlineUI;
+    if (!mounted && optionUI !== undefined && optionUI !== null) {
+        mounted = typeof optionUI === 'function'
+            ? await mountComponent(optionUI)
+            : ((container.innerHTML = String(optionUI)), true);
+        reactive = typeof optionUI === 'function';
+    }
+    const errorFn = findErrorComponent(chain);
+    if (!mounted && errorFn) {
+        // Existing error boundary opts in via `props.offline` /
+        // `props.networkState`.
+        const err = new Error('You are offline');
+        err.statusCode = 0;
+        err.offline = true;
+        await renderErrorPage(router, match, container, err);
+        mounted = true;
+    }
+    if (!mounted) {
+        container.innerHTML = defaultOfflineHtml(url);
+        const retryBtn = (container.querySelector ? container.querySelector('[data-vesk-offline-retry]') : null);
+        if (retryBtn)
+            retryBtn.addEventListener('click', safeRetry);
+        reactive = true;
+    }
+    router._showingOffline = true;
+    registerOnlineRecovery(router);
+    // Live-swap the displayed boundary when connectivity changes (e.g.
+    // offline → 3g → 4g), but stop as soon as a newer navigation takes over.
+    if (reactive && typeof window !== 'undefined') {
+        container.__veskNetworkUI = true;
+        const unsubscribe = watchNetwork(() => {
+            const stillCurrent = router._navToken === navTokenAtRender &&
+                container.__veskNetworkUI === true &&
+                router._showingOffline === true;
+            if (!stillCurrent) {
+                unsubscribe();
+                return;
+            }
+            void renderOfflinePage(router, match, container);
+        });
+    }
+}
+function registerOnlineRecovery(router) {
+    const r = router;
+    if (r._onlineHandler || typeof window === 'undefined' || typeof window.addEventListener !== 'function')
+        return;
+    r._onlineHandler = () => {
+        if (!r._showingOffline)
+            return;
+        r._showingOffline = false;
+        router.navigate(window.location.pathname + window.location.search, { replace: true });
+    };
+    window.addEventListener('online', r._onlineHandler);
+}
 async function applyRouteData(router, match, data, container, render = renderMatch) {
+    if (data.offline) {
+        await renderOfflinePage(router, match, container);
+        return;
+    }
     if (data.notFound) {
         await renderNotFound(router, match, container);
         return;
@@ -229,7 +414,7 @@ function shouldFetchData(router, match) {
     return Date.now() - fetchedAt >= ttl;
 }
 function hasRealPageData(data) {
-    if (data.notFound || data.redirect || data.error)
+    if (data.offline || data.notFound || data.redirect || data.error)
         return true;
     if (data.head && data.head.trim().length > 0)
         return true;
@@ -339,7 +524,27 @@ function replacePageContent(container, newContent) {
     }
     return true;
 }
-function renderMatch(router, match, container) {
+function storePageInstance(router, pageNode, pageProps, result) {
+    if (!router || !pageNode._pageName || !result || result.nodeType !== 1)
+        return;
+    if (!router.__componentInstances)
+        router.__componentInstances = new Map();
+    const name = pageNode._pageName;
+    if (!router.__componentInstances.has(name))
+        router.__componentInstances.set(name, []);
+    router.__componentInstances.get(name).push({ root: result, props: pageProps, node: pageNode, type: 'page' });
+}
+function storeLayoutInstance(router, node, layoutProps, result) {
+    if (!router || !node._layoutName || !result || result.nodeType !== 1)
+        return;
+    if (!router.__componentInstances)
+        router.__componentInstances = new Map();
+    const name = node._layoutName;
+    if (!router.__componentInstances.has(name))
+        router.__componentInstances.set(name, []);
+    router.__componentInstances.get(name).push({ root: result, props: layoutProps, node, type: 'layout' });
+}
+function renderMatch(router, match, container, navToken) {
     const chain = match.matchChain;
     const paramValues = match.params;
     let pageNode = findPageNodeOrFailed(match);
@@ -379,11 +584,25 @@ function renderMatch(router, match, container) {
         return;
     }
     // The route matched and has a page name, but its component chunk failed
-    // to load or compile. Render the route's error boundary (or a generic
-    // error page) without touching any other route's components.
-    if (!pageNode.page && pageNode._pageName) {
-        const chunkErr = chunkErrorForNode(pageNode);
-        return renderErrorPage(router, match, container, chunkErr || new Error(`Component "${pageNode._pageName}" is unavailable`));
+    // to load or compile (or its component ref is still an unwired name).
+    // While offline that is a connectivity problem, not a broken route —
+    // show the offline experience instead of an error page. The connectivity
+    // probe only runs when a chunk actually failed or the browser reports
+    // offline, so ordinary lazy-loading never pays for it.
+    if (pageNode._pageName && (!pageNode.page || typeof pageNode.page === 'string')) {
+        const suspectOffline = failedChunks.has(pageNode._chunk)
+            || (typeof navigator !== 'undefined' && !!navigator && navigator.onLine === false);
+        navDebug('unresolved page guard', String(pageNode._pageName), 'suspect=', String(suspectOffline));
+        if (!suspectOffline) {
+            const chunkErr0 = chunkErrorForNode(pageNode);
+            return renderErrorPage(router, match, container, chunkErr0 || new Error(`Component "${pageNode._pageName}" is unavailable`));
+        }
+        return looksOffline().then((offline) => {
+            if (offline)
+                return renderOfflinePage(router, match, container);
+            const chunkErr = chunkErrorForNode(pageNode);
+            return renderErrorPage(router, match, container, chunkErr || new Error(`Component "${pageNode._pageName}" is unavailable`));
+        });
     }
     const layoutNodes = chain.filter(n => n.layout);
     const tempRoot = document.createDocumentFragment();
@@ -434,7 +653,10 @@ function renderMatch(router, match, container) {
     const pageStep = () => {
         set(_state.params, paramValues);
         set(_state.path, match.pathname || window.location.pathname);
-        set(_state.search, window.location.search || '');
+        {
+            const s = window.location.search || '';
+            set(_state.search, s.startsWith('?') ? s.slice(1) : s);
+        }
         const pageProps = { params: paramValues, ...pageNode.props };
         const result = pageNode.page(pageProps, new Map(), clientWalker);
         if (result && typeof result.then === 'function') {
@@ -457,7 +679,7 @@ function renderMatch(router, match, container) {
                 router.navigate(window.location.pathname, { replace: true });
             }
         };
-        const errorProps = { error, retry, params: paramValues, statusCode: error?.statusCode ?? 500, stack: error instanceof Error ? error.stack : String(error), url: typeof window !== 'undefined' ? window.location.pathname : '' };
+        const errorProps = { error, retry, params: paramValues, statusCode: error?.statusCode ?? 500, stack: error instanceof Error ? error.stack : String(error), url: typeof window !== 'undefined' ? window.location.pathname : '', offline: error?.offline === true, networkState: getNetworkState() };
         return runInBlockWindow(() => renderLayoutWith(0, () => {
             const result = errorFn(errorProps, new Map(), clientWalker);
             if (result && typeof result.then === 'function') {
@@ -478,7 +700,7 @@ function renderMatch(router, match, container) {
                 router.navigate(window.location.pathname, { replace: true });
             }
         };
-        const errorProps = { error, retry, params: paramValues, statusCode: error?.statusCode ?? 500, stack: error instanceof Error ? error.stack : String(error), url: typeof window !== 'undefined' ? window.location.pathname : '' };
+        const errorProps = { error, retry, params: paramValues, statusCode: error?.statusCode ?? 500, stack: error instanceof Error ? error.stack : String(error), url: typeof window !== 'undefined' ? window.location.pathname : '', offline: error?.offline === true, networkState: getNetworkState() };
         const errDom = runInBlockWindow(() => errorFn(errorProps, new Map(), clientWalker));
         if (errDom && typeof errDom.then === 'function') {
             errDom.then(mountDom);
@@ -487,27 +709,14 @@ function renderMatch(router, match, container) {
             mountDom(errDom);
         }
     }
-    function storePageInstance(router, pageNode, pageProps, result) {
-        if (!router || !pageNode._pageName || !result || result.nodeType !== 1)
-            return;
-        if (!router.__componentInstances)
-            router.__componentInstances = new Map();
-        const name = pageNode._pageName;
-        if (!router.__componentInstances.has(name))
-            router.__componentInstances.set(name, []);
-        router.__componentInstances.get(name).push({ root: result, props: pageProps, node: pageNode, type: 'page' });
-    }
-    function storeLayoutInstance(router, node, layoutProps, result) {
-        if (!router || !node._layoutName || !result || result.nodeType !== 1)
-            return;
-        if (!router.__componentInstances)
-            router.__componentInstances = new Map();
-        const name = node._layoutName;
-        if (!router.__componentInstances.has(name))
-            router.__componentInstances.set(name, []);
-        router.__componentInstances.get(name).push({ root: result, props: layoutProps, node, type: 'layout' });
-    }
     const mountDom = (dom) => {
+        // Staleness guard: a suspended (async) page whose render resolves after
+        // a NEWER navigation must not clobber the newer page's DOM. The file
+        // router stamps the container with the latest nav token per navigation.
+        if (navToken !== undefined &&
+            container.__veskMountToken !== navToken) {
+            return;
+        }
         if (dom && typeof dom === 'object' && dom.nodeType) {
             if (container.replaceChildren)
                 container.replaceChildren(dom);
@@ -566,7 +775,13 @@ function makeSsrError(message) {
 // failure or when the SSR output is already an error page). The error
 // component renders in place of the page inside the layout chain so the error
 // page keeps the site nav.
+function clearOfflineFlag(router, container) {
+    router._showingOffline = false;
+    if (container)
+        container.__veskNetworkUI = false;
+}
 async function renderErrorPage(router, match, container, error) {
+    clearOfflineFlag(router, container);
     const chain = match.matchChain;
     const paramValues = match.params;
     const errorFn = findErrorComponent(chain);
@@ -586,7 +801,7 @@ async function renderErrorPage(router, match, container, error) {
             router.navigate(window.location.pathname, { replace: true });
         }
     };
-    const errorProps = { error, retry, params: paramValues, statusCode: error?.statusCode ?? 500, stack: error instanceof Error ? error.stack : String(error), url: typeof window !== 'undefined' ? window.location.pathname : '' };
+    const errorProps = { error, retry, params: paramValues, statusCode: error?.statusCode ?? 500, stack: error instanceof Error ? error.stack : String(error), url: typeof window !== 'undefined' ? window.location.pathname : '', offline: error?.offline === true, networkState: getNetworkState() };
     const renderErrorChain = (index) => {
         if (index >= layoutNodes.length) {
             const result = errorFn(errorProps, new Map(), walker);
@@ -660,7 +875,10 @@ async function hydrateInitial(router, match, container, strategy) {
     })();
     set(_state.params, paramValues);
     set(_state.path, match.pathname || window.location.pathname);
-    set(_state.search, window.location.search || '');
+    {
+        const s = window.location.search || '';
+        set(_state.search, s.startsWith('?') ? s.slice(1) : s);
+    }
     if (ssrErrorMarker !== null) {
         let message = 'Internal Server Error';
         if (ssrErrorMarker.startsWith(':')) {
@@ -677,8 +895,13 @@ async function hydrateInitial(router, match, container, strategy) {
     const layoutNodes = chain.filter(n => n.layout);
     const hydrators = router.__hydrators;
     if (!pageNode.page && !(hydrators && pageNode._pageName && hydrators[pageNode._pageName])) {
-        // The route's component chunk failed to load or compile. Render the
-        // error boundary for this route instead of hydrating nothing.
+        // The route's component chunk failed to load or compile. While
+        // offline that is a connectivity problem — show the offline
+        // experience; otherwise render the error boundary for this route.
+        if (await looksOffline()) {
+            await renderOfflinePage(router, match, container);
+            return;
+        }
         const chunkErr = chunkErrorForNode(pageNode);
         await renderErrorPage(router, match, container, chunkErr || new Error(`Component "${pageNode._pageName}" is unavailable`));
         return;
@@ -698,7 +921,10 @@ async function hydrateInitial(router, match, container, strategy) {
             if (!strategy || strategy === 'full') {
                 const walker = createHydrateWalker(container);
                 setIsHydrating(true);
-                await runInBlockWindow(() => hydPage(pageProps, new Map(), walker));
+                await runInBlockWindow(() => {
+                    const result = hydPage(pageProps, new Map(), walker);
+                    storePageInstance(router, pageNode, pageProps, result);
+                });
                 setIsHydrating(false);
             }
             else if (strategy === 'viewport') {
@@ -723,7 +949,10 @@ async function hydrateInitial(router, match, container, strategy) {
             if (index >= layoutNodes.length) {
                 return (subWalker) => {
                     if (!strategy || strategy === 'full') {
-                        return hydPage({ params: paramValues, ...pageNode.props }, new Map(), subWalker);
+                        const pageProps = { params: paramValues, ...pageNode.props };
+                        const result = hydPage(pageProps, new Map(), subWalker);
+                        storePageInstance(router, pageNode, pageProps, result);
+                        return result;
                     }
                     else if (strategy === 'viewport') {
                         hydrateViewport(subWalker.root, hydPage, { params: paramValues, ...pageNode.props });
@@ -741,7 +970,9 @@ async function hydrateInitial(router, match, container, strategy) {
             const hydLayout = hydLayouts[index];
             const childHydrator = renderLayoutChain(index + 1);
             const layoutProps = { children: childHydrator, params: paramValues };
-            return hydLayout(layoutProps, new Map(), walker);
+            const result = hydLayout(layoutProps, new Map(), walker);
+            storeLayoutInstance(router, node, layoutProps, result);
+            return result;
         }
         const walker = createHydrateWalker(container);
         await runInBlockWindow(() => renderLayoutChain(0));
@@ -764,6 +995,20 @@ async function hydrateInitial(router, match, container, strategy) {
         }
     }
 }
+function scrollToHash() {
+    const h = typeof window !== 'undefined' ? window.location.hash : '';
+    if (!h || h === '#')
+        return;
+    const id = h.slice(1);
+    setTimeout(() => {
+        try {
+            const el = document.getElementById(id);
+            if (el && typeof el.scrollIntoView === 'function')
+                el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+        }
+        catch { /* element may not exist */ }
+    }, 80);
+}
 export function createRouter(routes, options = {}) {
     const container = options.container || document.getElementById('root');
     const prefetch = options.prefetch !== false;
@@ -777,6 +1022,51 @@ export function createRouter(routes, options = {}) {
         _currentSegments: null,
         _depth: 0,
         _routeDataCache: options.routeDataCache ?? 0,
+        _offlineUI: (options.offline ?? null),
+        _beforeGuards: [],
+        _viewTransitions: options.viewTransitions === true,
+        beforeEach(fn) {
+            this._beforeGuards.push(fn);
+            let active = true;
+            return () => {
+                if (!active)
+                    return;
+                active = false;
+                const guards = this._beforeGuards;
+                const i = guards.indexOf(fn);
+                if (i > -1)
+                    guards.splice(i, 1);
+            };
+        },
+        _runGuards(to) {
+            const from = window.location.pathname;
+            for (const g of this._beforeGuards ?? []) {
+                const d = g(to, from);
+                if (d instanceof Promise) {
+                    return d.then((r) => {
+                        if (r === false || typeof r === 'string')
+                            return r;
+                    });
+                }
+                if (d === false || typeof d === 'string')
+                    return d;
+            }
+        },
+        go(n) {
+            window.history.go(n);
+        },
+        get route() {
+            const m = this._currentMatch;
+            if (!m)
+                return null;
+            const chain = m.matchChain ?? [];
+            const deepest = chain[chain.length - 1];
+            return {
+                pathname: m.pathname || '',
+                params: m.params,
+                pattern: deepest?.fullPath || '/',
+            };
+        },
         start() {
             setCurrentRouter(this);
             if (typeof window !== 'undefined' && 'scrollRestoration' in window.history) {
@@ -795,24 +1085,52 @@ export function createRouter(routes, options = {}) {
                     }, 100);
                 }, { passive: true });
             }
+            // Navigation policy: SPA navigation happens through <Link>/
+            // <NavLink>/navigate() and opt-in plain anchors
+            // `<a href="..." no-reload>`. Plain <a href> without `no-reload`
+            // (or `data-no-reload`) always does native browser navigation.
+            // `no-reload` anchors are intercepted via a delegated document
+            // click listener that respects modifier keys, target="_blank",
+            // download, external origins, hash/mailto/tel schemes.
+            window.addEventListener('popstate', () => {
+                setIsPopStateNavigation(true);
+                this.navigate(window.location.href, { replace: true });
+            });
             document.addEventListener('click', (e) => {
-                const link = e.target?.nodeType === 1 ? e.target.closest('a[href]') : null;
-                if (!link)
+                const target = e.target;
+                if (!target || target.nodeType !== 1)
+                    return;
+                const anchor = target.closest('a[href]');
+                if (!anchor)
+                    return;
+                if (!anchor.hasAttribute('no-reload') && !anchor.hasAttribute('data-no-reload'))
+                    return;
+                if (e.defaultPrevented)
+                    return;
+                const me = e;
+                if (me.metaKey || me.ctrlKey || me.shiftKey || me.altKey || me.button !== 0)
                     return;
-                if (link.hostname && link.hostname !== window.location.hostname)
+                if (anchor.target === '_blank')
                     return;
-                const href = link.getAttribute('href');
-                if (!href || href.startsWith('#') || href.startsWith('mailto:') || href.startsWith('tel:'))
+                if (anchor.hasAttribute('download'))
                     return;
-                if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0)
+                if (anchor.getAttribute('rel') === 'external')
                     return;
+                const href = anchor.getAttribute('href');
+                if (!href || href.startsWith('#') || href.startsWith('mailto:') || href.startsWith('tel:') || href.startsWith('javascript:'))
+                    return;
+                try {
+                    const url = new URL(href, window.location.origin);
+                    if (url.origin !== window.location.origin)
+                        return;
+                }
+                catch {
+                    return;
+                }
                 e.preventDefault();
+                e.stopPropagation();
                 this.navigate(href);
             });
-            window.addEventListener('popstate', () => {
-                setIsPopStateNavigation(true);
-                this.navigate(window.location.href, { replace: true });
-            });
             if (prefetch) {
                 document.addEventListener('mouseenter', (e) => {
                     const link = e.target?.nodeType === 1 ? e.target.closest('a[href]') : null;
@@ -846,74 +1164,133 @@ export function createRouter(routes, options = {}) {
                 return;
             }
             match.pathname = url.pathname;
-            if (!_isPopStateNavigation) {
-                _scrollPositions.set(window.location.pathname, window.scrollY);
-            }
-            const loadingFn = findLoadingComponent(match.matchChain);
-            this._navToken = (this._navToken || 0) + 1;
-            const navToken = this._navToken;
-            let firstRenderFailed = false;
-            const updateUrl = () => {
-                if (!opts.replace) {
-                    window.history.pushState({ path: url.pathname }, '', url.pathname);
+            // Navigation guards (programmatic/Link navigations only).
+            const self = this;
+            const guardResult = self._runGuards(url.pathname);
+            const proceedNav = () => {
+                if (!_isPopStateNavigation) {
+                    _scrollPositions.set(window.location.pathname, window.scrollY);
                 }
-                else {
-                    window.history.replaceState({ path: url.pathname }, '', url.pathname);
-                }
-                set(_state.path, url.pathname);
-                set(_state.search, url.search);
-            };
-            const renderContent = () => {
-                try {
-                    renderMatch(this, match, this.container);
+                const loadingFn = findLoadingComponent(match.matchChain);
+                this._navToken = (this._navToken || 0) + 1;
+                const navToken = this._navToken;
+                loadingStart();
+                let firstRenderFailed = false;
+                const updateUrl = () => {
+                    if (!opts.replace) {
+                        window.history.pushState({ path: url.pathname }, '', url.pathname + url.search);
+                    }
+                    else {
+                        window.history.replaceState({ path: url.pathname }, '', url.pathname + url.search);
+                    }
+                    set(_state.path, url.pathname);
+                    set(_state.search, url.search.startsWith('?') ? url.search.slice(1) : url.search);
+                };
+                const renderContent = () => {
+                    try {
+                        renderMatch(this, match, this.container);
+                    }
+                    catch (e) {
+                        firstRenderFailed = true;
+                        throw e;
+                    }
+                    this._currentMatch = match;
+                    clearOfflineFlag(this, container);
+                    handleScroll(url.pathname, opts.replace);
+                };
+                const swapView = (fn) => {
+                    const d = document;
+                    if (this._viewTransitions && typeof d.startViewTransition === 'function')
+                        d.startViewTransition(fn);
+                    else
+                        fn();
+                };
+                const doRender = () => {
+                    updateUrl();
+                    swapView(() => renderContent());
+                    scrollToHash();
+                };
+                const fetchData = () => {
+                    if (firstRenderFailed)
+                        return;
+                    if (!shouldFetchData(this, match)) {
+                        loadingFinish();
+                        scrollToHash();
+                        return;
+                    }
+                    getRouteData(url.pathname + url.search, 'nav' + navToken).then(async (data) => {
+                        if (navToken !== this._navToken)
+                            return;
+                        if (!data) {
+                            loadingFinish();
+                            return;
+                        }
+                        if (data.redirect) {
+                            loadingFinish();
+                            this.navigate(data.redirect, { replace: true });
+                            return;
+                        }
+                        if (!hasRealPageData(data)) {
+                            loadingFinish();
+                            scrollToHash();
+                            return;
+                        }
+                        await swapView(() => applyRouteData(this, match, data, this.container));
+                        scrollToHash();
+                        loadingFinish({ error: !!data.error });
+                    }).catch(() => loadingFinish({ error: true }));
+                };
+                if (loadingFn) {
+                    showLoadingInContainer(this.container, loadingFn, match.params);
+                    Promise.resolve().then(() => { try {
+                        doRender();
+                    }
+                    finally {
+                        fetchData();
+                    } });
                 }
-                catch (e) {
-                    firstRenderFailed = true;
-                    throw e;
+                else {
+                    try {
+                        doRender();
+                    }
+                    finally {
+                        fetchData();
+                    }
                 }
-                this._currentMatch = match;
-                handleScroll(url.pathname, opts.replace);
-            };
-            const doRender = () => {
-                updateUrl();
-                renderContent();
             };
-            const fetchData = () => {
-                if (firstRenderFailed)
-                    return;
-                if (!shouldFetchData(this, match))
-                    return;
-                getRouteData(url.pathname + url.search, 'nav' + navToken).then(async (data) => {
-                    if (navToken !== this._navToken)
-                        return;
-                    if (!data)
+            // If guards return a Promise, chain the rest asynchronously.
+            // If sync (the common case), the navigation completes synchronously,
+            // preserving backward compatibility with callers that don't await.
+            if (guardResult instanceof Promise) {
+                return guardResult.then((decision) => {
+                    if (decision === false)
                         return;
-                    if (data.redirect) {
-                        this.navigate(data.redirect, { replace: true });
+                    if (typeof decision === 'string' && decision !== url.pathname && (self._guardDepth ?? 0) < 5) {
+                        self._guardDepth = (self._guardDepth ?? 0) + 1;
+                        try {
+                            self.navigate(decision, { replace: true });
+                        }
+                        finally {
+                            self._guardDepth = 0;
+                        }
                         return;
                     }
-                    if (!hasRealPageData(data))
-                        return;
-                    await applyRouteData(this, match, data, this.container);
+                    proceedNav();
                 });
-            };
-            if (loadingFn) {
-                showLoadingInContainer(this.container, loadingFn, match.params);
-                Promise.resolve().then(() => { try {
-                    doRender();
-                }
-                finally {
-                    fetchData();
-                } });
             }
-            else {
+            if (guardResult === false)
+                return;
+            if (typeof guardResult === 'string' && guardResult !== url.pathname && (self._guardDepth ?? 0) < 5) {
+                self._guardDepth = (self._guardDepth ?? 0) + 1;
                 try {
-                    doRender();
+                    self.navigate(guardResult, { replace: true });
                 }
                 finally {
-                    fetchData();
+                    self._guardDepth = 0;
                 }
+                return;
             }
+            proceedNav();
         },
         prefetch(path) {
             const url = new URL(path, window.location.origin);
@@ -933,6 +1310,10 @@ export function createRouter(routes, options = {}) {
         get currentPath() {
             return get(_state.path);
         },
+        get isLoading() {
+            const cells = getLoadingState();
+            return Boolean(get(cells.isLoading));
+        },
         hmrUpdate() {
             const updated = globalThis.__updatedComponents;
             if (!updated || updated.size === 0)
@@ -996,6 +1377,51 @@ export function createFileRouter(routeTree, options = {}) {
         _currentSegments: null,
         _depth: 0,
         _routeDataCache: options.routeDataCache ?? 0,
+        _offlineUI: (options.offline ?? null),
+        _beforeGuards: [],
+        _viewTransitions: options.viewTransitions === true,
+        beforeEach(fn) {
+            this._beforeGuards.push(fn);
+            let active = true;
+            return () => {
+                if (!active)
+                    return;
+                active = false;
+                const guards = this._beforeGuards;
+                const i = guards.indexOf(fn);
+                if (i > -1)
+                    guards.splice(i, 1);
+            };
+        },
+        _runGuards(to) {
+            const from = window.location.pathname;
+            for (const g of this._beforeGuards ?? []) {
+                const d = g(to, from);
+                if (d instanceof Promise) {
+                    return d.then((r) => {
+                        if (r === false || typeof r === 'string')
+                            return r;
+                    });
+                }
+                if (d === false || typeof d === 'string')
+                    return d;
+            }
+        },
+        go(n) {
+            window.history.go(n);
+        },
+        get route() {
+            const m = router._currentMatch;
+            if (!m)
+                return null;
+            const chain = m.matchChain ?? [];
+            const deepest = chain[chain.length - 1];
+            return {
+                pathname: m.pathname || '',
+                params: m.params,
+                pattern: deepest?.fullPath || '/',
+            };
+        },
         start() {
             setCurrentRouter(this);
             if (typeof window !== 'undefined' && 'scrollRestoration' in window.history) {
@@ -1019,6 +1445,41 @@ export function createFileRouter(routeTree, options = {}) {
                 setIsPopStateNavigation(true);
                 router.navigate(window.location.pathname + window.location.search, { replace: true });
             });
+            document.addEventListener('click', (e) => {
+                const target = e.target;
+                if (!target || target.nodeType !== 1)
+                    return;
+                const anchor = target.closest('a[href]');
+                if (!anchor)
+                    return;
+                if (!anchor.hasAttribute('no-reload') && !anchor.hasAttribute('data-no-reload'))
+                    return;
+                if (e.defaultPrevented)
+                    return;
+                const me = e;
+                if (me.metaKey || me.ctrlKey || me.shiftKey || me.altKey || me.button !== 0)
+                    return;
+                if (anchor.target === '_blank')
+                    return;
+                if (anchor.hasAttribute('download'))
+                    return;
+                if (anchor.getAttribute('rel') === 'external')
+                    return;
+                const href = anchor.getAttribute('href');
+                if (!href || href.startsWith('#') || href.startsWith('mailto:') || href.startsWith('tel:') || href.startsWith('javascript:'))
+                    return;
+                try {
+                    const url = new URL(href, window.location.origin);
+                    if (url.origin !== window.location.origin)
+                        return;
+                }
+                catch {
+                    return;
+                }
+                e.preventDefault();
+                e.stopPropagation();
+                router.navigate(href);
+            });
             if (options.prefetch !== false) {
                 document.addEventListener('mouseenter', (e) => {
                     const link = e.target?.nodeType === 1 ? e.target.closest('a[href]') : null;
@@ -1074,148 +1535,225 @@ export function createFileRouter(routeTree, options = {}) {
                 return;
             }
             match.pathname = url.pathname;
-            if (!_isPopStateNavigation) {
-                _scrollPositions.set(window.location.pathname, window.scrollY);
-            }
-            const loadingFn = findLoadingComponent(match.matchChain);
-            router._navToken = (router._navToken || 0) + 1;
-            const navToken = router._navToken;
-            const middlewareFns = Array.isArray(middleware) ? middleware : (middleware ? [middleware] : []);
-            let firstRenderFailed = false;
-            const updateUrl = () => {
-                const fullUrl = url.pathname + url.search;
-                if (!opts.replace) {
-                    window.history.pushState({ path: fullUrl }, '', fullUrl);
-                }
-                else {
-                    window.history.replaceState({ path: fullUrl }, '', fullUrl);
-                }
-                set(_state.path, url.pathname);
-                set(_state.search, url.search);
-            };
-            const renderContent = () => {
-                // Data isolation: route nodes are shared singletons. When the
-                // navigation changes the path a node was last hydrated with, its
-                // cached props must not render on the new path (a params-only or
-                // failed data payload would otherwise merge stale foreign data
-                // into the new page).
-                const propsNode = findPageNode(match);
-                if (propsNode && propsNode._dataPath !== url.pathname) {
-                    propsNode.props = undefined;
-                }
-                try {
-                    renderFn(router, match, container);
-                }
-                catch (e) {
-                    firstRenderFailed = true;
-                    throw e;
+            const afterGuards = () => {
+                if (!_isPopStateNavigation) {
+                    _scrollPositions.set(window.location.pathname, window.scrollY);
                 }
-                router._currentMatch = match;
-                handleScroll(url.pathname, opts.replace);
-            };
-            const doRender = () => {
-                updateUrl();
-                renderContent();
-            };
-            const fetchData = () => {
-                if (firstRenderFailed)
-                    return;
-                if (!shouldFetchData(router, match))
-                    return;
-                getRouteData(url.pathname + url.search, 'nav' + navToken).then(async (data) => {
-                    if (navToken !== router._navToken)
-                        return;
-                    if (!data)
+                const swapView = (fn) => {
+                    const d = document;
+                    if (router._viewTransitions && typeof d.startViewTransition === 'function')
+                        d.startViewTransition(fn);
+                    else
+                        fn();
+                };
+                const loadingFn = findLoadingComponent(match.matchChain);
+                router._navToken = (router._navToken || 0) + 1;
+                navDebug('navigate', url.pathname, 'token=' + router._navToken, 'pendingChunks', hasPendingChunks(match.matchChain));
+                const navToken = router._navToken;
+                loadingStart();
+                const middlewareFns = Array.isArray(middleware) ? middleware : (middleware ? [middleware] : []);
+                let firstRenderFailed = false;
+                const updateUrl = () => {
+                    const fullUrl = url.pathname + url.search;
+                    if (!opts.replace) {
+                        window.history.pushState({ path: fullUrl }, '', fullUrl);
+                    }
+                    else {
+                        window.history.replaceState({ path: fullUrl }, '', fullUrl);
+                    }
+                    set(_state.path, url.pathname);
+                    set(_state.search, url.search.startsWith('?') ? url.search.slice(1) : url.search);
+                };
+                const renderContent = () => {
+                    const propsNode = findPageNode(match);
+                    if (propsNode && propsNode._dataPath !== url.pathname) {
+                        propsNode.props = undefined;
+                    }
+                    try {
+                        container.__veskMountToken = navToken;
+                        renderFn(router, match, container, navToken);
+                    }
+                    catch (e) {
+                        firstRenderFailed = true;
+                        throw e;
+                    }
+                    router._currentMatch = match;
+                    clearOfflineFlag(router, container);
+                    handleScroll(url.pathname, opts.replace);
+                };
+                const doRender = () => {
+                    navDebug('doRender', url.pathname, 'token=' + navToken);
+                    updateUrl();
+                    swapView(() => renderContent());
+                    scrollToHash();
+                    navDebug('painted', url.pathname);
+                };
+                const fetchData = () => {
+                    if (firstRenderFailed)
                         return;
-                    if (data.redirect) {
-                        router.navigate(data.redirect, { replace: true });
+                    navDebug('fetchData?', url.pathname, String(shouldFetchData(router, match)));
+                    if (!shouldFetchData(router, match)) {
+                        loadingFinish();
+                        scrollToHash();
                         return;
                     }
-                    if (!hasRealPageData(data))
-                        return;
-                    const pending = hasPendingChunks(match.matchChain);
-                    if (pending.length > 0) {
-                        await loadChunksQuietly(pending);
+                    getRouteData(url.pathname + url.search, 'nav' + navToken).then(async (data) => {
+                        navDebug('data arrived', url.pathname, 'token=' + navToken, 'current=' + router._navToken, 'realProps', JSON.stringify(data && hasRealPageData(data)));
                         if (navToken !== router._navToken)
                             return;
-                        if (typeof router.__updateComponents === 'function') {
-                            router.__updateComponents(match.matchChain);
+                        if (!data) {
+                            loadingFinish();
+                            return;
                         }
-                    }
-                    await applyRouteData(router, match, data, container, renderFn);
-                });
-            };
-            const pendingChunks = hasPendingChunks(match.matchChain);
-            const doRenderWithChunks = pendingChunks.length > 0
-                ? () => {
-                    updateUrl();
-                    return loadChunksQuietly(pendingChunks).then(() => {
-                        // A newer navigation (e.g. popstate back while the chunk
-                        // was still loading) may have superseded this one; don't
-                        // paint the stale route over the current URL.
-                        if (navToken !== router._navToken)
+                        if (data.redirect) {
+                            loadingFinish();
+                            router.navigate(data.redirect, { replace: true });
                             return;
+                        }
+                        if (!hasRealPageData(data)) {
+                            loadingFinish();
+                            return;
+                        }
+                        const pending = hasPendingChunks(match.matchChain);
+                        if (pending.length > 0) {
+                            await loadChunksQuietly(pending);
+                            if (navToken !== router._navToken)
+                                return;
+                            if (typeof router.__updateComponents === 'function') {
+                                router.__updateComponents(match.matchChain);
+                            }
+                        }
+                        await swapView(() => applyRouteData(router, match, data, container, renderFn));
+                        scrollToHash();
+                        loadingFinish({ error: !!data.error });
+                    }).catch(() => loadingFinish({ error: true }));
+                };
+                const pendingChunks = hasPendingChunks(match.matchChain);
+                const handleNavFailure = (err) => {
+                    navDebug('handleNavFailure', String(err?.message || err).slice(0, 80));
+                    if (navToken !== router._navToken)
+                        return;
+                    loadingFinish({ error: true });
+                    looksOffline().then((offline) => {
+                        navDebug('handleNavFailure verdict', offline ? 'offline' : 'online');
+                        if (offline)
+                            return void renderOfflinePage(router, match, container);
+                        return void renderErrorPage(router, match, container, err);
+                    }).catch(() => { });
+                };
+                const doRenderWithChunks = pendingChunks.length > 0
+                    ? () => {
+                        updateUrl();
+                        return loadChunksQuietly(pendingChunks).then(() => {
+                            if (navToken !== router._navToken)
+                                return;
+                            if (typeof router.__updateComponents === 'function') {
+                                router.__updateComponents(match.matchChain);
+                            }
+                            try {
+                                renderContent();
+                                loadingFinish();
+                            }
+                            catch (e) {
+                                handleNavFailure(e);
+                            }
+                        }, (e) => {
+                            handleNavFailure(e);
+                        });
+                    }
+                    : (() => {
                         if (typeof router.__updateComponents === 'function') {
                             router.__updateComponents(match.matchChain);
                         }
-                        renderContent();
+                        doRender();
                     });
-                }
-                : (() => { doRender(); });
-            async function runMwChain(index) {
-                if (index >= middlewareFns.length) {
-                    await doRenderWithChunks();
-                    return;
-                }
-                const fn = middlewareFns[index];
-                const ctx = { url: url.pathname, params: match.params, router, locals: {} };
-                async function next(rewrite) {
-                    if (rewrite) {
-                        match.pathname = rewrite;
-                        url.pathname = rewrite;
-                    }
-                    return runMwChain(index + 1);
-                }
-                try {
-                    const result = await fn(ctx, next);
-                    if (result && result.redirect) {
-                        router.navigate(result.redirect, { replace: true });
+                async function runMwChain(index) {
+                    if (index >= middlewareFns.length) {
+                        await doRenderWithChunks();
                         return;
                     }
-                }
-                catch (e) {
-                    if (e && e.name === 'Redirect') {
-                        router.navigate(e.url, { replace: true });
-                        return;
+                    const fn = middlewareFns[index];
+                    const ctx = { url: url.pathname, params: match.params, router, locals: {} };
+                    async function next(rewrite) {
+                        if (rewrite) {
+                            match.pathname = rewrite;
+                            url.pathname = rewrite;
+                        }
+                        return runMwChain(index + 1);
                     }
-                }
-            }
-            if (middlewareFns.length > 0 || loadingFn) {
-                if (loadingFn) {
-                    showLoadingInContainer(container, loadingFn, match.params);
-                }
-                Promise.resolve().then(() => {
                     try {
-                        if (middlewareFns.length > 0) {
-                            runMwChain(0);
+                        const result = await fn(ctx, next);
+                        if (result && result.redirect) {
+                            router.navigate(result.redirect, { replace: true });
+                            return;
                         }
-                        else {
-                            doRenderWithChunks();
+                    }
+                    catch (e) {
+                        if (e && e.name === 'Redirect') {
+                            router.navigate(e.url, { replace: true });
+                            return;
                         }
                     }
+                }
+                if (middlewareFns.length > 0 || loadingFn) {
+                    if (loadingFn) {
+                        showLoadingInContainer(container, loadingFn, match.params);
+                    }
+                    Promise.resolve().then(() => {
+                        try {
+                            if (middlewareFns.length > 0) {
+                                runMwChain(0);
+                            }
+                            else {
+                                doRenderWithChunks();
+                            }
+                        }
+                        finally {
+                            fetchData();
+                        }
+                    });
+                }
+                else {
+                    try {
+                        doRenderWithChunks();
+                    }
                     finally {
                         fetchData();
                     }
+                }
+            };
+            // Navigation guards — sync fast path for sync guard functions.
+            const guardResult = router._runGuards(url.pathname);
+            if (guardResult instanceof Promise) {
+                return guardResult.then((decision) => {
+                    if (decision === false)
+                        return;
+                    if (typeof decision === 'string' && decision !== url.pathname && (router._guardDepth || 0) < 5) {
+                        router._guardDepth = (router._guardDepth || 0) + 1;
+                        try {
+                            router.navigate(decision, { replace: true });
+                        }
+                        finally {
+                            router._guardDepth = 0;
+                        }
+                        return;
+                    }
+                    afterGuards();
                 });
             }
-            else {
+            if (guardResult === false)
+                return;
+            if (typeof guardResult === 'string' && guardResult !== url.pathname && (router._guardDepth || 0) < 5) {
+                router._guardDepth = (router._guardDepth || 0) + 1;
                 try {
-                    doRenderWithChunks();
+                    router.navigate(guardResult, { replace: true });
                 }
                 finally {
-                    fetchData();
+                    router._guardDepth = 0;
                 }
+                return;
             }
+            afterGuards();
         },
         prefetch(path) {
             const url = new URL(path, window.location.origin);
@@ -1237,6 +1775,10 @@ export function createFileRouter(routeTree, options = {}) {
         get currentPath() {
             return get(_state.path);
         },
+        get isLoading() {
+            const cells = getLoadingState();
+            return Boolean(get(cells.isLoading));
+        },
         hmrUpdate() {
             const updated = globalThis.__updatedComponents;
             if (!updated || updated.size === 0)
@@ -1245,43 +1787,15 @@ export function createFileRouter(routeTree, options = {}) {
             if (typeof router.__updateComponents === 'function') {
                 router.__updateComponents(router.routeTree);
             }
-            const instances = router.__componentInstances;
-            if (instances && instances.size > 0) {
-                let didUpdate = false;
-                for (const [name, nameInstances] of instances) {
-                    if (updated.has(name)) {
-                        for (const inst of nameInstances) {
-                            try {
-                                const isPage = inst.type === 'page';
-                                const newFn = isPage ? inst.node.page : inst.node.layout;
-                                if (!newFn)
-                                    continue;
-                                const walker = createHydrateWalker(document.createDocumentFragment(), []);
-                                let newDom;
-                                root(() => {
-                                    newDom = newFn(inst.props, new Map(), walker);
-                                });
-                                if (newDom && newDom.nodeType === 1 && inst.root && inst.root.parentNode) {
-                                    inst.root.parentNode.replaceChild(newDom, inst.root);
-                                    inst.root = newDom;
-                                    didUpdate = true;
-                                }
-                            }
-                            catch (e) {
-                                console.error('HMR update error:', e);
-                            }
-                        }
-                    }
-                }
-                if (!didUpdate) {
-                    const path = window.location.pathname + window.location.search;
-                    router.navigate(path, { replace: true });
+            const path = window.location.pathname + window.location.search;
+            const match = matchRoute(router.routeTree, path);
+            if (match) {
+                match.pathname = path;
+                const result = renderMatch(router, match, container);
+                if (result && typeof result.then === 'function') {
+                    result.catch((e) => console.error('HMR renderMatch error:', e));
                 }
             }
-            else {
-                const path = window.location.pathname + window.location.search;
-                router.navigate(path, { replace: true });
-            }
         },
     };
     return router;
@@ -1306,6 +1820,8 @@ export function buildRouteTree(definitions) {
             loading: def.loading || null,
             error: def.error || null,
             notFound: def.notFound || null,
+            offline: def.offline ?? null,
+            network: def.network ?? null,
             children: (def.children || []).map(c => {
                 const cParts = (c.path || '').split('/').filter(Boolean);
                 return {
@@ -1318,11 +1834,11 @@ export function buildRouteTree(definitions) {
                     loading: null,
                     error: null,
                     notFound: null,
-                    segmentCount: Math.max(1, cParts.length),
+                    segmentCount: cParts.length || 1,
                     children: [],
                 };
             }),
-            segmentCount: Math.max(1, parts.length),
+            segmentCount: parts.length,
         };
         tree.push(node);
     }