@nuraly/lumenjs 0.1.2 → 0.1.4

package/dist/runtime/error-boundary.d.ts

@@ -0,0 +1,23 @@
+/**
+ * <nk-error-boundary> — Client-side error boundary for Lit/web component pages.
+ *
+ * Wraps page content via <slot>. If a child throws during render or in an
+ * event handler, catches the error and displays a fallback UI.
+ *
+ * Usage:
+ *   <nk-error-boundary>
+ *     <my-page></my-page>
+ *   </nk-error-boundary>
+ *
+ * Attributes:
+ *   fallback-message — Custom message shown on error (default: "Something went wrong")
+ */
+declare class NkErrorBoundary extends HTMLElement {
+    private hasError;
+    private caughtError;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private handleError;
+    private showFallback;
+    private recover;
+}

package/dist/runtime/error-boundary.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * <nk-error-boundary> — Client-side error boundary for Lit/web component pages.
+ *
+ * Wraps page content via <slot>. If a child throws during render or in an
+ * event handler, catches the error and displays a fallback UI.
+ *
+ * Usage:
+ *   <nk-error-boundary>
+ *     <my-page></my-page>
+ *   </nk-error-boundary>
+ *
+ * Attributes:
+ *   fallback-message — Custom message shown on error (default: "Something went wrong")
+ */
+class NkErrorBoundary extends HTMLElement {
+    constructor() {
+        super(...arguments);
+        this.hasError = false;
+        this.caughtError = null;
+        this.handleError = (event) => {
+            event.stopPropagation();
+            this.showFallback(event.error || new Error(event.message));
+        };
+    }
+    connectedCallback() {
+        // Listen for unhandled errors from slotted children
+        this.addEventListener('error', this.handleError);
+        // Create a slot for normal content
+        if (!this.shadowRoot) {
+            const shadow = this.attachShadow({ mode: 'open' });
+            shadow.innerHTML = `
+        <style>
+          :host { display: contents; }
+          .nk-error-fallback {
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            padding: 2rem;
+            min-height: 200px;
+            font-family: system-ui, -apple-system, sans-serif;
+            color: #dc2626;
+            text-align: center;
+          }
+          .nk-error-fallback h2 {
+            margin: 0 0 0.5rem;
+            font-size: 1.25rem;
+            font-weight: 600;
+          }
+          .nk-error-fallback p {
+            margin: 0 0 1rem;
+            color: #6b7280;
+            font-size: 0.875rem;
+          }
+          .nk-error-fallback button {
+            padding: 0.5rem 1rem;
+            border: 1px solid #d1d5db;
+            border-radius: 0.375rem;
+            background: white;
+            color: #374151;
+            font-size: 0.875rem;
+            cursor: pointer;
+          }
+          .nk-error-fallback button:hover {
+            background: #f9fafb;
+          }
+          .nk-error-hidden { display: none; }
+        </style>
+        <slot></slot>
+        <div class="nk-error-fallback nk-error-hidden">
+          <h2></h2>
+          <p></p>
+          <button>Try again</button>
+        </div>
+      `;
+            const button = shadow.querySelector('button');
+            button.addEventListener('click', () => this.recover());
+        }
+    }
+    disconnectedCallback() {
+        this.removeEventListener('error', this.handleError);
+    }
+    showFallback(error) {
+        this.hasError = true;
+        this.caughtError = error;
+        const shadow = this.shadowRoot;
+        if (!shadow)
+            return;
+        const slot = shadow.querySelector('slot');
+        const fallback = shadow.querySelector('.nk-error-fallback');
+        const message = this.getAttribute('fallback-message') || 'Something went wrong';
+        slot.classList.add('nk-error-hidden');
+        fallback.classList.remove('nk-error-hidden');
+        fallback.querySelector('h2').textContent = message;
+        fallback.querySelector('p').textContent = error.message || 'An unexpected error occurred.';
+        // Dispatch custom event for external error tracking
+        this.dispatchEvent(new CustomEvent('nk-error', {
+            bubbles: true,
+            composed: true,
+            detail: { error },
+        }));
+    }
+    recover() {
+        this.hasError = false;
+        this.caughtError = null;
+        const shadow = this.shadowRoot;
+        if (!shadow)
+            return;
+        const slot = shadow.querySelector('slot');
+        const fallback = shadow.querySelector('.nk-error-fallback');
+        fallback.classList.add('nk-error-hidden');
+        slot.classList.remove('nk-error-hidden');
+        // Re-trigger the current route to re-render
+        window.dispatchEvent(new PopStateEvent('popstate'));
+    }
+}
+if (!customElements.get('nk-error-boundary')) {
+    customElements.define('nk-error-boundary', NkErrorBoundary);
+}

