@zenithbuild/router 0.5.0-beta.2.3

package/dist/match.js

@@ -0,0 +1,191 @@
+// ---------------------------------------------------------------------------
+// match.js — Zenith Router V0
+// ---------------------------------------------------------------------------
+// Deterministic path matching engine.
+//
+// Algorithm:
+//   1. Split pathname and route path by '/'
+//   2. Walk segments:
+//      - ':param' → extract one segment into params object
+//      - '*slug'  → extract remaining segments (must be terminal, 1+ segments,
+//                   except root catch-all '/*slug' which allows 0+)
+//      - '*slug?' → optional catch-all (must be terminal, 0+ segments)
+//      - literal  → exact string comparison
+//   3. Deterministic precedence: static > :param > *catchall
+//
+// No regex.
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{ path: string, load: Function }} RouteEntry
+ * @typedef {{ route: RouteEntry, params: Record<string, string> }} MatchResult
+ */
+
+/**
+ * Match a pathname against a single route definition.
+ *
+ * @param {string} routePath - The route pattern (e.g. '/users/:id')
+ * @param {string} pathname  - The actual URL path (e.g. '/users/42')
+ * @returns {{ matched: boolean, params: Record<string, string> }}
+ */
+export function matchPath(routePath, pathname) {
+    const routeSegments = _splitPath(routePath);
+    const pathSegments = _splitPath(pathname);
+
+    const params = {};
+    let routeIndex = 0;
+    let pathIndex = 0;
+
+    while (routeIndex < routeSegments.length) {
+        const routeSeg = routeSegments[routeIndex];
+        if (routeSeg.startsWith('*')) {
+            // Catch-all must be terminal.
+            const optionalCatchAll = routeSeg.endsWith('?');
+            const paramName = optionalCatchAll
+                ? routeSeg.slice(1, -1)
+                : routeSeg.slice(1);
+            if (routeIndex !== routeSegments.length - 1) {
+                return { matched: false, params: {} };
+            }
+            const rest = pathSegments.slice(pathIndex);
+            const rootRequiredCatchAll = !optionalCatchAll && routeSegments.length === 1;
+            if (rest.length === 0 && !optionalCatchAll && !rootRequiredCatchAll) {
+                return { matched: false, params: {} };
+            }
+            params[paramName] = _normalizeCatchAll(rest);
+            pathIndex = pathSegments.length;
+            routeIndex = routeSegments.length;
+            break;
+        }
+
+        if (pathIndex >= pathSegments.length) {
+            return { matched: false, params: {} };
+        }
+
+        const pathSeg = pathSegments[pathIndex];
+        if (routeSeg.startsWith(':')) {
+            // Dynamic param — extract value as string
+            const paramName = routeSeg.slice(1);
+            params[paramName] = pathSeg;
+        } else if (routeSeg !== pathSeg) {
+            // Literal mismatch
+            return { matched: false, params: {} };
+        }
+
+        routeIndex += 1;
+        pathIndex += 1;
+    }
+
+    if (routeIndex !== routeSegments.length || pathIndex !== pathSegments.length) {
+        return { matched: false, params: {} };
+    }
+
+    return { matched: true, params };
+}
+
+/**
+ * Match a pathname against an ordered array of route definitions.
+ * Returns the first match (deterministic, first-match-wins).
+ *
+ * @param {RouteEntry[]} routes - Ordered route manifest
+ * @param {string} pathname     - The URL path to match
+ * @returns {MatchResult | null}
+ */
+export function matchRoute(routes, pathname) {
+    const ordered = [...routes].sort((a, b) => _compareRouteSpecificity(a.path, b.path));
+    for (let i = 0; i < ordered.length; i++) {
+        const route = ordered[i];
+        const result = matchPath(route.path, pathname);
+
+        if (result.matched) {
+            return { route, params: result.params };
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Split a path string into non-empty segments.
+ *
+ * @param {string} path
+ * @returns {string[]}
+ */
+function _splitPath(path) {
+    return path.split('/').filter(Boolean);
+}
+
+/**
+ * Catch-all params are normalized as slash-joined, non-empty path segments.
+ * Segments keep raw URL-encoded bytes (no decodeURIComponent).
+ *
+ * @param {string[]} segments
+ * @returns {string}
+ */
+function _normalizeCatchAll(segments) {
+    return segments.filter(Boolean).join('/');
+}
+
+/**
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function _compareRouteSpecificity(a, b) {
+    if (a === '/' && b !== '/') return -1;
+    if (b === '/' && a !== '/') return 1;
+
+    const aSegs = _splitPath(a);
+    const bSegs = _splitPath(b);
+    const aClass = _routeClass(aSegs);
+    const bClass = _routeClass(bSegs);
+    if (aClass !== bClass) {
+        return bClass - aClass;
+    }
+
+    const max = Math.min(aSegs.length, bSegs.length);
+
+    for (let i = 0; i < max; i++) {
+        const aWeight = _segmentWeight(aSegs[i]);
+        const bWeight = _segmentWeight(bSegs[i]);
+        if (aWeight !== bWeight) {
+            return bWeight - aWeight;
+        }
+    }
+
+    if (aSegs.length !== bSegs.length) {
+        return bSegs.length - aSegs.length;
+    }
+
+    return a.localeCompare(b);
+}
+
+/**
+ * @param {string[]} segments
+ * @returns {number}
+ */
+function _routeClass(segments) {
+    let hasParam = false;
+    let hasCatchAll = false;
+    for (const segment of segments) {
+        if (segment.startsWith('*')) {
+            hasCatchAll = true;
+        } else if (segment.startsWith(':')) {
+            hasParam = true;
+        }
+    }
+    if (!hasParam && !hasCatchAll) return 3;
+    if (hasCatchAll) return 1;
+    return 2;
+}
+
+/**
+ * @param {string | undefined} segment
+ * @returns {number}
+ */
+function _segmentWeight(segment) {
+    if (!segment) return 0;
+    if (segment.startsWith('*')) return 1;
+    if (segment.startsWith(':')) return 2;
+    return 3;
+}

package/dist/navigate.js

@@ -0,0 +1,67 @@
+// ---------------------------------------------------------------------------
+// navigate.js — Zenith Router V0
+// ---------------------------------------------------------------------------
+// Navigation API.
+//
+// - navigate(path)    → push to history, trigger route change
+// - back()            → history.back()
+// - forward()         → history.forward()
+// - getCurrentPath()  → current pathname
+//
+// The navigate function accepts a resolver callback so the router
+// can wire match → mount logic without circular dependencies.
+// ---------------------------------------------------------------------------
+
+import { push, current } from './history.js';
+import { _dispatchRouteChange } from './events.js';
+
+/** @type {((path: string) => Promise<void>) | null} */
+let _resolveNavigation = null;
+
+/**
+ * Wire the navigation resolver.
+ * Called once by createRouter() to bind match → mount logic.
+ *
+ * @param {(path: string) => Promise<void>} resolver
+ */
+export function _setNavigationResolver(resolver) {
+    _resolveNavigation = resolver;
+}
+
+/**
+ * Navigate to a path.
+ * Pushes history, then resolves through the router pipeline.
+ *
+ * @param {string} path
+ * @returns {Promise<void>}
+ */
+export async function navigate(path) {
+    push(path);
+
+    if (_resolveNavigation) {
+        await _resolveNavigation(path);
+    }
+}
+
+/**
+ * Go back in history.
+ */
+export function back() {
+    history.back();
+}
+
+/**
+ * Go forward in history.
+ */
+export function forward() {
+    history.forward();
+}
+
+/**
+ * Get the current pathname.
+ *
+ * @returns {string}
+ */
+export function getCurrentPath() {
+    return current();
+}

package/dist/navigation/client-router.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Navigation & Prefetch Runtime
+ *
+ * Phase 7: Prefetch compiled output, safe SPA navigation, route caching
+ *
+ * This runtime handles:
+ * - Prefetching compiled HTML + JS for routes
+ * - Caching prefetched routes
+ * - Safe DOM mounting and hydration
+ * - Browser history management
+ * - Explicit data exposure for navigation
+ */
+/**
+ * Route cache entry containing compiled output
+ */
+export interface RouteCacheEntry {
+    html: string;
+    js: string;
+    styles: string[];
+    routePath: string;
+    compiledAt: number;
+}
+/**
+ * Navigation options with explicit data
+ */
+export interface NavigateOptions {
+    loaderData?: any;
+    props?: any;
+    stores?: any;
+    replace?: boolean;
+    prefetch?: boolean;
+}
+/**
+ * Prefetch a route's compiled output
+ *
+ * @param routePath - The route path to prefetch (e.g., "/dashboard")
+ * @returns Promise that resolves when prefetch is complete
+ */
+export declare function prefetchRoute(routePath: string): Promise<void>;
+/**
+ * Get cached route entry
+ */
+export declare function getCachedRoute(routePath: string): RouteCacheEntry | null;
+/**
+ * Navigate to a route with explicit data
+ *
+ * @param routePath - The route path to navigate to
+ * @param options - Navigation options with loaderData, props, stores
+ */
+export declare function navigate(routePath: string, options?: NavigateOptions): Promise<void>;
+/**
+ * Handle browser back/forward navigation
+ */
+export declare function setupHistoryHandling(): void;
+/**
+ * Generate navigation runtime code (to be included in bundle)
+ */
+export declare function generateNavigationRuntime(): string;
+//# sourceMappingURL=client-router.d.ts.map

package/dist/navigation/client-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-router.d.ts","sourceRoot":"","sources":["../../src/navigation/client-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,UAAU,CAAC,EAAE,GAAG,CAAA;IAChB,KAAK,CAAC,EAAE,GAAG,CAAA;IACX,MAAM,CAAC,EAAE,GAAG,CAAA;IACZ,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACrB;AAaD;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BpE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAGxE;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAC1B,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,eAAoB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAgEf;AAoGD;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAY3C;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAgJlD"}

package/dist/navigation/client-router.js

@@ -0,0 +1,373 @@
+/**
+ * Navigation & Prefetch Runtime
+ *
+ * Phase 7: Prefetch compiled output, safe SPA navigation, route caching
+ *
+ * This runtime handles:
+ * - Prefetching compiled HTML + JS for routes
+ * - Caching prefetched routes
+ * - Safe DOM mounting and hydration
+ * - Browser history management
+ * - Explicit data exposure for navigation
+ */
+/**
+ * Route cache - stores prefetched compiled output
+ */
+const routeCache = new Map();
+/**
+ * Current navigation state
+ */
+let currentRoute = '';
+let navigationInProgress = false;
+/**
+ * Prefetch a route's compiled output
+ *
+ * @param routePath - The route path to prefetch (e.g., "/dashboard")
+ * @returns Promise that resolves when prefetch is complete
+ */
+export async function prefetchRoute(routePath) {
+    // Normalize route path
+    const normalizedPath = routePath === '' ? '/' : routePath;
+    // Check if already cached
+    if (routeCache.has(normalizedPath)) {
+        return Promise.resolve();
+    }
+    // In a real implementation, this would fetch from the build output
+    // For Phase 7, we'll generate a placeholder that indicates the route needs to be built
+    try {
+        // Fetch compiled HTML + JS
+        // In production, this would be:
+        // const htmlResponse = await fetch(`${normalizedPath}.html`)
+        // const jsResponse = await fetch(`${normalizedPath}.js`)
+        // For now, return a placeholder that indicates prefetch structure
+        const cacheEntry = {
+            html: `<!-- Prefetched route: ${normalizedPath} -->`,
+            js: `// Prefetched route runtime: ${normalizedPath}`,
+            styles: [],
+            routePath: normalizedPath,
+            compiledAt: Date.now()
+        };
+        routeCache.set(normalizedPath, cacheEntry);
+    }
+    catch (error) {
+        console.warn(`[Zenith] Failed to prefetch route ${normalizedPath}:`, error);
+        throw error;
+    }
+}
+/**
+ * Get cached route entry
+ */
+export function getCachedRoute(routePath) {
+    const normalizedPath = routePath === '' ? '/' : routePath;
+    return routeCache.get(normalizedPath) || null;
+}
+/**
+ * Navigate to a route with explicit data
+ *
+ * @param routePath - The route path to navigate to
+ * @param options - Navigation options with loaderData, props, stores
+ */
+export async function navigate(routePath, options = {}) {
+    if (navigationInProgress) {
+        console.warn('[Zenith] Navigation already in progress, skipping');
+        return;
+    }
+    navigationInProgress = true;
+    try {
+        const normalizedPath = routePath === '' ? '/' : routePath;
+        // Check if route is cached, otherwise prefetch
+        let cacheEntry = getCachedRoute(normalizedPath);
+        if (!cacheEntry && options.prefetch !== false) {
+            await prefetchRoute(normalizedPath);
+            cacheEntry = getCachedRoute(normalizedPath);
+        }
+        if (!cacheEntry) {
+            throw new Error(`Route ${normalizedPath} not found. Ensure the route is compiled.`);
+        }
+        // Cleanup previous route
+        cleanupPreviousRoute();
+        // Get router outlet
+        const outlet = getRouterOutlet();
+        if (!outlet) {
+            throw new Error('Router outlet not found. Ensure <div id="zenith-outlet"></div> exists.');
+        }
+        // Mount compiled HTML
+        outlet.innerHTML = cacheEntry.html;
+        // Inject styles
+        injectStyles(cacheEntry.styles);
+        // Execute JS runtime (compiled expressions + hydration)
+        await executeRouteRuntime(cacheEntry.js, {
+            loaderData: options.loaderData || {},
+            props: options.props || {},
+            stores: options.stores || {}
+        });
+        // Update browser history
+        if (typeof window !== 'undefined') {
+            const url = normalizedPath + (window.location.search || '');
+            if (options.replace) {
+                window.history.replaceState({ route: normalizedPath }, '', url);
+            }
+            else {
+                window.history.pushState({ route: normalizedPath }, '', url);
+            }
+        }
+        currentRoute = normalizedPath;
+        // Dispatch navigation event
+        dispatchNavigationEvent(normalizedPath, options);
+    }
+    catch (error) {
+        console.error('[Zenith] Navigation error:', error);
+        throw error;
+    }
+    finally {
+        navigationInProgress = false;
+    }
+}
+/**
+ * Cleanup previous route
+ */
+function cleanupPreviousRoute() {
+    if (typeof window === 'undefined')
+        return;
+    // Cleanup hydration runtime
+    if (window.zenithCleanup) {
+        ;
+        window.zenithCleanup();
+    }
+    // Remove previous page styles
+    document.querySelectorAll('style[data-zen-route-style]').forEach(style => {
+        style.remove();
+    });
+    // Clear window state (if needed)
+    // State is managed per-route, so we don't clear it here
+}
+/**
+ * Get router outlet element
+ */
+function getRouterOutlet() {
+    if (typeof window === 'undefined')
+        return null;
+    return document.querySelector('#zenith-outlet') || document.querySelector('[data-zen-outlet]');
+}
+/**
+ * Inject route styles
+ */
+function injectStyles(styles) {
+    if (typeof window === 'undefined')
+        return;
+    styles.forEach((styleContent, index) => {
+        const style = document.createElement('style');
+        style.setAttribute('data-zen-route-style', String(index));
+        style.textContent = styleContent;
+        document.head.appendChild(style);
+    });
+}
+/**
+ * Execute route runtime JS
+ *
+ * This executes the compiled JS bundle for the route, which includes:
+ * - Expression wrappers
+ * - Hydration runtime
+ * - Event bindings
+ */
+async function executeRouteRuntime(jsCode, data) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        // Execute the compiled JS (which registers expressions and hydration functions)
+        // In a real implementation, this would use a script tag or eval (secure context)
+        const script = document.createElement('script');
+        script.textContent = jsCode;
+        document.head.appendChild(script);
+        document.head.removeChild(script);
+        // After JS executes, call hydrate with explicit data
+        if (window.zenithHydrate) {
+            const state = window.__ZENITH_STATE__ || {};
+            window.zenithHydrate(state, data.loaderData, data.props, data.stores, getRouterOutlet());
+        }
+    }
+    catch (error) {
+        console.error('[Zenith] Error executing route runtime:', error);
+        throw error;
+    }
+}
+/**
+ * Dispatch navigation event
+ */
+function dispatchNavigationEvent(routePath, options) {
+    if (typeof window === 'undefined')
+        return;
+    const event = new CustomEvent('zenith:navigate', {
+        detail: {
+            route: routePath,
+            loaderData: options.loaderData,
+            props: options.props,
+            stores: options.stores
+        }
+    });
+    window.dispatchEvent(event);
+}
+/**
+ * Handle browser back/forward navigation
+ */
+export function setupHistoryHandling() {
+    if (typeof window === 'undefined')
+        return;
+    window.addEventListener('popstate', (event) => {
+        const state = event.state;
+        const routePath = state?.route || window.location.pathname;
+        // Navigate without pushing to history (browser already changed it)
+        navigate(routePath, { replace: true, prefetch: false }).catch((error) => {
+            console.error('[Zenith] History navigation error:', error);
+        });
+    });
+}
+/**
+ * Generate navigation runtime code (to be included in bundle)
+ */
+export function generateNavigationRuntime() {
+    return `
+// Zenith Navigation Runtime (Phase 7)
+(function() {
+  'use strict';
+  
+  // Route cache
+  const __zen_routeCache = new Map();
+  
+  // Current route state
+  let __zen_currentRoute = '';
+  let __zen_navigationInProgress = false;
+  
+  /**
+   * Prefetch a route
+   */
+  async function prefetchRoute(routePath) {
+    const normalizedPath = routePath === '' ? '/' : routePath;
+    
+    if (__zen_routeCache.has(normalizedPath)) {
+      return Promise.resolve();
+    }
+    
+    try {
+      // Fetch compiled HTML + JS
+      // This is a placeholder - in production, fetch from build output
+      const cacheEntry = {
+        html: '<!-- Prefetched: ' + normalizedPath + ' -->',
+        js: '// Prefetched runtime: ' + normalizedPath,
+        styles: [],
+        routePath: normalizedPath,
+        compiledAt: Date.now()
+      };
+      
+      __zen_routeCache.set(normalizedPath, cacheEntry);
+    } catch (error) {
+      console.warn('[Zenith] Prefetch failed:', routePath, error);
+      throw error;
+    }
+  }
+  
+  /**
+   * Navigate to route with explicit data
+   */
+  async function navigate(routePath, options) {
+    options = options || {};
+    
+    if (__zen_navigationInProgress) {
+      console.warn('[Zenith] Navigation in progress');
+      return;
+    }
+    
+    __zen_navigationInProgress = true;
+    
+    try {
+      const normalizedPath = routePath === '' ? '/' : routePath;
+      
+      // Get cached route or prefetch
+      let cacheEntry = __zen_routeCache.get(normalizedPath);
+      if (!cacheEntry && options.prefetch !== false) {
+        await prefetchRoute(normalizedPath);
+        cacheEntry = __zen_routeCache.get(normalizedPath);
+      }
+      
+      if (!cacheEntry) {
+        throw new Error('Route not found: ' + normalizedPath);
+      }
+      
+      // Get outlet
+      const outlet = document.querySelector('#zenith-outlet') || document.querySelector('[data-zen-outlet]');
+      if (!outlet) {
+        throw new Error('Router outlet not found');
+      }
+      
+      // Mount HTML
+      outlet.innerHTML = cacheEntry.html;
+      
+      // Execute runtime JS
+      if (cacheEntry.js) {
+        const script = document.createElement('script');
+        script.textContent = cacheEntry.js;
+        document.head.appendChild(script);
+        document.head.removeChild(script);
+      }
+      
+      // Hydrate with explicit data
+      if (window.zenithHydrate) {
+        const state = window.__ZENITH_STATE__ || {};
+        window.zenithHydrate(
+          state,
+          options.loaderData || {},
+          options.props || {},
+          options.stores || {},
+          outlet
+        );
+      }
+      
+      // Update history
+      const url = normalizedPath + (window.location.search || '');
+      if (options.replace) {
+        window.history.replaceState({ route: normalizedPath }, '', url);
+      } else {
+        window.history.pushState({ route: normalizedPath }, '', url);
+      }
+      
+      __zen_currentRoute = normalizedPath;
+      
+      // Dispatch event
+      window.dispatchEvent(new CustomEvent('zenith:navigate', {
+        detail: { route: normalizedPath, options: options }
+      }));
+    } catch (error) {
+      console.error('[Zenith] Navigation error:', error);
+      throw error;
+    } finally {
+      __zen_navigationInProgress = false;
+    }
+  }
+  
+  /**
+   * Handle browser history
+   */
+  function setupHistoryHandling() {
+    window.addEventListener('popstate', function(event) {
+      const state = event.state;
+      const routePath = state && state.route ? state.route : window.location.pathname;
+      
+      navigate(routePath, { replace: true, prefetch: false }).catch(function(error) {
+        console.error('[Zenith] History navigation error:', error);
+      });
+    });
+  }
+  
+  // Initialize history handling
+  setupHistoryHandling();
+  
+  // Expose API
+  if (typeof window !== 'undefined') {
+    window.__zenith_navigate = navigate;
+    window.__zenith_prefetch = prefetchRoute;
+    window.navigate = navigate; // Global convenience
+  }
+})();
+`;
+}
+//# sourceMappingURL=client-router.js.map