@zolomedia/bifrost-client 1.7.74

package/L4_Orchestration/facade/renderer_registry.js

@@ -0,0 +1,274 @@
+/**
+ * L4_Orchestration/facade/renderer_registry.js
+ * 
+ * Renderer Registry - Centralized Lazy Loading for All Renderers
+ * 
+ * Consolidates 16 individual _ensure*Renderer() methods from bifrost_client.js
+ * into a single registry-based loader.
+ * 
+ * Extracted from bifrost_client.js (Task 0, Step 1.2)
+ * 
+ * @module facade/renderer_registry
+ * @layer L4 (Orchestration)
+ */
+
+/**
+ * Renderer Registry - Maps renderer types to their module paths and classes
+ *
+ * TODO: Tiered initialization for publish-time performance
+ * ──────────────────────────────────────────────────────────
+ * Add a `priority` field to each entry:
+ *   - 'critical'  → load before WebSocket connects (blocks first paint)
+ *   - 'deferred'  → load after first chunk renders (requestIdleCallback / post-paint hook)
+ *
+ * Critical tier (must exist before first chunk renders):
+ *   typography, text, header (header_renderer if separate), list
+ *
+ * Deferred tier (never in a typical first chunk):
+ *   code, card, button, table, dl, image, icon, navigation,
+ *   dashboard, swiper, terminal, spinner, progressBar, form, menu
+ *
+ * Implementation sketch:
+ *   1. Add `priority: 'critical' | 'deferred'` to each entry below
+ *   2. In asset_loader.js (or initializer.js), call
+ *      rendererRegistry.preloadTier('critical') before WS connect
+ *   3. After first-paint signal (first WebSocket chunk ACK), call
+ *      rendererRegistry.preloadTier('deferred') via requestIdleCallback
+ *   4. ensureRenderer() stays unchanged — cache hit on any pre-loaded renderer
+ *
+ * Expected gain: time-to-interactive drops from ~40 module fetches to ~4-5
+ * before first content paint, remainder loads invisibly in background.
+ */
+export const RENDERER_REGISTRY = {
+  // Outputs - Typography & Text
+  typography: {
+    path: 'L2_Handling/display/outputs/typography_renderer.js',
+    className: 'TypographyRenderer',
+    isDefault: true,
+    passClient: false
+  },
+  text: {
+    path: 'L2_Handling/display/outputs/text_renderer.js',
+    className: 'TextRenderer',
+    isDefault: true,
+    passClient: false
+  },
+  code: {
+    path: 'L2_Handling/display/outputs/code_renderer.js',
+    className: 'CodeRenderer',
+    isDefault: true,
+    passClient: false
+  },
+  
+  // Outputs - Cards & Buttons
+  card: {
+    path: 'L2_Handling/display/outputs/card_renderer.js',
+    className: 'CardRenderer',
+    isDefault: true,
+    passClient: false
+  },
+  button: {
+    path: 'L2_Handling/display/inputs/button_renderer.js',
+    className: 'ButtonRenderer',
+    isDefault: true,
+    passClient: true // ButtonRenderer needs client for event handling
+  },
+  
+  // Outputs - Data Display
+  table: {
+    path: 'L2_Handling/display/outputs/table_renderer.js',
+    className: 'TableRenderer',
+    isDefault: true,
+    passClient: false
+  },
+  list: {
+    path: 'L2_Handling/display/outputs/list_renderer.js',
+    className: 'ListRenderer',
+    isDefault: true,
+    passClient: true // ListRenderer needs client for nested rendering
+  },
+  dl: {
+    path: 'L2_Handling/display/outputs/dl_renderer.js',
+    className: 'DLRenderer',
+    isDefault: false,
+    passClient: false,
+    useModuleRegistry: true // Uses MODULE_REGISTRY for loading
+  },
+  
+  // Outputs - Media
+  image: {
+    path: 'L2_Handling/display/outputs/image_renderer.js',
+    className: 'ImageRenderer',
+    isDefault: true,
+    passClient: false
+  },
+  video: {
+    path: 'L2_Handling/display/outputs/video_renderer.js',
+    className: 'VideoRenderer',
+    isDefault: true,
+    passClient: false
+  },
+  audio: {
+    path: 'L2_Handling/display/outputs/audio_renderer.js',
+    className: 'AudioRenderer',
+    isDefault: true,
+    passClient: false
+  },
+  icon: {
+    path: 'L2_Handling/display/outputs/icon_renderer.js',
+    className: 'IconRenderer',
+    isDefault: true,
+    passClient: false
+  },
+  
+  // Outputs - Navigation
+  navigation: {
+    path: 'L2_Handling/display/outputs/navigation_renderer.js',
+    className: 'NavigationRenderer',
+    isDefault: false,
+    passClient: true, // NavigationRenderer needs client for link primitives
+    useModuleRegistry: true
+  },
+  
+  // Composite - Complex Components
+  dashboard: {
+    path: 'L2_Handling/display/composite/dashboard_renderer.js',
+    className: 'DashboardRenderer',
+    isDefault: true,
+    passClient: true // DashboardRenderer needs client for nested rendering
+  },
+  swiper: {
+    path: 'L2_Handling/display/composite/swiper_renderer.js',
+    className: 'SwiperRenderer',
+    isDefault: true,
+    passClient: false
+  },
+  terminal: {
+    path: 'L2_Handling/display/composite/terminal_renderer.js',
+    className: 'TerminalRenderer',
+    isDefault: true,
+    passClient: true, // TerminalRenderer needs client for execution
+    exposeToWindow: true // Expose to window._TerminalRenderer for message handler
+  },
+  
+  // Feedback - UI State
+  spinner: {
+    path: 'L2_Handling/display/feedback/spinner_renderer.js',
+    className: 'SpinnerRenderer',
+    isDefault: true,
+    passClient: false
+  },
+  progressBar: {
+    path: 'L2_Handling/display/feedback/progressbar_renderer.js',
+    className: 'ProgressBarRenderer',
+    isDefault: true,
+    passClient: false
+  },
+  
+  // Inputs - Forms
+  form: {
+    path: 'L2_Handling/display/inputs/form_renderer.js',
+    className: 'FormRenderer',
+    isDefault: false,
+    passClient: true, // FormRenderer needs client for form handling
+    useModuleRegistry: true
+  },
+  menu: {
+    path: 'L2_Handling/display/navigation/menu_renderer.js',
+    className: 'MenuRenderer',
+    isDefault: false,
+    passClient: true, // MenuRenderer needs client for menu interactions
+    useModuleRegistry: true
+  }
+};
+
+/**
+ * RendererRegistry - Centralized renderer loading and caching
+ */
+export class RendererRegistry {
+  constructor(client) {
+    this.client = client;
+    this.logger = client.logger;
+    this.baseUrl = client._baseUrl;
+    this.renderers = {}; // Cache for loaded renderers
+  }
+
+  /**
+   * Ensure a renderer is loaded and cached
+   * @param {string} type - Renderer type (e.g., 'typography', 'button', 'table')
+   * @returns {Promise<Object>} Renderer instance
+   */
+  async ensureRenderer(type) {
+    // Return cached renderer if already loaded
+    if (this.renderers[type]) {
+      return this.renderers[type];
+    }
+
+    // Get renderer config from registry
+    const config = RENDERER_REGISTRY[type];
+    if (!config) {
+      throw new Error(`Unknown renderer type: ${type}`);
+    }
+
+    // Load renderer module
+    let RendererClass;
+    if (config.useModuleRegistry) {
+      // Use client's _loadModule for MODULE_REGISTRY lookup
+      const module = await this.client._loadModule(type === 'dl' ? 'dl_renderer' : 
+                                                    type === 'navigation' ? 'navigation_renderer' :
+                                                    type === 'form' ? 'form_renderer' :
+                                                    type === 'menu' ? 'menu_renderer' : type);
+      RendererClass = module[config.className];
+    } else {
+      // Direct import
+      const fullPath = `${this.baseUrl}${config.path}`;
+      const module = await import(fullPath);
+      RendererClass = config.isDefault ? module.default : module[config.className];
+    }
+
+    // Instantiate renderer
+    const args = config.passClient ? [this.logger, this.client] : [this.logger];
+    const renderer = new RendererClass(...args);
+
+    // Expose to window if needed (for TerminalRenderer)
+    if (config.exposeToWindow) {
+      window[`_${config.className}`] = RendererClass;
+    }
+
+    // Cache and return
+    this.renderers[type] = renderer;
+    this.logger.debug(`${config.className} loaded via registry`);
+    return renderer;
+  }
+
+  /**
+   * Get a cached renderer (throws if not loaded)
+   * @param {string} type - Renderer type
+   * @returns {Object} Renderer instance
+   */
+  getRenderer(type) {
+    const renderer = this.renderers[type];
+    if (!renderer) {
+      throw new Error(`Renderer not loaded: ${type}`);
+    }
+    return renderer;
+  }
+
+  /**
+   * Check if a renderer is loaded
+   * @param {string} type - Renderer type
+   * @returns {boolean}
+   */
+  hasRenderer(type) {
+    return !!this.renderers[type];
+  }
+
+  /**
+   * Preload multiple renderers in parallel
+   * @param {string[]} types - Array of renderer types
+   * @returns {Promise<void>}
+   */
+  async preloadRenderers(types) {
+    await Promise.all(types.map(type => this.ensureRenderer(type)));
+  }
+}

