@zolomedia/bifrost-client 1.7.74

package/L2_Handling/display/outputs/alert_renderer.js

@@ -0,0 +1,161 @@
+/**
+ * 
+ * Alert Renderer - Signal/Feedback Messages
+ * 
+ *
+ * Renders alert/signal events from zCLI backend (zSignals subsystem).
+ * Provides visual feedback for success, info, warning, and error states.
+ *
+ * @module rendering/alert_renderer
+ * @layer 3
+ * @pattern Strategy (single event family)
+ *
+ * Philosophy:
+ * - "Terminal first" - alerts are visual feedback primitives
+ * - Pure rendering (no auto-dismiss, no complex animations)
+ * - Semantic colors (success=green, info=blue, warning=orange, error=red)
+ * - Uses Layer 2 utilities exclusively (no inline logic)
+ *
+ * Dependencies:
+ * - Layer 2: dom_utils.js, ztheme_utils.js
+ *
+ * Exports:
+ * - AlertRenderer: Class for rendering alert/signal events
+ *
+ * Example:
+ * ```javascript
+ * import { AlertRenderer } from './alert_renderer.js';
+ *
+ * const renderer = new AlertRenderer(logger);
+ * renderer.render({
+ *   content: 'Operation successful!',
+ *   eventType: 'success'
+ * }, 'zVaF');
+ * ```
+ */
+
+// ─────────────────────────────────────────────────────────────────
+// Imports
+// ─────────────────────────────────────────────────────────────────
+
+// Layer 2: Utilities
+import { createElement, setAttributes } from '../../../zSys/dom/dom_utils.js';
+import { getAlertColorClass } from '../../../zSys/theme/ztheme_utils.js';
+import { withErrorBoundary } from '../../../zSys/validation/error_boundary.js';
+
+// 
+// Alert Renderer Class
+// 
+
+/**
+ * AlertRenderer - Renders signal/alert events
+ *
+ * Handles zCLI signal events (error, warning, success, info) which
+ * provide visual feedback to users. Maps to zTheme's zSignal components.
+ *
+ * Event Mapping:
+ * - error   → zSignal-error   (red)
+ * - warning → zSignal-warning (orange)
+ * - success → zSignal-success (green)
+ * - info    → zSignal-info    (blue)
+ */
+export class AlertRenderer {
+  /**
+   * Create an AlertRenderer instance
+   * @param {Object} logger - Logger instance for debugging
+   */
+  constructor(logger) {
+    this.logger = logger || console;
+    this.logger.debug('[AlertRenderer] Initialized');
+
+    // Wrap render method with error boundary
+    const originalRender = this.render.bind(this);
+    this.render = withErrorBoundary(originalRender, {
+      component: 'AlertRenderer',
+      logger: this.logger
+    });
+  }
+
+  /**
+   * Render an alert/signal event
+   *
+   * @param {Object} data - Alert event data
+   * @param {string} data.content - Alert message text
+   * @param {string} data.eventType - Event type (error, warning, success, info)
+   * @param {number} [data.indent=0] - Indentation level (0 = no indent)
+   * @param {string} [data.class] - Custom CSS class (optional)
+   * @param {string} zone - Target DOM element ID
+   * @returns {HTMLElement|null} Created alert element or null if failed
+   *
+   * @example
+   * renderer.render({ content: 'Success!', eventType: 'success' }, 'zVaF');
+   * renderer.render({ content: 'Warning!', eventType: 'warning', indent: 1 }, 'zVaF');
+   * renderer.render({ content: 'Error!', eventType: 'error' }, 'zVaF');
+   */
+  render(data, zone) {
+    const { content, eventType, indent = 0, class: customClass } = data;
+
+    // Validate required parameters
+    if (!content) {
+      this.logger.error('[AlertRenderer] [ERROR] Missing required parameter: content');
+      return null;
+    }
+
+    if (!eventType) {
+      this.logger.error('[AlertRenderer] [ERROR] Missing required parameter: eventType');
+      return null;
+    }
+
+    // Get target container
+    const container = document.getElementById(zone);
+    if (!container) {
+      this.logger.error(`[AlertRenderer] [ERROR] Zone not found: ${zone}`);
+      return null;
+    }
+
+    // Build CSS classes array
+    const classes = ['zSignal'];
+
+    // Add alert color class (uses Layer 2 utility)
+    const alertClass = getAlertColorClass(eventType);
+    if (alertClass) {
+      classes.push(alertClass);
+    }
+
+    // Add custom class if provided (from YAML)
+    if (customClass) {
+      classes.push(customClass);
+    }
+
+    // Create alert element (using Layer 2 utility)
+    const alert = createElement('div', classes);
+    alert.textContent = content; // Use textContent for XSS safety
+
+    // Apply attributes
+    const attributes = {
+      role: 'alert' // ARIA role for accessibility
+    };
+
+    // Apply indent as inline style (zTheme doesn't have indent utilities)
+    // Each indent level = 1rem left margin
+    if (indent > 0) {
+      attributes.style = `margin-left: ${indent}rem;`;
+    }
+
+    setAttributes(alert, attributes);
+
+    // Append to container
+    container.appendChild(alert);
+
+    // Log success
+    this.logger.log(`[AlertRenderer] Rendered ${eventType} alert (${content.length} chars, indent: ${indent})`);
+
+    return alert;
+  }
+}
+
+// 
+// Default Export
+// 
+export default AlertRenderer;
+

