https://github.com/benyblack/novaterminal

Cross-platform terminal emulator for deterministic rendering, VT correctness, GPU-accelerated performance, and modern SSH workflows.
https://github.com/benyblack/novaterminal

aot avaloniaui conformance cross-platform csharp deterministic developer-tools dotnet gpu-rendering performance pty replay-testing ssh terminal terminal-emulator tui vt-compatibility vt100

Last synced: about 1 month ago
JSON representation

Cross-platform terminal emulator for deterministic rendering, VT correctness, GPU-accelerated performance, and modern SSH workflows.

• Host: GitHub
• URL: https://github.com/benyblack/novaterminal
• Owner: benyblack
• License: mit
• Created: 2026-01-27T17:28:34.000Z (6 months ago)
• Default Branch: main
• Last Pushed: 2026-07-05T16:36:30.000Z (about 1 month ago)
• Last Synced: 2026-07-05T17:05:43.966Z (about 1 month ago)
• Topics: aot, avaloniaui, conformance, cross-platform, csharp, deterministic, developer-tools, dotnet, gpu-rendering, performance, pty, replay-testing, ssh, terminal, terminal-emulator, tui, vt-compatibility, vt100
• Language: C#
• Homepage:
• Size: 4.22 MB
• Stars: 10
• Watchers: 0
• Forks: 1
• Open Issues: 34
• Metadata Files:
  • Readme: README.internal.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Roadmap: docs/ROADMAP.md
  • Agents: AGENTS.md

Awesome Lists containing this project

README

          
# NovaTerminal – Internal Engineering Guide

This document defines **engineering intent**, **non-negotiable rules**, and

**how work is evaluated** in NovaTerminal.

It is authoritative for contributors and automated agents.

---

## Core Principle

> Terminal correctness is enforced by automated tests, not discipline.

Any change that weakens determinism, parity, or replayability is rejected.

---

## Non-Negotiable Rules

1. **Terminal Core is OS-agnostic**

   - No platform conditionals

   - No UI or rendering logic

   - No PTY knowledge

2. **Renderer is semantics-free**

   - Renderer may not “fix” buffer mistakes

   - All drawing is derived from buffer snapshots

3. **Tests have veto power**

   - Replay tests block merges

   - Parity tests block merges

   - Renderer metric regressions block merges

4. **If it cannot be replayed, it cannot be safely fixed**

---

## Architecture Boundaries

The solution keeps terminal semantics isolated behind small project boundaries so the VT core remains pure and reusable:

- **NovaTerminal.App** owns Avalonia UI, interaction, and app composition.

- **NovaTerminal.Platform** owns platform-integration utilities (input routing, path mapping, process abstraction, SSH) and the credential vault.

- **NovaTerminal.VT** owns terminal state, parsing, buffer semantics, and reflow.

- **NovaTerminal.Rendering** owns Skia-based drawing from immutable buffer snapshots.

- **NovaTerminal.Pty** owns OS/process and stream integration.

- **NovaTerminal.Replay** owns recording and replay infrastructure.

Key constraints:

- **NovaTerminal.VT** contains **no** Avalonia or SkiaSharp references.

- **NovaTerminal.Rendering** contains **no** Avalonia references and does not fix semantic bugs.

- **NovaTerminal.Pty** is strictly for stream/process management and binary interop.

- UI concerns stay out of the terminal core logic.

---

## Automated Test Gates

### Phase −1 (Blocking)

- Deterministic replay harness

- Cross-platform parity checks

- Renderer metrics (full redraw, dirty cells, frame time)

### Phase 0 (Correctness)

- VT completeness

- Alternate screen correctness

- Resize & reflow stability

- Zero flicker under stress

Feature work is blocked until these gates pass.

---

## What We Do NOT Optimize For

- Fast feature shipping at the expense of correctness

- Pixel-perfect UI tests over buffer-state tests

- Platform-specific hacks in core logic

- “Looks fine on my machine” fixes

---

## How Changes Are Evaluated

A change is acceptable only if:

- buffer invariants remain intact

- replay tests cover new behavior

- cross-platform parity is preserved

- renderer metrics do not regress

---

## Useful Docs

- `docs/ROADMAP.md` – test-gated product roadmap

- `docs/MODULE_OWNERSHIP.md` – invariant ownership

- `docs/IMPLEMENTATION_WORK_PLAN.md` – correctness-first execution plan

---

## Final Reminder

> UI attracts users.  

> Correctness keeps them.