npm - @zolomedia/bifrost-client - Versions diffs - 1.7.74 - Mend

@zolomedia/bifrost-client 1.7.74

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (140) hide show

package/L1_Foundation/L1_Foundation.js +13 -0
package/L1_Foundation/bootstrap/bootstrap.js +11 -0
package/L1_Foundation/bootstrap/bootstrap_hooks.js +123 -0
package/L1_Foundation/bootstrap/bootstrap_index.js +15 -0
package/L1_Foundation/bootstrap/bootstrap_logger.js +135 -0
package/L1_Foundation/bootstrap/cdn_loader.js +217 -0
package/L1_Foundation/bootstrap/module_registry.js +102 -0
package/L1_Foundation/bootstrap/prism_loader.js +164 -0
package/L1_Foundation/config/client_config.js +110 -0
package/L1_Foundation/config/config.js +7 -0
package/L1_Foundation/connection/connection.js +8 -0
package/L1_Foundation/connection/websocket_connection.js +122 -0
package/L1_Foundation/constants/bifrost_constants.js +284 -0
package/L1_Foundation/constants/constants.js +7 -0
package/L1_Foundation/logger/logger.js +10 -0
package/L2_Handling/L2_Handling.js +15 -0
package/L2_Handling/cache/cache.js +22 -0
package/L2_Handling/cache/cache_constants.js +69 -0
package/L2_Handling/cache/orchestration/cache_manager.js +299 -0
package/L2_Handling/cache/orchestration/cache_orchestrator.js +260 -0
package/L2_Handling/cache/orchestration/orchestration.js +12 -0
package/L2_Handling/cache/storage/session_manager.js +289 -0
package/L2_Handling/cache/storage/storage.js +10 -0
package/L2_Handling/cache/storage/storage_manager.js +590 -0
package/L2_Handling/display/composite/composite.js +13 -0
package/L2_Handling/display/composite/dashboard_renderer.js +221 -0
package/L2_Handling/display/composite/swiper_renderer.js +564 -0
package/L2_Handling/display/composite/terminal_renderer.js +922 -0
package/L2_Handling/display/composite/wizard_conditional_renderer.js +274 -0
package/L2_Handling/display/display.js +30 -0
package/L2_Handling/display/feedback/feedback.js +11 -0
package/L2_Handling/display/feedback/progressbar_renderer.js +418 -0
package/L2_Handling/display/feedback/spinner_renderer.js +246 -0
package/L2_Handling/display/inputs/button_renderer.js +634 -0
package/L2_Handling/display/inputs/form_renderer.js +583 -0
package/L2_Handling/display/inputs/input_renderer.js +658 -0
package/L2_Handling/display/inputs/inputs.js +12 -0
package/L2_Handling/display/navigation/menu_renderer.js +206 -0
package/L2_Handling/display/navigation/navigation.js +11 -0
package/L2_Handling/display/navigation/navigation_renderer.js +703 -0
package/L2_Handling/display/orchestration/orchestration.js +11 -0
package/L2_Handling/display/orchestration/renderer.js +430 -0
package/L2_Handling/display/orchestration/zdisplay_orchestrator.js +1759 -0
package/L2_Handling/display/outputs/alert_renderer.js +161 -0
package/L2_Handling/display/outputs/audio_renderer.js +94 -0
package/L2_Handling/display/outputs/card_renderer.js +229 -0
package/L2_Handling/display/outputs/code_renderer.js +66 -0
package/L2_Handling/display/outputs/dl_renderer.js +131 -0
package/L2_Handling/display/outputs/header_renderer.js +162 -0
package/L2_Handling/display/outputs/icon_renderer.js +107 -0
package/L2_Handling/display/outputs/image_renderer.js +145 -0
package/L2_Handling/display/outputs/list_renderer.js +190 -0
package/L2_Handling/display/outputs/outputs.js +19 -0
package/L2_Handling/display/outputs/table_renderer.js +765 -0
package/L2_Handling/display/outputs/text_renderer.js +818 -0
package/L2_Handling/display/outputs/typography_renderer.js +293 -0
package/L2_Handling/display/outputs/video_renderer.js +116 -0
package/L2_Handling/display/primitives/document_structure_primitives.js +319 -0
package/L2_Handling/display/primitives/form_primitives.js +526 -0
package/L2_Handling/display/primitives/generic_containers.js +109 -0
package/L2_Handling/display/primitives/interactive_primitives.js +305 -0
package/L2_Handling/display/primitives/link_primitives.js +552 -0
package/L2_Handling/display/primitives/lists_primitives.js +262 -0
package/L2_Handling/display/primitives/media_primitives.js +383 -0
package/L2_Handling/display/primitives/primitives.js +19 -0
package/L2_Handling/display/primitives/semantic_element_primitive.js +226 -0
package/L2_Handling/display/primitives/table_primitives.js +528 -0
package/L2_Handling/display/primitives/typography_primitives.js +175 -0
package/L2_Handling/display/specialized/input_request_renderer.js +467 -0
package/L2_Handling/display/specialized/specialized.js +10 -0
package/L2_Handling/hooks/hooks.js +9 -0
package/L2_Handling/hooks/menu_integration.js +57 -0
package/L2_Handling/hooks/widget_hook_manager.js +292 -0
package/L2_Handling/message/message.js +8 -0
package/L2_Handling/message/message_handler.js +701 -0
package/L2_Handling/navigation/navigation.js +8 -0
package/L2_Handling/navigation/navigation_manager.js +403 -0
package/L2_Handling/zhooks/features/cache_live.js +287 -0
package/L2_Handling/zhooks/features/crumbs_live.js +292 -0
package/L2_Handling/zhooks/zhooks_manager.js +65 -0
package/L2_Handling/zvaf/zvaf.js +8 -0
package/L2_Handling/zvaf/zvaf_manager.js +334 -0
package/L3_Abstraction/L3_Abstraction.js +12 -0
package/L3_Abstraction/orchestrator/container_unwrapper.js +101 -0
package/L3_Abstraction/orchestrator/group_renderer.js +698 -0
package/L3_Abstraction/orchestrator/input_event_handler.js +797 -0
package/L3_Abstraction/orchestrator/metadata_processor.js +249 -0
package/L3_Abstraction/orchestrator/navbar_builder.js +201 -0
package/L3_Abstraction/orchestrator/orchestrator.js +13 -0
package/L3_Abstraction/orchestrator/wizard_gate_handler.js +360 -0
package/L3_Abstraction/renderer/renderer.js +1 -0
package/L3_Abstraction/session/session.js +1 -0
package/L4_Orchestration/L4_Orchestration.js +11 -0
package/L4_Orchestration/client/client.js +1 -0
package/L4_Orchestration/facade/facade.js +9 -0
package/L4_Orchestration/facade/manager_registry.js +118 -0
package/L4_Orchestration/facade/renderer_registry.js +274 -0
package/L4_Orchestration/lifecycle/asset_loader.js +255 -0
package/L4_Orchestration/lifecycle/initializer.js +135 -0
package/L4_Orchestration/lifecycle/lifecycle.js +8 -0
package/L4_Orchestration/rendering/facade.js +94 -0
package/L4_Orchestration/rendering/rendering.js +7 -0
package/LICENSE +21 -0
package/README.md +82 -0
package/bifrost_client.js +204 -0
package/bifrost_core.js +1686 -0
package/docs/ARCHITECTURE.md +111 -0
package/docs/PROTOCOL.md +106 -0
package/docs/RENDERERS.md +101 -0
package/docs/SECURITY.md +92 -0
package/package.json +24 -0
package/syntax/prism-zconfig.js +41 -0
package/syntax/prism-zenv.js +69 -0
package/syntax/prism-zolo-theme.css +288 -0
package/syntax/prism-zolo.js +380 -0
package/syntax/prism-zschema.js +38 -0
package/syntax/prism-zspark.js +25 -0
package/syntax/prism-zui.js +68 -0
package/zSys/accessibility/accessibility.js +10 -0
package/zSys/accessibility/emoji_accessibility.js +173 -0
package/zSys/dom/block_utils.js +122 -0
package/zSys/dom/container_utils.js +370 -0
package/zSys/dom/dom.js +13 -0
package/zSys/dom/dom_utils.js +328 -0
package/zSys/dom/encoding_utils.js +117 -0
package/zSys/dom/style_utils.js +71 -0
package/zSys/errors/error_display.js +299 -0
package/zSys/errors/errors.js +10 -0
package/zSys/theme/color_utils.js +274 -0
package/zSys/theme/dark_mode_utils.js +272 -0
package/zSys/theme/size_utils.js +256 -0
package/zSys/theme/spacing_utils.js +405 -0
package/zSys/theme/theme.js +14 -0
package/zSys/theme/zbase.css +1735 -0
package/zSys/theme/zbase_inject.js +161 -0
package/zSys/theme/ztheme_utils.js +305 -0
package/zSys/validation/error_boundary.js +201 -0
package/zSys/validation/validation.js +11 -0
package/zSys/validation/validation_utils.js +238 -0
package/zSys/zSys.js +14 -0

