@zenithbuild/compiler 1.0.2

package/dist/runtime/hydration.js

@@ -0,0 +1,271 @@
+/**
+ * Runtime Hydration Layer
+ *
+ * Phase 5: Browser-side runtime that hydrates static HTML with dynamic expressions
+ *
+ * This runtime:
+ * - Locates DOM placeholders (data-zen-text, data-zen-attr-*)
+ * - Evaluates precompiled expressions against state
+ * - Updates DOM textContent, attributes, and properties
+ * - Binds event handlers
+ * - Handles reactive state updates
+ */
+const bindings = [];
+/**
+ * Hydrate static HTML with dynamic expressions
+ *
+ * @param state - The state object to evaluate expressions against
+ * @param container - The container element to hydrate (defaults to document)
+ */
+export function hydrate(state, container = document) {
+    if (!state) {
+        console.warn('[Zenith] hydrate called without state object');
+        return;
+    }
+    // Store state globally for event handlers
+    if (typeof window !== 'undefined') {
+        window.__ZENITH_STATE__ = state;
+    }
+    // Clear existing bindings
+    bindings.length = 0;
+    // Find all text expression placeholders
+    const textPlaceholders = container.querySelectorAll('[data-zen-text]');
+    for (let i = 0; i < textPlaceholders.length; i++) {
+        const node = textPlaceholders[i];
+        if (!node)
+            continue;
+        const expressionId = node.getAttribute('data-zen-text');
+        if (!expressionId)
+            continue;
+        bindings.push({
+            node,
+            type: 'text',
+            expressionId
+        });
+        updateTextBinding(node, expressionId, state);
+    }
+    // Find all attribute expression placeholders
+    const attrPlaceholders = container.querySelectorAll('[data-zen-attr-class], [data-zen-attr-style], [data-zen-attr-src], [data-zen-attr-href], [data-zen-attr-disabled], [data-zen-attr-checked]');
+    for (let i = 0; i < attrPlaceholders.length; i++) {
+        const node = attrPlaceholders[i];
+        if (!(node instanceof Element))
+            continue;
+        // Check each possible attribute
+        const attrNames = ['class', 'style', 'src', 'href', 'disabled', 'checked'];
+        for (const attrName of attrNames) {
+            const expressionId = node.getAttribute(`data-zen-attr-${attrName}`);
+            if (!expressionId)
+                continue;
+            bindings.push({
+                node,
+                type: 'attribute',
+                attributeName: attrName,
+                expressionId
+            });
+            updateAttributeBinding(node, attrName, expressionId, state);
+        }
+    }
+    // Bind event handlers
+    bindEvents(container);
+}
+/**
+ * Update a text binding
+ */
+function updateTextBinding(node, expressionId, state) {
+    try {
+        const expression = window.__ZENITH_EXPRESSIONS__?.get(expressionId);
+        if (!expression) {
+            console.warn(`[Zenith] Expression ${expressionId} not found in registry`);
+            return;
+        }
+        const result = expression(state);
+        // Handle different result types
+        if (result === null || result === undefined || result === false) {
+            node.textContent = '';
+        }
+        else if (typeof result === 'string' || typeof result === 'number') {
+            node.textContent = String(result);
+        }
+        else if (result instanceof Node) {
+            // Replace node with result node
+            if (node.parentNode) {
+                node.parentNode.replaceChild(result, node);
+            }
+        }
+        else if (Array.isArray(result)) {
+            // Handle array results (for map expressions)
+            if (node.parentNode) {
+                const fragment = document.createDocumentFragment();
+                for (const item of result) {
+                    if (item instanceof Node) {
+                        fragment.appendChild(item);
+                    }
+                    else {
+                        fragment.appendChild(document.createTextNode(String(item)));
+                    }
+                }
+                node.parentNode.replaceChild(fragment, node);
+            }
+        }
+        else {
+            node.textContent = String(result);
+        }
+    }
+    catch (error) {
+        console.error(`[Zenith] Error evaluating expression ${expressionId}:`, error);
+        console.error('Expression ID:', expressionId, 'State:', state);
+    }
+}
+/**
+ * Update an attribute binding
+ */
+function updateAttributeBinding(element, attributeName, expressionId, state) {
+    try {
+        const expression = window.__ZENITH_EXPRESSIONS__?.get(expressionId);
+        if (!expression) {
+            console.warn(`[Zenith] Expression ${expressionId} not found in registry`);
+            return;
+        }
+        const result = expression(state);
+        // Handle different attribute types
+        if (attributeName === 'class' || attributeName === 'className') {
+            element.className = String(result ?? '');
+        }
+        else if (attributeName === 'style') {
+            if (typeof result === 'string') {
+                element.setAttribute('style', result);
+            }
+            else if (result && typeof result === 'object') {
+                // Handle style object
+                const styleStr = Object.entries(result)
+                    .map(([key, value]) => `${key}: ${value}`)
+                    .join('; ');
+                element.setAttribute('style', styleStr);
+            }
+        }
+        else if (attributeName === 'disabled' || attributeName === 'checked' || attributeName === 'readonly') {
+            // Boolean attributes
+            if (result) {
+                element.setAttribute(attributeName, '');
+            }
+            else {
+                element.removeAttribute(attributeName);
+            }
+        }
+        else {
+            // Regular attributes
+            if (result === null || result === undefined || result === false) {
+                element.removeAttribute(attributeName);
+            }
+            else {
+                element.setAttribute(attributeName, String(result));
+            }
+        }
+    }
+    catch (error) {
+        console.error(`[Zenith] Error updating attribute ${attributeName} with expression ${expressionId}:`, error);
+        console.error('Expression ID:', expressionId, 'State:', state);
+    }
+}
+/**
+ * Bind event handlers to DOM elements
+ *
+ * @param container - The container element to bind events in (defaults to document)
+ */
+export function bindEvents(container = document) {
+    const eventTypes = ['click', 'change', 'input', 'submit', 'focus', 'blur', 'keyup', 'keydown'];
+    for (const eventType of eventTypes) {
+        const elements = container.querySelectorAll(`[data-zen-${eventType}]`);
+        for (let i = 0; i < elements.length; i++) {
+            const element = elements[i];
+            if (!(element instanceof Element))
+                continue;
+            const handlerName = element.getAttribute(`data-zen-${eventType}`);
+            if (!handlerName)
+                continue;
+            // Remove existing listener if any (to avoid duplicates)
+            const existingHandler = element[`__zen_${eventType}_handler`];
+            if (existingHandler) {
+                element.removeEventListener(eventType, existingHandler);
+            }
+            // Create new handler
+            const handler = (event) => {
+                try {
+                    // Get handler function from window (functions are registered on window)
+                    const handlerFunc = window[handlerName];
+                    if (typeof handlerFunc === 'function') {
+                        handlerFunc(event, element);
+                    }
+                    else {
+                        console.warn(`[Zenith] Event handler "${handlerName}" not found for ${eventType} event`);
+                    }
+                }
+                catch (error) {
+                    console.error(`[Zenith] Error executing event handler "${handlerName}":`, error);
+                }
+            };
+            element[`__zen_${eventType}_handler`] = handler;
+            element.addEventListener(eventType, handler);
+        }
+    }
+}
+/**
+ * Update all bindings when state changes
+ *
+ * @param state - The new state object
+ */
+export function update(state) {
+    if (!state) {
+        console.warn('[Zenith] update called without state object');
+        return;
+    }
+    // Update global state
+    if (typeof window !== 'undefined') {
+        window.__ZENITH_STATE__ = state;
+    }
+    // Update all tracked bindings
+    for (const binding of bindings) {
+        if (binding.type === 'text') {
+            updateTextBinding(binding.node, binding.expressionId, state);
+        }
+        else if (binding.type === 'attribute' && binding.attributeName) {
+            if (binding.node instanceof Element) {
+                updateAttributeBinding(binding.node, binding.attributeName, binding.expressionId, state);
+            }
+        }
+    }
+}
+/**
+ * Initialize the expression registry
+ * Called once when the runtime loads
+ *
+ * @param expressions - Map of expression IDs to evaluation functions
+ */
+export function initExpressions(expressions) {
+    if (typeof window !== 'undefined') {
+        window.__ZENITH_EXPRESSIONS__ = expressions;
+    }
+}
+/**
+ * Clear all bindings and event listeners
+ * Useful for cleanup when navigating away
+ */
+export function cleanup(container = document) {
+    // Remove event listeners
+    const eventTypes = ['click', 'change', 'input', 'submit', 'focus', 'blur', 'keyup', 'keydown'];
+    for (const eventType of eventTypes) {
+        const elements = container.querySelectorAll(`[data-zen-${eventType}]`);
+        for (let i = 0; i < elements.length; i++) {
+            const element = elements[i];
+            if (!(element instanceof Element))
+                continue;
+            const handler = element[`__zen_${eventType}_handler`];
+            if (handler) {
+                element.removeEventListener(eventType, handler);
+                delete element[`__zen_${eventType}_handler`];
+            }
+        }
+    }
+    // Clear bindings
+    bindings.length = 0;
+}

package/dist/runtime/navigation.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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;

package/dist/runtime/navigation.js

@@ -0,0 +1,372 @@
+/**
+ * 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
+  }
+})();
+`;
+}