package/dist/runtime/i18n.d.ts

@@ -1,6 +1,11 @@
 /**
  * LumenJS i18n runtime — provides translation lookup, locale management,
  * and translation loading for both SSR and client-side navigation.
+ *
+ * State is stored on globalThis so that it survives Vite's SSR module
+ * invalidation. During dev SSR, page and layout modules may each get a
+ * separate copy of this module after cache invalidation — globalThis
+ * ensures they all read from the same translation map.
  */
 /**
  * Look up a translation key. Returns the translated string, or the key itself
@@ -31,7 +36,7 @@ export declare function initI18n(config: {
 }, locale: string, trans: Record<string, string>): void;
 /**
  * Load translations for a locale from the server and swap them in.
- * Used during client-side locale switches.
+ * Used during client-side locale switches and HMR updates.
  */
 export declare function loadTranslations(locale: string): Promise<void>;
 /**

package/dist/runtime/i18n.js

@@ -1,31 +1,38 @@
 /**
  * LumenJS i18n runtime — provides translation lookup, locale management,
  * and translation loading for both SSR and client-side navigation.
+ *
+ * State is stored on globalThis so that it survives Vite's SSR module
+ * invalidation. During dev SSR, page and layout modules may each get a
+ * separate copy of this module after cache invalidation — globalThis
+ * ensures they all read from the same translation map.
  */
