limoni

package module

v0.2.4 Latest Latest Go to latest Published: Sep 10, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/thebanri/limoni

Links

Open Source Insights

README ¶

🍋 Limoni

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

Language: English • Türkçe

What's New • 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.

🆕 What's New & Recent Updates

🧱 Composable Lego-Like Component Architecture (component package): Build rich, responsive interfaces declaratively using composable view trees (limoni.VStack, limoni.HStack, limoni.Border, limoni.Pad, limoni.Center, limoni.Flex, limoni.FixedSize). The underlying stack solver allocates zero heap memory on the hot rendering path while retaining full interoperability with monolithic widgets via limoni.AsComponent.
🔄 Package Reorganization & Idiomatic Go Naming:
- core/engine: The Elm Architecture (TEA) application loop, message scheduling, cancellation precedence, and panic recovery (renamed from core/runtime to eliminate collisions with Go's standard library runtime).
- core/driver: Cross-platform VT driver abstraction, raw mode termios, epoll/kqueue event loop, Windows VT, WebAssembly bridge, and SSH PTY streams (renamed from core/backend to clearly reflect responsibilities).
🛑 Configurable Signal & Ctrl+C Handling: Configure process termination behavior with limoni.WithCatchCtrlC(bool) and limoni.WithoutDefaultQuitKeys(), enabling applications to intercept Ctrl+C for modal confirmations, subshell escapes, or custom shutdown routines.
⚡ Zero-Allocation Hot-Path Verification: Continuous benchmark enforcement in CI ensuring 0 B/op and 0 allocs/op on buffer diffing, widget drawing, and component stack layout.
🧪 Comprehensive Cross-Platform CI: Full automated verification on Linux, macOS, and Windows with active data race detection (-race) across the entire codebase.

💡 Why Limoni?

Feature / Goal	🍋 Limoni (Go)	🫧 Bubble Tea + Lipgloss (Go)	🐀 Ratatui (Rust)
Language & Tooling	Go (Native)	Go (Native)	Rust (Native)
Render Architecture	Flat 1D Grid + Adaptive ANSI Diff	String concatenation / TEA	Immediate Mode Double Buffer
Hot-Path Allocations	`0 B/op` (Zero Alloc)	High heap allocation overhead	Stack / RAII
Layout Paradigm	Declarative Flexbox & Stack Solver	String slicing (`JoinHorizontal/Vertical`)	Constraint solver
Mouse Interaction	Spatial Hit-Testing & Z-Index Routing	None (manual coordinate math)	Manual coordinates
Double Buffering & Diff	Sub-microsecond dirty-cell diff + Adaptive flush	None (entire strings dumped to stdout)	Double-buffered diff
Large Datasets / Tables	Virtual Paging (1M+ rows, 22 µs)	High GC load on scroll	High layout cloning overhead
3D & Vector Graphics	Built-in 3D (OBJ/STL/PLY) & Gouraud 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

🍋 Limoni Composable (Lego UI) vs. 🎀 Charm Lipgloss

While Lipgloss popularized styling in Go, its string-concatenation architecture imposes structural limits on interactive, high-frequency applications:

Capability	🍋 Limoni Composable (`component`)	🎀 Charm Lipgloss
Data Primitive	16-byte cache-aligned `Cell` struct matrix	Raw ANSI-escaped strings (`string`)
Hot-Path Allocations	`0 B/op` (0 allocs/op) on layout & render	High allocation rate (~100s of KBs to MBs/sec)
Layout Model	True Flexbox & Grid constraint solver	String slicing (`JoinHorizontal`, `JoinVertical`)
Size Constraints	Proportional `Flex`, `Ratio`, `Min`, `Max`	Fixed manual character widths only
Mouse Hit-Testing	Automatic spatial bounds & z-index routing	None (requires manual coordinate mapping)
Screen Clipping	Sub-cell rectangular spatial clipping	String chopping (causes broken ANSI codes)
Z-Index & Overlays	Hardware-like layer stack & modal trapping	Line-by-line string splicing (`PlaceOverlay`)
Rendering Pipeline	Double-buffered ANSI diffing (`~7.1 µs`)	Full terminal string dump (causes screen flicker)
Migration Bridge	`compat/bubbletea` fluent style builder	Native Charm ecosystem standard

Why Zero-Allocation Architecture Matters:

Eliminating Garbage Collector Stutter: Lipgloss computes layouts by allocating intermediate heap strings for every border, padding byte, and horizontal slice. In animated 60 FPS applications, this generates massive heap churn that triggers periodic Go GC pauses (frame stutter). Limoni's component modifiers wrap children on the call stack and write directly into a reusable flat 1D buffer—generating zero heap allocations (0 B/op).
Native Interactivity & Hit-Testing: Because Lipgloss outputs only a flat text string, it cannot determine which component received a mouse click. Limoni components automatically register their physical terminal boundaries (cell.Rect), dispatching click, hover, drag, and scroll events directly to callbacks with z-index ordering.

Key Advantages:

Zero GC Stutter: Critical rendering loops generate zero heap allocations, eliminating random frame drops during heavy interactions or animations.
True Multithreaded State: Push state updates from any goroutine safely without bottlenecking the main event loop.
Virtual Viewport Paging: Render tables and lists with millions of rows without loading invisible cells into memory.
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.

# Run locally (supports up to 240 FPS via -fps flag or [F] key):
go run ./examples/3d_viewer -fps 240

# Or run directly anywhere without cloning:
go run github.com/thebanri/limoni/examples/3d_viewer@latest -fps 240

📁 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. Composable Lego-Style UI Example (Zero Allocation)

package main

import (
	"fmt"

	"github.com/thebanri/limoni"
	"github.com/thebanri/limoni/widgets"
)

func main() {
	err := limoni.Run(func(f *limoni.Frame, ev *limoni.Event) bool {
		if ev != nil && ev.Type == limoni.EventKey && ev.Key.Type == limoni.KeyEsc {
			return false // Exit
		}

		// Declarative layout composition with zero heap allocations on hot path:
		view := limoni.VStack(
			// Header (Fixed height 3 rows)
			limoni.FixedSize(0, 3, limoni.Border(
				limoni.Center(limoni.Label("🍋 Limoni Composable Architecture", limoni.Bold().WithFg(limoni.Hex("#00FFAA")))),
				widgets.SymbolsRounded,
				limoni.Fg(limoni.Hex("#00FFAA")),
			)),

			// Body (Flex 1): 2-Column Split
			limoni.Flex(1, limoni.HStack(
				limoni.Flex(1, limoni.Border(
					limoni.Label("Left Sidebar\n- Fast\n- Zero-Alloc\n- Thread-Safe", limoni.Fg(limoni.Hex("#FFCC00"))),
					widgets.SymbolsSingle,
					limoni.Fg(limoni.Hex("#FFCC00")),
				)),
				limoni.Flex(2, limoni.Border(
					limoni.Center(limoni.Label("Main Content Area\nPress ESC to exit.", limoni.Fg(limoni.Hex("#FFFFFF")))),
					widgets.SymbolsDouble,
					limoni.Fg(limoni.Hex("#3399FF")),
				)),
			)),

			// Footer (Fixed height 3 rows)
			limoni.FixedSize(0, 3, limoni.Border(
				limoni.Center(limoni.Label("ESC: Quit | 60+ FPS ANSI Diff", limoni.Fg(limoni.Hex("#888888")))),
				widgets.SymbolsSingle,
				limoni.Fg(limoni.Hex("#666666")),
			)),
		)

		f.RenderComponent(view, f.Area())
		return true
	})
	if err != nil {
		fmt.Printf("Error: %v\n", err)
	}
}

2. Interactive TEA (The Elm Architecture) Example

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/thebanri/limoni/core/cell"
	"github.com/thebanri/limoni/core/driver"
	"github.com/thebanri/limoni/core/engine"
	"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() []engine.Cmd {
	return nil
}

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