package/L2_Handling/display/outputs/audio_renderer.js

@@ -0,0 +1,94 @@
+/**
+ *
+ * Audio Renderer - Media Display Events
+ *
+ * Terminal-First Design:
+ * - Backend sends src, alt_text, caption (works with URLs, served paths)
+ * - Terminal displays metadata + button to open (zOpen)
+ * - Bifrost renders a native <audio controls> element with zTheme styling
+ *
+ * Mirrors ImageRenderer / VideoRenderer: primitives-first, _zClass / _id
+ * passthrough, optional <figure>/<figcaption> when a caption is present.
+ *
+ * @module rendering/audio_renderer
+ * @layer 3
+ * @pattern Primitives-First
+ *
+ * Exports:
+ * - AudioRenderer: Class for rendering audio events
+ */
+
+import { withErrorBoundary } from '../../../zSys/validation/error_boundary.js';
+
+export class AudioRenderer {
+  constructor(logger) {
+    this.logger = logger;
+
+    const originalRender = this.render.bind(this);
+    this.render = withErrorBoundary(originalRender, {
+      component: 'AudioRenderer',
+      logger: this.logger
+    });
+  }
+
+  /**
+   * Render an <audio> element from event primitives.
+   *
+   * @param {Object} eventData - Event data from backend
+   * @param {string} eventData.src - Audio source (URL or served path)
+   * @param {string} [eventData.alt_text] - Accessibility label (→ aria-label)
+   * @param {string} [eventData.caption] - Optional caption (→ <figcaption>)
+   * @param {boolean} [eventData.loop] - Loop playback
+   * @param {boolean} [eventData.muted] - Start muted
+   * @param {string} [eventData._zClass] - Custom classes for styling
+   * @param {string} [eventData._id] - Custom DOM id for targeting
+   * @returns {HTMLElement} Audio element (or <figure> when captioned)
+   */
+  render(eventData) {
+    const { src, alt_text, caption, _zClass, _id, loop, muted } = eventData;
+
+    if (!src) {
+      this.logger.error('[AudioRenderer] Missing src parameter');
+      return this._createErrorElement();
+    }
+
+    this.logger.debug(`[AudioRenderer] Rendering audio: ${src}`);
+
+    const audio = document.createElement('audio');
+    audio.src = src;
+    audio.controls = true;
+    audio.preload = 'metadata';
+    audio.style.maxWidth = '100%';
+
+    if (_zClass) audio.className = _zClass;
+    if (_id) audio.setAttribute('id', _id);
+    if (alt_text) audio.setAttribute('aria-label', alt_text);
+    if (loop) audio.loop = true;
+    if (muted) audio.muted = true;
+
+    if (caption) {
+      const figure = document.createElement('figure');
+      figure.appendChild(audio);
+      const figcaption = document.createElement('figcaption');
+      figcaption.textContent = caption;
+      figcaption.className = 'zText-muted zText-center zmt-2';
+      figure.appendChild(figcaption);
+      // _zClass/_zStyle live on the inner <audio>; skip the central pass on the wrapper.
+      figure.__zMetaScoped = true;
+      this.logger.debug('[AudioRenderer] Audio with caption rendered');
+      return figure;
+    }
+
+    this.logger.debug('[AudioRenderer] Audio rendered');
+    return audio;
+  }
+
+  _createErrorElement() {
+    const error = document.createElement('div');
+    error.className = 'zAlert zAlert-danger';
+    error.textContent = '[WARN] Audio source missing';
+    return error;
+  }
+}
+
+export default AudioRenderer;