-let currentLocale = 'en';
-let translations = {};
-let i18nConfig = null;
+const G = globalThis;
+if (!G.__nk_i18n) {
+    G.__nk_i18n = { locale: 'en', translations: {}, config: null };
+}
+const state = G.__nk_i18n;
 /**
  * Look up a translation key. Returns the translated string, or the key itself
  * if no translation is found.
  */
 export function t(key) {
-    return translations[key] ?? key;
+    return state.translations[key] ?? key;
 }
 /** Returns the current locale. */
 export function getLocale() {
-    return currentLocale;
+    return state.locale;
 }
 /** Returns the i18n config, or null if i18n is not enabled. */
 export function getI18nConfig() {
-    return i18nConfig;
+    return state.config;
 }
 /**
  * Switch to a new locale. Navigates to the same pathname under the new
  * locale prefix and sets the `nk-locale` cookie.
  */
 export function setLocale(locale) {
-    if (!i18nConfig || !i18nConfig.locales.includes(locale))
+    if (!state.config || !state.config.locales.includes(locale))
         return;
     document.cookie = `nk-locale=${locale};path=/;max-age=${60 * 60 * 24 * 365};SameSite=Lax`;
     const pathname = stripLocalePrefix(location.pathname);
@@ -37,13 +44,13 @@ export function setLocale(locale) {
  * Called during hydration (from SSR data) or on first load.
  */
 export function initI18n(config, locale, trans) {
-    i18nConfig = config;
-    currentLocale = locale;
-    translations = trans;
+    state.config = config;
+    state.locale = locale;
+    state.translations = trans;
 }
 /**
  * Load translations for a locale from the server and swap them in.
- * Used during client-side locale switches.
+ * Used during client-side locale switches and HMR updates.
  */
 export async function loadTranslations(locale) {
     const res = await fetch(`/__nk_i18n/${locale}.json`);
@@ -51,8 +58,22 @@ export async function loadTranslations(locale) {
         console.error(`[i18n] Failed to load translations for locale "${locale}"`);
         return;
     }
-    translations = await res.json();
-    currentLocale = locale;
+    state.translations = await res.json();
+    state.locale = locale;
+}
+/**
+ * Register the HMR reload handler on the global scope.
+ * The i18n Vite plugin injects an inline script that calls this function
+ * when a locale file changes — ensuring translations are updated in this
+ * module instance (not a duplicate created by Vite's cache-busting).
+ */
+if (typeof window !== 'undefined') {
+    window.__lumenjs_i18n_reload = async (locale) => {
+        if (locale !== state.locale)
+            return false;
+        await loadTranslations(locale);
+        return true;
+    };
 }
 /**
  * Strip the locale prefix from a pathname.
@@ -60,10 +81,10 @@ export async function loadTranslations(locale) {
  *   /about    → /about
  */
 export function stripLocalePrefix(pathname) {
-    if (!i18nConfig)
+    if (!state.config)
         return pathname;
-    for (const loc of i18nConfig.locales) {
-        if (loc === i18nConfig.defaultLocale && !i18nConfig.prefixDefault)
+    for (const loc of state.config.locales) {
+        if (loc === state.config.defaultLocale && !state.config.prefixDefault)
             continue;
         if (pathname === `/${loc}` || pathname.startsWith(`/${loc}/`)) {
             return pathname.slice(loc.length + 1) || '/';
@@ -77,9 +98,9 @@ export function stripLocalePrefix(pathname) {
  *   (en, /about) → /about        (when prefixDefault=false)
  */
 export function buildLocalePath(locale, pathname) {
-    if (!i18nConfig)
+    if (!state.config)
         return pathname;
-    if (locale === i18nConfig.defaultLocale && !i18nConfig.prefixDefault) {
+    if (locale === state.config.defaultLocale && !state.config.prefixDefault) {
         return pathname;
     }
     return `/${locale}${pathname === '/' ? '' : pathname}` || `/${locale}`;
@@ -89,12 +110,12 @@ export function buildLocalePath(locale, pathname) {
  * Returns the locale and the pathname with the prefix stripped.
  */
 export function detectLocaleFromPath(pathname) {
-    if (!i18nConfig)
+    if (!state.config)
         return { locale: 'en', pathname };
-    for (const loc of i18nConfig.locales) {
+    for (const loc of state.config.locales) {
         if (pathname === `/${loc}` || pathname.startsWith(`/${loc}/`)) {
             return { locale: loc, pathname: pathname.slice(loc.length + 1) || '/' };
         }
     }
-    return { locale: i18nConfig.defaultLocale, pathname };
+    return { locale: state.config.defaultLocale, pathname };
 }

package/dist/runtime/router-data.d.ts

@@ -1,3 +1,8 @@
+export declare function getCachedLoaderData(key: string): any | undefined;
+export declare function prefetchLoaderData(pathname: string, params: Record<string, string>): Promise<any>;
+export declare function prefetchLayoutLoaderData(dir: string): Promise<any>;
 export declare function fetchLoaderData(pathname: string, params: Record<string, string>): Promise<any>;
 export declare function fetchLayoutLoaderData(dir: string): Promise<any>;
+export declare function connectSubscribe(pathname: string, params: Record<string, string>): EventSource;
+export declare function connectLayoutSubscribe(dir: string): EventSource;
 export declare function render404(pathname: string): string;

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,38 +68,83 @@ 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 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);
+    if (Object.keys(params).length > 0) {
+        url.searchParams.set('__params', JSON.stringify(params));
     }
-    const data = await res.json();
-    if (data?.__nk_no_loader)
-        return undefined;
-    return data;
+    const config = getI18nConfig();
+    if (config) {
+        url.searchParams.set('__locale', getLocale());
+    }
+    return new EventSource(url.toString());
+}
+export function connectLayoutSubscribe(dir) {
+    const url = new URL('/__nk_subscribe/__layout/', location.origin);
+    url.searchParams.set('__dir', dir);
+    const config = getI18nConfig();
+    if (config) {
+        url.searchParams.set('__locale', getLocale());
+    }
+    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,6 +15,16 @@ export async function hydrateInitialRoute(routes, outlet, matchRoute, onHydrated
         catch { /* ignore */ }
         i18nScript.remove();
     }
+    // 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 locale prefix for route matching (routes are locale-agnostic)
     const config = getI18nConfig();
     const matchPath = config ? stripLocalePrefix(location.pathname) : location.pathname;
@@ -45,6 +55,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 +76,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 +90,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

@@ -1,6 +1,7 @@
 export interface LayoutInfo {
     tagName: string;
     hasLoader?: boolean;
+    hasSubscribe?: boolean;
     load?: () => Promise<any>;
     loaderPath?: string;
 }
@@ -8,6 +9,8 @@ export interface Route {
     path: string;
     tagName: string;
     hasLoader?: boolean;
+    hasSubscribe?: boolean;
+    hasMeta?: boolean;
     load?: () => Promise<any>;
     layouts?: LayoutInfo[];
     pattern?: RegExp;
@@ -23,17 +26,34 @@ export declare class NkRouter {
     private outlet;
     private currentTag;
     private currentLayoutTags;
+    private subscriptions;
+    private siteTitle;
     params: Record<string, string>;
     constructor(routes: Route[], outlet: HTMLElement, hydrate?: boolean);
     private compilePattern;
-    navigate(pathname: string, pushState?: boolean): Promise<void>;
+    private cleanupSubscriptions;
+    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;
+    prefetch(fullPath: string): Promise<void>;
     /** Strip 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;