@nuraly/lumenjs 0.1.3 → 0.2.0

package/dist/runtime/router-data.js

@@ -1,5 +1,65 @@
 import { getI18nConfig, getLocale } from './i18n.js';
+const PREFETCH_TTL = 30_000; // 30 seconds
+const MAX_PREFETCH_CACHE_SIZE = 50;
+const prefetchCache = new Map();
+const inflightRequests = new Map();
+// Periodic sweep of expired prefetch entries (every 60s)
+if (typeof setInterval !== 'undefined') {
+    setInterval(() => {
+        const now = Date.now();
+        for (const [key, entry] of prefetchCache) {
+            if (now - entry.timestamp > PREFETCH_TTL)
+                prefetchCache.delete(key);
+        }
+    }, 60_000);
+}
+export function getCachedLoaderData(key) {
+    const entry = prefetchCache.get(key);
+    if (!entry)
+        return undefined;
+    if (Date.now() - entry.timestamp > PREFETCH_TTL) {
+        prefetchCache.delete(key);
+        return undefined;
+    }
+    return entry.data;
+}
+function setCachedLoaderData(key, data) {
+    // Evict oldest entry if cache is full
+    if (prefetchCache.size >= MAX_PREFETCH_CACHE_SIZE) {
+        const firstKey = prefetchCache.keys().next().value;
+        if (firstKey)
+            prefetchCache.delete(firstKey);
+    }
+    prefetchCache.set(key, { data, timestamp: Date.now() });
+}
+export async function prefetchLoaderData(pathname, params) {
+    const cacheKey = `page:${pathname}`;
+    const cached = getCachedLoaderData(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    const data = await fetchLoaderDataRaw(pathname, params);
+    setCachedLoaderData(cacheKey, data);
+    return data;
+}
+export async function prefetchLayoutLoaderData(dir) {
+    const cacheKey = `layout:${dir}`;
+    const cached = getCachedLoaderData(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    const data = await fetchLayoutLoaderDataRaw(dir);
+    setCachedLoaderData(cacheKey, data);
+    return data;
+}
 export async function fetchLoaderData(pathname, params) {
+    const cacheKey = `page:${pathname}`;
+    const cached = getCachedLoaderData(cacheKey);
+    if (cached !== undefined) {
+        prefetchCache.delete(cacheKey);
+        return cached;
+    }
+    return fetchLoaderDataRaw(pathname, params);
+}
+async function fetchLoaderDataRaw(pathname, params) {
     const url = new URL(`/__nk_loader${pathname}`, location.origin);
     if (Object.keys(params).length > 0) {
         url.searchParams.set('__params', JSON.stringify(params));
@@ -8,30 +68,51 @@ export async function fetchLoaderData(pathname, params) {
     if (config) {
         url.searchParams.set('__locale', getLocale());
     }
-    const res = await fetch(url.toString());
-    if (!res.ok) {
-        throw new Error(`Loader returned ${res.status}`);
-    }
-    const data = await res.json();
-    if (data?.__nk_no_loader)
-        return undefined;
-    return data;
+    const key = url.toString();
+    const inflight = inflightRequests.get(key);
+    if (inflight)
+        return inflight;
+    const promise = fetch(key)
+        .then(async (res) => {
+        if (!res.ok)
+            throw new Error(`Loader returned ${res.status}`);
+        const data = await res.json();
+        return data?.__nk_no_loader ? undefined : data;
+    })
+        .finally(() => inflightRequests.delete(key));
+    inflightRequests.set(key, promise);
+    return promise;
 }
 export async function fetchLayoutLoaderData(dir) {
+    const cacheKey = `layout:${dir}`;
+    const cached = getCachedLoaderData(cacheKey);
+    if (cached !== undefined) {
+        prefetchCache.delete(cacheKey);
+        return cached;
+    }
+    return fetchLayoutLoaderDataRaw(dir);
+}
+async function fetchLayoutLoaderDataRaw(dir) {
     const url = new URL(`/__nk_loader/__layout/`, location.origin);
     url.searchParams.set('__dir', dir);
     const config = getI18nConfig();
     if (config) {
         url.searchParams.set('__locale', getLocale());
     }
-    const res = await fetch(url.toString());
-    if (!res.ok) {
-        throw new Error(`Layout loader returned ${res.status}`);
-    }
-    const data = await res.json();
-    if (data?.__nk_no_loader)
-        return undefined;
-    return data;
+    const key = url.toString();
+    const inflight = inflightRequests.get(key);
+    if (inflight)
+        return inflight;
+    const promise = fetch(key)
+        .then(async (res) => {
+        if (!res.ok)
+            throw new Error(`Layout loader returned ${res.status}`);
+        const data = await res.json();
+        return data?.__nk_no_loader ? undefined : data;
+    })
+        .finally(() => inflightRequests.delete(key));
+    inflightRequests.set(key, promise);
+    return promise;
 }
 export function connectSubscribe(pathname, params) {
     const url = new URL(`/__nk_subscribe${pathname}`, location.origin);
@@ -53,13 +134,17 @@ export function connectLayoutSubscribe(dir) {
     }
     return new EventSource(url.toString());
 }
+function escapeHtml(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
 export function render404(pathname) {
+    const safe = escapeHtml(pathname);
     return `<div style="display:flex;align-items:center;justify-content:center;min-height:80vh;font-family:system-ui,-apple-system,sans-serif;padding:2rem">
   <div style="text-align:center;max-width:400px">
     <div style="font-size:5rem;font-weight:200;letter-spacing:-2px;color:#cbd5e1;line-height:1">404</div>
     <div style="width:32px;height:2px;background:#e2e8f0;border-radius:1px;margin:1.25rem auto"></div>
     <h1 style="font-size:1rem;font-weight:500;color:#334155;margin:1.25rem 0 .5rem">Page not found</h1>
-    <p style="color:#94a3b8;font-size:.8125rem;line-height:1.5;margin:0 0 2rem"><code style="background:#f8fafc;padding:.125rem .375rem;border-radius:3px;font-size:.75rem;color:#64748b;border:1px solid #f1f5f9">${pathname}</code> doesn't exist</p>
+    <p style="color:#94a3b8;font-size:.8125rem;line-height:1.5;margin:0 0 2rem"><code style="background:#f8fafc;padding:.125rem .375rem;border-radius:3px;font-size:.75rem;color:#64748b;border:1px solid #f1f5f9">${safe}</code> doesn't exist</p>
     <a href="/" style="display:inline-flex;align-items:center;gap:.375rem;padding:.4375rem 1rem;background:#f8fafc;color:#475569;border:1px solid #e2e8f0;border-radius:6px;font-size:.8125rem;font-weight:400;text-decoration:none;transition:all .15s">
       <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m15 18-6-6 6-6"/></svg>
       Back to home

package/dist/runtime/router-hydration.js

@@ -15,9 +15,26 @@ export async function hydrateInitialRoute(routes, outlet, matchRoute, onHydrated
         catch { /* ignore */ }
         i18nScript.remove();
     }
-    // Strip locale prefix for route matching (routes are locale-agnostic)
+    // Read auth data and init before route matching
+    const authScript = document.getElementById('__nk_auth__');
+    if (authScript) {
+        try {
+            const { initAuth } = await import('@lumenjs/auth');
+            initAuth(JSON.parse(authScript.textContent || ''));
+        }
+        catch { }
+        authScript.remove();
+    }
+    // Strip Vite base path and locale prefix for route matching
+    let matchPath = location.pathname;
+    const base = import.meta.env?.BASE_URL;
+    if (base && base !== '/' && matchPath.startsWith(base)) {
+        matchPath = '/' + matchPath.slice(base.length);
+    }
     const config = getI18nConfig();
-    const matchPath = config ? stripLocalePrefix(location.pathname) : location.pathname;
+    if (config) {
+        matchPath = stripLocalePrefix(matchPath);
+    }
     const match = matchRoute(matchPath);
     if (!match)
         return;
@@ -45,6 +62,19 @@ export async function hydrateInitialRoute(routes, outlet, matchRoute, onHydrated
             }
         }
     }
+    /** Spread loader data as individual properties on an element. */
+    const BLOCKED = new Set(['__proto__', 'constructor', 'prototype',
+        'innerHTML', 'outerHTML', 'textContent',
+        'render', 'connectedCallback', 'disconnectedCallback']);
+    function spreadData(el, data) {
+        if (data && typeof data === 'object') {
+            for (const [key, value] of Object.entries(data)) {
+                if (!BLOCKED.has(key)) {
+                    el[key] = value;
+                }
+            }
+        }
+    }
     // Load each layout module and immediately set loaderData on the
     // existing DOM element BEFORE the next await yields to microtasks.
     for (const layout of layouts) {
@@ -53,6 +83,7 @@ export async function hydrateInitialRoute(routes, outlet, matchRoute, onHydrated
             const data = layoutDataMap.get(layout.loaderPath ?? '');
             if (data !== undefined) {
                 existingLayout.loaderData = data;
+                spreadData(existingLayout, data);
             }
         }
         if (layout.load && !customElements.get(layout.tagName)) {
@@ -66,6 +97,7 @@ export async function hydrateInitialRoute(routes, outlet, matchRoute, onHydrated
     const existingPage = outlet?.querySelector(match.route.tagName);
     if (existingPage && pageData !== undefined) {
         existingPage.loaderData = pageData;
+        spreadData(existingPage, pageData);
     }
     // Load the page module (registers element, triggers hydration microtask)
     if (match.route.load && !customElements.get(match.route.tagName)) {

package/dist/runtime/router.d.ts

@@ -10,6 +10,8 @@ export interface Route {
     tagName: string;
     hasLoader?: boolean;
     hasSubscribe?: boolean;
+    hasSocket?: boolean;
+    hasMeta?: boolean;
     load?: () => Promise<any>;
     layouts?: LayoutInfo[];
     pattern?: RegExp;
@@ -26,19 +28,34 @@ export declare class NkRouter {
     private currentTag;
     private currentLayoutTags;
     private subscriptions;
+    private _sockets;
+    private siteTitle;
     params: Record<string, string>;
     constructor(routes: Route[], outlet: HTMLElement, hydrate?: boolean);
     private compilePattern;
     private cleanupSubscriptions;
-    navigate(pathname: string, pushState?: boolean): Promise<void>;
+    navigate(fullPath: string, pushState?: boolean): Promise<void>;
+    private setupSubscriptions;
     private matchRoute;
     private renderRoute;
     private buildLayoutTree;
+    /** Spread loader data as individual properties on an element. */
+    private spreadData;
     private createPageElement;
     private findPageElement;
+    /**
+     * Resolve the page title from the route's meta export and update
+     * document.title, the aria-live announcer, and focus.
+     */
+    private updatePageMeta;
     private handleLinkClick;
-    /** Strip locale prefix from a path for internal route matching. */
+    prefetch(fullPath: string): Promise<void>;
+    /** Strip base and locale prefix from a path for internal route matching. */
     private stripLocale;
     /** Prepend locale prefix for browser-facing URLs. */
     private withLocale;
 }
+/** Navigate via the client-side router. Falls back to full reload for unknown routes. */
+export declare function navigate(href: string): void;
+/** Programmatically prefetch a route's JS chunks and loader data. */
+export declare function prefetch(href: string): void;

package/dist/runtime/router.js

@@ -1,6 +1,6 @@
-import { fetchLoaderData, fetchLayoutLoaderData, connectSubscribe, connectLayoutSubscribe, render404 } from './router-data.js';
+import { fetchLoaderData, fetchLayoutLoaderData, prefetchLoaderData, prefetchLayoutLoaderData, connectSubscribe, connectLayoutSubscribe, render404 } from './router-data.js';
 import { hydrateInitialRoute } from './router-hydration.js';
-import { getI18nConfig, getLocale, stripLocalePrefix, buildLocalePath } from './i18n.js';
+import { getI18nConfig, getLocale, initI18n, stripLocalePrefix, buildLocalePath } from './i18n.js';
 /**
  * Simple client-side router for LumenJS pages.
  * Handles popstate and link clicks for SPA navigation.
@@ -13,27 +13,79 @@ export class NkRouter {
         this.currentTag = null;
         this.currentLayoutTags = [];
         this.subscriptions = [];
+        this._sockets = new Map();
         this.params = {};
         this.outlet = outlet;
+        this.siteTitle = document.title || 'LumenJS App';
         this.routes = routes.map(r => ({
             ...r,
             ...this.compilePattern(r.path),
         }));
+        // Initialize i18n from inlined data before any rendering
+        const i18nScript = document.getElementById('__nk_i18n__');
+        if (i18nScript) {
+            try {
+                const i18nData = JSON.parse(i18nScript.textContent || '');
+                initI18n(i18nData.config, i18nData.locale, i18nData.translations);
+            }
+            catch { /* ignore */ }
+            if (!hydrate)
+                i18nScript.remove();
+        }
         window.addEventListener('popstate', () => {
             const path = this.stripLocale(location.pathname);
             this.navigate(path, false);
         });
+        // Re-run loader when page is restored from bfcache (back/forward on mobile Safari, etc.)
+        window.addEventListener('pageshow', (e) => {
+            if (e.persisted) {
+                const path = this.stripLocale(location.pathname);
+                this.navigate(path, false);
+            }
+        });
         document.addEventListener('click', (e) => this.handleLinkClick(e));
+        window.__nk_navigate = (href) => {
+            const path = this.stripLocale(href);
+            if (this.matchRoute(path.split('?')[0])) {
+                this.navigate(path);
+            }
+            else {
+                window.location.href = href;
+            }
+        };
+        window.__nk_prefetch = (href) => {
+            const path = this.stripLocale(href);
+            this.prefetch(path);
+        };
         if (hydrate) {
             hydrateInitialRoute(this.routes, this.outlet, (p) => this.matchRoute(p), (tag, layoutTags, params) => {
                 this.currentTag = tag;
                 this.currentLayoutTags = layoutTags;
                 this.params = params;
             });
+            // Wire up SSE subscriptions after hydration
+            const path = this.stripLocale(location.pathname);
+            this.setupSubscriptions(path);
         }
         else {
-            const path = this.stripLocale(location.pathname);
-            this.navigate(path, false);
+            // Initialize auth from inlined data before navigating (CSR path)
+            const authScript = document.getElementById('__nk_auth__');
+            if (authScript) {
+                import('@lumenjs/auth').then(({ initAuth }) => {
+                    try {
+                        initAuth(JSON.parse(authScript.textContent || ''));
+                    }
+                    catch { }
+                    authScript.remove();
+                }).catch(() => { }).finally(() => {
+                    const path = this.stripLocale(location.pathname);
+                    this.navigate(path, false);
+                });
+            }
+            else {
+                const path = this.stripLocale(location.pathname);
+                this.navigate(path, false);
+            }
         }
     }
     compilePattern(path) {
@@ -49,9 +101,14 @@ export class NkRouter {
             es.close();
         }
         this.subscriptions = [];
+        // Disconnect any active socket.io connections
+        for (const [, sock] of this._sockets)
+            sock.disconnect();
+        this._sockets.clear();
     }
-    async navigate(pathname, pushState = true) {
+    async navigate(fullPath, pushState = true) {
         this.cleanupSubscriptions();
+        const pathname = fullPath.split('?')[0];
         const match = this.matchRoute(pathname);
         if (!match) {
             if (this.outlet)
@@ -61,51 +118,53 @@ export class NkRouter {
             return;
         }
         if (pushState) {
-            const localePath = this.withLocale(pathname);
+            const localePath = this.withLocale(fullPath);
             history.pushState(null, '', localePath);
             window.scrollTo(0, 0);
         }
         this.params = match.params;
-        // Lazy-load the page component if not yet registered
-        if (match.route.load && !customElements.get(match.route.tagName)) {
-            await match.route.load();
-        }
-        // Load layout components
-        const layouts = match.route.layouts || [];
-        for (const layout of layouts) {
-            if (layout.load && !customElements.get(layout.tagName)) {
-                await layout.load();
-            }
-        }
-        // Fetch loader data for page
-        let loaderData = undefined;
-        if (match.route.hasLoader) {
+        // Auth guard: SPA-navigate unauthenticated users to login page
+        if (match.route.__nk_has_auth) {
             try {
-                loaderData = await fetchLoaderData(pathname, match.params);
-            }
-            catch (err) {
-                console.error('[NkRouter] Loader fetch failed:', err);
-            }
-        }
-        // Fetch loader data for layouts
-        const layoutDataList = [];
-        for (const layout of layouts) {
-            if (layout.hasLoader) {
-                try {
-                    const data = await fetchLayoutLoaderData(layout.loaderPath || '');
-                    layoutDataList.push(data);
-                }
-                catch (err) {
-                    console.error('[NkRouter] Layout loader fetch failed:', err);
-                    layoutDataList.push(undefined);
+                const { isAuthenticated } = await import('@lumenjs/auth');
+                if (!isAuthenticated()) {
+                    const loginPath = '/auth/login';
+                    const loginUrl = `${loginPath}?returnTo=${encodeURIComponent(pathname)}`;
+                    history.pushState(null, '', loginUrl);
+                    this.navigate(loginPath, false);
+                    return;
                 }
             }
-            else {
-                layoutDataList.push(undefined);
-            }
+            catch { }
         }
+        const layouts = match.route.layouts || [];
+        // Load all component JS chunks in parallel
+        await Promise.all([
+            match.route.load && !customElements.get(match.route.tagName) ? match.route.load() : undefined,
+            ...layouts.map(l => l.load && !customElements.get(l.tagName) ? l.load() : undefined),
+        ]);
+        // Fetch all loader data in parallel
+        const loaderPromises = [
+            match.route.hasLoader
+                ? fetchLoaderData(pathname, match.params).catch(err => { console.error('[NkRouter] Loader fetch failed:', err); return undefined; })
+                : Promise.resolve(undefined),
+            ...layouts.map(layout => layout.hasLoader
+                ? fetchLayoutLoaderData(layout.loaderPath || '').catch(err => { console.error('[NkRouter] Layout loader fetch failed:', err); return undefined; })
+                : Promise.resolve(undefined)),
+        ];
+        const [loaderData, ...layoutDataList] = await Promise.all(loaderPromises);
         this.renderRoute(match.route, loaderData, layouts, layoutDataList);
-        // Set up SSE subscriptions for page
+        // Update document.title and announce route change for screen readers
+        this.updatePageMeta(match.route, loaderData);
+        // Set up SSE subscriptions
+        this.setupSubscriptions(pathname);
+    }
+    setupSubscriptions(pathname) {
+        const match = this.matchRoute(pathname);
+        if (!match)
+            return;
+        const layouts = match.route.layouts || [];
+        // Page subscription
         if (match.route.hasSubscribe) {
             const es = connectSubscribe(pathname, match.params);
             es.onmessage = (e) => {
@@ -115,7 +174,43 @@ export class NkRouter {
             };
             this.subscriptions.push(es);
         }
-        // Set up SSE subscriptions for layouts
+        // Page socket (bidirectional via Socket.IO)
+        if (match.route.hasSocket) {
+            import('socket.io-client').then(({ io }) => {
+                const ns = `/nk${pathname === '/' ? '/index' : pathname}`;
+                const query = {};
+                if (Object.keys(match.params).length > 0)
+                    query.__params = JSON.stringify(match.params);
+                try {
+                    const locale = getLocale();
+                    if (locale)
+                        query.__locale = locale;
+                }
+                catch { }
+                const existing = this._sockets.get(pathname);
+                if (existing)
+                    existing.disconnect();
+                const socket = io(ns, { path: '/__nk_socketio/', query });
+                this._sockets.set(pathname, socket);
+                const injectEmit = () => {
+                    const pageEl = this.findPageElement(match.route.tagName);
+                    if (pageEl) {
+                        pageEl.emit = (event, payload) => {
+                            socket.emit(`nk:${event}`, payload);
+                        };
+                    }
+                };
+                injectEmit();
+                socket.on('nk:data', (data) => {
+                    const pageEl = this.findPageElement(match.route.tagName);
+                    if (pageEl) {
+                        pageEl.liveData = data;
+                        injectEmit();
+                    }
+                });
+            }).catch(err => console.error('[NkRouter] Socket connection failed:', err));
+        }
+        // Layout subscriptions
         for (const layout of layouts) {
             if (layout.hasSubscribe) {
                 const es = connectLayoutSubscribe(layout.loaderPath || '');
@@ -177,6 +272,7 @@ export class NkRouter {
                 }
                 if (layoutDataList && layoutDataList[i] !== undefined) {
                     layoutEl.loaderData = layoutDataList[i];
+                    this.spreadData(layoutEl, layoutDataList[i]);
                 }
                 parentEl = layoutEl;
             }
@@ -201,12 +297,14 @@ export class NkRouter {
         const outerLayout = document.createElement(layouts[0].tagName);
         if (layoutDataList[0] !== undefined) {
             outerLayout.loaderData = layoutDataList[0];
+            this.spreadData(outerLayout, layoutDataList[0]);
         }
         let current = outerLayout;
         for (let i = 1; i < layouts.length; i++) {
             const inner = document.createElement(layouts[i].tagName);
             if (layoutDataList[i] !== undefined) {
                 inner.loaderData = layoutDataList[i];
+                this.spreadData(inner, layoutDataList[i]);
             }
             current.appendChild(inner);
             current = inner;
@@ -215,6 +313,19 @@ export class NkRouter {
         current.appendChild(pageEl);
         return outerLayout;
     }
+    /** Spread loader data as individual properties on an element. */
+    spreadData(el, data) {
+        if (data && typeof data === 'object') {
+            const BLOCKED = new Set(['__proto__', 'constructor', 'prototype',
+                'innerHTML', 'outerHTML', 'textContent',
+                'render', 'connectedCallback', 'disconnectedCallback']);
+            for (const [key, value] of Object.entries(data)) {
+                if (!BLOCKED.has(key)) {
+                    el[key] = value;
+                }
+            }
+        }
+    }
     createPageElement(route, loaderData) {
         const el = document.createElement(route.tagName);
         for (const [key, value] of Object.entries(this.params)) {
@@ -222,6 +333,7 @@ export class NkRouter {
         }
         if (loaderData !== undefined) {
             el.loaderData = loaderData;
+            this.spreadData(el, loaderData);
         }
         return el;
     }
@@ -230,6 +342,49 @@ export class NkRouter {
             return null;
         return this.outlet.querySelector(tagName) ?? this.outlet.querySelector(`${tagName}:last-child`);
     }
+    /**
+     * Resolve the page title from the route's meta export and update
+     * document.title, the aria-live announcer, and focus.
+     */
+    async updatePageMeta(route, loaderData) {
+        let pageTitle;
+        if (route.hasMeta && route.load) {
+            try {
+                const mod = await route.load();
+                if (mod) {
+                    let meta;
+                    if (typeof mod.meta === 'function') {
+                        meta = mod.meta({ data: loaderData, params: this.params });
+                    }
+                    else if (mod.meta && typeof mod.meta === 'object') {
+                        meta = mod.meta;
+                    }
+                    if (meta?.title) {
+                        pageTitle = `${meta.title} | ${this.siteTitle}`;
+                    }
+                }
+            }
+            catch { /* fall back to site title */ }
+        }
+        const title = pageTitle || this.siteTitle;
+        document.title = title;
+        // Let layout components adjust title (e.g. prepend badge counts)
+        window.dispatchEvent(new CustomEvent('nk-title-updated'));
+        // Announce route change to screen readers
+        const announcer = document.getElementById('nk-route-announcer');
+        if (announcer) {
+            announcer.textContent = '';
+            // Use a microtask delay so aria-live picks up the change
+            requestAnimationFrame(() => { announcer.textContent = title; });
+        }
+        // Move focus to the router outlet for keyboard/screen reader users
+        if (this.outlet) {
+            if (!this.outlet.hasAttribute('tabindex')) {
+                this.outlet.setAttribute('tabindex', '-1');
+            }
+            this.outlet.focus({ preventScroll: true });
+        }
+    }
     handleLinkClick(event) {
         const path = event.composedPath();
         const anchor = path.find((el) => el instanceof HTMLElement && el.tagName === 'A');
@@ -238,11 +393,34 @@ export class NkRouter {
         const href = anchor.getAttribute('href');
         if (!href || href.startsWith('http') || href.startsWith('#') || anchor.hasAttribute('target'))
             return;
+        // Allow modifier-key clicks to behave normally (Ctrl+Click = new tab, etc.)
+        if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+            return;
         event.preventDefault();
         this.navigate(this.stripLocale(href));
     }
-    /** Strip locale prefix from a path for internal route matching. */
+    async prefetch(fullPath) {
+        const pathname = fullPath.split('?')[0];
+        const match = this.matchRoute(pathname);
+        if (!match)
+            return;
+        const layouts = match.route.layouts || [];
+        await Promise.all([
+            // Preload component JS chunks
+            match.route.load && !customElements.get(match.route.tagName) ? match.route.load() : undefined,
+            ...layouts.map(l => l.load && !customElements.get(l.tagName) ? l.load() : undefined),
+            // Prefetch loader data (cached)
+            match.route.hasLoader ? prefetchLoaderData(pathname, match.params).catch(() => { }) : undefined,
+            ...layouts.map(l => l.hasLoader ? prefetchLayoutLoaderData(l.loaderPath || '').catch(() => { }) : undefined),
+        ]);
+    }
+    /** Strip base and locale prefix from a path for internal route matching. */
     stripLocale(path) {
+        // Strip Vite base path (e.g. /__app_dev/{id}/) before route matching
+        const base = import.meta.env?.BASE_URL;
+        if (base && base !== '/' && path.startsWith(base)) {
+            path = '/' + path.slice(base.length);
+        }
         const config = getI18nConfig();
         return config ? stripLocalePrefix(path) : path;
     }
@@ -252,3 +430,19 @@ export class NkRouter {
         return config ? buildLocalePath(getLocale(), path) : path;
     }
 }
+/** Navigate via the client-side router. Falls back to full reload for unknown routes. */
+export function navigate(href) {
+    const nav = window.__nk_navigate;
+    if (nav) {
+        nav(href);
+    }
+    else {
+        window.location.href = href;
+    }
+}
+/** Programmatically prefetch a route's JS chunks and loader data. */
+export function prefetch(href) {
+    const pf = window.__nk_prefetch;
+    if (pf)
+        pf(href);
+}

package/dist/runtime/socket-client.d.ts

@@ -0,0 +1,2 @@
+export declare function connectSocket(routePath: string, params: Record<string, string>): Promise<any>;
+export declare function disconnectAllSockets(): void;