@zolomedia/bifrost-client 1.7.74

package/zSys/dom/encoding_utils.js

@@ -0,0 +1,117 @@
+/**
+ * ═══════════════════════════════════════════════════════════════
+ * Encoding Utilities - String Encoding/Decoding (Layer 2)
+ * ═══════════════════════════════════════════════════════════════
+ * 
+ * Pure utility functions for string encoding and decoding operations.
+ * Extracted from duplicate implementations in 4 renderer files.
+ * 
+ * @module utils/encoding_utils
+ * @layer 2 (Utilities - Pure functions)
+ * 
+ * Dependencies: None (Layer 0 - Browser APIs only)
+ * 
+ * Exports:
+ * - decodeUnicodeEscapes(text): Decode Unicode escape sequences
+ * - escapeHtml(text): Escape the 5 HTML-significant chars (SSOT — text & attr safe)
+ * - safeHref(url): Block dangerous URL schemes + attr-escape (SSOT for href values)
+ * 
+ * Example:
+ * ```javascript
+ * import { decodeUnicodeEscapes, escapeHtml, safeHref } from '../../zSys/dom/encoding_utils.js';
+ * const decoded = decodeUnicodeEscapes('Hello \\u2764\\uFE0F'); // "Hello ❤️"
+ * el.innerHTML = `<a href="${safeHref(url)}">${escapeHtml(label)}</a>`;
+ * ```
+ */
+
+// ─────────────────────────────────────────────────────────────────
+// HTML Escaping (SSOT) — replaces per-renderer ad-hoc escape chains
+// ─────────────────────────────────────────────────────────────────
+
+const _HTML_ESCAPES = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#039;',
+};
+
+/**
+ * Escape the five HTML-significant characters. Safe for both element text and
+ * double/single-quoted attribute contexts (escapes both " and '). Deterministic,
+ * no DOM dependency. This is the single source of truth for HTML escaping in the
+ * client — renderers must not hand-roll their own `.replace(/&/g, ...)` chains.
+ *
+ * @param {*} text - Value to escape (coerced to string; null/undefined → '')
+ * @returns {string} Escaped string
+ */
+export function escapeHtml(text) {
+  if (text === null || text === undefined) return '';
+  return String(text).replace(/[&<>"']/g, (ch) => _HTML_ESCAPES[ch]);
+}
+
+// Schemes that can execute script / smuggle payloads when placed in href/src.
+const _DANGEROUS_SCHEME = /^(javascript|data|vbscript):/i;
+
+/**
+ * Sanitize a URL for safe embedding in an href/src attribute. Blocks dangerous
+ * schemes (javascript:, data:, vbscript:) — including whitespace/control-char
+ * obfuscation — then attribute-escapes the result. Returns '#' for blocked or
+ * empty input. http(s)/mailto/tel/anchor/relative/zPath URLs pass through.
+ *
+ * @param {*} url - Candidate URL (already zPath-resolved by the caller)
+ * @returns {string} Safe, attribute-escaped URL or '#'
+ */
+export function safeHref(url) {
+  if (url === null || url === undefined) return '#';
+  const raw = String(url).trim();
+  if (!raw) return '#';
+  // Strip whitespace + control chars before the scheme test so "java\tscript:"
+  // and "  javascript:" cannot slip past the guard.
+  const probe = raw.replace(/[\u0000-\u001F\u007F\s]/g, '');
+  if (_DANGEROUS_SCHEME.test(probe)) return '#';
+  return escapeHtml(raw);
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Unicode Decoding
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Decode Unicode escape sequences in text
+ * 
+ * Handles multiple Unicode escape formats:
+ * - \uXXXX: Standard 4-digit Unicode escape (e.g., \u2764 → ❤)
+ * - \UXXXXXXXX: Extended 4-8 digit for supplementary characters & emojis
+ * - Basic escape sequences: \n, \t, \r, etc.
+ * 
+ * @param {string} text - Text containing Unicode escapes
+ * @returns {string} Decoded text
+ * 
+ * @example
+ * decodeUnicodeEscapes('Hello \\u2764\\uFE0F'); // "Hello ❤️"
+ * decodeUnicodeEscapes('Line 1\\nLine 2'); // "Line 1\nLine 2"
+ * decodeUnicodeEscapes('\\U0001F600'); // "😀"
+ */
+export function 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));
+  });
+  
+  // Replace basic escape sequences (literal strings like \\n, \\t, etc.)
+  // These come from JSON where Python sends "\n" which becomes "\\n" in JSON
+  text = text.replace(/\\n/g, '\n');
+  text = text.replace(/\\r/g, '\r');
+  text = text.replace(/\\t/g, '\t');
+  text = text.replace(/\\\\/g, '\\');
+  
+  return text;
+}