package/L2_Handling/display/outputs/card_renderer.js

@@ -0,0 +1,229 @@
+/**
+ * 
+ * Card Renderer - zTheme Card Components
+ * 
+ *
+ * Renders card/panel components aligned with zTheme card system:
+ * - zCard (basic cards with proper body wrapper)
+ * - zCard-header/footer (optional sections)
+ * - zCard-title/subtitle/text (typography)
+ * - Color variants (zCard-primary, zCard-success, etc.)
+ *
+ *  REFACTORED: Uses Layer 0 primitives + Layer 2 utilities
+ *
+ * @module rendering/card_renderer
+ * @layer 3
+ * @pattern Strategy (card components)
+ *
+ * @see https://github.com/ZoloAi/zTheme/blob/main/src/css/zCards.css
+ */
+
+// ─────────────────────────────────────────────────────────────────
+// Imports
+// ─────────────────────────────────────────────────────────────────
+
+// Layer 0: Primitives
+import { createDiv } from '../primitives/generic_containers.js';
+import { createHeading, createParagraph } from '../primitives/typography_primitives.js';
+
+export default class CardRenderer {
+  /**
+   * Create a CardRenderer instance
+   * @param {Object} logger - Logger instance for debugging
+   */
+  constructor(logger) {
+    this.logger = logger || console;
+    this.logger.debug('[CardRenderer] Initialized');
+  }
+
+  /**
+   * Enhance a container with proper zCard structure
+   *
+   * Transforms:
+   *   <div class="zCard">
+   *     <h2>Title</h2>
+   *     <p>Content</p>
+   *   </div>
+   *
+   * Into:
+   *   <div class="zCard">
+   *     <div class="zCard-body">
+   *       <h2 class="zCard-title">Title</h2>
+   *       <p class="zCard-text">Content</p>
+   *     </div>
+   *   </div>
+   *
+   * @param {HTMLElement} container - Container element with zCard class
+   * @returns {HTMLElement} Enhanced card element
+   */
+  enhanceCard(container) {
+    if (!container || !container.classList.contains('zCard')) {
+      return container;
+    }
+
+    // Check if zCard-body already exists
+    const existingBody = container.querySelector(':scope > .zCard-body');
+    if (existingBody) {
+      this.logger.log('[CardRenderer] Card already has zCard-body, skipping enhancement');
+      return container;
+    }
+
+    // Create zCard-body wrapper (using primitive)
+    const cardBody = createDiv({ class: 'zCard-body' });
+
+    // Move all direct children into the card body
+    while (container.firstChild) {
+      const child = container.firstChild;
+
+      // Apply zCard typography classes based on element type
+      if (child.nodeType === Node.ELEMENT_NODE) {
+        this._applyCardTypography(child);
+      }
+
+      cardBody.appendChild(child);
+    }
+
+    // Append the card body back to the container
+    container.appendChild(cardBody);
+
+    this.logger.log('[CardRenderer] Enhanced card with zCard-body wrapper');
+    return container;
+  }
+
+  /**
+   * Apply zCard typography classes to elements
+   * @private
+   * @param {HTMLElement} element - Element to enhance
+   */
+  _applyCardTypography(element) {
+    const tagName = element.tagName.toLowerCase();
+
+    // Apply zCard-title to first heading (h1-h6)
+    if (['h1', 'h2', 'h3', 'h4', 'h5', 'h6'].includes(tagName)) {
+      // Check if this is the first heading in the card
+      const parentCard = element.closest('.zCard');
+      if (parentCard) {
+        const existingTitle = parentCard.querySelector('.zCard-title');
+        if (!existingTitle) {
+          element.classList.add('zCard-title');
+          this.logger.log(`[CardRenderer] Applied zCard-title to ${tagName}`);
+        } else {
+          // Subsequent headings could be subtitles
+          element.classList.add('zCard-subtitle');
+          this.logger.log(`[CardRenderer] Applied zCard-subtitle to ${tagName}`);
+        }
+      }
+    } else if (tagName === 'p') {
+      // Apply zCard-text to paragraphs
+      element.classList.add('zCard-text');
+      this.logger.log('[CardRenderer] Applied zCard-text to paragraph');
+    }
+  }
+
+  /**
+   * Create a complete card from scratch
+   *
+   * @param {Object} options - Card configuration
+   * @param {string} [options.title] - Card title
+   * @param {string} [options.subtitle] - Card subtitle
+   * @param {string} [options.text] - Card text content
+   * @param {string} [options.variant] - Color variant (primary, success, info, etc.)
+   * @param {string} [options.header] - Header text
+   * @param {string} [options.footer] - Footer text
+   * @param {string} [options.classes] - Additional CSS classes
+   * @returns {HTMLElement} Complete card element
+   */
+  createCard(options = {}) {
+    const {
+      title = '',
+      subtitle = '',
+      text = '',
+      variant = null,
+      header = null,
+      footer = null,
+      classes = ''
+    } = options;
+
+    // Create card container (using primitive)
+    const card = createDiv({ class: 'zCard' });
+
+    // Apply variant class
+    if (variant) {
+      card.classList.add(`zCard-${variant}`);
+    }
+
+    // Apply additional classes
+    if (classes) {
+      const classList = classes.split(' ').filter(c => c.trim());
+      card.classList.add(...classList);
+    }
+
+    // Add header if provided (using primitive)
+    if (header) {
+      const headerEl = createDiv({ class: 'zCard-header' });
+      headerEl.textContent = header;
+      card.appendChild(headerEl);
+    }
+
+    // Create card body (using primitive)
+    const cardBody = createDiv({ class: 'zCard-body' });
+
+    // Add title (using primitive)
+    if (title) {
+      const titleEl = createHeading(2, { class: 'zCard-title' });
+      titleEl.textContent = title;
+      cardBody.appendChild(titleEl);
+    }
+
+    // Add subtitle (using primitive)
+    if (subtitle) {
+      const subtitleEl = createHeading(6, { class: 'zCard-subtitle zmb-2 zText-muted' });
+      subtitleEl.textContent = subtitle;
+      cardBody.appendChild(subtitleEl);
+    }
+
+    // Add text content (using primitive)
+    if (text) {
+      const textEl = createParagraph({ class: 'zCard-text' });
+      textEl.textContent = text;
+      cardBody.appendChild(textEl);
+    }
+
+    card.appendChild(cardBody);
+
+    // Add footer if provided (using primitive)
+    if (footer) {
+      const footerEl = createDiv({ class: 'zCard-footer zText-muted' });
+      footerEl.textContent = footer;
+      card.appendChild(footerEl);
+    }
+
+    this.logger.log('[CardRenderer] Created card:', {title, variant, hasHeader: !!header, hasFooter: !!footer});
+
+    return card;
+  }
+
+  /**
+   * Extract card variant from color code
+   * @param {string} color - Color code (PRIMARY, SUCCESS, etc.)
+   * @returns {string|null} Card variant class or null
+   */
+  getCardVariant(color) {
+    if (!color) {
+      return null;
+    }
+
+    const variantMap = {
+      'PRIMARY': 'primary',
+      'SECONDARY': 'secondary',
+      'SUCCESS': 'success',
+      'INFO': 'info',
+      'WARNING': 'warning',
+      'DANGER': 'danger',
+      'LIGHT': 'light',
+      'DARK': 'dark'
+    };
+
+    return variantMap[color.toUpperCase()] || null;
+  }
+}

