A modern TypeScript library for building organized, dynamic terminal interfaces with zone-based layouts

---

Zonr transforms terminal output from chaotic text streams into organized, responsive interfaces. Create dashboards, build tools, monitoring systems, and interactive applications with intuitive zone-based layouts that adapt to your terminal size.

---

✨ Key Features

• 🎯 Zone-Based Architecture: Organize output into distinct, configurable areas
• 📐 Dynamic Layout System: Automatic row grouping with intelligent space distribution
• 📱 Responsive Design: Zones adapt automatically to terminal size changes
• ⚡ Real-Time Updates: Event-driven messaging for instant UI updates
• 🎨 Customizable Styling: Configurable borders, colors, headers, and dimensions
• 🔧 Perfect Alignment: Custom ANSI renderer ensures pixel-perfect borders
• 🌍 Wide Character Support: Proper handling of emoji and Unicode characters
• 🚀 High Performance: Differential rendering updates only changed content
• 🪟 Cross-Platform: Full Windows support with resize detection workarounds
• 📁 File Transport: High-performance logging with sonic-boom and automatic cleanup
• 🛡️ Signal Handling: Automatic graceful shutdown with transport flushing on SIGINT/SIGTERM

---

📦 Installation

npm install @zonr-logs/core
# or
pnpm add @zonr-logs/core  
# or
yarn add @zonr-logs/core

Requirements: Node.js ≥16

---

🎮 Quick Start

import Zonr, { FileTransport } from '@zonr-logs/core';

// Create a new terminal UI with automatic signal handling
const zonr = new Zonr({ autoCleanup: true });

// Add zones with different layouts and file logging
const logs = zonr.addZone({
  name: "Application Logs",
  width: "70%",
  height: "auto", 
  borderColor: "blue",
  additionalTransports: [
    new FileTransport({
      filePath: "./app.log",
      highVolume: true  // Optimized for high-throughput logging
    })
  ]
});

const status = zonr.addZone({
  name: "System Status",
  width: "30%", 
  height: "auto",
  borderColor: "green"
});

// Start logging - automatically flushes to file on exit
logs.info('🚀 Application started');
logs.warn('⚠️  High memory usage detected');
logs.error('❌ Database connection failed');

status.info('✅ Server: Online');
status.info('📊 CPU: 45%'); 
status.info('💾 Memory: 2.1GB');

---

🎬 Demo Gallery

🚀 Playground Demo - Basic file processing with progress tracking

The main playground demonstration showing file processing with real-time progress bars, metadata tracking, and logging.

pnpm run playground

Features: Progress bars, batch processing, real-time metrics, file logging

📊 Minimal Dashboard - Simple two-zone layout

Clean, minimal interface demonstrating basic zone creation with application logs and system status.

pnpm run demo:minimal

Features: Basic layouts, log levels, system metrics, auto-updating status

🎮 Gaming Interface Demo - Multi-zone gaming server monitor

Comprehensive gaming server monitoring interface with player activity, server stats, game events, and match results.

pnpm run demo:gaming

Features: Multi-zone layout, real-time stats, emoji rendering, leaderboards

🔧 Build System Monitor - Complex build pipeline visualization

Advanced build pipeline demonstration with progress tracking, build logs, test results, and deployment status.

pnpm run demo:build

Features: Build stages, progress indicators, test results, deployment tracking

📈 Data Processing Dashboard - Real-time data pipeline

Real-time data processing pipeline with input queues, processing steps, output results, and performance metrics.

pnpm run demo:data

Features: Queue management, processing analytics, throughput metrics, auto-height zones

🖥️ Full Development Dashboard - Complete monitoring interface

Comprehensive developer monitoring interface with system metrics, application logs, alerts, and status indicators.

pnpm run demo:dashboard

Features: System monitoring, log aggregation, alert management, comprehensive layouts

---

📚 API Reference

Creating a Zonr Instance

import Zonr from '@zonr-logs/core';

const zonr = new Zonr();

Adding Zones

const zone = zonr.addZone({
  name: string,           // Zone header text
  width: string | number, // "50%", "auto", or pixel value
  height: string | number,// "auto", "50%", or pixel value  
  borderColor?: string,   // "red", "blue", "green", etc.
  showHeader?: boolean,   // Show/hide zone header
  showBorder?: boolean    // Show/hide zone borders
});

Zone Methods

// Logging methods
zone.info(message: string)    // Blue info message
zone.warn(message: string)    // Yellow warning message  
zone.error(message: string)   // Red error message
zone.debug(message: string)   // Gray debug message
zone.log(message: string)     // Default log message

// Zone management
zone.clear()                  // Clear all messages
zone.getName()               // Get zone name
zone.getConfig()             // Get zone configuration

Zone Management

// Zone management methods
zonr.addZone(config)         // Add a new zone
zonr.getZone(name)           // Find zone by name
zonr.hasZone(name)           // Check if zone exists
zonr.getAllZones()           // Get all zones array
zonr.removeZone(nameOrZone)  // Remove specific zone by name or reference
zonr.clearZones()            // Remove all zones

// Legacy API still available
zonr.zones.add(config)       // Same as zonr.addZone()
zonr.zones.get(name)         // Same as zonr.getZone()
zonr.zones.list()            // Same as zonr.getAllZones()

Layout Configuration

