Crate Boundaries: The Full Specification

For each crate: responsibility, what it must not know about, public API, internal state, dependencies, test strategy, platform independence — and, added here because it is the part that makes a boundary real, the concrete capability lost if the boundary breaks.

The workspace chapter gave you these as a plan. This chapter is the audit: check your actual code against each row.

1. terminal-protocol

Audit command:

cargo tree -p terminal-protocol --depth 1     # must show ONLY the crate itself
cargo build -p terminal-protocol --target wasm32-unknown-unknown
grep -rn "cfg(unix)\|cfg(windows)\|cfg(target_os" crates/terminal-protocol/src/   # empty

2. terminal-core

The take_* pattern deserves a note. terminal-core does no I/O, but several sequences require an effect outside the screen: CSI 6n needs a reply written to the PTY; OSC 52 needs the clipboard set; OSC 0 needs the window title changed. Rather than taking callbacks (which would put the caller's types into the core's signatures) or doing I/O (which would destroy portability), the core queues requests the caller drains. That inversion is the single most important API decision in the workspace.

cargo tree -p terminal-core | grep -E 'nix|rustix|libc|mio|tokio|winit|wgpu'   # must be empty
cargo build -p terminal-core --target wasm32-unknown-unknown

3. terminal-input

Note: The dependency on terminal-core is the weakest link in the graph, and it exists only for TerminalModes. Moving the mode flags into terminal-protocol (where they arguably belong — they are protocol state, not screen state) would make terminal-input depend on nothing but the protocol. That is a real refactor worth considering, and noticing it is exactly the kind of thing this audit is for.

4. terminal-pty

This crate's non-portability is a feature. It is the designated place for cfg(unix) and cfg(windows), and its existence is what keeps every other crate clean. Adding a ConPTY backend should require changing exactly one crate.

# Everything EXCEPT terminal-pty and terminal-gui must be cfg-free:
grep -rn "cfg(unix)\|cfg(windows)\|cfg(target_os" crates/ \
  | grep -v terminal-pty | grep -v terminal-gui        # must be empty

5. terminal-render-model

This is the crate people skip, and skipping it is why terminal codebases end up with renderers reaching into Grid's private fields.

6. terminal-gui

7. terminal-mux

cargo tree -p terminal-mux | grep -E 'winit|wgpu|softbuffer|fontdue|cosmic-text'   # must be empty

8. terminal-debugger

9. terminal-cli

Configuration: The Concern Everyone Gets Wrong

Concern 8 from the section index. Configuration is where clean architectures go to die, because it is tempting to make it global.

#![allow(unused)]
fn main() {
// ✗ WRONG. Now terminal-core depends on a file format, a filesystem, a global,
// and initialization order. It no longer compiles for WASM. It cannot be
// instantiated twice with different settings — which the MUX needs.
static CONFIG: OnceLock<Config> = OnceLock::new();
impl Terminal {
    fn new(rows: usize, cols: usize) -> Self {
        let scrollback = CONFIG.get().unwrap().scrollback_limit;   // NO
        // ...
    }
}

// ✓ RIGHT. Configuration is DATA, passed down. The core does not know what TOML
// is, cannot read a file, and can be instantiated a hundred times with a
// hundred different configurations — which is exactly what the mux does.
#[derive(Clone, Debug)]
pub struct TerminalConfig {
    pub scrollback_limit: usize,
    pub tab_width: usize,
    pub ambiguous_width_is_wide: bool,
    pub clipboard_policy: ClipboardPolicy,
    pub max_osc_len: usize,
}
impl Default for TerminalConfig { /* documented, sensible defaults */ }

impl Terminal {
    pub fn new(rows: usize, cols: usize, config: TerminalConfig) -> Self { /* ... */ }
}
}

The rule: each crate defines the config struct it needs, with Default. The application parses the file, builds each struct, and passes them down. Only terminal-gui and the mux binaries know that TOML exists.

Live reload then falls out for free: the app re-parses and calls terminal.set_config(new). No global to invalidate, no ordering problem.

The Audit: Run This Against Your Code

#!/usr/bin/env bash
set -e
echo "=== 1. terminal-protocol has no dependencies ==="
test "$(cargo tree -p terminal-protocol --depth 1 | wc -l)" -le 2

echo "=== 2. terminal-core has no OS dependencies ==="
! cargo tree -p terminal-core | grep -E 'nix|rustix|libc|mio|tokio|winit|wgpu'

echo "=== 3. terminal-mux has no GUI dependencies ==="
! cargo tree -p terminal-mux | grep -E 'winit|wgpu|softbuffer|fontdue|cosmic-text'

echo "=== 4. terminal-input has no windowing dependencies ==="
! cargo tree -p terminal-input | grep -E 'winit|wgpu|softbuffer'

echo "=== 5. The portable crates build for wasm32 ==="
cargo build --target wasm32-unknown-unknown \
  -p terminal-protocol -p terminal-core -p terminal-render-model -p terminal-input

echo "=== 6. Platform cfgs are confined to pty and gui ==="
! grep -rn 'cfg(unix)\|cfg(windows)\|cfg(target_os' crates/ \
    --include=*.rs | grep -v terminal-pty | grep -v terminal-gui

echo "=== 7. Public APIs are documented ==="
cargo doc --no-deps --workspace 2>&1 | grep -q 'missing documentation' && exit 1 || true

echo "=== 8. No escape bytes in terminal-pty ==="
! grep -rn '0x1b\|\\x1b\|\\033' crates/terminal-pty/src/

echo "ALL BOUNDARY CHECKS PASSED"

Put this in CI. It is eight commands, it runs in seconds, and it is the difference between a designed architecture and a described one.

Reading Other Projects Against This Map

The best way to confirm the pattern is general is to find it elsewhere:

Exercise: clone one of these, run cargo tree or read its module layout, and produce the mapping table onto your nine crates. Where it differs, ask what it bought them. That exercise is worth more than another chapter of prose.

Validation / Self-check

1. For each of the nine crates: responsibility, one thing it must not know, and the capability lost if that boundary breaks.
2. Which crate is allowed to be platform-specific, and why is it a virtue that it is the only one?
3. Explain the take_* pattern. Why not callbacks? Why not I/O?
4. Why does terminal-input depend on terminal-core, and what refactor would remove it?
5. Why must configuration be passed down rather than read from a global? Name three things a global costs you.
6. Write the eight audit commands from memory.
7. Which arrow in the dependency graph must never exist, and what does it cost?
8. Map alacritty_terminal, vte, termwiz, and libghostty onto your crates.
9. Your renderer needs a cell's hyperlink URI. Which crate exposes it, and how, without putting a String in Cell?
10. Run the audit script. Which checks fail on your code, and what will you do about each?

Next: Embedding Scenarios.