The Rust Workspace Design

This is the target architecture. You do not build it up front — you grow into it, and Section 5 is where you critique it. But you should know where you are going, because the boundaries here are the same boundaries a real reusable terminal library (libghostty, alacritty_terminal, termwiz) has to draw, and drawing them badly is the most common way a terminal project becomes unmaintainable.

The Workspace

mini-terminal/
├── Cargo.toml                      # [workspace]
├── crates/
│   ├── terminal-protocol/          # M4  bytes → actions
│   ├── terminal-core/              # M5  actions → screen state
│   ├── terminal-input/             # M8  key/mouse events → bytes
│   ├── terminal-pty/               # M2  PTY + process lifecycle
│   ├── terminal-render-model/      # M7  renderer-independent view of the screen
│   ├── terminal-gui/               # M7  winit + CPU/GPU rendering
│   ├── terminal-mux/               # M9  sessions, panes, client/server
│   ├── terminal-debugger/          # M3  hex dump, tracing, record/replay, diff
│   └── terminal-cli/               # M6  headless binary
└── tests/
    ├── golden/                     # recorded byte streams + expected snapshots
    └── integration/                # real-PTY tests

When each crate appears:

flowchart LR
    M1[M1 raw-inspector<br/>throwaway bin] --> M2[M2 terminal-pty]
    M2 --> M3[M3 + terminal-debugger]
    M3 --> M4[M4 terminal-protocol]
    M4 --> M5[M5 terminal-core]
    M5 --> M6[M6 terminal-cli]
    M6 --> M7[M7 render-model + gui]
    M7 --> M8[M8 terminal-input]
    M6 --> M9[M9 terminal-mux]
    M8 --> M9
    M9 --> M13[M13 extract stable APIs]

The Dependency Graph — and the Arrows That Must Not Exist

                      ┌────────────────────┐
                      │ terminal-protocol  │  std + unicode-width only
                      └─────────┬──────────┘
                                │
                      ┌─────────▼──────────┐
                      │   terminal-core    │  the screen; no I/O of any kind
                      └───┬─────────┬──────┘
             ┌────────────┘         └────────────┐
             │                                   │
  ┌──────────▼───────────┐            ┌──────────▼──────────┐
  │ terminal-render-model│            │  terminal-input     │
  └──────────┬───────────┘            └──────────┬──────────┘
             │                                   │
             └──────────────┬────────────────────┘
                            │
      ┌────────────────┐    │    ┌──────────────────┐
      │ terminal-pty   │────┼───▶│  terminal-gui    │  the ONLY crate with pixels
      └───────┬────────┘    │    └──────────────────┘
              │             │
              │      ┌──────▼──────────┐
              └─────▶│  terminal-mux   │  ✗ NEVER depends on terminal-gui
                     └─────────────────┘

Enforce it mechanically, not by discipline:

# terminal-mux must not pull in the GUI stack. This must print nothing.
cargo tree -p terminal-mux | grep -E 'winit|wgpu|softbuffer|fontdue|cosmic-text'

# terminal-core must not pull in any I/O or OS crate. This must print nothing.
cargo tree -p terminal-core | grep -E 'nix|rustix|libc|mio|tokio|winit'

# terminal-protocol must have essentially no dependencies at all.
cargo tree -p terminal-protocol --depth 1

Warning: Put those three commands in CI on the day you create the second crate. Boundary rot is silent and one-directional: nobody ever notices the day terminal-core gained a libc dependency, and by the time you want a headless test harness it is a week of work to remove.

Crate Specifications

For each crate: responsibility, what it must not know about, public API, internal state, dependencies, test strategy, platform independence.

terminal-protocol — bytes to actions

terminal-core — actions to screen state

terminal-input — events to bytes

terminal-pty — the OS integration

terminal-render-model — a renderer-independent view

Note: This crate is the one people skip, and skipping it is why terminal codebases end up with the renderer reaching into the grid's private fields. Its real job is to be a stable boundary: you can swap CPU for GPU rendering, or add a second frontend, without touching terminal-core.

terminal-gui — the only crate that knows about pixels

terminal-mux — sessions, panes, client/server

terminal-debugger — observability

terminal-cli — the headless binary

The Core Types (First Draft — Expect to Change)

The brief proposes these. Take them as a starting sketch, not a specification. Every one of them has a problem you will discover and fix.

#![allow(unused)]
fn main() {
pub struct Terminal {
    parser: Parser,
    screen: Screen,
    modes: TerminalModes,
    cursor: Cursor,
}

pub struct Screen {
    primary: Grid,
    alternate: Grid,
    active_buffer: BufferKind,
    scrollback: Vec<Line>,
}

pub struct Grid {
    rows: usize,
    columns: usize,
    cells: Vec<Cell>,
}

pub struct Cell {
    grapheme: String,
    style: Style,
    width: CellWidth,
}
}

Critique — the problems you will hit, in the order you will hit them

Tip: Do not fix these in advance. Build the naïve version, write the benchmark or the test that exposes the problem, then fix it. A refactor you can justify with a measurement is worth ten you did because a book told you to. That is why this table names the chapter where each one bites.

The Test Layout

mini-terminal/
├── crates/*/src/**            # #[cfg(test)] unit tests live next to the code
├── crates/*/tests/            # per-crate integration tests
└── tests/
    ├── golden/
    │   ├── cases/
    │   │   ├── vim-startup.bytes         # recorded PTY output
    │   │   ├── vim-startup.snapshot      # expected screen, checked in
    │   │   ├── top-one-frame.bytes
    │   │   └── top-one-frame.snapshot
    │   └── golden_test.rs
    └── integration/
        └── pty_test.rs                    # spawns real processes

Details in the Testing Strategy.

Validation / Self-check

1. For each of the nine crates, state its responsibility in one sentence and name one thing it must not know about.
2. Which crate is allowed to be platform-specific, and why is it a virtue that it is the only one?
3. Write the three cargo tree commands that mechanically enforce the boundaries.
4. Why must terminal-mux never depend on terminal-gui? Give the concrete capability you lose.
5. Name three problems with the Cell { grapheme: String, ... } sketch and say which milestone exposes each.
6. If you wanted to run the terminal core in a browser via WebAssembly, which crates could you compile unchanged, and which is the first one that would fail?
7. Where do terminal replies (the response to CSI 6n) come from, and why can terminal-core not just write them to the PTY itself?

Next: The Roadmap — fifteen milestones with concrete completion criteria.