package/L4_Orchestration/lifecycle/asset_loader.js

@@ -0,0 +1,255 @@
+/**
+ * L4_Orchestration/lifecycle/asset_loader.js
+ * 
+ * Asset Loading Orchestrator
+ * 
+ * Manages loading of external assets and libraries:
+ * - Prism.js syntax highlighting (core + languages + .zolo variants)
+ * - _zScripts from YAML metadata (plugin scripts)
+ * 
+ * Extracted from bifrost_client.js (Phase 5.4)
+ *
+ * TODO: Tiered renderer initialization for publish-time performance
+ * ──────────────────────────────────────────────────────────────────
+ * This is the right place to orchestrate the two-phase load sequence:
+ *
+ *   Phase 1 — before WebSocket connect (called from initializer.js):
+ *     await client.rendererRegistry.preloadTier('critical')
+ *     // loads: typography, text, list — ~4 files, unblocks first paint
+ *
+ *   Phase 2 — after first chunk renders (post-paint, background):
+ *     const afterFirstPaint = () => {
+ *       requestIdleCallback(() => client.rendererRegistry.preloadTier('deferred'));
+ *     };
+ *     // hook into message_handler.js first-chunk-rendered signal, or
+ *     // use a one-shot WebSocket message ACK as the trigger
+ *
+ * Prerequisite: add `priority: 'critical' | 'deferred'` to each entry
+ * in renderer_registry.js (see TODO there), then add preloadTier() to
+ * RendererRegistry that filters by priority and calls ensureRenderer().
+ *
+ * No changes to ensureRenderer() needed — cache hit on pre-loaded renderers
+ * means existing lazy-load call sites stay identical.
+ */
+
+export class AssetLoader {
+  constructor(client) {
+    this.client = client;
+    this.logger = client.logger;
+  }
+
+  /**
+   * Load _zScripts from YAML metadata (plugin scripts)
+   * Resolves plugin references: &.plugin_name → /plugins/plugin_name.js
+   */
+  loadZScripts() {
+    if (typeof document === 'undefined') {
+      return;
+    }
+
+    // Extract zScripts from zuiConfig.zMeta (renamed from _zScripts in v1.7.26)
+    const zScripts = this.client.zuiConfig?.zMeta?.zScripts || this.client.zuiConfig?.zMeta?._zScripts || [];
+    
+    if (!Array.isArray(zScripts) || zScripts.length === 0) {
+      this.logger.debug('[AssetLoader] No zScripts found in YAML metadata');
+      return;
+    }
+
+    this.logger.debug('[AssetLoader] Loading %s _zScripts from YAML', zScripts.length);
+
+    zScripts.forEach(scriptRef => {
+      // Resolve plugin reference: &.plugin_name → /plugins/plugin_name.js
+      let scriptUrl = scriptRef;
+      if (scriptRef.startsWith('&.')) {
+        const pluginName = scriptRef.substring(2);
+        scriptUrl = `/plugins/${pluginName}.js`;
+        this.logger.debug('[AssetLoader] Resolving plugin: %s → %s', scriptRef, scriptUrl);
+      }
+
+      // Check if script already loaded
+      if (!document.querySelector(`script[src="${scriptUrl}"]`)) {
+        const script = document.createElement('script');
+        script.src = scriptUrl;
+        script.async = true;
+        script.onload = () => {
+          this.logger.debug('[AssetLoader] Loaded _zScript: %s', scriptUrl);
+        };
+        script.onerror = () => {
+          this.logger.error('[AssetLoader] Failed to load _zScript: %s', scriptUrl);
+        };
+        document.head.appendChild(script);
+      } else {
+        this.logger.debug('[AssetLoader] _zScript already loaded: %s', scriptUrl);
+      }
+    });
+  }
+
+  /**
+   * Load Prism.js from CDN for syntax highlighting
+   * Complex sequential loading: core → components → .zolo languages
+   */
+  loadPrismJS() {
+    if (typeof document === 'undefined') {
+      return;
+    }
+
+    this.logger.debug('[AssetLoader] Loading Prism.js...');
+
+    const prismCDN = 'https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0';
+    const prismTheme = `${prismCDN}/themes/prism-tomorrow.min.css`;
+    
+    // Check if Prism CSS already loaded
+    if (!document.querySelector(`link[href="${prismTheme}"]`)) {
+      const link = document.createElement('link');
+      link.rel = 'stylesheet';
+      link.href = prismTheme;
+      document.head.appendChild(link);
+      this.logger.debug('[AssetLoader] Prism CSS loaded (prism-tomorrow)');
+    } else {
+      this.logger.debug('[AssetLoader] Prism CSS already loaded');
+    }
+    
+    // Load custom .zolo theme overrides — bundled WITH the client (syntax/),
+    // resolved relative to this module so the zlsp palette ships built-in.
+    const zoloTheme = new URL('../../syntax/prism-zolo-theme.css', import.meta.url).href;
+    if (!document.querySelector(`link[href="${zoloTheme}"]`)) {
+      const link = document.createElement('link');
+      link.rel = 'stylesheet';
+      link.href = zoloTheme;
+      document.head.appendChild(link);
+      this.logger.debug('[AssetLoader] Prism .zolo custom theme loaded');
+    }
+
+    // Load Prism core + common languages
+    const scripts = [
+      { src: `${prismCDN}/prism.min.js`, name: 'core' },
+      { src: `${prismCDN}/components/prism-markup.min.js`, name: 'markup' },
+      { src: `${prismCDN}/components/prism-css.min.js`, name: 'css' },
+      { src: `${prismCDN}/components/prism-javascript.min.js`, name: 'javascript' },
+      { src: `${prismCDN}/components/prism-python.min.js`, name: 'python' },
+      { src: `${prismCDN}/components/prism-bash.min.js`, name: 'bash' },
+      { src: `${prismCDN}/components/prism-yaml.min.js`, name: 'yaml' }
+    ];
+
+    // Load scripts sequentially (Prism components depend on core)
+    const loadScript = (scriptInfo, index) => {
+      // Check if script already loaded
+      if (document.querySelector(`script[src="${scriptInfo.src}"]`)) {
+        // Already loaded, continue to next
+        this.logger.debug(`[AssetLoader] Prism ${scriptInfo.name} already loaded`);
+        if (index < scripts.length - 1) {
+          loadScript(scripts[index + 1], index + 1);
+        } else {
+          this.logger.debug('[AssetLoader] All Prism.js scripts already loaded');
+          this.loadPrismZolo();
+        }
+        return;
+      }
+
+      const script = document.createElement('script');
+      script.src = scriptInfo.src;
+      script.onload = () => {
+        // Load next script in sequence (silent)
+        if (index < scripts.length - 1) {
+          loadScript(scripts[index + 1], index + 1);
+        } else {
+          // Load custom .zolo language definition
+          this.loadPrismZolo();
+        }
+      };
+      script.onerror = () => {
+        this.logger.warn(`[AssetLoader] Failed to load Prism ${scriptInfo.name}`);
+      };
+      document.head.appendChild(script);
+    };
+
+    // Start loading chain
+    loadScript(scripts[0], 0);
+  }
+
+  /**
+   * Load custom .zolo language definitions for Prism.js
+   * Loads 6 .zolo variants: zolo, zspark, zui, zschema, zconfig, zenv
+   */
+  loadPrismZolo() {
+    if (typeof document === 'undefined') {
+      return;
+    }
+
+    this.logger.debug('[AssetLoader] Loading custom .zolo languages...');
+
+    // Keep dependency order deterministic: extensions rely on base "zolo".
+    const zoloLanguages = ['zolo', 'zspark', 'zui', 'zschema', 'zconfig', 'zenv'];
+    const totalLanguages = zoloLanguages.length;
+
+    // zolo grammars ship WITH the client (syntax/), not the host app. Resolve
+    // them relative to this module so every zApp gets zolo highlighting for
+    // free — no per-app /static/js/prism-*.js copies required.
+    const syntaxBase = new URL('../../syntax/', import.meta.url).href;
+
+    const alreadyLoaded = zoloLanguages.every((lang) => window.Prism?.languages?.[lang]);
+    if (alreadyLoaded) {
+      this.logger.debug('[AssetLoader] Prism .zolo languages already loaded');
+      return;
+    }
+
+    const finishLoad = () => {
+      this.logger.debug('[AssetLoader] Prism.js loaded (7 languages + %s .zolo variants)', totalLanguages);
+
+      // Rehighlight ALL code blocks rendered before grammars loaded — covers
+      // zolo variants AND stock languages (bash, python, …) from zMD fences.
+      if (window.Prism) {
+        const codeBlocks = document.querySelectorAll('pre code[class*="language-"]');
+        if (codeBlocks.length > 0) {
+          this.logger.debug(`[AssetLoader] Rehighlighting ${codeBlocks.length} code blocks`);
+          codeBlocks.forEach(block => {
+            Prism.highlightElement(block);
+          });
+        }
+      }
+    };
+
+    const loadLanguageSequentially = (index) => {
+      if (index >= totalLanguages) {
+        finishLoad();
+        return;
+      }
+
+      const lang = zoloLanguages[index];
+      const path = `${syntaxBase}prism-${lang}.js`;
+
+      // If language is already registered, continue.
+      if (window.Prism?.languages?.[lang]) {
+        this.logger.debug(`[AssetLoader] Prism ${lang} already registered`);
+        loadLanguageSequentially(index + 1);
+        return;
+      }
+
+      // Reuse existing script tag if present but language not yet available.
+      const existingScript = document.querySelector(`script[src="${path}"]`);
+      if (existingScript) {
+        existingScript.addEventListener('load', () => {
+          this.logger.debug(`[AssetLoader] Loaded Prism language ${index + 1}/${totalLanguages}: ${path}`);
+          loadLanguageSequentially(index + 1);
+        }, { once: true });
+        existingScript.addEventListener('error', () => {
+          this.logger.error(`[AssetLoader] Failed to load Prism language: ${path}`);
+        }, { once: true });
+        return;
+      }
+
+      const script = document.createElement('script');
+      script.src = path;
+      script.onload = () => {
+        this.logger.debug(`[AssetLoader] Loaded Prism language ${index + 1}/${totalLanguages}: ${path}`);
+        loadLanguageSequentially(index + 1);
+      };
+      script.onerror = () => {
+        this.logger.error(`[AssetLoader] Failed to load Prism language: ${path}`);
+      };
+      document.head.appendChild(script);
+    };
+
+    loadLanguageSequentially(0);
+  }
+}

