@effect-tui/core

Low-level terminal UI primitives built with Effect.

Installation

bun add @effect-tui/core effect

Features

• CellBuffer - Frame storage with glyph, style, and width-aware cells
• Palette - Style deduplication for ANSI output
• Colors - Color helpers (indexed, RGB, hex, grayscale)
• Keys - Raw TTY key decoding
• Spring animations - Analytical spring physics

Core Concepts

CellBuffer

A 2D grid of cells, each storing a codepoint, style ID, and width. Handles wide characters (CJK, emoji) correctly.

const buffer = new CellBuffer(80, 24)
buffer.put(0, 0, "Hello", styleId)     // Put string
buffer.drawCP(5, 0, 0x1F600, styleId)  // Draw codepoint (emoji)
buffer.fillRect(0, 1, 10, 3, 32, styleId) // Fill rectangle

Palette

Maps style objects to numeric IDs and generates ANSI escape sequences:

const palette = new Palette()
const style = palette.id({ fg: Colors.green, bg: Colors.black })
const ansi = palette.sgr(style)  // "\x1b[32;40m"

Colors

Colors.red           // Named color (indexed)
Colors.rgb(255,0,0)  // RGB
Colors.hex("#ff0000") // Hex
Colors.gray(12)      // Grayscale (0-23)
Colors.idx(196)      // 256-color index

Basic Usage

import { CellBuffer, Surface, Colors } from "@effect-tui/core"

// Create a buffer
const buffer = new CellBuffer(80, 24)
buffer.put(0, 0, "Hello", { fg: Colors.green })

// Render to terminal
const surface = new Surface(process.stdout)
surface.render(buffer)

Spring Physics

Analytical spring equations (matches framer-motion):

import { Spring } from "@effect-tui/core"

// Create spring with target
const spring = Spring.init(0)
const animated = Spring.to(spring, 100, { visualDuration: 0.35, bounce: 0.2 })

// Tick each frame
const next = Spring.tick(animated, 16)  // 16ms delta
const value = Spring.value(next)        // Current position
const done = Spring.settled(next)       // Animation complete?

Parameters:

• visualDuration - Time to reach ~99% of target (seconds)
• bounce - Overshoot amount (0 = no bounce, 0.5 = bouncy)

Related

• @effect-tui/react - React renderer for terminal UIs

License

MIT