tuibox

What it is

tuibox (“toybox”) is a single-header C library for terminal UI built around three nested concepts: a UI (the top-level event/render loop), a Screen (a viewport on the terminal), and a Box (a rectangular area with content, event handlers, and child boxes). It’s mouse-driven by default, completely dependency-free (uses only ANSI escape sequences for everything — no termcap, no termios magic beyond what read() needs), and explicitly incrementally adoptable: each part of the library works independently, so a project can use the box hierarchy without the event loop, or the event loop without the render cache, or vice versa. Render is cached with a per-box dirty bit so only changed regions repaint.

Companion projects in the same family (also single-header C, also dependency-free) are linked from the README: bdfedit (bitmap font editor built on tuibox), colorslide (RGBA/HSL/CMYK color picker), vt100utils (ANSI escape encoder/decoder).

Key takeaways for KN-86

• The dirty-bit render cache pattern is the single biggest technical takeaway. Each Box tracks whether its content changed since the last render; the render loop walks the hierarchy and emits ANSI sequences only for the dirty regions. This is exactly the right optimization for KN-86’s nOSh runtime on a Pi Zero 2 W — bandwidth to the Elecrow 7″ panel is finite, full-screen redraws are expensive, and most of the time most of the screen is stable. Cross-link game-programming-patterns.md — “Dirty Flag” is a named pattern in that book.
• UI → Screen → Box hierarchy as the right structural model for nOSh. Maps cleanly onto KN-86’s chrome contract: the UI owns the event loop; the Screen owns the 80×25 grid + the CIPHER-LINE OLED; each Box is a region (Row 0, Rows 1–23, Row 24, or sub-regions inside the cart-content area). Each Box has its own dirty bit, its own event handlers, its own child boxes. Cart authors compose boxes through NoshAPI; the runtime walks the tree.
• The C-core alternative path for KN-86. If the Bubble Tea + Lip Gloss recommendation (per the Batch-3 synthesis) falls through for any reason — Go runtime size, integration with the existing kn86-emulator/ C11 codebase, the desire to ship a smaller binary — tuibox is the single-file C drop-in alternative. Combined with termbox2 (also single-header C, but lower-level) and cl-termbox2 (Common Lisp bindings to termbox2), a fully Lisp-driven C-backed runtime is a real architectural option.
• Pure ANSI escapes, no termcap dependency. Means the library compiles cleanly anywhere with a C compiler. Same property termbox2 has. For a KN-86 runtime that wants to be embeddable inside the existing C emulator (kn86-emulator/), this matters — no library detection at build time, no terminfo at runtime.
• Incremental adoption is a design virtue. Even projects that don’t adopt tuibox wholesale can lift the box-tree pattern, or the dirty-bit cache, or the event-loop structure, individually. Worth treating the source as a reference implementation to read even if not to depend on.

Image

No image downloaded — tuibox is captured as a code-pattern reference. The repo’s demo GIFs (demo_basic.gif, demo_bounce.gif, demo_drag.gif, demo_bdfedit.gif, demo_colorslide.gif) are worth a glance for what tuibox-built UIs feel like in motion, but the value is the source-code patterns, not the demos.

Notes

• Cross-link termbox2.md — the cell-based equivalent. tuibox is higher-level (boxes, events, render cache); termbox2 is lower-level (cells, raw input, present-to-screen). They compose: termbox2 as the cell backend, tuibox patterns on top, for a minimal C-core KN-86 runtime.
• Cross-link game-programming-patterns.md for the Dirty Flag + Game Loop + Observer patterns. tuibox is a small reference implementation of the same.
• Cross-link bubble-tea.md — the recommended primary stack. tuibox is the fallback C-core path, not the default.
• The companion bdfedit, colorslide, and vt100utils projects are useful technical references if KN-86 ever needs a bitmap font editor (for Press Start 2P custom-glyph work) or an ANSI-escape decoder.