@zolomedia/bifrost-client 1.7.74

package/L4_Orchestration/rendering/facade.js

@@ -0,0 +1,94 @@
+/**
+ * L4_Orchestration/rendering/facade.js
+ * 
+ * Rendering Facade
+ * 
+ * Thin delegation layer that ensures orchestrator is loaded and routes
+ * rendering requests. Extracted from bifrost_client.js to reduce facade bloat.
+ * 
+ * All methods are simple delegations to ZDisplayOrchestrator.
+ * 
+ * Extracted from bifrost_client.js (Phase 5.1)
+ */
+
+export class RenderingFacade {
+  constructor(client) {
+    this.client = client;
+  }
+
+  /**
+   * Render a complete block of YAML data
+   * @param {Object} blockData - Block data to render
+   */
+  async renderBlock(blockData) {
+    await this.client._ensureZDisplayOrchestrator();
+    return this.client.zDisplayOrchestrator.renderBlock(blockData);
+  }
+
+  /**
+   * Progressive chunk rendering (Terminal First philosophy)
+   * Appends chunks from backend as they arrive, stops at failed gates
+   * @param {Object} message - Chunk message from backend
+   */
+  async renderChunkProgressive(message) {
+    // Clear navigation timeout when first chunk arrives
+    if (this.client._navigationTimeout) {
+      clearTimeout(this.client._navigationTimeout);
+      this.client._navigationTimeout = null;
+    }
+    
+    await this.client._ensureZDisplayOrchestrator();
+    return this.client.zDisplayOrchestrator.renderChunkProgressive(message);
+  }
+
+  /**
+   * Recursively render YAML items (handles nested structures like implicit wizards)
+   * @param {Object} data - YAML data to render
+   * @param {HTMLElement} parentElement - Parent element to render into
+   */
+  async renderItems(data, parentElement) {
+    await this.client._ensureZDisplayOrchestrator();
+    return this.client.zDisplayOrchestrator.renderItems(data, parentElement);
+  }
+
+  /**
+   * Create container wrapper for a zKey with zTheme responsive classes
+   * Supports _zClass metadata for customization
+   * @param {string} zKey - The key name
+   * @param {Object} metadata - Metadata object (_zClass, _zStyle, _zHTML, zId)
+   */
+  async createContainer(zKey, metadata) {
+    await this.client._ensureZDisplayOrchestrator();
+    return this.client.zDisplayOrchestrator.createContainer(zKey, metadata);
+  }
+
+  /**
+   * Render navbar HTML (returns DOM element, doesn't inject into DOM)
+   * @param {Array} items - Navbar items (e.g., ['zVaF', 'zAbout', '^zLogin'])
+   * @returns {Promise<HTMLElement>} Navbar DOM element
+   */
+  async renderMetaNavBarHTML(items) {
+    await this.client._ensureZDisplayOrchestrator();
+    return this.client.zDisplayOrchestrator.renderMetaNavBarHTML(items);
+  }
+
+  /**
+   * Render navigation bar from metadata (~zNavBar* in content)
+   * @param {Array} items - Navbar items
+   * @param {HTMLElement} parentElement - Parent element to render into
+   */
+  async renderNavBar(items, parentElement) {
+    await this.client._ensureZDisplayOrchestrator();
+    return this.client.zDisplayOrchestrator.renderNavBar(items, parentElement);
+  }
+
+  /**
+   * Render a single zDisplay event as DOM element
+   * @param {Object} eventData - zDisplay event data
+   * @returns {Promise<HTMLElement>} Rendered element
+   */
+  async renderZDisplayEvent(eventData) {
+    await this.client._ensureZDisplayOrchestrator();
+    return this.client.zDisplayOrchestrator.renderZDisplayEvent(eventData);
+  }
+}

package/L4_Orchestration/rendering/rendering.js

