limoni

README

🍋 Limoni

An Ultra-Fast, Zero-Allocation, Thread-Safe Modern TUI Framework for Go.

Language: English • Türkçe

Why Limoni? • Showcase • Key Features • Quick Start • Documentation • Widgets • Benchmarks • Examples • Awesome Limoni

---

⚡ Overview

Limoni is a modern, high-performance Terminal User Interface (TUI) engine for Go. Designed from the ground up for data-intensive dashboards, devtools, and responsive terminal applications, Limoni bridges the gap between Go's developer ergonomics and Rust-like raw rendering speed.

By utilizing a flat 1D cell grid, zero-allocation hot-paths, and an optimized differential ANSI engine, Limoni achieves ultra-smooth 60+ FPS rendering without triggering Go's Garbage Collector.

---

💡 Why Limoni?

Feature / Goal	🍋 Limoni (Go)	🫧 Bubble Tea (Go)	🐀 Ratatui (Rust)
Language & Tooling	Go (Native)	Go (Native)	Rust (Native)
Render Architecture	Flat 1D Grid + ANSI Diff Engine	String concatenation / TEA	Immediate Mode Double Buffer
Hot-Path Allocations	0 B/op (Zero Alloc)	High heap allocation overhead	Stack / RAII
Large Datasets / Tables	Virtual Paging (Millions of rows)	High GC load on scroll	High layout cloning overhead
3D & Vector Graphics	Built-in 3D (OBJ/STL/PLY) & Shaders	Third-party / custom	Addons required
Accessibility (A11y)	Screen-reader & semantic tree built-in	Limited / Manual	Experimental
Concurrency Model	Synchronized Model Lifecycle & Event Loops	Single-threaded TEA loop	Manual thread coordination

Key Advantages:

1. Zero GC Stutter: Critical rendering loops generate zero heap allocations, eliminating random frame drops during heavy interactions or animations.
2. True Multithreaded State: Push state updates from any goroutine safely without bottlenecking the main event loop.
3. Virtual Viewport Paging: Render tables and lists with millions of rows without loading invisible cells into memory.
4. Batteries-Included: 3D Wireframe/Lambert/Gouraud rendering, rich markdown parser, physics/easing animations, fuzzy search, and command palettes out-of-the-box.

---

🎬 Showcase & Demos

🎮 3D Mesh & Vector Graphics Engine

Real-time 3D software rasterization running at 60+ FPS directly in terminal cells. Supports .obj, .stl, and .ply mesh models, depth-buffer Gouraud shading, Lambertian diffuse lighting, and interactive mouse/keyboard orbital controls.

go run ./examples/3d_viewer

---

📁 Superfile-Grade TreeView & Image Previews

Hierarchical collapsible file explorer widget (widgets.TreeView) with directory icons, tree guide lines, git/file status indicators, and live TrueColor half-block image previews.

go run ./examples/treeview

---

📊 High-Resolution Charts & Data Visualization

Sub-pixel Braille curves (widgets.LineChart), vertical gradient spectrum bars (widgets.BarChart), and donut distributions (widgets.PieChart) rendering high-frequency streaming telemetry with zero heap allocations.

go run ./examples/charts

---

✨ Key Features

• 🚀 Ultra-Fast ANSI Diffing: Computes dirty cell regions and emits minimal ANSI escape sequences in ~7.1 µs on full-screen changes (~140,000 FPS throughput) with zero heap allocations, short-circuiting in ~2 ns when clean.
• 📦 Contiguous 1D Buffer: Flat memory layout eliminates pointer chasing and maximizes CPU L1/L2 cache locality.
• 🎨 TrueColor & Fallback Engine: Full 24-bit RGB TrueColor support with automatic downsampling fallbacks for 256-color and 16-color terminals.
• 📐 Responsive Flexbox Layouts: Declarative layout engine supporting proportional splits, minimum/maximum size constraints, and nested alignments.
• 🎬 Animation & Easing Engine: Built-in interpolation for float, color, and transitions (Linear, Quad, Cubic, Elastic, Bounce).
• 🕶️ Native 3D & Vector Graphics: Render 3D .obj, .stl, .ply meshes directly in terminal cells with camera projection, rotation, and lighting!
• ♿ Built-in Accessibility: Accessible navigation tree, line-by-line inspection mode, and semantic annotations for screen-readers.

