Terminal UI libraries often rely on heavy dependencies (e.g., curses) or platform-specific hacks. Lua’s minimal standard library makes this even harder—how can we provide a portable, lightweight solution? In this talk we’ll explore terminal.lua (built on top of luasystem): a minimal, cross-platform terminal UI library for Lua designed to provide essential terminal primitives without external dependencies like curses. The work presented here includes developments made during its participation in GSoC 2025, as well as improvements made afterwards.

Lua intentionally keeps its standard library small, so handling terminals requires defining the true minimum set of capabilities needed for Unix, macOS, and Windows — while keeping the API simple, consistent, and predictable. The talk begins by outlining the problem: how to handle terminals portably and transparently in a lightweight language by creating a level playing field. We’ll then walk through the minimal core implemented in luasystem and how terminal.lua builds a higher-level layer on top.

We’ll discuss: Low-level: - Bridging differences between Unix/POSIX and Windows - UTF-8/Unicode handling (including double-width characters such as emojis) - Non-blocking async keyboard input in single-threaded Lua - Querying the terminal (e.g., retrieving cursor position)

Higher-level: - Representing terminal state (color, cursor position/shape/visibility) - Basic layouting and color handling

Projects:

• LuaSystem — a C library exposing the absolute bare minimum terminal and system primitives needed to let Lua build a UI layer on top: https://github.com/lunarmodules/luasystem
• terminal.lua — the “proof of the pudding”: a pure-Lua UI library that demonstrates what can be built cleanly and portably when sticking to those minimal primitives: https://github.com/lunarmodules/terminal.lua