@@ -0,0 +1,7 @@
+/**
+ * L4_Orchestration/rendering/rendering.js
+ * 
+ * Rendering Layer Barrel
+ */
+
+export { RenderingFacade } from './facade.js';

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZoloMedia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# zBifrost Client
+
+The browser client for **zBifrost** — the WebSocket bridge between a zOS Python
+server and the browser. It turns JSON events streamed from a zOS server into live
+DOM, with no application code of its own.
+
+## What it is
+
+A thin bootstrap (`bifrost_client.js`, ~190 lines) that:
+
+1. Reads server config injected into the page (`<script id="zui-config">`)
+2. Opens a WebSocket to the zOS server
+3. Receives `connection_info` carrying the core module URL
+4. Dynamically imports `bifrost_core.js` (server-controlled version)
+5. Hands off — all rendering is driven by what the server sends
+
+**The server controls what the client loads. The client controls nothing about
+your app.**
+
+## What it is not
+
+There is no routing logic, no `.zolo` parsing, no RBAC, no business logic, and no
+secrets. The JS receives JSON events from Python and creates DOM elements. That is
+the entire job. See [`docs/SECURITY.md`](docs/SECURITY.md) for the trust boundary.
+
+## Structure
+
+```
+bifrost_client.js       — thin bootstrap (~190 lines), hardcoded in the page <head>
+bifrost_core.js         — full WebSocket client, loaded dynamically at runtime
+L1_Foundation/          — WebSocket connection, constants, config, bootstrap, registries
+L2_Handling/            — message handling, renderers, cache, navigation, zvaf, hooks
+L3_Abstraction/         — orchestrators (navbar, wizard gate, session)
+L4_Orchestration/       — rendering facade, renderer/manager registries, lifecycle
+zSys/                   — DOM utils, theme utils, accessibility, validation, encoding
+syntax/                 — Prism.js grammars for .zolo / zUI / zSchema / zSpark / zEnv
+```
+
+## Usage
+
+The page loads the bootstrap and instantiates it; the server injects the config:
+
+```html
+<script src="https://cdn.jsdelivr.net/gh/ZoloAi/zbifrost-client@v1.7.62/bifrost_client.js"></script>
+<script>
+  window.bifrostClient = new BifrostClient(null, { autoConnect: true });
+</script>
+```
+
+The server injects `<script id="zui-config" type="application/json">` with the
+WebSocket config, `zBlock`, `zVaFile`, `zVaFolder`, and pre-built nav HTML, and
+sends `connection_info.bifrost_core_url` over the socket to select the core build.
+
+### Pinning & CDN
+
+Releases are git tags consumed via jsDelivr. Pin an exact tag in production:
+
+```html
+<script src="https://cdn.jsdelivr.net/gh/ZoloAi/zbifrost-client@v1.7.62/bifrost_client.js"></script>
+```
+
+The matching `bifrost_core.js` version is chosen **server-side** (see the zOS
+bridge `connection_info.bifrost_core_url`) — bump both together on each release.
+For a CDN other than jsDelivr, pass `coreOriginAllowlist` (see
+[`docs/SECURITY.md`](docs/SECURITY.md#core-import-origin-pinning)).
+
+## Documentation
+
+| Guide | What it covers |
+|-------|----------------|
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Bootstrap/core split, L1–L4 + zSys layers, registries, lazy loading |
+| [docs/PROTOCOL.md](docs/PROTOCOL.md) | The wire protocol from the client's side: `connection_info`, `render_chunk` + opcode decoding, the `PROTOCOL_EVENTS` vocabulary, message flow |
+| [docs/RENDERERS.md](docs/RENDERERS.md) | The renderer model, the registry, how to add a renderer, the HTML-escape SSOT |
+| [docs/SECURITY.md](docs/SECURITY.md) | Trust boundary, XSS escaping SSOT, core-import origin pinning, session-cookie handling |
+
+> The **server-side** zBifrost mechanism (render-opcode encoding, auth, chunking)
+> is documented in the zOS/zGuard repos — it is intentionally not shipped here.
+> This repo documents only the open, browser-side renderer.
+
+## License
+
+MIT — see [LICENSE](LICENSE)

package/bifrost_client.js

@@ -0,0 +1,204 @@
+/**
+ * bifrost_client.js — Thin bootstrap for BifrostCore
+ *
+ * Phase 4: Reduced to ~180 lines.
+ * Responsibilities:
+ *   1. Read zui-config from DOM
+ *   2. Open a raw WebSocket to receive connection_info
+ *   3. connection_info.bifrost_core_url → dynamic import(url) of the real client
+ *   4. Instantiate BifrostCore and set window.bifrostClient
+ *   5. Forward registerHook() calls queued before core is ready
+ *
+ * Intelligence lives in bifrost_core.js (server-controlled URL = Phase 3B).
+ * zVaF.html does: new BifrostClient() — autoConnect defaults on; pass
+ * { autoConnect: false } to opt out (the exception, not the rule).
+ */
+
+(function (root) {
+  'use strict';
+
+  // ─── helpers ────────────────────────────────────────────────────────────────
+
+  function readZuiConfig() {
+    try {
+      const el = document.getElementById('zui-config');
+      return el ? JSON.parse(el.textContent) : {};
+    } catch (_) { return {}; }
+  }
+
+  function buildWsUrl(wsCfg) {
+    wsCfg = wsCfg || {};
+    const proto = wsCfg.ssl_enabled ? 'wss' : 'ws';
+    const host  = wsCfg.host || '127.0.0.1';
+    const port  = wsCfg.port || 8765;
+    return `${proto}://${host}:${port}`;
+  }
+
+  function makeLogger(cfg) {
+    const isProd = cfg.deployment === 'Production';
+    const prefix = '[BifrostBootstrap]';
+    return {
+      debug: isProd ? () => {} : (...a) => console.debug(prefix, ...a),
+      info:  isProd ? () => {} : (...a) => console.info(prefix,  ...a),
+      warn:  (...a) => console.warn(prefix,  ...a),
+      error: (...a) => console.error(prefix, ...a),
+    };
+  }
+
+  // ─── BifrostClient (bootstrap) ──────────────────────────────────────────────
+
+  class BifrostClient {
+    constructor(url, options = {}) {
+      // Ergonomic single-object form: new BifrostClient({ zHooks: {...} }).
+      // A non-string first arg is treated as the options bag.
+      if (url && typeof url === 'object') { options = url; url = null; }
+
+      this._cfg   = readZuiConfig();
+      this._opts  = options;
+      this._url   = url || buildWsUrl(this._cfg.websocket);
+      this._core  = null;
+      this._coreLoading = false;
+      this._pendingHooks = [];   // hooks registered before core is ready
+      this.logger = makeLogger(this._cfg);
+
+      // Default-on: connect unless the caller explicitly opts out.
+      if (options.autoConnect !== false) {
+        this._bootstrap();
+      }
+    }
+
+    // ── bootstrap: minimal WS just to receive connection_info ─────────────────
+
+    _bootstrap() {
+      const ws = this._ws = new WebSocket(this._url);
+
+      ws.addEventListener('open', () => {
+        this.logger.info('Connected (bootstrap)');
+        // Do NOT send execute_walker here — BifrostCore will do it on its own connect.
+        // Sending here would cause a redundant server-side walker execution on an
+        // orphaned WS connection that we are about to close.
+      });
+
+      ws.addEventListener('message', ({ data }) => {
+        let msg;
+        try { msg = JSON.parse(data); } catch { return; }
+
+        if (msg.event === 'connection_info' && !this._core) {
+          this._loadCore(msg).catch(err => this.logger.error('Core load failed:', err));
+        }
+        // All other messages are ignored by the bootstrap; BifrostCore handles them.
+      });
+
+      ws.addEventListener('close', () => {
+        if (!this._core && !this._coreLoading) this.logger.warn('Bootstrap WS closed before core loaded');
+      });
+
+      ws.addEventListener('error', () => {
+        this.logger.error('Bootstrap WS error');
+      });
+    }
+
+    // ── core loading ──────────────────────────────────────────────────────────
+
+    async _loadCore(connectionInfo) {
+      this._coreLoading = true;
+      // 3B: server tells us the authoritative core URL; falls back to local.
+      // Relative ("/...") resolves against the page origin; absolute URLs are
+      // taken as-is (CDN deployments).
+      const rawUrl = connectionInfo.bifrost_core_url || '/bifrost/src/bifrost_core.js';
+      let coreUrl;
+      try {
+        coreUrl = new URL(rawUrl, window.location.origin).href;
+      } catch (e) {
+        this._coreLoading = false;
+        this.logger.error('Invalid bifrost_core_url, refusing to load core:', rawUrl);
+        return;
+      }
+
+      // Origin pinning: bifrost_core_url arrives over the WebSocket and is therefore
+      // attacker-influenceable if connection_info is spoofed. Only import from the
+      // page origin, the official jsDelivr CDN (where the canonical client ships),
+      // or an explicitly configured allowlist — never an arbitrary origin, which
+      // would load attacker code into the page context.
+      const allowedOrigins = [
+        window.location.origin,
+        'https://cdn.jsdelivr.net',
+        ...(this._opts.coreOriginAllowlist || []),
+      ];
+      const coreOrigin = new URL(coreUrl).origin;
+      if (!allowedOrigins.includes(coreOrigin)) {
+        this._coreLoading = false;
+        this.logger.error(
+          `Refusing to load bifrost core from disallowed origin "${coreOrigin}". ` +
+          `Allowed: ${allowedOrigins.join(', ')}. ` +
+          `Set opts.coreOriginAllowlist to permit a trusted CDN.`
+        );
+        return;
+      }
+      this.logger.info('Loading core from', coreUrl);
+
+      // Close the bootstrap WS cleanly before the core opens its own
+      this._ws.close();
+
+      const mod = await import(coreUrl);
+
+      // Instantiate BifrostCore — it reads zui-config itself, connects, sends execute_walker
+      const core = new mod.BifrostCore(this._url, {
+        autoConnect: true,
+        zTheme:      false,   // ztheme.js already loaded by zVaF.html
+        ...this._opts,
+      });
+
+      this._core = core;
+      window.bifrostClient = core;
+
+      // Replay any hooks registered on the bootstrap before the core was ready
+      for (const { hookName, fn } of this._pendingHooks) {
+        core.registerHook(hookName, fn);
+      }
+      this._pendingHooks = [];
+
+      this.logger.info('Core attached — window.bifrostClient is now BifrostCore');
+    }
+
+    // ── forwarding API (called by zVaF.html / menu_integration before core ready) ──
+
+    registerHook(hookName, fn) {
+      if (this._core) {
+        this._core.registerHook(hookName, fn);
+      } else {
+        this._pendingHooks.push({ hookName, fn });
+      }
+    }
+
+    unregisterHook(hookName) {
+      if (this._core) this._core.unregisterHook(hookName);
+    }
+
+    send(data) {
+      if (this._core) return this._core.send(data);
+      this.logger.warn('send() called before core is ready');
+    }
+
+    read(resource, params) {
+      if (this._core) return this._core.read(resource, params);
+      return Promise.reject(new Error('BifrostClient: core not yet loaded'));
+    }
+
+    // Expose connect() for callers who do: client.connect() manually
+    async connect() {
+      // Bootstrap already opened a WS; if core is loaded, delegate
+      if (this._core) return this._core.connect();
+      // Otherwise wait for core to be ready (already bootstrapping)
+      return new Promise((resolve) => {
+        const poll = setInterval(() => {
+          if (this._core) { clearInterval(poll); resolve(); }
+        }, 50);
+      });
+    }
+  }
+
+  // Expose globally — zVaF.html does: window.bifrostClient = new BifrostClient(...)
+  root.BifrostClient = BifrostClient;
+
+}(typeof self !== 'undefined' ? self : this));