---

🚀 Quick Start

Installation

go get github.com/thebanri/limoni

1. Minimal TEA (The Elm Architecture) Example

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/thebanri/limoni/core/backend"
	"github.com/thebanri/limoni/core/cell"
	"github.com/thebanri/limoni/core/runtime"
	"github.com/thebanri/limoni/core/terminal"
	"github.com/thebanri/limoni/layout"
	"github.com/thebanri/limoni/widgets"
)

type AppModel struct {
	count int
}

func (m *AppModel) Init() []runtime.Cmd {
	return nil
}

func (m *AppModel) Update(msg runtime.Msg) runtime.UpdateResult {
	switch msg := msg.(type) {
	case runtime.KeyPressMsg:
		switch msg.Key.Type {
		case backend.KeyEsc:
			return runtime.UpdateResult{Quit: true}
		case backend.KeyRune:
			switch msg.Key.Ch {
			case 'q', 'Q':
				return runtime.UpdateResult{Quit: true}
			case '+', '=':
				m.count++
				return runtime.UpdateResult{Redraw: true}
			case '-', '_':
				m.count--
				return runtime.UpdateResult{Redraw: true}
			}
		}
	}
	return runtime.UpdateResult{}
}

func (m *AppModel) View(frame *terminal.Frame) {
	area := frame.Area()
	chunks := layout.FlexLayout{
		Direction: layout.Vertical,
		Constraints: []layout.Constraint{
			layout.Fixed(3),
			layout.Fill(),
			layout.Fixed(3),
		},
	}.Split(area)

	// Header
	frame.RenderWidget(widgets.Block{
		Title:       " 🍋 Limoni Quickstart ",
		BorderStyle: cell.Style{Fg: cell.NewColorRGB(255, 215, 0)},
		TitleStyle:  cell.Style{Fg: cell.NewColorRGB(255, 255, 255), Modifier: cell.ModifierBold},
	}, chunks[0])

	// Body
	text := fmt.Sprintf("Counter: %d  (Press '+' / '-' to change, 'q' to quit)", m.count)
	p := &widgets.Paragraph{
		Text:  text,
		Style: cell.Style{Fg: cell.NewColorRGB(0, 255, 200), Modifier: cell.ModifierBold},
	}
	frame.RenderWidget(p, chunks[1])

	// Footer
	frame.RenderWidget(widgets.Block{
		Title:       " [+] Increment  [-] Decrement  [Q/Esc] Quit ",
		BorderStyle: cell.Style{Fg: cell.NewColorRGB(100, 110, 120)},
	}, chunks[2])
}

func main() {
	b := backend.NewBackend(os.Stdin, os.Stdout)
	if err := b.Setup(); err != nil {
		fmt.Fprintf(os.Stderr, "Setup failed: %v\n", err)
		os.Exit(1)
	}
	defer b.Close()

	term, err := terminal.New(b)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Terminal failed: %v\n", err)
		os.Exit(1)
	}

	app := runtime.New(
		runtime.WithModel(&AppModel{}),
		runtime.WithFPS(60),
	)

	if err := app.RunTerminal(context.Background(), term, b); err != nil {
		panic(err)
	}
}

---

📚 Documentation

Detailed guides and API references are available in the docs/ directory and on our Interactive Documentation Website:

Guide	Description
⚡ Getting Started	Step-by-step introduction, installation, and first interactive app.
🏛️ Architecture & Zero-Alloc Deep Dive	Memory layout, 1D contiguous grid, and cache locality.
⚙️ Core API Reference	cell, buffer, terminal, backend, and runtime packages.
📐 Flexbox Layout Engine	Multi-column, multi-row, percentage, ratio, and constraint layouts.
🧩 Widget Reference & Guide	Full reference for all display, input, and modal widgets.
🎨 2D/3D Graphics & Canvas	Braille canvas, 3D Mesh loaders, Lambert/Gouraud shaders, and image protocols.
🎬 Animation & Physics	Interpolation, spring physics, and smooth easing curves.
♿ Accessibility & Theming	Screen-readers, High-Contrast mode, and NO_COLOR standard.
🌐 Drivers & WebAssembly	Cross-platform details: Linux, macOS, Windows VT100, WASM, and SSH.
📂 Examples Directory Guide	Feature map and run instructions for all 12 example applications.