// Width options
width: "50%"        // Percentage of terminal width
width: "auto"       // Automatic width distribution
width: 80           // Fixed pixel width

// Height options  
height: "auto"      // Adapts to terminal size and content
height: "30%"       // Percentage of terminal height
height: 20          // Fixed row height

// Color options
borderColor: "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "gray"

---

🎯 Use Cases

Development Tools

• Build Monitors: Track compilation, testing, and deployment stages
• Log Aggregation: Organize application logs by service or severity
• Development Servers: Show multiple service statuses simultaneously

System Monitoring

• Server Dashboards: Display metrics, alerts, and system health
• Process Monitoring: Track multiple running processes and their output
• Network Tools: Monitor connections, throughput, and diagnostics

Interactive Applications

• Gaming Interfaces: Leaderboards, chat, game state visualization
• CLI Tools: Multi-step workflows with progress tracking
• Data Processing: Real-time pipeline monitoring and statistics

---

🔧 Advanced Usage

File Transport

import { FileTransport } from '@zonr-logs/core';

// High-performance file logging with automatic cleanup
const fileTransport = new FileTransport({
  filePath: './logs/app.log',        // Direct file path
  highVolume: true,                  // Optimize for high-throughput logging
  maxFiles: 5,                       // File rotation (placeholder)
  maxSize: '100MB'                   // Size rotation (placeholder)
});

// Alternative: path + filename pattern
const altTransport = new FileTransport({
  path: './logs',                    // Directory path
  filename: 'application.log',       // Filename
  sync: true,                        // Synchronous writes for reliability
  minLength: 8192                    // Buffer size for performance
});

const zone = zonr.addZone({
  name: "Persistent Logs",
  width: "100%",
  height: "auto",
  additionalTransports: [fileTransport]  // Updated property name
});

// Automatic transport cleanup on SIGINT/SIGTERM
// Files are properly flushed and closed when process exits

Event-Driven Updates

// Zones automatically emit events for real-time updates
zone.info('Processing started...');

// Updates are immediately reflected in the terminal
setTimeout(() => {
  zone.info('Processing completed ✅');
}, 2000);

Automatic Signal Handling

// Create Zonr instance with automatic cleanup (default: true)
const zonr = new Zonr({ autoCleanup: true });

// Add zones with file transports
const logger = zonr.addZone({
  name: "Application",
  additionalTransports: [
    new FileTransport({ filePath: './app.log' })
  ]
});

logger.info('Application started');

// When user presses Ctrl+C or process receives SIGTERM:
// 1. All transports are automatically flushed
// 2. All transports are properly closed  
// 3. Process exits gracefully
// 4. No data is lost!

// Disable automatic cleanup if needed
const manualZonr = new Zonr({ autoCleanup: false });
// You would need to manually call:
// await manualZonr.flushAllTransports();
// await manualZonr.closeAllTransports();

Dynamic Layout Changes

// Zones automatically reflow when terminal is resized
// No additional code needed - Zonr handles it automatically!

// Works perfectly on Windows with built-in resize detection

---

🏗️ Architecture

Zonr uses a custom ANSI-based rendering system that provides:

• Direct Terminal Control: Precise cursor positioning and screen management
• Differential Updates: Only redraws changed content to eliminate flicker
• Layout Engine: Sophisticated algorithm for space distribution and row grouping
• Event System: Real-time communication between zones and renderer
• Windows Compatibility: Specialized handling for Windows terminal limitations

Key Components

• Zonr Class: Main facade providing the public API
• Zone Manager: Handles zone lifecycle and organization
• Layout Calculator: Dynamic space allocation and row grouping
• Custom Renderer: ANSI-based rendering with perfect border alignment
• Transport System: Pluggable output destinations (terminal, file, etc.)

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository  
git clone https://github.com/itsJess1ca/Zonr-Core.git
cd zonr

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build the project
pnpm build

# Try the demos
pnpm run demo:minimal
pnpm run demo:gaming

Conventional Commits

This project uses Conventional Commits with automated semantic versioning:

# Interactive commit prompts (recommended)
pnpm run commit

# Manual conventional format
git commit -m "feat: add new zone layout algorithm"
git commit -m "fix: resolve border alignment issue" 
git commit -m "docs: update API documentation"

# Test what would be released
pnpm run release:dry

Commit Types:

• feat: - New features (minor version bump)
• fix: - Bug fixes (patch version bump)
• docs: - Documentation changes
• style: - Code style changes
• refactor: - Code refactoring
• test: - Adding or updating tests
• chore: - Maintenance tasks
• ci: - CI/CD changes
• perf: - Performance improvements
• build: - Build system changes

Breaking Changes: Add BREAKING CHANGE: in commit footer for major version bumps.

Automated Releases: Semantic releases are automatically created when conventional commits are pushed to the main branch.

Running Tests

pnpm test           # Run tests in watch mode
pnpm test:run       # Run tests once
pnpm test:ui        # Run tests with UI

---

📄 License

This project is licensed under the MIT License - see the LICENSE.md file for details

---

🙏 Acknowledgments

• Built with TypeScript for excellent developer experience
• Inspired by modern terminal UI libraries but designed for simplicity
• Special thanks to the Node.js community for terminal handling insights

---

📞 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: jessica.ide247@gmail.com

---

⭐ Give us a star on GitHub!

Made with ❤️ for the terminal-loving community