func (m *AppModel) View(frame *terminal.Frame) {
	area := frame.Area()

	// 3-Row Vertical Layout: Header, Counter, Footer
	chunks := layout.NewFlexLayout(layout.Vertical, 0,
		layout.Fixed(3),
		layout.Fill(),
		layout.Fixed(3),
	).Split(area)

	// Header
	frame.RenderWidget(widgets.Block{
		Title:       " 🍋 Limoni Counter Application ",
		BorderStyle: cell.Style{Fg: cell.NewColorRGB(0, 255, 200)},
	}, chunks[0])

	// Counter Body
	text := fmt.Sprintf("Current Counter Value: %d\n\nPress '+' to increment, '-' to decrement.", 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() {
	d := driver.NewDriver(os.Stdin, os.Stdout)
	if err := d.Setup(); err != nil {
		fmt.Fprintf(os.Stderr, "Setup failed: %v\n", err)
		os.Exit(1)
	}
	defer d.Close()

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

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

	if err := app.RunTerminal(context.Background(), term, d); 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.

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
                                          ▼
                      ┌────────────────────────────────────────┐
                      │    Composable UI / Declarative Widgets │
                      │   (VStack, Border, Pad, Tables, 3D)    │
                      └───────────────────┬────────────────────┘
                                          │ 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 Driver (Unix/Win/WASM/SSH)  │
                      └────────────────────────────────────────┘

1. Zero-Allocation Rendering Pipeline

Contiguous 1D Flat Matrix: Screen state is stored in a single flat slice of []cell.Cell instead of jagged 2D slices, maximizing CPU L1/L2 cache locality.
Cache-Friendly 16-Byte Cell Alignment: Every cell.Cell is exactly 16 bytes (Content: 4 bytes, Style: 12 bytes), fitting cleanly across 64-bit cache lines.
Stack-Allocated Context: Rendering parameters and cascading styles are passed by value on the call stack via cell.Context, generating zero heap escape.
Pre-Allocated ANSI Diff Buffer: buffer.Diff computes changes between double-buffered frame snapshots and writes minimal ANSI escape sequences into a reused byte slice (writeBuf), yielding 0 B/op and 0 allocs/op on hot rendering paths.

2. Decoupled, Non-Dogmatic Concurrency & TEA

Optional Elm Architecture (TEA): Limoni includes a production-ready, typed Elm Architecture via core/engine.Program (Model, Update, View, Cmd, Msg) with redraw coalescing, background command worker pools, and panic recovery.
Non-Dogmatic Freedom: Unlike frameworks that mandate TEA for every task, Limoni allows you to choose the paradigm that best fits your project:
- Composable Lego Trees: Build declarative layouts with limoni.VStack, limoni.HStack, limoni.Border, and limoni.Pad.
- Immediate-Mode Callbacks: Write quick scripts or simple tools using limoni.Run(func(f, ev) bool).
- Multithreaded Goroutine Streaming: Safely push background telemetry updates from arbitrary goroutines without bottlenecking the main loop.

📊 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.

🖥️ Rendering Quirks & FAQ

1. Why do lines, 3D meshes, or images show hairline gaps in some terminals?

In standard terminal emulators, default monospace font line-height (cell padding) often adds 1–2px of empty vertical space between adjacent character rows. When rendering contiguous sub-pixel Braille matrices or half-blocks, this leading gap can cause surfaces to appear perforated ("grid gap" artifact).

How Limoni Solves This: The Lower Half-Block (`▄`) Baseline Standard

Traditional TUI frameworks frequently use the Upper Half Block (▀, U+2580). Because typography engines anchor font glyphs to the baseline (bottom of the character cell), any extra line-height creates an uncolored gap at the top of the cell, physically detaching ▀ from the row above it.

Limoni standardizes on the Lower Half Block (▄, U+2584):

Upper Pixel: Rendered via the cell background (Cell.Bg).
Lower Pixel: Rendered via the cell foreground (Cell.Fg).
Glyph: Set to ▄.

Because background colors always stretch to fill 100% of the character cell, and ▄ rests directly on the baseline, half-block graphics connect seamlessly without inter-cell cracks even on terminals with loose vertical spacing.

2. Recommended Terminal Settings for Visual Perfection

To experience Limoni's 3D software rasterization, charts, and Braille vector graphics at maximum fidelity:

Set Line Height to 1.0: In your terminal's configuration, ensure line-height / cell-height is set to 1.0 (or 100% / 0px vertical line padding).
Recommended Modern Terminals:
- Ghostty: Native GPU renderer with pixel-perfect contiguous box-drawing, Braille, and block element rendering out-of-the-box.
- Kitty: Ultra-fast OpenGL engine with native graphics protocols (kitty protocol) and gapless glyph rendering.
- WezTerm: Exceptional font fallback and contiguous box glyph handling.
- Alacritty: Ensure font.offset.y: 0 and standard line spacing in alacritty.toml.
Recommended Monospace Fonts: JetBrains Mono, Fira Code, or any patched Nerd Font.

3. How does Limoni maintain 60+ FPS during rapid full-screen animations?

Limoni features a threshold-based Adaptive Flush Engine:

Sparse Diffing (dirtyRatio < 0.45): For typing, metric tickers, and cursor blinks, computes minimal dirty cell regions and emits precise cursor jumps (CUP), completing in ~7.1 µs with zero heap allocations.
Full-Stream Redraw (dirtyRatio >= 0.45): When rotating 3D meshes, scrolling large tables, or fading tabs, switching to jump diffing would produce thousands of disjoint escape sequences. Limoni automatically switches to synchronized home (\x1b[H) full-stream streaming wrapped in DEC synchronized update mode (\x1b[?2026h), completely eliminating visual tearing and flicker while preserving 0 B/op zero-allocation efficiency.

📂 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`
`composable`	Declarative Lego-style UI composition with `VStack`, `HStack`, `Border`, and zero-alloc flex solvers.	`go run ./examples/composable`
`simple`	Minimal 50-line starting boilerplate with direct rendering and keyboard navigation.	`go run ./examples/simple`
`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!

💡 Engineering Philosophy & Acknowledgements

Limoni was conceived to push the boundaries of terminal performance in Go, bringing Rust-grade latency and memory determinism to the Go ecosystem.

[!NOTE] AI tools were used for generating initial boilerplates, documentation drafts, and test cases, while the core architecture, memory layout, and debugging were directed and implemented by the author.

Transparency & Tooling

In the spirit of modern open-source transparency:

AI-Accelerated Scaffolding: Modern AI developer tools (such as Claude and Gemini assistants) were utilized during development as high-velocity accelerators for generating boilerplate scaffolding, initial unit test cases, and draft documentation.
Human Systems Architecture: The low-level systems engineering—specifically the flat 1D contiguous cell grid, cache-aligned 16-byte structs, sub-microsecond ANSI differential encoder, stack-allocated context pipeline, zero-allocation layout negotiation, and native Unix/Windows terminal drivers—was conceived, profiled, benchmarked, and directed by the author.

We believe that combining ambitious low-level systems engineering with modern development acceleration leads to more robust, performant, and well-tested software for the entire community.

🤝 Contributing

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

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
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 Apache License 2.0. See LICENSE for more information.

Made with 🍋 by thebanri and contributors.

Documentation ¶

Index ¶

Constants
Variables
func DispatchEvent(root Component, ctx cell.Context, ev *driver.Event) bool
func Run(appFn func(f *Frame, ev *Event) bool, opts ...AppOption) error
func RuneWidth(r rune) int
func Start(drawFn func(f *Frame)) error
func StringWidth(text string) int
func Wakeup()
type AlignItems
type Alignment
type AppOption
- func WithCatchCtrlC(catch bool) AppOption
- func WithFPS(fps int) AppOption
- func WithoutDefaultQuitKeys() AppOption
type Backend
type Block
- func NewBlock() *Block
type BorderEdges
type BorderSymbols
type Buffer
type Cell
type Checkbox
type Color
- func ANSI(code uint8) Color
- func Hex(hexStr string) Color
- func RGB(r, g, b uint8) Color
type ColorType
type Component
- func AlignComponent(child Component, h HAlign, v VAlign) Component
- func AsComponent(w widgets.Widget) Component
- func Border(child Component, symbols widgets.BorderSymbols, style Style) Component
- func BorderCustom(child Component, symbols widgets.BorderSymbols, style Style, edges BorderEdges) Component
- func BottomBorder(child Component, symbol rune, style Style) Component
- func Center(child Component) Component
- func Constrain(minW, maxW, minH, maxH uint16, child Component) Component
- func Divider(style ...Style) Component
- func DividerWithTitle(title string, symbols widgets.BorderSymbols, style Style) Component
- func Dynamic(supplier func() Component) Component
- func Empty() Component
- func FixedSize(width, height uint16, child Component) Component
- func Flex(weight uint16, child Component) Component
- func ForEach[T any](items []T, fn func(item T, index int) Component) []Component
- func Inline(child Component) Component
- func Label(content string, style ...Style) Component
- func Lowercase(child Component) Component
- func Margin(child Component, top, right, bottom, left uint16) Component
- func MarginAll(child Component, m uint16) Component
- func MarginAxis(child Component, horizontal, vertical uint16) Component
- func Mask(child Component, mask rune) Component
- func Match[T comparable](value T, cases map[T]Component, defaultCase ...Component) Component
- func MaxHeight(maxH uint16, child Component) Component
- func MaxWidth(maxW uint16, child Component) Component
- func MinHeight(minH uint16, child Component) Component
- func MinWidth(minW uint16, child Component) Component
- func Overlay(base, overlay Component, x, y uint16) Component
- func Pad(child Component, top, right, bottom, left uint16) Component
- func PadAll(child Component, padding uint16) Component
- func PadAxis(child Component, horizontal, vertical uint16) Component
- func Place(width, height uint16, hAlign HAlign, vAlign VAlign, child Component) Component
- func Spacer(weight ...uint16) Component
- func TextFn(getter func() string, style ...Style) Component
- func TextRef(ptr *string, style ...Style) Component
- func TopBorder(child Component, symbol rune, style Style) Component
- func Transform(child Component, fn func(rune) rune) Component
- func Uppercase(child Component) Component
- func VDivider(style ...Style) Component
- func When(condition bool, then Component, otherwise ...Component) Component
- func WithBackground(color Color, child Component) Component
- func WithForeground(color Color, child Component) Component
- func WithStyle(style Style, child Component) Component
type Constraint
- func Fill() Constraint
- func Fixed(n uint16) Constraint
- func Max(m uint16) Constraint
- func Min(m uint16) Constraint
- func Percentage(p uint16) Constraint
- func Ratio(val uint16) Constraint
type Context
- func NewContext(area Rect, style Style) Context
type Dialog
type Direction
type Driver
type Event
type EventType
type FlexLayout
type Frame
type HAlign
type Insets
type InteractiveComponent
- func OnClick(child Component, handler func(ev MouseEvent)) InteractiveComponent
- func OnEvent(child Component, handler func(ctx cell.Context, ev *driver.Event) bool) InteractiveComponent
- func OnKey(child Component, key driver.KeyType, handler func(ev driver.KeyEvent) bool) InteractiveComponent
- func OnRune(child Component, r rune, handler func(ev driver.KeyEvent) bool) InteractiveComponent
type JustifyContent
type KeyEvent
type KeyType
type Layout
type LayoutProps
type Line
- func NewLine(spans ...Span) Line
type List
- func NewList(items ...string) *List
type ListState
- func NewListState() *ListState
type Markdown
- func NewMarkdown(content string) *Markdown
type Modifier
type MouseButton
type MouseEvent
type Paragraph
- func NewParagraph(text string) *Paragraph
type Point
type ProgressBar
type RadioButton
type Rect
- func NewRect(x, y, w, h uint16) Rect
- func SplitHorizontal(area Rect, constraints ...Constraint) []Rect
- func SplitVertical(area Rect, constraints ...Constraint) []Rect
type Select
type SelectState
- func NewSelectState() *SelectState
type Slider
type SliderState
- func NewSliderState(value int) *SliderState
type Span
- func NewSpan(text string, style Style) Span
type StackLayout
- func HStack(children ...Component) *StackLayout
- func VStack(children ...Component) *StackLayout
type Style
- func Bg(c Color) Style
- func Bold() Style
- func Dim() Style
- func Fg(c Color) Style
- func Italic() Style
- func NewStyle() Style
- func Reverse() Style
- func Underline() Style
type Table
- func NewTable() *Table
type TableCell
type TableConstraint
type TableRow
- func NewRow(cells ...string) TableRow
type TableState
- func NewTableState() *TableState
type Terminal
- func New() (*Terminal, error)
type Text
- func NewText(lines ...Line) *Text
type TextAlignment
type TextArea
type TextAreaState
- func NewTextAreaState() *TextAreaState
type TextInput
- func NewTextInput(id string) *TextInput
type TextInputState
- func NewTextInputState() *TextInputState
type VAlign
type Widget
type ZStackLayout
- func ZStack(children ...Component) *ZStackLayout

Constants ¶

View Source

const (
	HAlignLeft   = component.AlignLeft
	HAlignCenter = component.AlignCenter
	HAlignRight  = component.AlignRight

	AlignTop    = component.AlignTop
	AlignMiddle = component.AlignMiddle
	AlignBottom = component.AlignBottom
)

View Source

const (
	JustifyStart        = component.JustifyStart
	JustifyCenter       = component.JustifyCenter
	JustifyEnd          = component.JustifyEnd
	JustifySpaceBetween = component.JustifySpaceBetween
	JustifySpaceAround  = component.JustifySpaceAround
	JustifySpaceEvenly  = component.JustifySpaceEvenly
)

View Source

const (
	AlignItemsStretch = component.AlignItemsStretch
	AlignItemsStart   = component.AlignItemsStart
	AlignItemsCenter  = component.AlignItemsCenter
	AlignItemsEnd     = component.AlignItemsEnd
)

View Source

const (
	BorderEdgeTop        = component.BorderEdgeTop
	BorderEdgeRight      = component.BorderEdgeRight
	BorderEdgeBottom     = component.BorderEdgeBottom
	BorderEdgeLeft       = component.BorderEdgeLeft
	BorderEdgeAll        = component.BorderEdgeAll
	BorderEdgeHorizontal = component.BorderEdgeHorizontal
	BorderEdgeVertical   = component.BorderEdgeVertical
)

View Source

const (
	// Direction
	Horizontal = layout.Horizontal
	Vertical   = layout.Vertical

	// Alignment
	AlignLeft   = widgets.AlignLeft
	AlignCenter = widgets.AlignCenter
	AlignRight  = widgets.AlignRight

	// TextAlignment
	AlignTextLeft   = widgets.AlignTextLeft
	AlignTextCenter = widgets.AlignTextCenter
	AlignTextRight  = widgets.AlignTextRight

	// Borders
	BorderNone   = widgets.BorderNone
	BorderTop    = widgets.BorderTop
	BorderBottom = widgets.BorderBottom
	BorderLeft   = widgets.BorderLeft
	BorderRight  = widgets.BorderRight
	BorderAll    = widgets.BorderAll

	// Modifiers
	ModifierReset     = cell.ModifierReset
	ModifierBold      = cell.ModifierBold
	ModifierDim       = cell.ModifierDim
	ModifierItalic    = cell.ModifierItalic
	ModifierUnderline = cell.ModifierUnderline
	ModifierBlink     = cell.ModifierBlink
	ModifierReverse   = cell.ModifierReverse

	// Event Types
	EventKey    = driver.EventKey
	EventMouse  = driver.EventMouse
	EventResize = driver.EventResize

	// Key Types
	KeyRune      = driver.KeyRune
	KeySpace     = driver.KeySpace
	KeyEnter     = driver.KeyEnter
	KeyBackspace = driver.KeyBackspace
	KeyDelete    = driver.KeyDelete
	KeyTab       = driver.KeyTab
	KeyEsc       = driver.KeyEsc
	KeyUp        = driver.KeyArrowUp
	KeyDown      = driver.KeyArrowDown
	KeyLeft      = driver.KeyArrowLeft
	KeyRight     = driver.KeyArrowRight
	KeyHome      = driver.KeyHome
	KeyEnd       = driver.KeyEnd
	KeyPageUp    = driver.KeyPageUp
	KeyPageDown  = driver.KeyPageDown

	// Mouse Buttons
	MouseLeft       = driver.MouseLeft
	MouseMiddle     = driver.MouseMiddle
	MouseRight      = driver.MouseRight
	MouseRelease    = driver.MouseRelease
	MouseScrollUp   = driver.MouseScrollUp
	MouseScrollDown = driver.MouseScrollDown
)

Re-exported Constants

Variables ¶

View Source

var (
	SymbolsSingle  = widgets.SymbolsSingle
	SymbolsDouble  = widgets.SymbolsDouble
	SymbolsThick   = widgets.SymbolsThick
	SymbolsRounded = widgets.SymbolsRounded
	SymbolsBlock   = widgets.SymbolsBlock
)

View Source

var (
	ColorDefault = cell.NewColorDefault()
	ColorBlack   = cell.NewColorANSI(0)
	ColorRed     = cell.NewColorANSI(1)
	ColorGreen   = cell.NewColorANSI(2)
	ColorYellow  = cell.NewColorANSI(3)
	ColorBlue    = cell.NewColorANSI(4)
	ColorMagenta = cell.NewColorANSI(5)
	ColorCyan    = cell.NewColorANSI(6)
	ColorWhite   = cell.NewColorANSI(7)
)

Color Presets

Functions ¶

func DispatchEvent ¶ added in v0.2.0

func DispatchEvent(root Component, ctx cell.Context, ev *driver.Event) bool

DispatchEvent routes an event down a component tree starting from root within ctx.Area.

func Run ¶

func Run(appFn func(f *Frame, ev *Event) bool, opts ...AppOption) error

Run starts an event-driven Limoni application loop. appFn is invoked with the active Frame and the triggering Event. Returning false from appFn cleanly exits the application. On the first invocation, ev is nil for the initial render. By default, Ctrl+C automatically terminates the application gracefully, unless WithCatchCtrlC(true) or WithoutDefaultQuitKeys() is supplied.

func RuneWidth ¶

func RuneWidth(r rune) int

RuneWidth returns the terminal display column width of a single rune.

func Start ¶

func Start(drawFn func(f *Frame)) error

Start displays a static or single-state frame and cleanly exits when 'q', 'ESC', or Ctrl+C is pressed.

func StringWidth ¶

func StringWidth(text string) int

StringWidth returns the terminal display column width of UTF-8 text.

func Wakeup ¶ added in v0.2.1

func Wakeup()

Wakeup signals the render loop to re-render a frame immediately without waiting for terminal input. Safe to call concurrently from any goroutine (tickers, background workers, etc.).

Types ¶

type AlignItems ¶ added in v0.2.0

type AlignItems = component.AlignItems

type Alignment ¶

type Alignment = widgets.Alignment

Re-exported Core Types

type AppOption ¶ added in v0.2.0

type AppOption func(*appConfig)

AppOption configures the application lifecycle in Run.

func WithCatchCtrlC ¶ added in v0.2.0

func WithCatchCtrlC(catch bool) AppOption

WithCatchCtrlC configures whether Ctrl+C is forwarded to the application as a normal key event instead of automatically terminating the process.

func WithFPS ¶ added in v0.2.3

func WithFPS(fps int) AppOption

WithFPS configures a continuous animation frame rate (e.g. 60, 120, 240 FPS). When configured, the render loop continuously invokes the draw function at the target rate.

func WithoutDefaultQuitKeys ¶ added in v0.2.0

func WithoutDefaultQuitKeys() AppOption

WithoutDefaultQuitKeys disables automatic termination on Ctrl+C. When enabled, Ctrl+C is forwarded to the application's event handler.

type Backend ¶

type Backend = driver.Backend

Re-exported Core Types

type Block ¶

type Block = widgets.Block

Re-exported Core Types

func NewBlock ¶

func NewBlock() *Block

NewBlock creates a new Block widget configured with borders and rounded corners.

type BorderEdges ¶ added in v0.2.0

type BorderEdges = component.BorderEdges

BorderEdges specifies which sides of a border to render.

type BorderSymbols ¶

type BorderSymbols = widgets.BorderSymbols

Re-exported Core Types

type Buffer ¶

type Buffer = buffer.Buffer

Re-exported Core Types

type Cell ¶

type Cell = cell.Cell

Re-exported Core Types

type Checkbox ¶

type Checkbox = widgets.Checkbox

Re-exported Core Types

type Color ¶

type Color = cell.Color

Re-exported Core Types

func ANSI ¶

func ANSI(code uint8) Color

ANSI creates an 8-bit ANSI Color (0-255).

func Hex ¶

func Hex(hexStr string) Color

Hex parses a hex color string (e.g. "#FF5733" or "FF5733" or "#F53") into a TrueColor RGB Color.

func RGB ¶

func RGB(r, g, b uint8) Color

RGB creates a 24-bit TrueColor RGB Color.

type ColorType ¶

type ColorType = cell.ColorType

Re-exported Core Types

type Component ¶ added in v0.2.0

type Component = component.Component

Component is the minimal, unified interface for all composable UI elements.

func AlignComponent ¶ added in v0.2.0

func AlignComponent(child Component, h HAlign, v VAlign) Component

AlignComponent aligns a component within its allocated area according to horizontal and vertical rules.

func AsComponent ¶ added in v0.2.0

func AsComponent(w widgets.Widget) Component

AsComponent wraps an existing widgets.Widget to satisfy the Component interface.

func Border ¶ added in v0.2.0

func Border(child Component, symbols widgets.BorderSymbols, style Style) Component

Border wraps any component with a decorative 4-sided border.

func BorderCustom ¶ added in v0.2.0

func BorderCustom(child Component, symbols widgets.BorderSymbols, style Style, edges BorderEdges) Component

BorderCustom wraps any component with selective border edges.

func BottomBorder ¶ added in v0.2.0

func BottomBorder(child Component, symbol rune, style Style) Component

BottomBorder wraps a component with a single bottom border rule (e.g. tab underline).

func Center ¶ added in v0.2.0

func Center(child Component) Component

Center centers a component both horizontally and vertically within its allocated area.

func Constrain ¶ added in v0.2.0

func Constrain(minW, maxW, minH, maxH uint16, child Component) Component

Constrain enforces minimum and maximum width and height bounds on a child component.

func Divider ¶ added in v0.2.0

func Divider(style ...Style) Component

Divider creates a horizontal rule filling 100% of the available width with 1 row height.

func DividerWithTitle ¶ added in v0.2.0

func DividerWithTitle(title string, symbols widgets.BorderSymbols, style Style) Component

DividerWithTitle creates a horizontal rule with a title centered in the divider.

func Dynamic ¶ added in v0.2.0

func Dynamic(supplier func() Component) Component

Dynamic constructs a reactive component whose child subtree is resolved at render time.

func Empty ¶ added in v0.2.0

func Empty() Component

Empty returns a zero-sized no-op component.

func FixedSize ¶ added in v0.2.0

func FixedSize(width, height uint16, child Component) Component

FixedSize forces a fixed width and height onto a child component. (Named FixedSize to avoid collision with layout.Fixed constraints).

func Flex ¶ added in v0.2.0

func Flex(weight uint16, child Component) Component

Flex sets the expansion weight of a child component inside a StackLayout (VStack / HStack).

func ForEach ¶ added in v0.2.0

func ForEach[T any](items []T, fn func(item T, index int) Component) []Component

ForEach maps a slice of items of type T to a slice of Components using the provided mapping function. The resulting slice can be directly spread into container layouts such as VStack(...) or HStack(...).

func Inline ¶ added in v0.2.0

func Inline(child Component) Component

Inline constrains a component to render on a single line (height = 1). Useful for status bars, breadcrumbs, and inline badges.

func Label ¶ added in v0.2.0

func Label(content string, style ...Style) Component

Label creates an ultra-lightweight inline text component.

func Lowercase ¶ added in v0.2.0

func Lowercase(child Component) Component

Lowercase wraps a child component and transforms all text to lowercase.

func Margin ¶ added in v0.2.0

func Margin(child Component, top, right, bottom, left uint16) Component

Margin adds outer spacing around any component (outside any border).

func MarginAll ¶ added in v0.2.0

func MarginAll(child Component, m uint16) Component

MarginAll adds uniform outer spacing on all 4 sides.

func MarginAxis ¶ added in v0.2.0

func MarginAxis(child Component, horizontal, vertical uint16) Component

MarginAxis adds symmetric horizontal and vertical outer spacing.

func Mask ¶ added in v0.2.0

func Mask(child Component, mask rune) Component

Mask wraps a child component and replaces all visible text with a mask rune (e.g. '•' for passwords).

func Match ¶ added in v0.2.0

func Match[T comparable](value T, cases map[T]Component, defaultCase ...Component) Component

Match inspects value against cases map and returns the matching component, or defaultCase (or Empty()).

func MaxHeight ¶ added in v0.2.0

func MaxHeight(maxH uint16, child Component) Component

MaxHeight clamps the maximum height of a child component.

func MaxWidth ¶ added in v0.2.0

func MaxWidth(maxW uint16, child Component) Component

MaxWidth clamps the maximum width of a child component.

func MinHeight ¶ added in v0.2.0

func MinHeight(minH uint16, child Component) Component

MinHeight ensures a child component takes at least minH height.

func MinWidth ¶ added in v0.2.0

func MinWidth(minW uint16, child Component) Component

MinWidth ensures a child component takes at least minW width.

func Overlay ¶ added in v0.2.0

func Overlay(base, overlay Component, x, y uint16) Component

Overlay places an overlay component on top of a base component at absolute position (x, y) within the base's bounding area. Equivalent to Lipgloss's PlaceOverlay(x, y, fg, bg).

func Pad ¶ added in v0.2.0

func Pad(child Component, top, right, bottom, left uint16) Component

Pad adds inner spacing around any component.

func PadAll ¶ added in v0.2.0

func PadAll(child Component, padding uint16) Component

PadAll adds uniform padding on all 4 sides of a component.

func PadAxis ¶ added in v0.2.0

func PadAxis(child Component, horizontal, vertical uint16) Component

PadAxis adds symmetric horizontal and vertical padding.

func Place ¶ added in v0.2.0

func Place(width, height uint16, hAlign HAlign, vAlign VAlign, child Component) Component

Place positions a child component inside a fixed bounding box of (width x height) aligned horizontally and vertically according to hAlign and vAlign. Equivalent to Lipgloss's lipgloss.Place().

func Spacer ¶ added in v0.2.0

func Spacer(weight ...uint16) Component

Spacer returns an expanding, invisible flexible component. In an HStack, it expands horizontally pushing adjacent items apart. In a VStack, it expands vertically.

func TextFn ¶ added in v0.2.0

func TextFn(getter func() string, style ...Style) Component

TextFn creates a dynamic text component evaluated via a getter function on each frame.

func TextRef ¶ added in v0.2.0

func TextRef(ptr *string, style ...Style) Component

TextRef creates a dynamic, data-driven text component bound directly to a string variable pointer.

func TopBorder ¶ added in v0.2.0

func TopBorder(child Component, symbol rune, style Style) Component

TopBorder wraps a component with a single top border rule.

func Transform ¶ added in v0.2.0

func Transform(child Component, fn func(rune) rune) Component

Transform wraps a child component and applies fn to every non-zero rune in its bounding area after the child has drawn. Zero-allocation.

func Uppercase ¶ added in v0.2.0

func Uppercase(child Component) Component

Uppercase wraps a child component and transforms all text to uppercase.

func VDivider ¶ added in v0.2.0

func VDivider(style ...Style) Component

VDivider creates a vertical rule filling 100% of the available height with 1 column width.

func When ¶ added in v0.2.0

func When(condition bool, then Component, otherwise ...Component) Component

When renders then component if condition is true, otherwise the optional otherwise component (or Empty()).

func WithBackground ¶ added in v0.2.0

func WithBackground(color Color, child Component) Component

WithBackground cascades a background color override into the component subtree.

func WithForeground ¶ added in v0.2.0

func WithForeground(color Color, child Component) Component

WithForeground cascades a foreground color override into the component subtree.

func WithStyle ¶ added in v0.2.0

func WithStyle(style Style, child Component) Component

WithStyle cascades a Style into the component subtree by merging it into Context.Style.

type Constraint ¶

type Constraint = layout.Constraint

Re-exported Core Types

func Fill ¶

func Fill() Constraint

Fill creates a constraint that expands to take all remaining available space.

func Fixed ¶

func Fixed(n uint16) Constraint

Fixed creates a fixed-size layout constraint.

func Max ¶

func Max(m uint16) Constraint

Max creates a constraint that specifies a maximum size.

func Min ¶

func Min(m uint16) Constraint

Min creates a constraint that specifies a minimum size.

func Percentage ¶

func Percentage(p uint16) Constraint

Percentage creates a percentage-based layout constraint (0-100).

func Ratio ¶

func Ratio(val uint16) Constraint

Ratio creates a ratio-based layout constraint.

type Context ¶

type Context = cell.Context

Re-exported Core Types

func NewContext ¶ added in v0.2.0

func NewContext(area Rect, style Style) Context

NewContext creates a new ephemeral drawing Context for widgets and components.

type Dialog ¶

type Dialog = widgets.Dialog

Re-exported Core Types

type Direction ¶

type Direction = layout.Direction

Re-exported Core Types

type Driver ¶ added in v0.2.0

type Driver = driver.Driver

Re-exported Core Types

type Event ¶

type Event = driver.Event

Re-exported Core Types

type EventType ¶

type EventType = driver.EventType

Re-exported Core Types

type FlexLayout ¶

type FlexLayout = layout.FlexLayout

Re-exported Core Types

type Frame ¶

type Frame = terminal.Frame

Re-exported Core Types

type HAlign ¶ added in v0.2.0

type HAlign = component.HAlign

Composable alignment aliases

type Insets ¶

type Insets = widgets.Insets

Re-exported Core Types

type InteractiveComponent ¶ added in v0.2.0

type InteractiveComponent = component.InteractiveComponent

InteractiveComponent represents a composable element capable of handling input and mouse events.

func OnClick ¶ added in v0.2.0

func OnClick(child Component, handler func(ev MouseEvent)) InteractiveComponent

OnClick wraps any component with a click handler.

func OnEvent ¶ added in v0.2.0

func OnEvent(child Component, handler func(ctx cell.Context, ev *driver.Event) bool) InteractiveComponent

OnEvent attaches an arbitrary event listener (keyboard, mouse, resize, paste) to a component.

func OnKey ¶ added in v0.2.0

func OnKey(child Component, key driver.KeyType, handler func(ev driver.KeyEvent) bool) InteractiveComponent

OnKey binds a specific keyboard key to a component.

func OnRune ¶ added in v0.2.0

func OnRune(child Component, r rune, handler func(ev driver.KeyEvent) bool) InteractiveComponent

OnRune binds a specific character rune to a component.

type JustifyContent ¶ added in v0.2.0

type JustifyContent = component.JustifyContent

Composable Flexbox distribution & alignment

type KeyEvent ¶

type KeyEvent = driver.KeyEvent

Re-exported Core Types

type KeyType ¶

type KeyType = driver.KeyType

Re-exported Core Types

type Layout ¶

type Layout = layout.FlexLayout

Re-exported Core Types

type LayoutProps ¶ added in v0.2.0

type LayoutProps = component.LayoutProps

LayoutProps defines sizing and layout constraints for composable negotiation.

type Line ¶

type Line = widgets.Line

Re-exported Core Types

func NewLine ¶

func NewLine(spans ...Span) Line

NewLine creates a rich-text Line from styled Spans.

type List ¶

type List = widgets.List

Re-exported Core Types

func NewList ¶

func NewList(items ...string) *List

NewList creates a new List widget with the provided items.

type ListState ¶

type ListState = widgets.ListState

Re-exported Core Types

func NewListState ¶

func NewListState() *ListState

NewListState creates a new ListState for tracking list item selection and scroll offsets.

type Markdown ¶

type Markdown = widgets.Markdown

Re-exported Core Types

func NewMarkdown ¶

func NewMarkdown(content string) *Markdown

NewMarkdown creates a new Markdown rendering widget.

type Modifier ¶

type Modifier = cell.Modifier

Re-exported Core Types

type MouseButton ¶

type MouseButton = driver.MouseButton

Re-exported Core Types

type MouseEvent ¶

type MouseEvent = driver.MouseEvent

Re-exported Core Types

type Paragraph ¶

type Paragraph = widgets.Paragraph

Re-exported Core Types

func NewParagraph ¶

func NewParagraph(text string) *Paragraph

NewParagraph creates a new Paragraph widget with word-wrapping enabled.

type Point ¶

type Point = cell.Point

Re-exported Core Types

type ProgressBar ¶

type ProgressBar = widgets.ProgressBar

Re-exported Core Types

type RadioButton ¶

type RadioButton = widgets.RadioButton

Re-exported Core Types

type Rect ¶

type Rect = cell.Rect

Re-exported Core Types

func NewRect ¶

func NewRect(x, y, w, h uint16) Rect

NewRect creates a new Rect with specified x, y, width, and height.

func SplitHorizontal ¶

func SplitHorizontal(area Rect, constraints ...Constraint) []Rect

SplitHorizontal splits an area horizontally according to constraints.

func SplitVertical ¶

func SplitVertical(area Rect, constraints ...Constraint) []Rect

SplitVertical splits an area vertically according to constraints.

type Select ¶

type Select = widgets.Select

Re-exported Core Types

type SelectState ¶

type SelectState = widgets.SelectState

Re-exported Core Types

func NewSelectState ¶

func NewSelectState() *SelectState

NewSelectState creates a new SelectState for dropdown selection.

type Slider ¶

type Slider = widgets.Slider

Re-exported Core Types

type SliderState ¶

type SliderState = widgets.SliderState

Re-exported Core Types

func NewSliderState ¶

func NewSliderState(value int) *SliderState

NewSliderState creates a new SliderState with the given initial value.

type Span ¶

type Span = widgets.Span

Re-exported Core Types

func NewSpan ¶

func NewSpan(text string, style Style) Span

NewSpan creates a styled Span for rich-text lines.

type StackLayout ¶ added in v0.2.0

type StackLayout = component.StackLayout

StackLayout arranges components linearly along a primary axis.

func HStack ¶ added in v0.2.0

func HStack(children ...Component) *StackLayout

HStack creates a horizontal stack arranging children left-to-right.

func VStack ¶ added in v0.2.0

func VStack(children ...Component) *StackLayout

VStack creates a vertical stack arranging children top-to-bottom.

type Style ¶

type Style = cell.Style

Re-exported Core Types

func Bg ¶

func Bg(c Color) Style

Bg returns a Style with the given background color.

func Bold ¶

func Bold() Style

Bold returns a bold Style.

func Dim ¶

func Dim() Style

Dim returns a dim/faint Style.

func Fg ¶

func Fg(c Color) Style

Fg returns a Style with the given foreground color.

func Italic ¶

func Italic() Style

Italic returns an italic Style.

func NewStyle ¶

func NewStyle() Style

NewStyle returns an empty default Style.

func Reverse ¶

func Reverse() Style

Reverse returns a reverse (inverted foreground/background) Style.

func Underline ¶

func Underline() Style

Underline returns an underline Style.

type Table ¶

type Table = widgets.Table

Re-exported Core Types

func NewTable ¶

func NewTable() *Table

NewTable creates a new Table widget with grid lines enabled by default.

type TableCell ¶

type TableCell = widgets.TableCell

Re-exported Core Types

type TableConstraint ¶

type TableConstraint = widgets.TableConstraint

Re-exported Core Types

type TableRow ¶

type TableRow = widgets.TableRow

Re-exported Core Types

func NewRow ¶

func NewRow(cells ...string) TableRow

NewRow creates a new TableRow from string cells.

type TableState ¶

type TableState = widgets.TableState

Re-exported Core Types

func NewTableState ¶

func NewTableState() *TableState

NewTableState creates a new TableState for tracking selection, scrolling, and column sizes.

type Terminal ¶

type Terminal = terminal.Terminal

Re-exported Core Types

func New ¶

func New() (*Terminal, error)

New initializes standard OS input/output, switches to raw mode, enables mouse and TrueColor tracking, and returns a fully ready-to-use Terminal. The caller should defer term.Close() to restore the terminal state.

type Text ¶

type Text = widgets.Text

Re-exported Core Types

func NewText ¶

func NewText(lines ...Line) *Text

NewText creates a new rich Text widget with the provided lines.

type TextAlignment ¶

type TextAlignment = widgets.TextAlignment

Re-exported Core Types

type TextArea ¶

type TextArea = widgets.TextArea

Re-exported Core Types

type TextAreaState ¶

type TextAreaState = widgets.TextAreaState

Re-exported Core Types

func NewTextAreaState ¶

func NewTextAreaState() *TextAreaState

NewTextAreaState creates a new TextAreaState for multiline text editing.

type TextInput ¶

type TextInput = widgets.TextInput

Re-exported Core Types

func NewTextInput ¶

func NewTextInput(id string) *TextInput

NewTextInput creates a single-line interactive TextInput widget with the specified ID.

type TextInputState ¶

type TextInputState = widgets.TextInputState

Re-exported Core Types

func NewTextInputState ¶

func NewTextInputState() *TextInputState

NewTextInputState creates a new TextInputState for managing typed text and cursor position.

type VAlign ¶ added in v0.2.0

type VAlign = component.VAlign

type Widget ¶

type Widget = widgets.Widget

Re-exported Core Types

type ZStackLayout ¶ added in v0.2.0

type ZStackLayout = component.ZStackLayout

ZStackLayout arranges components in depth layers (Painter's algorithm).

func ZStack ¶ added in v0.2.0

func ZStack(children ...Component) *ZStackLayout

ZStack creates a depth-axis container rendering from background to foreground. All children share the same bounding area without offscreen buffer allocations.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
animation
benchmarks
runners/compare command
runners/dashboard command
runners/limoni command
cmd
limoni command Command limoni, Limoni TUI projeleri için iskelet (scaffold) üretir.	Command limoni, Limoni TUI projeleri için iskelet (scaffold) üretir.
compat
bubbletea
component
core
accessibility Package accessibility contains semantic UI metadata independent of rendering.	Package accessibility contains semantic UI metadata independent of rendering.
buffer
cell
driver
engine Package runtime provides an optional Init/Update/View application runtime.	Package runtime provides an optional Init/Update/View application runtime.
terminal
examples
3d_viewer command
animation command
ascii3d command ascii3d demonstrates real-time 3D ASCII & sub-cell rendering in Limoni TUI.	ascii3d demonstrates real-time 3D ASCII & sub-cell rendering in Limoni TUI.
charts command
composable command
custom_widget command
dashboard command
demo command Limoni Flagship Interactive Demo Designed with a clean, professional sidebar layout, full mouse click interaction, and studio-quality 3D lemon model rendering.	Limoni Flagship Interactive Demo Designed with a clean, professional sidebar layout, full mouse click interaction, and studio-quality 3D lemon model rendering.
forms command forms demonstrates the Select and Slider widgets.	forms demonstrates the Select and Slider widgets.
layer_demo command layer_demo demonstrates Limoni layered rendering capabilities: - Layered Rendering with z-index based compositing - Modal Dialog with Focus Trapping - Popup / Dropdown menus - Click-outside dismissal mechanism	layer_demo demonstrates Limoni layered rendering capabilities: - Layered Rendering with z-index based compositing - Modal Dialog with Focus Trapping - Popup / Dropdown menus - Click-outside dismissal mechanism
paint command
showcase command
simple command
ssh_server command
table_virtual command
toast command
todo command
treeview command
wasm command
graphics
internal
tools/widgetdocs command Command widgetdocs, widgets paketindeki kaynak koddan docs/widget-gallery.md dosyasını üretir.	Command widgetdocs, widgets paketindeki kaynak koddan docs/widget-gallery.md dosyasını üretir.
layout
testkit Package testkit provides deterministic, terminal-independent helpers for testing Limoni widgets and frames.	Package testkit provides deterministic, terminal-independent helpers for testing Limoni widgets and frames.
widgets

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

README ¶

🍋 Limoni

⚡ Overview

🆕 What's New & Recent Updates

💡 Why Limoni?

🍋 Limoni Composable (Lego UI) vs. 🎀 Charm Lipgloss

Why Zero-Allocation Architecture Matters:

Key Advantages:

🎬 Showcase & Demos

🎮 3D Mesh & Vector Graphics Engine

📁 Superfile-Grade TreeView & Image Previews

📊 High-Resolution Charts & Data Visualization

✨ Key Features

🚀 Quick Start

Installation

1. Composable Lego-Style UI Example (Zero Allocation)

2. Interactive TEA (The Elm Architecture) Example

📚 Documentation

🧩 Rich Widget Ecosystem

🏛️ Architecture

1. Zero-Allocation Rendering Pipeline

2. Decoupled, Non-Dogmatic Concurrency & TEA

📊 Benchmarks

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

🖥️ Rendering Quirks & FAQ

1. Why do lines, 3D meshes, or images show hairline gaps in some terminals?

How Limoni Solves This: The Lower Half-Block (▄) Baseline Standard

2. Recommended Terminal Settings for Visual Perfection

3. How does Limoni maintain 60+ FPS during rapid full-screen animations?

📂 Examples & Showcase Applications

🌟 Awesome Limoni

💡 Engineering Philosophy & Acknowledgements

Transparency & Tooling

🤝 Contributing

🛡️ Security Policy

📜 Code of Conduct

📄 License

Documentation ¶

Index ¶

Constants ¶

Variables ¶

Functions ¶

func DispatchEvent ¶ added in v0.2.0

func Run ¶

func RuneWidth ¶

func Start ¶

func StringWidth ¶

func Wakeup ¶ added in v0.2.1

Types ¶

type AlignItems ¶ added in v0.2.0

type Alignment ¶

type AppOption ¶ added in v0.2.0

func WithCatchCtrlC ¶ added in v0.2.0

func WithFPS ¶ added in v0.2.3

func WithoutDefaultQuitKeys ¶ added in v0.2.0

type Backend ¶

type Block ¶

func NewBlock ¶

type BorderEdges ¶ added in v0.2.0

type BorderSymbols ¶

type Buffer ¶

type Cell ¶

type Checkbox ¶

type Color ¶

func ANSI ¶

func Hex ¶

func RGB ¶

type ColorType ¶

type Component ¶ added in v0.2.0

func AlignComponent ¶ added in v0.2.0

func AsComponent ¶ added in v0.2.0

func Border ¶ added in v0.2.0

func BorderCustom ¶ added in v0.2.0

func BottomBorder ¶ added in v0.2.0

func Center ¶ added in v0.2.0

func Constrain ¶ added in v0.2.0

func Divider ¶ added in v0.2.0

func DividerWithTitle ¶ added in v0.2.0

func Dynamic ¶ added in v0.2.0

func Empty ¶ added in v0.2.0

How Limoni Solves This: The Lower Half-Block (`▄`) Baseline Standard