package/L2_Handling/display/outputs/code_renderer.js

@@ -0,0 +1,66 @@
+/**
+ * Code Renderer - Renders `code` display events
+ *
+ * Handles the 'code' zDisplay event, which is the SSOT for code block
+ * rendering shared by:
+ * - zCode shorthand
+ * - zMD code fences (delegated from markdown_parser.py)
+ * - zTerminal preview (delegated from terminal_executor.py)
+ *
+ * Produces a <pre><code class="language-{lang}"> block.
+ * Prism.js (if loaded) will auto-highlight based on the language class.
+ *
+ * @module rendering/code_renderer
+ * @layer 3
+ * @pattern Strategy (single event type)
+ */
+
+import { createLanguagePre } from '../primitives/semantic_element_primitive.js';
+import { withErrorBoundary } from '../../../zSys/validation/error_boundary.js';
+
+export class CodeRenderer {
+  /**
+   * @param {Object} logger - Logger instance
+   */
+  constructor(logger) {
+    this.logger = logger || console;
+    this.logger.debug('[CodeRenderer] Initialized');
+
+    const originalRenderCode = this.renderCode.bind(this);
+    this.renderCode = withErrorBoundary(originalRenderCode, {
+      component: 'CodeRenderer.renderCode',
+      logger: this.logger
+    });
+  }
+
+  /**
+   * Render a code block element.
+   *
+   * @param {Object} eventData
+   * @param {string} eventData.content   - Raw code content
+   * @param {string} [eventData.language] - Programming language (e.g. 'python', 'js', 'zolo')
+   * @param {number} [eventData.indent]   - Indentation level (unused in HTML; kept for symmetry)
+   * @returns {HTMLElement} <pre><code> element
+   */
+  renderCode(eventData) {
+    const content = eventData.content || '';
+    const language = eventData.language || null;
+
+    this.logger.debug(`[CodeRenderer] renderCode: language=${language}, length=${content.length}`);
+
+    const attrs = {};
+    if (eventData.zId || eventData._zId || eventData._id) {
+      attrs.id = eventData.zId || eventData._zId || eventData._id;
+    }
+    // _zClass is applied centrally by the orchestrator (SSOT); only legacy `class`
+    // is honoured here as a creation-time attribute.
+    if (eventData.class) {
+      attrs.class = eventData.class;
+    }
+
+    const element = createLanguagePre(language || 'text', content, attrs);
+    return element;
+  }
+}
+
+export default CodeRenderer;