---

🧩 Rich Widget Ecosystem

Limoni comes with an extensive suite of production-ready widgets:

Category	Available Widgets
Structure & Layout	Block, Dialog / Modal, Popup, ResponsiveGrid, Flexbox
Data Display	Table (Virtual/Paged), List (Virtual), Sparkline, ProgressBar, RichText
Input Controls	TextInput, TextArea, Checkbox, RadioGroup, Select / Dropdown, Slider
Navigation & Search	CommandPalette, FuzzySearch (FZF-style), Tabs, KeybindingManager
Graphics & 3D	Canvas (Braille / Block), Vector3D Mesh (OBJ/STL/PLY), Lambertian & Gouraud Shaders, Image (Kitty/Sixel/iTerm2/HalfBlock)
Text & Docs	Markdown (Full GFM), RichText Highlighting

---

🏛️ Architecture

                      ┌────────────────────────────────────────┐
                      │             User Application           │
                      └───────────────────┬────────────────────┘
                                          │ State & Views
                                          ▼
                      ┌────────────────────────────────────────┐
                      │         Declarative UI / Widgets       │
                      │   (Tables, Modals, 3D Canvas, Layout)  │
                      └───────────────────┬────────────────────┘
                                          │ Draw to Grid
                                          ▼
                      ┌────────────────────────────────────────┐
                      │          Flat 1D Buffer Grid           │
                      │  [Zero Heap Allocation Cell Memory]   │
                      └───────────────────┬────────────────────┘
                                          │
                        ┌─────────────────┴─────────────────┐
                        ▼                                   ▼
             ┌─────────────────────┐             ┌─────────────────────┐
             │ Previous Frame Snap │             │ Current Frame Snap  │
             └──────────┬──────────┘             └──────────┬──────────┘
                        └─────────────────┬─────────────────┘
                                          │ Sub-microsecond Diff
                                          ▼
                      ┌────────────────────────────────────────┐
                      │       ANSI Diff & Optimize Stream      │
                      │  (Minimizes cursor jump & color reset) │
                      └───────────────────┬────────────────────┘
                                          │ Direct Write
                                          ▼
                      ┌────────────────────────────────────────┐
                      │   Terminal TTY / Windows / macOS / SSH │
                      └────────────────────────────────────────┘

---

📊 Benchmarks

Limoni includes a standardized cross-implementation benchmark suite measuring real dirty diffing, partial invalidations, virtual scrolling, and memory allocations under standard virtual terminal conditions (120×40 cells = 4,800 cells).

Run benchmarks locally:

# Run Buffer Diff benchmarks (measured dirty and clean passes)
go test ./core/buffer -run '^$' -bench . -benchmem

# Run Widget & Layout benchmarks
go test ./benchmarks -run '^$' -bench . -benchmem

# Generate HTML Comparison Dashboard
go run ./benchmarks/runners/dashboard -output benchmark-results/dashboard.html benchmark-results/limoni.json benchmark-results/bubbletea.json benchmark-results/ratatui.json

Verified Benchmark Results (120×40 Viewport, AMD Ryzen / EPYC):