package/zSys/dom/style_utils.js

@@ -0,0 +1,71 @@
+/**
+ * zSys/dom/style_utils.js
+ * 
+ * Style Conversion Utilities
+ * 
+ * Handles _zStyle metadata conversion from various formats to CSS strings.
+ * Supports both legacy inline string format and new nested object syntax.
+ * 
+ * Created: 2026-04-19 - Phase 1.0 - _zStyle nested syntax migration
+ */
+
+/**
+ * Convert _zStyle to CSS string
+ * 
+ * Supports two formats:
+ * 1. String (legacy): "color: red; font-size: 16px"
+ * 2. Object (nested): { "color": "red", "font-size": "16px" }
+ * 
+ * @param {string|Object} style - CSS string or object with CSS properties
+ * @param {Object} [logger=null] - Optional logger for warnings
+ * @returns {string} CSS string for style attribute (empty string if invalid)
+ * 
+ * @example
+ * // String passthrough (legacy/inline)
+ * convertStyleToString("color: red; font-size: 16px")
+ * // => "color: red; font-size: 16px"
+ * 
+ * @example
+ * // Object to CSS string (new nested syntax)
+ * convertStyleToString({
+ *   "border-bottom": "2px solid var(--color-primary)",
+ *   "background": "red",
+ *   "letter-spacing": "0.1em"
+ * })
+ * // => "border-bottom: 2px solid var(--color-primary); background: red; letter-spacing: 0.1em"
+ * 
+ * @example
+ * // CSS variables work in both formats
+ * convertStyleToString({ "color": "var(--color-primary)" })
+ * // => "color: var(--color-primary)"
+ * 
+ * @example
+ * // Empty/null/undefined values filtered out
+ * convertStyleToString({ "color": "red", "background": null, "font-size": "" })
+ * // => "color: red"
+ */
+export function convertStyleToString(style, logger = null) {
+  // Handle null/undefined
+  if (style === null || style === undefined || style === '') {
+    return '';
+  }
+
+  // Legacy format: inline CSS string
+  if (typeof style === 'string') {
+    return style.trim();
+  }
+  
+  // New format: nested object (CSS-in-YAML)
+  if (typeof style === 'object' && !Array.isArray(style)) {
+    const cssString = Object.entries(style)
+      .filter(([_, value]) => value !== undefined && value !== null && value !== '')
+      .map(([prop, value]) => `${prop}: ${value}`)
+      .join('; ');
+    
+    return cssString;
+  }
+  
+  // Invalid type
+  logger?.warn(`[StyleUtils] Invalid _zStyle type: ${typeof style}`, style);
+  return '';
+}

package/zSys/errors/error_display.js