package/L4_Orchestration/lifecycle/initializer.js

@@ -0,0 +1,135 @@
+/**
+ * L4_Orchestration/lifecycle/initializer.js
+ * 
+ * Initialization Orchestrator
+ * 
+ * Coordinates the initialization sequence for BifrostClient:
+ * - zVaF elements (connection badge, navbar, content area)
+ * - Client-side navigation setup
+ * - Widget hooks registration
+ * - Cache hooks registration
+ * 
+ * Extracted from bifrost_client.js (Phase 5.2)
+ */
+
+export class Initializer {
+  constructor(client) {
+    this.client = client;
+    this.logger = client.logger;
+  }
+
+  /**
+   * Register default widget hooks (backward compatibility)
+   * Widget hooks are now registered in WidgetHookManager
+   */
+  registerDefaultWidgetHooks() {
+    // Widget hooks are now registered in the widget handler
+    // This method is kept for backward compatibility
+  }
+
+  /**
+   * Register cache-related hooks (onConnectionInfo, onDisconnected, onConnected)
+   */
+  async registerCacheHooks() {
+    await this.client._ensureCacheManager();
+    return this.client.cacheManager.registerCacheHooks();
+  }
+
+  /**
+   * Disable all forms during offline mode
+   */
+  async disableForms() {
+    await this.client._ensureCacheManager();
+    return this.client.cacheManager.disableForms();
+  }
+
+  /**
+   * Enable all forms when back online
+   */
+  async enableForms() {
+    await this.client._ensureCacheManager();
+    return this.client.cacheManager.enableForms();
+  }
+
+  /**
+   * Initialize zVaF elements (connection badges, navbar, content area)
+   * HTML structure (declared in zVaF.html):
+   *   <zBifrostBadge></zBifrostBadge>  ← Dynamic, always fresh
+   *   <zNavBar></zNavBar>              ← Dynamic, RBAC-aware
+   *   <zVaF>...</zVaF>                 ← Cacheable content area
+   */
+  async initZVaFElements() {
+    await this.client._ensureZVaFManager();
+    return this.client.zvafManager.initZVaFElements();
+  }
+
+  /**
+   * Populate connection badge content
+   */
+  async populateConnectionBadge() {
+    await this.client._ensureZVaFManager();
+    return this.client.zvafManager.populateConnectionBadge();
+  }
+
+  /**
+   * Update badge state
+   * @param {string} state - 'connecting', 'connected', 'disconnected', 'error'
+   */
+  async updateBadgeState(state) {
+    await this.client._ensureZVaFManager();
+    return this.client.zvafManager.updateBadgeState(state);
+  }
+
+  /**
+   * Update badge with bifrost render status (Rendering k/N → connected)
+   * @param {Object} opts - { current, total, done }
+   */
+  async updateRenderState(opts) {
+    await this.client._ensureZVaFManager();
+    return this.client.zvafManager.updateRenderState(opts);
+  }
+
+  /**
+   * Populate navbar from embedded config
+   * Uses zuiConfig from server, fetches fresh on auth change
+   */
+  async populateNavBar() {
+    await this.client._ensureZVaFManager();
+    return this.client.zvafManager.populateNavBar();
+  }
+
+  /**
+   * Fetch fresh navbar from API and populate (used after auth state changes)
+   */
+  async fetchAndPopulateNavBar(navHtmlFromServer = null) {
+    await this.client._ensureZVaFManager();
+    return this.client.zvafManager.fetchAndPopulateNavBar(navHtmlFromServer);
+  }
+
+  /**
+   * Enable client-side navigation (SPA-style) for navbar links
+   * Intercepts clicks to prevent full page reloads and uses WebSocket instead
+   */
+  async enableClientSideNavigation() {
+    await this.client._ensureNavigationManager();
+    return this.client.navigationManager.enableClientSideNavigation();
+  }
+
+  /**
+   * Navigate to a route via WebSocket (client-side navigation)
+   * @param {string} routePath - Path to navigate to (e.g., '/zAbout', '/zAccount')
+   * @param {Object} options - Navigation options
+   */
+  async navigateToRoute(routePath, options = {}) {
+    await this.client._ensureNavigationManager();
+    return this.client.navigationManager.navigateToRoute(routePath, options);
+  }
+
+  /**
+   * Freeze the page currently on screen into the trail (offline-browse).
+   */
+  async snapshotCurrentPage() {
+    await this.client._ensureNavigationManager();
+    return this.client.navigationManager.snapshotCurrentPage();
+  }
+}

package/L4_Orchestration/lifecycle/lifecycle.js

@@ -0,0 +1,8 @@
+/**
+ * L4_Orchestration/lifecycle/lifecycle.js
+ * 
+ * Lifecycle Management Barrel
+ */
+
+export { Initializer } from './initializer.js';
+export { AssetLoader } from './asset_loader.js';