Benchmark Operation	Measured Latency	Throughput	Allocations	Description
BenchmarkDiff_FullChanges	~90.1 µs	~11,100 FPS	0 B/op (0 allocs)	100% full-screen cell mutation (4,800 cells) diffed against persistent double-buffer emitting ANSI escape stream
BenchmarkDiff_PartialChanges	~20.5 µs	~48,800 FPS	0 B/op (0 allocs)	10% viewport mutation (480 cells across shifting rows) diffed against persistent double-buffer
BenchmarkDiff_NoChanges	~1.92 ns	~520,000,000 FPS	0 B/op (0 allocs)	Clean frame fast-path bypass when no buffer cells mutated
BenchmarkTextHeavyFrame	~60.8 µs	~16,400 FPS	5 B/op (0 allocs)	40-line text dashboard rendering with unicode symbols and word wrapping across 120 columns
BenchmarkHundredLayers	~47.0 µs	~21,200 FPS	0 B/op (0 allocs)	100 layered Block widgets evaluation and frame rendering (Ratatui hundred-layers parity)
BenchmarkTenThousandRowTable	~102 µs	~9,800 FPS	614 B/op	Active selection scrolling through a 10,000-row table rendering visible rows
BenchmarkOneMillionRowVirtualScroll	~2.53 ms	~395 FPS	4.9 KB/op (6 allocs)	Active virtual scrolling across 1,000,000 rows with viewport boundary pruning
BenchmarkMouseHitTest	~61.7 ns	~16,200,000 ops/s	0 B/op (0 allocs)	Hierarchical widget tree spatial hit testing across 100 click regions
BenchmarkAsyncUpdateBurst	~214 ns	~4,660,000 msg/s	8 B/op (0 allocs)	High-throughput Elm runtime async message dispatch

[!NOTE] Transparency & Engineering Integrity Guarantee: We do not use synthetic shortcuts, artificial buffer clears, or zero-offset static loops.

• Diff Benchmarks: Run against a persistent double-buffer where cells genuinely mutate every single frame, forcing the full diff algorithm and ANSI encoder to run end-to-end.
• Scroll Benchmarks: Actively cycle through rows (Select((i * 7) % N)), proving zero-overhead virtual window rendering under continuous scrolling.
• Hundred Layers: Genuinely renders 100 overlapping Block widgets rather than a synthetic hit-test shortcut.

---

📂 Examples & Showcase Applications

Explore runnable demo applications inside the examples/ directory. See the full Examples Directory Guide (docs/examples.md) for details on all available apps.

Example	Description	Run Command
3d_viewer	Professional 3D model viewer supporting .obj, .stl, .ply, texture mapping & Lambertian/Gouraud shaders.	go run ./examples/3d_viewer
todo	Full-featured TEA Todo app with tags, priorities, filters, fuzzy search, and progress bars.	go run ./examples/todo
dashboard	DevOps monitoring dashboard with CPU/Memory sparklines, live process table & streaming logs.	go run ./examples/dashboard
table_virtual	1,000,000 row virtual table showcasing 0 B/op zero-allocation 120 FPS streaming.	go run ./examples/table_virtual
colors_and_styles	24-bit TrueColor gradients, 256-color ANSI palettes, text modifiers & A11y themes.	go run ./examples/colors_and_styles
ssh_server	Remote terminal server streaming interactive 60 FPS Limoni sessions over network/SSH sockets.	go run ./examples/ssh_server
custom_widget	Developer guide for implementing custom widgets.Widget components (Analog Meter / Gauge).	go run ./examples/custom_widget
demo	Interactive 3D Lemon Model (GLB/ASCII/Braille/Half-Block) & Feature Trailer.	go run ./examples/demo
showcase	Full multi-tab suite with matrix rain, forms, 3D models, DevTools HUD (F12), and command palette.	go run ./examples/showcase
wasm	In-browser WebAssembly demo running on xterm.js.	go run ./examples/wasm
animation	Physics-based animations, color transitions, and easing curves.	go run ./examples/animation
forms	Text inputs, text areas, radios, checkboxes, and sliders.	go run ./examples/forms
layer_demo	Layered modals, popups, and focus isolation.	go run ./examples/layer_demo

---

🌟 Awesome Limoni

Check out our curated list of real-world apps, tools, and third-party widgets in AWESOME.md.

Built something cool with Limoni? Open a Pull Request and add your project to AWESOME.md!

---

🤝 Contributing

Contributions, issues, and feature requests are welcome! Please make sure to review our Code of Conduct before participating.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

🛡️ Security Policy

Please read our Security Policy to report vulnerabilities responsibly.

---

📜 Code of Conduct

This project adheres to the Contributor Covenant v2.1. By participating, you are expected to uphold this code.

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

Made with 🍋 by thebanri and contributors.