raxol

# Raxol

**The Most Advanced Terminal Framework in Elixir**

[![CI](https://github.com/Hydepwns/raxol/workflows/CI/badge.svg)](https://github.com/Hydepwns/raxol/actions/workflows/ci.yml)
[![Tests](https://img.shields.io/badge/tests-2681%20passing-brightgreen.svg)](https://github.com/Hydepwns/raxol/actions)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://codecov.io/gh/Hydepwns/raxol)
[![Warnings](https://img.shields.io/badge/warnings-0-brightgreen.svg)](https://github.com/Hydepwns/raxol)
[![Performance](https://img.shields.io/badge/parser-3.3μs%2Fop-blue.svg)](docs/bench)
[![Hex.pm](https://img.shields.io/hexpm/v/raxol.svg)](https://hex.pm/packages/raxol)
[![Documentation](https://img.shields.io/badge/docs-hexdocs-purple.svg)](https://hexdocs.pm/raxol)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)

## What is Raxol?

Raxol is a production-ready, high-performance terminal application framework that brings modern UI development patterns to the terminal. 

Think **React, Svelte, LiveView** meets tmux - choose your preferred UI paradigm with enterprise features built-in.

### Why Raxol?

- **World-Class Performance**: 3.3μs parser operations, 2.8MB memory per session
- **Multi-Framework Support**: Choose React, Svelte, LiveView, or HEEx - use what you know best
- **Enterprise Ready**: Audit logging, encryption, SAML/OIDC support, compliance (SOC2/HIPAA/GDPR)
- **Innovation First**: Sixel graphics, WASH-style session continuity, real-time collaboration

## Use Cases

### Perfect For
- **Terminal IDEs** - Build the next vim/emacs
- **DevOps Tools** - Modern k9s, lazygit alternatives
- **System Monitoring** - Real-time dashboards
- **Database Clients** - Interactive SQL/NoSQL tools
- **Chat Applications** - Terminal-based communication tools
- **Games** - Roguelikes, MUDs, interactive fiction

### Real-World Applications
- Internal DevOps tooling
- Customer support interfaces
- Infrastructure monitoring
- Interactive programming education

## Key Features

### Core Terminal Framework
- **Full VT100/ANSI Compliance** - Complete terminal emulation with modern extensions
- **Sixel Graphics** - Native image support in the terminal
- **Mouse Support** - Click, drag, selection with full event handling
- **Tab Completion** - Intelligent autocomplete with context awareness
- **Command History** - Multi-layer persistence with search
- **GPU Acceleration** - Hardware-accelerated rendering pipeline

### Multi-Framework UI System
- **React-Style Components** - Familiar React patterns with hooks and lifecycle
- **Svelte-Style Components** - Reactive architecture with compile-time optimization  
- **LiveView Integration** - Phoenix LiveView components work seamlessly
- **HEEx Templates** - Use Phoenix templates in terminal applications
- **Raw Terminal Access** - Direct buffer manipulation for maximum performance
- **Universal Features** - Actions, transitions, context, slots available across all frameworks

### WASH-Style Session Continuity
- **Seamless Migration** - Move between terminal and web without losing state
- **Real-time Collaboration** - Google Docs-style multi-user editing
- **Persistent State** - Automatic state preservation across restarts
- **CRDT Synchronization** - Conflict-free collaborative editing

### Enterprise Security & Compliance
- **Audit Logging** - SOC2/HIPAA/GDPR/PCI-DSS compliant logging
- **Encryption** - AES-256-GCM with key rotation and HSM support
- **SIEM Integration** - Splunk, Elasticsearch, QRadar, Sentinel
- **Access Control** - RBAC with fine-grained permissions
- **Threat Detection** - Real-time anomaly detection and alerting

## Performance Metrics

| Metric | Performance | Industry Standard |
|--------|------------|-------------------|
| Parser Speed | **3.3μs/op** | 100μs/op |
| Memory Usage | **2.8MB/session** | 10MB/session |
| Startup Time | **<10ms** | 100ms |
| Test Coverage | **100%** | 80% |
| Render Speed | **1.3μs** | 10μs |

## Quick Start

### Installation

```elixir
# Add to mix.exs
def deps do
  [
    {:raxol, "~> 1.0.0"}
  ]
end
```

### Try It Now

```bash
# Clone and explore
git clone https://github.com/Hydepwns/raxol.git
cd raxol
mix deps.get

# Interactive tutorial (5 minutes)
mix raxol.tutorial

# Component playground
mix raxol.playground

# Run tests (100% passing!)
mix test
```

### Choose Your Framework

- Use whatever you're comfortable with:
```bash
  use Raxol.UI, framework: :react      # Familiar React patterns
  use Raxol.UI, framework: :svelte     # Reactive with compile-time optimization
  use Raxol.UI, framework: :liveview   # Phoenix LiveView patterns
  use Raxol.UI, framework: :heex       # Phoenix templates
  use Raxol.UI, framework: :raw        # Direct terminal control

  #Universal Features (Work Across ALL Frameworks)
  - Actions system - use:tooltip, use:draggable, etc.
  - Transitions & animations - 60 FPS engine
  - Context API - no prop drilling
  - Slot system - component composition
  - Theme system - unified styling
  - Event handling - keyboard, mouse, custom

  # Framework Comparison Table
  ┌─────────────┬──────────────┬─────────────────┬──────────────┬───────────┐
  │ Framework   │ Paradigm     │ Best For        │ Learning Curve│
  ├─────────────┼──────────────┼─────────────────┼──────────┼───────────────┤
  │ React       │ Virtual DOM  │ Familiar APIs   │ Easy            │
  │ Svelte      │ Reactive     │ Performance     │ Medium          │
  │ LiveView    │ Server-side  │ Real-time apps  │ Easy            │
  │ HEEx        │ Templates    │ Simple UIs      │ Very Easy       │
  │ Raw         │ Direct       │ Maximum control │ Hard            │
  └─────────────┴──────────────┴─────────────────┴──────────────┴───────────┘
```
  
#### React-Style
```elixir  
defmodule MyApp do
  use Raxol.Component
  
  def render(assigns) do
    ~H"""
    <Box padding={2}>
      <Text color="green" bold>Hello, Raxol!</Text>
      <Button on_click={@on_click}>Click me!</Button>
    </Box>
    """
  end
end
```

#### Svelte-Style
```elixir
defmodule MyApp do
  use Raxol.Svelte.Component
  
  state :count, 0
  reactive :doubled, do: @count * 2

  def render(assigns) do
    ~H"""
    <Box padding={2} use:tooltip="Reactive component">
      <Text>Count: {@count} Doubled: {@doubled}</Text>
      <Button on_click={&increment/0} in:scale>+1</Button>
    </Box>
    """
  end
end
```

#### LiveView-Style
```elixir
defmodule MyApp do
  use Raxol.LiveView

  def mount(_params, _session, socket) do
    {:ok, assign(socket, count: 0)}
  end

  def render(assigns) do
    ~H"""
    <Box padding={2}>
      <Text>Count: {@count}</Text>
      <Button phx-click="increment">+1</Button>
    </Box>
    """
  end
end
```

## Architecture

```bash
┌──────────────────────────────────────────────────────────┐
│                    Applications                         │
│         (TUI Apps • Plugins • Extensions)               │
├──────────────────────────────────────────────────────────┤
│               Multi-Framework UI Layer                  │
│    React • Svelte • LiveView • HEEx • Raw               │
│     (Universal: Actions • Slots • Context)              │
├──────────────────────────────────────────────────────────┤
│               Session Continuity Layer                  │
│     (WASH Bridge • State Sync • Collaboration)          │
├──────────────────────────────────────────────────────────┤
│               Terminal Emulator Core                    │
│      (Parser • Buffer • Input • Rendering)              │
├──────────────────────────────────────────────────────────┤
│                Platform Services                        │
│   (Security • Metrics • Persistence • Plugins)          │
└──────────────────────────────────────────────────────────┘
```


## Documentation

### Getting Started
- **[Interactive Tutorial](docs/tutorials)** - Learn by doing with `mix raxol.tutorial`
- **[Code Examples](docs/examples)** - Working examples and snippets
- **[Component Playground](docs/tutorials)** - Try components live with `mix raxol.playground`

### Developer Resources
- **[API Reference](https://hexdocs.pm/raxol)** - Complete API documentation
- **[Component Catalog](docs/components)** - Pre-built UI components
- **[Architecture Guide](docs/ARCHITECTURE.md)** - System design and patterns
- **[Contributing Guide](CONTRIBUTING.md)** - Join the development

### Advanced Topics
- **[Benchmarks](docs/bench)** - Performance measurements and optimization
- **[Architecture Decisions](docs/adr)** - ADR documentation
- **[Consolidated Guide](docs/CONSOLIDATED_README.md)** - Comprehensive documentation
- **[Web Interface](docs/WEB_INTERFACE_GUIDE.md)** - Browser integration

## VSCode Extension

Install our VSCode extension for the best development experience:

```bash
code --install-extension raxol-1.0.0.vsix
```

Features:
- Syntax highlighting for Raxol components
- IntelliSense autocomplete
- Component snippets
- Live preview
- Integrated terminal

## Roadmap

### Coming Soon
- Plugin marketplace
- Cloud-native deployment
- AI-powered autocomplete
- WebAssembly support
- Mobile terminal apps

## License

MIT License - see [LICENSE.md](LICENSE.md)

---

**Ready to build the future of terminal applications?**

[Get Started](docs/tutorials) • [View Source](https://github.com/Hydepwns/raxol) • [Report Issues](https://github.com/Hydepwns/raxol/issues)