termgrid-core

termgrid-core is a deterministic terminal grid state engine.

It provides a canonical grid model with invariant enforcement, explicit Unicode width policy via a glyph registry, and damage tracking for incremental redraw. The output surface is backend-decoupled: you apply render operations to a grid, then render the grid through whatever backend you choose (terminal, xterm.js, headless tests, etc.).

Why this exists

Modern “terminal-ish” rendering is frequently stream-oriented (ANSI output) and environment-dependent (Unicode width behavior varies across terminals). For systems that need correctness, replayability, and consistent layout, treating rendering as deterministic state mutation is materially simpler to test and reason about.

Quick start

use termgrid_core::{Grid, Renderer};

let mut grid = Grid::new(80, 25);
let mut r = Renderer::new();

r.draw_text(&mut grid, 0, 0, "Hello, termgrid.");
let damage = r.take_damage();

// Backend renders (&grid, damage)

Documentation

• Documentation site: https://termgrid.entropy.quest
• Rust API (docs.rs): https://docs.rs/termgrid-core
• Wire format v1 (contract): docs/contracts/wire-format-v1.md

Local docs build (includes rustdoc under site/api/):

./scripts/docs_build.sh
python -m http.server -d site 8000

MSRV

Minimum supported Rust version: 1.82.

CI enforces MSRV via a dedicated test lane.

What this crate does not do

• Parse arbitrary ANSI input streams
• Implement a terminal emulator
• Provide IPC/protocol layers (belongs above this crate)

License

Licensed under AGPL-3.0-or-later by default.

A paid commercial license (LicenseRef-VaranidWorks-Commercial-1.0) is available to allow use without AGPL obligations.

See LICENSE and LICENSES/.