package/L2_Handling/zvaf/zvaf_manager.js ADDED Viewed

@@ -0,0 +1,334 @@
+/**
+ * ZVaFManager - Manages zVaF elements (badge, navbar, content area)
+ *
+ * Responsibilities:
+ * - Initialize zVaF elements (zBifrostBadge, zNavBar, zVaF)
+ * - Populate connection badge
+ * - Update badge state (connecting, connected, disconnected, error)
+ * - Populate navbar from embedded config or API
+ * - Fetch fresh navbar after auth state changes
+ *
+ * Extracted from bifrost_client.js (Phase 3.2)
+ */
+import { NavBarBuilder } from '../../L3_Abstraction/orchestrator/navbar_builder.js';
+export class ZVaFManager {
+  constructor(client) {
+    this.client = client;
+    this.logger = client.logger;
+    this.options = client.options;
+    this.zuiConfig = client.zuiConfig;
+  }
+  /**
+   * Initialize zVaF elements.
+   *
+   * SSOT (hard cut): <zVaF> is the bifrost ROOT — the single mount an app template
+   * provides. EVERYTHING bifrost-generated lives under it, never as stray <body>
+   * children:
+   *
+   *   <zVaF>                          ← root (template owns this tag only)
+   *     <zNavBar>…</zNavBar>          ← chrome (runtime-created), sticky top
+   *     <div id="zVaF-content">…</div>← the render/clear target (page content)
+   *     <zBifrostBadge>…</zBifrostBadge> ← chrome (runtime-created), fixed
+   *     <div class="bifrost-error-container">…</div> ← error toasts (lazy)
+   *
+   * Chrome are SIBLINGS of the content host, so re-renders (which wipe the content
+   * host) never destroy them. Position/look come purely from built-in zClass in
+   * zbase.css (navbar sticky, badge/errors fixed).
+   */
+  initZVaFElements() {
+    this.logger.debug('[ZVaFManager] Starting initialization');
+    if (typeof document === 'undefined') {
+      this.logger.warn('[ZVaFManager] Not in browser environment');
+      return;
+    }
+    // The <zVaF> ROOT is the only required mount (template owns the bare tag).
+    const zVaFRoot = document.querySelector(this.options.targetElement) ||
+                     document.getElementById(this.options.targetElement);
+    if (!zVaFRoot) {
+      this.logger.error(`[ZVaFManager] [ERROR] <${this.options.targetElement}> root not found in DOM`);
+      return;
+    }
+    this.client._zVaFRoot = zVaFRoot;
+    this.logger.debug('[ZVaFManager] zVaF root found');
+    // Inner content host (#zVaF-content) — THE render/clear target. Created inside
+    // the root so chrome siblings survive content re-renders.
+    let contentHost = zVaFRoot.querySelector('#zVaF-content');
+    if (!contentHost) {
+      contentHost = document.createElement('div');
+      contentHost.id = 'zVaF-content';
+      contentHost.className = 'zVaF-content';
+      zVaFRoot.appendChild(contentHost);
+      this.logger.debug('[ZVaFManager] Created content host #zVaF-content');
+    }
+    this.client._zVaFElement = contentHost;
+    // NavBar: sticky-top chrome → FIRST child of the root (above content).
+    const navElement = this._ensureChromeHost('zNavBar', (el) => {
+      zVaFRoot.insertBefore(el, zVaFRoot.firstChild);
+    });
+    if (navElement) {
+      this.client._zNavBarElement = navElement;
+      // Populate asynchronously (don't block initialization).
+      this.populateNavBar().catch(err => {
+        this.logger.error('[ZVaFManager] Failed to populate navbar:', err);
+      });
+      this.logger.debug('[ZVaFManager] NavBar host ready, populating');
+    }
+    // Badge: fixed chrome → appended to the root (DOM position is cosmetic; it's
+    // viewport-fixed via zbase.css). The badge is a core zHook — ON by default,
+    // opt out with zHooks: { badge: false }. When off, the element is never
+    // created and every updateBadgeState/updateRenderState call no-ops via its
+    // own _zConnectionBadge null-guard.
+    if (this._badgeEnabled()) {
+      const badgeElement = this._ensureChromeHost('zBifrostBadge', (el) => {
+        zVaFRoot.appendChild(el);
+      });
+      if (badgeElement) {
+        this.client._zConnectionBadge = badgeElement;
+        this.populateConnectionBadge();
+        this.logger.debug('[ZVaFManager] Badge host ready');
+      }
+    } else {
+      this.logger.debug('[ZVaFManager] Badge zHook disabled (zHooks.badge:false)');
+    }
+    // Client-side navigation (SPA link interception + popstate handler) is
+    // PAGE-LEVEL infrastructure — independent of whether this page renders a
+    // navbar. Enable it unconditionally here. Previously it was only wired from
+    // populateNavBar()'s navbar branches, so a zNavBar:false page loaded directly
+    // (hard reload) never registered the popstate listener → server-driven
+    // history.back() rewrote the URL without re-rendering. (populateNavBar still
+    // calls it too; enablement is idempotent.)
+    this.client._enableClientSideNavigation().catch(err => {
+      this.logger.error('[ZVaFManager] Failed to enable client-side navigation:', err);
+    });
+    this.logger.log('[ZVaFManager] All elements initialized under <zVaF> root');
+  }
+  /**
+   * Is the connection-badge zHook enabled? Default-on; opt out via
+   * zHooks: { badge: false }. (Core zHook — gated here, not loaded as a module.)
+   * @returns {boolean}
+   */
+  _badgeEnabled() {
+    const zHooks = this.options.zHooks || {};
+    return zHooks.badge !== false;
+  }
+  /**
+   * Ensure a runtime-owned chrome host element exists, returning it.
+   *
+   * Reuses an existing element if present (legacy templates); otherwise creates it
+   * and places it via `place(el)`. Hard-cut SSOT — <zNavBar>/<zBifrostBadge> are no
+   * longer required in app templates; the runtime creates them inside <zVaF>.
+   *
+   * @param {string} tagName - Custom element tag (zNavBar | zBifrostBadge)
+   * @param {(el: HTMLElement) => void} place - Inserts the freshly created element
+   * @returns {HTMLElement}
+   */
+  _ensureChromeHost(tagName, place) {
+    let el = document.querySelector(tagName);
+    if (el) return el;
+    el = document.createElement(tagName);
+    place(el);
+    this.logger.debug(`[ZVaFManager] Created runtime chrome host <${tagName}>`);
+    return el;
+  }
+  /**
+   * Populate connection badge content (v1.6.0: Simplified - element exists, just set content)
+   */
+  populateConnectionBadge() {
+    if (!this.client._zConnectionBadge) {
+      return;
+    }
+    // Set initial badge content (will be updated by connection hooks)
+    this.client._zConnectionBadge.className = 'zConnection zBadge zBadge-connection zBadge-pending';
+    this.client._zConnectionBadge.innerHTML = `
+      <svg class="zIcon zIcon-sm zBadge-dot" aria-hidden="true">
+        <use xlink:href="#icon-circle-fill"></use>
+      </svg>
+      <span class="zBadge-text">Connecting...</span>
+    `;
+    this.logger.log('[ConnectionBadge] Badge populated with initial state');
+  }
+  /**
+   * Update badge state (v1.6.0: Helper method called from hooks)
+   * @param {string} state - 'connecting', 'connected', 'disconnected', 'error'
+   */
+  updateBadgeState(state) {
+    if (!this.client._zConnectionBadge) {
+      // Badge is opt-in (zHooks.badge). When disabled the element is never
+      // created — that's expected, not an error. Stay quiet (matches
+      // updateRenderState's silent no-op) so it doesn't spam the console.
+      this.logger.debug('[ConnectionBadge] No badge element (badge disabled) — skipping update');
+      return;
+    }
+    const badge = this.client._zConnectionBadge;
+    const badgeText = badge.querySelector('.zBadge-text');
+    if (!badgeText) {
+      this.logger.warn('[ConnectionBadge] Cannot update - badge text element not found');
+      return;
+    }
+    this.logger.debug(`[ConnectionBadge] Updating badge to: ${state}`);
+    // Remove all state classes
+    badge.classList.remove('zBadge-pending', 'zBadge-success', 'zBadge-error');
+    // Apply new state
+    switch (state) {
+      case 'connected':
+        badge.classList.add('zBadge-success');
+        badgeText.textContent = 'Connected';
+        this.logger.log('[ConnectionBadge] Connected');
+        break;
+      case 'disconnected':
+        badge.classList.add('zBadge-pending');
+        badgeText.textContent = 'Disconnected';
+        this.logger.debug('[ConnectionBadge] Disconnected');
+        break;
+      case 'error':
+        badge.classList.add('zBadge-error');
+        badgeText.textContent = 'Error';
+        this.logger.debug('[ConnectionBadge] Error');
+        break;
+      case 'connecting':
+      default:
+        badge.classList.add('zBadge-pending');
+        badgeText.textContent = 'Connecting...';
+        this.logger.debug('[ConnectionBadge] Connecting');
+        break;
+    }
+  }
+  /**
+   * Update the badge with bifrost RENDER status (distinct from connection state).
+   *
+   * This is the zOS↔user "page is painting" contract: as the runtime streams a
+   * page in, the badge reads "Rendering k/N", then snaps back to the connected
+   * state when the last section lands. It reuses the same pending/success chip —
+   * no new chrome, no layout impact.
+   *
+   * @param {Object} opts
+   * @param {number} [opts.current] - Sections painted so far
+   * @param {number} [opts.total]   - Total sections in this render
+   * @param {boolean} [opts.done]   - Render finished → restore connected state
+   */
+  updateRenderState({ current = 0, total = 0, done = false } = {}) {
+    if (done) {
+      this.updateBadgeState('connected');
+      return;
+    }
+    const badge = this.client._zConnectionBadge;
+    if (!badge) return;
+    const badgeText = badge.querySelector('.zBadge-text');
+    if (!badgeText) return;
+    badge.classList.remove('zBadge-success', 'zBadge-error');
+    badge.classList.add('zBadge-pending');
+    badgeText.textContent = total > 0 ? `Rendering ${current}/${total}` : 'Rendering…';
+  }
+  /**
+   * Populate navbar from embedded config.
+   * 3A: Prefers server-built nav_html; falls back to array-based builder.
+   */
+  async populateNavBar() {
+    if (!this.client._zNavBarElement) return;
+    try {
+      const navHtml = this.zuiConfig?.nav_html;
+      if (navHtml) {
+        // 3A path: Python sent pre-built HTML — inject + wire events
+        this.client._zNavBarElement.innerHTML = navHtml;
+        NavBarBuilder.wireNavBarEvents(
+          this.client._zNavBarElement.firstElementChild,
+          this.client,
+          this.logger
+        );
+        this.logger.log('[NavBar] NavBar populated from server HTML (3A)');
+      } else if (this.zuiConfig?.zNavBar) {
+        // Legacy path: build from items array
+        const navElement = await this.client._renderMetaNavBarHTML(this.zuiConfig.zNavBar);
+        this.client._zNavBarElement.innerHTML = '';
+        if (navElement) {
+          this.client._zNavBarElement.appendChild(navElement);
+          this.logger.log('[NavBar] NavBar populated from embedded config (DOM element):', this.zuiConfig.zNavBar);
+        } else {
+          this.logger.warn('[NavBar] renderMetaNavBarHTML returned null');
+        }
+      } else {
+        this.logger.warn('[NavBar] No nav_html or zNavBar in embedded zuiConfig');
+        return;
+      }
+      await this.client._enableClientSideNavigation();
+    } catch (error) {
+      this.logger.error('[NavBar] Failed to populate:', error);
+    }
+  }
+  /**
+   * Re-populate navbar from connection_info nav_html (3A) or API fallback.
+   * Called after auth state changes / reconnect.
+   */
+  async fetchAndPopulateNavBar(navHtmlFromServer = null) {
+    if (!this.client._zNavBarElement) return;
+    try {
+      if (navHtmlFromServer) {
+        // 3A path: server pushed updated HTML via connection_info
+        this.client._zNavBarElement.innerHTML = navHtmlFromServer;
+        NavBarBuilder.wireNavBarEvents(
+          this.client._zNavBarElement.firstElementChild,
+          this.client,
+          this.logger
+        );
+        this.logger.log('[NavBar] NavBar updated from connection_info nav_html (3A)');
+        await this.client._enableClientSideNavigation();
+        return;
+      }
+      // Client-side bounce-back / refresh has no new server round-trip, so reuse
+      // the RBAC-filtered nav_html the server embedded in the page head
+      // (zui-config). This is the SSOT: the server resolves the navbar and ships
+      // it inline (and via connection_info / route-config). The legacy
+      // /api/zui/config endpoint was removed — the client no longer re-fetches a
+      // parallel copy of server-owned config.
+      const embeddedNav = this.zuiConfig?.nav_html || this.client?.zuiConfig?.nav_html;
+      if (embeddedNav) {
+        this.client._zNavBarElement.innerHTML = embeddedNav;
+        NavBarBuilder.wireNavBarEvents(
+          this.client._zNavBarElement.firstElementChild,
+          this.client,
+          this.logger
+        );
+        this.logger.log('[NavBar] NavBar refreshed from embedded zui-config nav_html');
+        await this.client._enableClientSideNavigation();
+        return;
+      }
+      this.logger.warn('[NavBar] No embedded nav_html — nothing to refresh');
+    } catch (error) {
+      this.logger.error('[NavBar] Failed to populate:', error);
+    }
+  }
+}
+export default ZVaFManager;

