zbifrost-client

v1.6.1

Published

a month ago

Production-ready WebSocket client for zCLI's zBifrost bridge

Downloads

258

0High
0Medium
0Low

zolomedia

websocket bifrost zcli client real-time zos ztheme progressive-rendering

zBifrost Client (JavaScript)

Production-ready JavaScript WebSocket client for zCLI's zBifrost bridge.

Structure

bifrost/
├── src/                       # Source files
│   ├── bifrost_client.js      # Main BifrostClient class (Layer 6: Application)
│   ├── managers/              # Feature managers (Layer 5: Business logic)
│   │   ├── cache_manager.js
│   │   ├── navigation_manager.js
│   │   ├── widget_hook_manager.js
│   │   └── zvaf_manager.js
│   ├── core/                  # Core primitives (Layer 1: Platform abstraction)
│   │   ├── connection.js
│   │   ├── hooks.js
│   │   ├── logger.js
│   │   ├── message_handler.js
│   │   ├── storage_manager.js
│   │   ├── session_manager.js
│   │   ├── cache_orchestrator.js
│   │   ├── error_display.js
│   │   └── caches/            # Cache implementations
│   ├── rendering/             # Renderers (Layer 3: Presentation logic)
│   │   ├── zdisplay_orchestrator.js
│   │   ├── *_renderer.js      # Specialized renderers
│   │   └── primitives/        # HTML primitive functions
│   └── utils/                 # Utilities (Layer 2: Pure functions)
│       ├── dom_utils.js
│       ├── ztheme_utils.js
│       ├── error_boundary.js
│       └── *_utils.js         # Various utility helpers
├── testing/                   # Test files
├── ARCHITECTURE.md            # 7-layer architecture guide
├── PATTERNS.md                # Coding patterns reference
└── README.md                  # This file

Installation

Via CDN (Recommended)

<!-- Simple script tag - works in all modern browsers -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/src/bifrost_client.js"></script>

Via NPM

npm install zbifrost-client

import BifrostClient from 'zbifrost-client';

Usage

Swiper-Style Elegance (Recommended)

<!DOCTYPE html>
<html>
<head>
  <title>Bifrost Demo</title>
</head>
<body>
  <div id="zVaF"></div> <!-- Default zCLI container (zView and Function) -->

  <script src="https://cdn.jsdelivr.net/npm/[email protected]/src/bifrost_client.js"></script>
  <script>
    // One declaration, everything happens automatically!
    const client = new BifrostClient('ws://localhost:8765', {
      autoConnect: true,              // Auto-connect on instantiation
      zTheme: true,                   // Enable zTheme CSS & rendering
      // targetElement: 'zVaF',       // Optional: default is 'zVaF'
      autoRequest: 'my_event',        // Auto-send on connect
      onConnected: (info) => console.log('✅ Connected!', info)
    });
  </script>
</body>
</html>

Traditional (More Control)

<script src="https://cdn.jsdelivr.net/npm/[email protected]/src/bifrost_client.js"></script>
<script>
  const client = new BifrostClient('ws://localhost:8765', {
    zTheme: true,
    hooks: {
      onConnected: (info) => console.log('Connected!', info),
      onDisconnected: (reason) => console.log('Disconnected:', reason),
      onMessage: (msg) => console.log('Message:', msg),
      onError: (error) => console.error('Error:', error)
    }
  });
  
  // Manually connect and send
  client.connect().then(() => {
    client.send({event: 'my_event'});
  });
</script>

ES Module Import (For Build Tools)

<script type="module">
  import BifrostClient from 'https://cdn.jsdelivr.net/npm/[email protected]/src/bifrost_client.js';
  
  const client = new BifrostClient('ws://localhost:8765', {
    autoConnect: true,
    zTheme: true
  });
</script>

Local Development

<script src="../../../../zCLI/subsystems/zComm/zComm_modules/bifrost/client/src/bifrost_client.js"></script>

Browser Compatibility

✅ Chrome 61+ (2017)
✅ Firefox 60+ (2018)
✅ Safari 11+ (2017)
✅ Edge 79+ (2020)

Note: Bifrost uses ES modules for lazy-loaded components. Modern browsers (2017+) are required.

Features

7-Layer Architecture: Industry-grade separation of concerns (see ARCHITECTURE.md)
Swiper-Style Elegance: autoConnect, zTheme, autoRequest for one-line initialization
Lazy Loading: Modules load dynamically only when needed
Auto-Reconnect: Automatic reconnection with exponential backoff
zTheme Integration: Optional CSS loading & automatic rendering
Hooks System: Lifecycle callbacks (onConnected, onDisconnected, onMessage, etc.)
Multi-Tier Caching: 5-tier cache system (system, pinned, plugin, session, rendered)
Error Boundaries: Graceful error handling with visual fallback UI
Auto-Rendering: Renderers for all zDisplay events (text, table, form, menu, etc.)
Client-Side Routing: Delta navigation without page reloads
zCLI Integration: Full support for zDisplay, zDialog, zMenu, zDash events

Documentation

ARCHITECTURE.md - 7-layer architecture guide
PATTERNS.md - Coding patterns & best practices
testing/README.md - Test suite documentation
Backend integration: Documentation/zBifrost_GUIDE.md (in main repo)

Demos

See ../Demos/Layer_2/zBifrost_Demo/ for progressive tutorials:

Frontend demos showcasing BifrostClient features
Progressive complexity (basic connection → full zDisplay integration)
Test files available in testing/ directory (21 HTML test files)