package/L2_Handling/display/outputs/dl_renderer.js

@@ -0,0 +1,131 @@
+/**
+ * DL Renderer - Description List Rendering
+ * 
+ * Renders HTML description lists (<dl>, <dt>, <dd>) from zDisplay events.
+ * 
+ * Extracted from zdisplay_renderer.js (Phase 9, Task 3.2)
+ * 
+ * @module display/outputs/dl_renderer
+ * @layer L2 (Handling)
+ */
+
+export class DLRenderer {
+  constructor(logger) {
+    this.logger = logger;
+  }
+
+  /**
+   * Render a description list element
+   * @param {Object} event - DL event data
+   * @param {Array} event.items - Array of {term, desc} objects
+   * @param {string} event._zClass - Optional CSS classes
+   * @param {number} event.indent - Optional indent level
+   * @returns {HTMLElement} - Description list element
+   */
+  render(event) {
+    const dl = document.createElement('dl');
+
+    // _zClass / _zStyle applied centrally by the orchestrator (SSOT) on this <dl>.
+
+    // Apply indent as left margin
+    if (event.indent && event.indent > 0) {
+      dl.style.marginLeft = `${event.indent}rem`;
+    }
+
+    // Render description list items
+    const items = event.items || [];
+    items.forEach(item => {
+      // Create <dt> for the term
+      const dt = document.createElement('dt');
+      const termContent = item.term || '';
+      dt.innerHTML = this._sanitizeHTML(this._decodeUnicodeEscapes(termContent));
+      dl.appendChild(dt);
+
+      // Create <dd> for description(s)
+      // desc can be a string or an array of strings
+      const descriptions = Array.isArray(item.desc) ? item.desc : [item.desc];
+      descriptions.forEach(desc => {
+        const dd = document.createElement('dd');
+        const descContent = desc || '';
+        dd.innerHTML = this._sanitizeHTML(this._decodeUnicodeEscapes(descContent));
+        dl.appendChild(dd);
+      });
+    });
+
+    return dl;
+  }
+
+  /**
+   * Decode Unicode escape sequences to actual characters
+   * Supports: \uXXXX (standard) and \UXXXXXXXX (extended) formats
+   * 
+   * Note: Basic escape sequences (\n, \t, etc.) are handled by JSON.parse()
+   * automatically when receiving data from backend. We only need to decode
+   * custom Unicode formats that JSON doesn't handle.
+   * 
+   * @param {string} text - Text containing Unicode escapes
+   * @returns {string} - Decoded text
+   * @private
+   */
+  _decodeUnicodeEscapes(text) {
+    if (!text || typeof text !== 'string') return text;
+    
+    // Replace \uXXXX format (standard 4-digit Unicode escape)
+    text = text.replace(/\\u([0-9A-Fa-f]{4})/g, (match, hexCode) => {
+      return String.fromCodePoint(parseInt(hexCode, 16));
+    });
+    
+    // Replace \UXXXXXXXX format (extended 4-8 digit for supplementary characters & emojis)
+    text = text.replace(/\\U([0-9A-Fa-f]{4,8})/g, (match, hexCode) => {
+      return String.fromCodePoint(parseInt(hexCode, 16));
+    });
+    
+    return text;
+  }
+
+  /**
+   * Sanitize HTML to prevent XSS attacks
+   * Allows common safe tags: <strong>, <em>, <code>, <a>, <br>, <span>
+   * 
+   * @param {string} html - HTML string to sanitize
+   * @returns {string} - Sanitized HTML
+   * @private
+   */
+  _sanitizeHTML(html) {
+    if (!html) {
+      return '';
+    }
+
+    // Allow common safe tags: <strong>, <em>, <code>, <a>, <br>
+    // This is a basic sanitizer - for production, consider using DOMPurify
+    const allowedTags = ['strong', 'em', 'code', 'a', 'br', 'span'];
+
+    // Create a temporary div to parse HTML
+    const temp = document.createElement('div');
+    temp.innerHTML = html;
+
+    // Remove script tags and event handlers
+    const scripts = temp.querySelectorAll('script');
+    scripts.forEach(script => script.remove());
+
+    // Remove event handler attributes (onclick, onerror, etc.)
+    const allElements = temp.querySelectorAll('*');
+    allElements.forEach(el => {
+      Array.from(el.attributes).forEach(attr => {
+        if (attr.name.startsWith('on')) {
+          el.removeAttribute(attr.name);
+        }
+      });
+
+      // Remove elements not in allowed list (except text nodes)
+      if (!allowedTags.includes(el.tagName.toLowerCase())) {
+        // Keep the text content but remove the tag
+        const textContent = el.textContent;
+        const textNode = document.createTextNode(textContent);
+        el.parentNode.replaceChild(textNode, el);
+      }
+    });
+
+    return temp.innerHTML;
+  }
+}