package/L3_Abstraction/L3_Abstraction.js ADDED Viewed

@@ -0,0 +1,12 @@
+/**
+ * L3_Abstraction - High-Level Abstractions Layer
+ *
+ * Coordinates L2 handlers, provides unified interfaces.
+ * Depends on: L1_Foundation, L2_Handling
+ * Provides: Orchestration, Rendering, Session management
+ */
+// Export subdirectories (will be populated in Step 4)
+export * from './orchestrator/orchestrator.js';
+export * from './renderer/renderer.js';
+export * from './session/session.js';

package/L3_Abstraction/orchestrator/container_unwrapper.js ADDED Viewed

@@ -0,0 +1,101 @@
+/**
+ * L3_Abstraction/orchestrator/container_unwrapper.js
+ *
+ * Container Unwrapping Logic
+ *
+ * Prevents double-nesting and unnecessary wrapper divs by detecting
+ * when a container and its child have identical classes or when a
+ * container has no styling purpose.
+ *
+ * Unwrapping rules:
+ * 1. If container and element have identical classes → unwrap
+ * 2. If container has no classes AND no styles → unwrap
+ * 3. If element has all container classes (superset) → unwrap
+ * 4. Otherwise → keep wrapper
+ *
+ * Extracted from zdisplay_orchestrator.js (Phase 4.4c)
+ */
+/**
+ * ContainerUnwrapper - Detects and handles unnecessary wrapper divs
+ */
+export class ContainerUnwrapper {
+  constructor(logger) {
+    this.logger = logger;
+  }
+  /**
+   * Check if container should be unwrapped (element appended directly to parent)
+   * @param {HTMLElement} container - The wrapper container
+   * @param {HTMLElement} element - The child element
+   * @returns {boolean} True if should unwrap
+   */
+  shouldUnwrap(container, element) {
+    // Never unwrap comment nodes (delegated elements)
+    if (element.nodeType === Node.COMMENT_NODE) {
+      return false;
+    }
+    const containerClasses = container.className ? container.className.split(' ').filter(c => c.trim()) : [];
+    const elementClasses = element.className ? element.className.split(' ').filter(c => c.trim()) : [];
+    const hasAllContainerClasses = containerClasses.length > 0 && containerClasses.every(cls => elementClasses.includes(cls));
+    // Case 1: Container and element have identical classes (or element has all container classes)
+    if (container.className && element.className && (container.className === element.className || hasAllContainerClasses)) {
+      this.logger.debug(`[ContainerUnwrapper] Should unwrap: element has same/superset classes`);
+      return true;
+    }
+    // Case 2: Container has no classes AND no styles (no styling purpose)
+    if ((!container.className || container.className === '') && !container.getAttribute('style')) {
+      this.logger.debug(`[ContainerUnwrapper] Should unwrap: container has no styling`);
+      return true;
+    }
+    // Case 3: Keep wrapper
+    this.logger.debug(`[ContainerUnwrapper] Keep wrapper (classes: ${container.className || 'none'})`);
+    return false;
+  }
+  /**
+   * Unwrap a container by transferring metadata to element and returning element
+   * @param {HTMLElement} container - The wrapper container
+   * @param {HTMLElement} element - The child element
+   * @param {string} key - The data-zkey value
+   * @returns {HTMLElement} The unwrapped element
+   */
+  unwrap(container, element, key) {
+    // Transfer data-zkey and id to the element
+    element.setAttribute('data-zkey', key);
+    if (!element.id) {
+      element.setAttribute('id', key);
+    }
+    this.logger.debug(`[ContainerUnwrapper] Unwrapped ${key}: appending directly to parent`);
+    return element;
+  }
+  /**
+   * Process element unwrapping and return result
+   * Returns { shouldAppendContainer: boolean, elementToAppend: HTMLElement }
+   * @param {HTMLElement} container - The wrapper container
+   * @param {HTMLElement} element - The child element
+   * @param {string} key - The data-zkey value
+   * @returns {{shouldAppendContainer: boolean, elementToAppend: HTMLElement}}
+   */
+  processUnwrapping(container, element, key) {
+    if (this.shouldUnwrap(container, element)) {
+      return {
+        shouldAppendContainer: false,
+        elementToAppend: this.unwrap(container, element, key)
+      };
+    } else {
+      this.logger.debug(`[ContainerUnwrapper] Keeping wrapper for ${key} (classes: ${container.className || 'none'})`);
+      container.appendChild(element);
+      return {
+        shouldAppendContainer: true,
+        elementToAppend: container
+      };
+    }
+  }
+}