justerm-core 0.7.0

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 (e.g. beamterm, WebGL2).
  • Theme-agnostic — colors are references (Default / Indexed / RGB), never resolved hex; the consumer resolves them.

Pairs as the engine half of a -term family with the renderer beamterm. First consumer: PenTerm.

Status: early. The architecture is design-complete and prior-art-validated; implementation is in progress per the build plan. Start at issue #2 (the only currently-unblocked slice).

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 beamterm).
  • Build plan: GitHub issues — Epic #1 (the PRD-equivalent) + slices #2–#12.

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.