A Terminal User Interface (TUI) Library for Odin

Ansuz is an immediate-mode TUI library inspired by Clay, designed specifically for the Odin programming language.

• True Immediate Mode API - Simple, declarative UI that's easy to reason about
• Full Frame Rendering - Complete screen redraw each frame for maximum simplicity
• Raw Terminal Control - Direct ANSI escape sequence management
• Full Color Support - 16-color ANSI, 256-color palette, and 24-bit TrueColor (RGB)
• Layout System - Flexible layout engine inspired by Clay (flex-like)
• Cross-Platform - Unix/Linux support (Windows planned)

• Odin compiler (latest)
• Unix/Linux terminal

This project uses mise for task management, but tasks are standard bash scripts that can be run directly.

Using mise (Recommended):

mise run build        # Build all examples
mise run build -- -c  # Clean and build
./bin/hello_world     # Run example

Using Odin directly:

odin build examples/hello_world.odin -file -out:bin/hello_world
./bin/hello_world

• Architecture - Technical overview, immediate mode concepts, and ANSI reference.
• API Reference - Detailed API documentation for context management, drawing, and input.
• Layout System - Guide to the flex-box inspired layout engine.
• Testing - Testing patterns and guide.
• Odin Patterns - Common idioms used in the codebase.

package main

import ansuz "ansuz"

main :: proc() {
    ctx, err := ansuz.init()
    if err != .None do return
    defer ansuz.shutdown(ctx)

    ansuz.run(ctx, proc(ctx: ^ansuz.Context) -> bool {
        for event in ansuz.poll_events(ctx) {
            if ansuz.is_quit_key(event) do return false
        }

        if ansuz.layout(ctx) {
            if ansuz.container(ctx, {
                direction = .TopToBottom,
                sizing = {.X = ansuz.grow(), .Y = ansuz.grow()},
                alignment = {.Center, .Center},
            }) {
                if ansuz.box(ctx, {
                    sizing = {.X = ansuz.fixed(40), .Y = ansuz.fixed(9)},
                }, ansuz.style(.BrightCyan, .Default, {}), .Rounded) {
                    ansuz.label(ctx, "Hello, Ansuz!")
                }
            }
        }

        return true
    })
}

Key features of the new scoped API:

• No callbacks - Use if ansuz.container(ctx) { ... } instead of callback procs
• Local variables accessible - Variables in enclosing scope work inside blocks
• Auto-cleanup - Containers close automatically when scope exits via @(deferred_in_out)
• Natural control flow - return, break, continue work normally

Status: Early Development / MVP Phase Platform: Unix/Linux

Key implemented features:

• ✅ Core immediate mode architecture with full-frame redraws
• ✅ Scoped layout API and Clay-style element helpers
• ✅ Basic Drawing (Text, Rects, Boxes)
• ✅ Input Handling (Keys, Resize)
• ✅ Theme-driven widgets (buttons, checkboxes) with focus management

See AGENTS.md for internal development workflows and contribution guidelines.

MIT - See LICENSE for details.