justerm-core 0.9.1

A pure terminal engine: VT byte stream to grid + scrollback + damage. No I/O, no rendering, theme-agnostic.
Documentation

justerm-core

A pure terminal engine in Rust — the core crate of the justerm family. Feed it a VT byte stream; it owns the terminal state (grid + scrollback + cursor + selection) and emits a viewport snapshot, damage, scroll ops, and extractable text. It is not a renderer and not a full emulator.

  • No I/O — the caller feeds bytes (feed(&[u8])); justerm-core never touches a PTY/SSH/socket.
  • No IPC — it provides a binary format, not transport.
  • No rendering — a renderer draws (the family's first-party justerm-renderer, WebGL2, replacing the third-party beamterm).
  • Theme-agnostic — colors are references (Default / Indexed / RGB), never resolved hex; the consumer resolves them.

The engine half of the -term family. First consumer: PenTerm.

Status: in active use. The core engine is implemented and consumed across the family (justerm-wasm-decode, justerm-web, justerm-renderer). VT compliance is cumulative — the common cases are covered and the long tail grows as dogfooding surfaces it. See the issue tracker for the current frontier.

Docs (start here)

  • CLAUDE.md — identity, boundary invariants, conventions, working method.
  • CONTEXT.md — glossary.
  • docs/architecture.md — the contract: cell, damage, viewport/scroll, cadence, selection, serialization, engine API — plus a Hidden VT state checklist (with where to look in reference impls) for implementers.
  • docs/adr/ — key decisions (build on vte, not alacritty_terminal; adopt then replace beamterm with the first-party justerm-renderer, ADR-0002 → ADR-0018).
  • Build plan: GitHub issues — Epic #1 (the engine, closed); the family now builds under Epic #103 (justerm-web) and Epic #258 (justerm-renderer).

Web consumers

The wire format's decoder is shipped to the web as justerm-wasm-decode — the native decode compiled to WASM and published to npm, version-locked to this crate, so the backend encoder and the webview decoder share one implementation (no TypeScript mirror to drift). It decodes into structure-of-arrays cell columns and ships the format-owned helpers (resolveRgb / buildPalette / flags); the theme values (your palette) and render policy (atlas, cursor) stay the consumer's adapter. See justerm-wasm-decode/README.md and ADR-0008.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.