@@ -0,0 +1,299 @@
+/**
+ * 
+ * Error Display Module - Visual Error Boundaries for UI
+ * 
+ */
+
+export class ErrorDisplay {
+  constructor(options = {}) {
+    this.containerId = options.containerId || 'bifrost-errors';
+    this.autoCreate = options.autoCreate !== false; // Default true
+    this.maxErrors = options.maxErrors || 5; // Max errors to show
+    this.autoDismiss = options.autoDismiss || 10000; // TIMEOUTS.AUTO_DISMISS (UMD limitation, can't import)
+    this.position = options.position || 'top-right'; // top-right, top-left, bottom-right, bottom-left
+
+    this.errors = [];
+    this.container = null;
+    // Dedup: collapse repeated identical errors (e.g. WebSocket reconnect loops,
+    // missing _requestId) into ONE toast with a ×N counter. Repeats after the
+    // first go to the console only — dev-accurate without the UX spam.
+    this._active = new Map(); // key -> { el, countEl, count, timer }
+
+    if (this.autoCreate) {
+      this._createContainer();
+    }
+  }
+
+  /**
+   * Create error container if it doesn't exist
+   * @private
+   */
+  _createContainer() {
+    // Check if container already exists
+    this.container = document.getElementById(this.containerId);
+
+    if (!this.container) {
+      this.container = document.createElement('div');
+      this.container.id = this.containerId;
+
+      // Canonical, class-based styling (SSOT in zbase.css) — no inline styles.
+      // A corner modifier selects the fixed position.
+      const corner = ['top-right', 'top-left', 'bottom-right', 'bottom-left']
+        .includes(this.position) ? this.position : 'top-right';
+      this.container.className =
+        `bifrost-error-container bifrost-error-container--${corner}`;
+
+      // Centralize under the <zVaF> root (SSOT — all bifrost chrome lives there);
+      // fall back to <body> if the root isn't present yet.
+      const root = document.querySelector('zVaF') || document.body;
+      root.appendChild(this.container);
+    }
+  }
+
+  /**
+   * Display an error in the UI
+   */
+  show(errorInfo) {
+    if (!this.container) {
+      this._createContainer();
+    }
+
+    // ── Dedup ──────────────────────────────────────────────────────────────
+    // Same title+message already on screen → don't stack another toast. Bump its
+    // ×N counter, refresh its auto-dismiss, and log the repeat to the console.
+    const dedupeKey = `${this._getErrorTitle(errorInfo)}::${errorInfo.message || ''}`;
+    const existing = this._active.get(dedupeKey);
+    if (existing && existing.el && existing.el.parentNode) {
+      existing.count += 1;
+      if (existing.countEl) existing.countEl.textContent = ` ×${existing.count}`;
+      if (typeof console !== 'undefined' && console.warn) {
+        console.warn('[Bifrost][repeat suppressed]', dedupeKey, errorInfo);
+      }
+      if (existing.timer) clearTimeout(existing.timer);
+      if (this.autoDismiss) {
+        existing.timer = setTimeout(() => this._dismissError(existing.el), this.autoDismiss);
+      }
+      return;
+    }
+
+    // Create error element
+    const errorEl = document.createElement('div');
+    errorEl.className = 'bifrost-error';
+    errorEl.style.cssText = `
+      background: #fee;
+      border-left: 4px solid #c33;
+      padding: 1rem;
+      margin-bottom: 0.5rem;
+      border-radius: 4px;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.15);
+      pointer-events: auto;
+      animation: slideIn 0.3s ease-out;
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      font-size: 0.875rem;
+      line-height: 1.5;
+    `;
+
+    // Error title
+    const title = document.createElement('div');
+    title.style.cssText = `
+      font-weight: 600;
+      color: #c33;
+      margin-bottom: 0.5rem;
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+    `;
+    title.innerHTML = `
+      <span>[WARN] ${this._getErrorTitle(errorInfo)}<span class="bifrost-error-count" style="font-weight:600;"></span></span>
+      <button style="
+        background: none;
+        border: none;
+        color: #c33;
+        cursor: pointer;
+        font-size: 1.2rem;
+        padding: 0;
+        margin-left: 0.5rem;
+        line-height: 1;
+      " title="Dismiss">×</button>
+    `;
+
+    // Error message
+    const message = document.createElement('div');
+    message.style.cssText = 'color: #600; margin-bottom: 0.5rem;';
+    message.textContent = errorInfo.message || 'An error occurred';
+
+    // Error details (collapsible)
+    const details = document.createElement('details');
+    details.style.cssText = 'color: #800; font-size: 0.75rem; margin-top: 0.5rem;';
+    details.innerHTML = `
+      <summary style="cursor: pointer; user-select: none;">Show details</summary>
+      <pre style="
+        margin-top: 0.5rem;
+        padding: 0.5rem;
+        background: #fff;
+        border-radius: 3px;
+        overflow-x: auto;
+        font-size: 0.7rem;
+        white-space: pre-wrap;
+        word-wrap: break-word;
+      ">${this._formatStack(errorInfo)}</pre>
+    `;
+
+    errorEl.appendChild(title);
+    errorEl.appendChild(message);
+    errorEl.appendChild(details);
+
+    // Add dismiss handler
+    const dismissBtn = title.querySelector('button');
+    dismissBtn.onclick = () => this._dismissError(errorEl);
+
+    // Add to container
+    this.container.appendChild(errorEl);
+    this.errors.push(errorEl);
+
+    // Register as the active toast for this dedupe key
+    const countEl = title.querySelector('.bifrost-error-count');
+    const entry = { el: errorEl, countEl, count: 1, timer: null, key: dedupeKey };
+    errorEl.dataset.dedupeKey = dedupeKey;
+    this._active.set(dedupeKey, entry);
+
+    // Remove oldest error if we exceed max
+    if (this.errors.length > this.maxErrors) {
+      const oldest = this.errors.shift();
+      if (oldest && oldest.parentNode) {
+        oldest.remove();
+      }
+    }
+
+    // Auto-dismiss after timeout
+    if (this.autoDismiss) {
+      entry.timer = setTimeout(() => this._dismissError(errorEl), this.autoDismiss);
+    }
+
+    // Add slide-in animation
+    this._addAnimationStyles();
+  }
+
+  /**
+   * Dismiss an error
+   * @private
+   */
+  _dismissError(errorEl) {
+    if (!errorEl || !errorEl.parentNode) {
+      return;
+    }
+
+    // Fade out animation
+    errorEl.style.animation = 'fadeOut 0.3s ease-out';
+
+    // Release the dedupe slot so a later occurrence can toast fresh
+    const key = errorEl.dataset ? errorEl.dataset.dedupeKey : null;
+    if (key && this._active.get(key)?.el === errorEl) {
+      const entry = this._active.get(key);
+      if (entry.timer) clearTimeout(entry.timer);
+      this._active.delete(key);
+    }
+
+    setTimeout(() => {
+      if (errorEl.parentNode) {
+        errorEl.remove();
+      }
+      const index = this.errors.indexOf(errorEl);
+      if (index > -1) {
+        this.errors.splice(index, 1);
+      }
+    }, 300);  // TIMEOUTS.FADE_TRANSITION (UMD limitation, can't import)
+  }
+
+  /**
+   * Get error title based on error type
+   * @private
+   */
+  _getErrorTitle(errorInfo) {
+    if (errorInfo.type === 'hook_error') {
+      return `Hook Error: ${errorInfo.hookName}`;
+    }
+    if (errorInfo.type === 'render_error') {
+      return 'Rendering Error';
+    }
+    if (errorInfo.type === 'connection_error') {
+      return 'Connection Error';
+    }
+    return 'BifrostClient Error';
+  }
+
+  /**
+   * Format error stack for display
+   * @private
+   */
+  _formatStack(errorInfo) {
+    if (errorInfo.stack) {
+      return errorInfo.stack;
+    }
+    if (errorInfo.error && errorInfo.error.stack) {
+      return errorInfo.error.stack;
+    }
+    return JSON.stringify(errorInfo, null, 2);
+  }
+
+  /**
+   * Add animation styles to document
+   * @private
+   */
+  _addAnimationStyles() {
+    if (document.getElementById('bifrost-error-styles')) {
+      return;
+    }
+
+    const style = document.createElement('style');
+    style.id = 'bifrost-error-styles';
+    style.textContent = `
+      @keyframes slideIn {
+        from {
+          transform: translateX(100%);
+          opacity: 0;
+        }
+        to {
+          transform: translateX(0);
+          opacity: 1;
+        }
+      }
+      
+      @keyframes fadeOut {
+        from {
+          opacity: 1;
+        }
+        to {
+          opacity: 0;
+        }
+      }
+    `;
+    document.head.appendChild(style);
+  }
+
+  /**
+   * Clear all errors
+   */
+  clearAll() {
+    this.errors.forEach(errorEl => {
+      if (errorEl.parentNode) {
+        errorEl.remove();
+      }
+    });
+    this.errors = [];
+    this._active.forEach(entry => { if (entry.timer) clearTimeout(entry.timer); });
+    this._active.clear();
+  }
+
+  /**
+   * Destroy error display (remove container)
+   */
+  destroy() {
+    this.clearAll();
+    if (this.container && this.container.parentNode) {
+      this.container.remove();
+    }
+    this.container = null;
+  }
+}
+

package/zSys/errors/errors.js

@@ -0,0 +1,10 @@
+/**
+ * zSys/errors - Error Utilities Barrel
+ * 
+ * Error display and formatting utilities.
+ * 
+ * @module zSys/errors
+ * @layer zSys (System Utilities)
+ */
+
+export * from './error_display.js';