leaf

A small, no-frills terminal emulator for macOS, rendered on the GPU with wgpu. It does what vim, tmux, less and a shell need and not much else: no tabs, splits, profiles, plugins or scripting. The whole thing is ~4,000 lines of Rust meant to be read and changed.

Build and run

cargo run --release
make app        # target/release/Leaf.app
make install    # copies it to /Applications

The icon is the leaf from Yarndings 20 (SIL Open Font License). make icon FONT=path/to/font.ttf GLYPH=h redraws macos/Leaf.icns from any glyph of any font.

What it supports

16, 256 and 24-bit color; bold, italic, dim, underline, strikethrough, inverse
Any installed font by family name (or a font file path), with real bold/italic faces and automatic fallback for CJK, emoji and symbols
Programming ligatures (->, !=, >= ... in fonts like Berkeley Mono, Fira Code or JetBrains Mono), via text shaping
Combining characters (accents, Vietnamese tone marks, emoji variation selectors)
Box-drawing, block and powerline characters drawn by leaf itself, so vim splits, tmux borders and statuslines join seamlessly
Alternate screen, scroll regions, application cursor keys, bracketed paste, focus events, synchronized output, cursor shape changes (vim's t_SI/t_EI)
Mouse reporting (vim mouse=a, tmux), with Shift held to select instead
Scrollback, mouse/trackpad scrolling, click-drag / double-click (word) / triple-click (line) selection
Text re-wraps when the window is resized
Blinking cursor (programs like vim can switch blinking and shape)
OSC 52 clipboard writes (e.g. vim/tmux yanking over ssh), window titles
Multiple windows

Keys

Key	Action
Cmd+C / Cmd+V	Copy selection / paste
Cmd+N / Cmd+W	New window / close window
Cmd+= / Cmd+- / Cmd+0	Bigger / smaller / default font size
Cmd+K	Clear scrollback
Cmd+← / Cmd+→	Start / end of line
Option+← / Option+→	Back / forward a word
Cmd+Backspace / Option+Backspace	Delete to start of line / previous word
Cmd+Delete / Option+Delete	Delete to end of line / next word
Cmd+↑ / Cmd+↓	Scroll back / forward a line
Cmd or Shift + PageUp / PageDown	Scroll back / forward a page
Cmd or Shift + Home / End	Top / bottom of scrollback
Option+key	Sent as Meta (Esc+key); see `option_as_alt`
Cmd+drag	Move the window from anywhere in it

The line-editing keys work like iTerm's "Natural Text Editing" preset: they send the shell's (readline/zsh) bindings Ctrl-A, Ctrl-E, Ctrl-U, Ctrl-W, Ctrl-K, Esc-b, Esc-f and Esc-d, as iTerm does. In vim's insert mode only the Backspace ones (Ctrl-U, Ctrl-W) mean the same thing.

Mouse wheel scrolls the scrollback; in full-screen programs without mouse support (less, man) it sends arrow keys instead.

Configuration

~/.config/leaf/config.toml is read at startup. Everything is optional; these are the defaults:

[font]
family = "Menlo"            # family name, or a path like "~/fonts/Foo.ttf"
size = 14.0                 # points
line_height = 1.0           # multiplier
fallback = []               # extra families for missing glyphs, e.g. ["Symbols Nerd Font Mono"]
builtin_box_drawing = true  # draw ─│┌ ▀█ etc. instead of using the font
ligatures = true

[window]
columns = 100
rows = 30
padding = 6.0               # points
option_as_alt = "both"      # "both", "left", "right" or "none" (Option types special characters)
decorations = "buttonless"  # "buttonless", "transparent", "none" or "full" (see below)

[colors]
foreground = "#d4d4d4"
background = "#1c1c1c"
cursor = "#d4d4d4"
# cursor_text = "#1c1c1c"   # text under the block cursor; defaults to background
selection = "#3e4a5c"
palette = [
  "#1c1c1c", "#e06c75", "#98c379", "#e5c07b", "#61afef", "#c678dd", "#56b6c2", "#c8c8c8",
  "#5c6370", "#ff7a85", "#b5e890", "#ffd88a", "#82c4ff", "#de96f0", "#7ad4de", "#ffffff",
]

[terminal]
# shell = "/bin/zsh"        # defaults to $SHELL, run as a login shell
args = []
# working_directory = "~"   # defaults to $HOME
scrollback = 10000
cursor_style = "block"      # "block", "beam" or "underline"
cursor_blink = true
scroll_multiplier = 3.0
copy_on_select = false

decorations picks the window frame on macOS:

buttonless: no visible title bar or buttons; drag the window by the strip along its top (double-click it to zoom)
transparent: like buttonless, with the traffic-light buttons
none: no title bar or border at all, square corners; move the window with Cmd+drag
full: the standard title bar (dark when the background is dark)

Finding your way around

File	What's in it
`src/main.rs`	Windows, the event loop, keyboard shortcuts, mouse and selection
`src/term.rs`	Terminal state and escape-sequence handling (the xterm subset)
`src/input.rs`	Key and mouse events → bytes for the program
`src/renderer.rs`	wgpu setup, glyph atlas, building each frame
`src/shader.wgsl`	The one shader: instanced rects and glyphs
`src/font.rs`	Font lookup, fallback, shaping and rasterizing (swash)
`src/boxdraw.rs`	Procedurally drawn line and block characters
`src/pty.rs`	Starting the shell on a pseudo-terminal
`src/config.rs`	Config file and defaults

Things deliberately left out: tabs and splits (use tmux), IME composition, images, hyperlinks, and the kitty keyboard protocol.

cargo test runs the terminal-emulation and key-encoding tests.

# leaf

A small, no-frills terminal emulator for macOS, rendered on the GPU with
[wgpu](https://wgpu.rs). It does what vim, tmux, less and a shell need and
not much else: no tabs, splits, profiles, plugins or scripting. The whole
thing is ~4,000 lines of Rust meant to be read and changed.

## Build and run

```sh
cargo run --release
make app        # target/release/Leaf.app
make install    # copies it to /Applications
```

The icon is the leaf from [Yarndings 20](https://fonts.google.com/specimen/Yarndings+20)
(SIL Open Font License). `make icon FONT=path/to/font.ttf GLYPH=h` redraws
`macos/Leaf.icns` from any glyph of any font.

## What it supports

- 16, 256 and 24-bit color; bold, italic, dim, underline, strikethrough, inverse
- Any installed font by family name (or a font file path), with real bold/italic
  faces and automatic fallback for CJK, emoji and symbols
- Programming ligatures (`->`, `!=`, `>=` ... in fonts like Berkeley Mono, Fira
  Code or JetBrains Mono), via text shaping
- Combining characters (accents, Vietnamese tone marks, emoji variation selectors)
- Box-drawing, block and powerline characters drawn by leaf itself, so vim
  splits, tmux borders and statuslines join seamlessly
- Alternate screen, scroll regions, application cursor keys, bracketed paste,
  focus events, synchronized output, cursor shape changes (vim's `t_SI`/`t_EI`)
- Mouse reporting (vim `mouse=a`, tmux), with Shift held to select instead
- Scrollback, mouse/trackpad scrolling, click-drag / double-click (word) /
  triple-click (line) selection
- Text re-wraps when the window is resized
- Blinking cursor (programs like vim can switch blinking and shape)
- OSC 52 clipboard writes (e.g. vim/tmux yanking over ssh), window titles
- Multiple windows

## Keys

| Key | Action |
| --- | --- |
| Cmd+C / Cmd+V | Copy selection / paste |
| Cmd+N / Cmd+W | New window / close window |
| Cmd+= / Cmd+- / Cmd+0 | Bigger / smaller / default font size |
| Cmd+K | Clear scrollback |
| Cmd+← / Cmd+→ | Start / end of line |
| Option+← / Option+→ | Back / forward a word |
| Cmd+Backspace / Option+Backspace | Delete to start of line / previous word |
| Cmd+Delete / Option+Delete | Delete to end of line / next word |
| Cmd+↑ / Cmd+↓ | Scroll back / forward a line |
| Cmd or Shift + PageUp / PageDown | Scroll back / forward a page |
| Cmd or Shift + Home / End | Top / bottom of scrollback |
| Option+key | Sent as Meta (Esc+key); see `option_as_alt` |
| Cmd+drag | Move the window from anywhere in it |

The line-editing keys work like iTerm's "Natural Text Editing" preset: they send
the shell's (readline/zsh) bindings Ctrl-A, Ctrl-E, Ctrl-U, Ctrl-W, Ctrl-K, Esc-b,
Esc-f and Esc-d, as iTerm does. In vim's insert mode only the Backspace ones
(Ctrl-U, Ctrl-W) mean the same thing.

Mouse wheel scrolls the scrollback; in full-screen programs without mouse
support (less, man) it sends arrow keys instead.

## Configuration

`~/.config/leaf/config.toml` is read at startup. Everything is optional; these
are the defaults:

```toml
[font]
family = "Menlo"            # family name, or a path like "~/fonts/Foo.ttf"
size = 14.0                 # points
line_height = 1.0           # multiplier
fallback = []               # extra families for missing glyphs, e.g. ["Symbols Nerd Font Mono"]
builtin_box_drawing = true  # draw ─│┌ ▀█ etc. instead of using the font
ligatures = true

[window]
columns = 100
rows = 30
padding = 6.0               # points
option_as_alt = "both"      # "both", "left", "right" or "none" (Option types special characters)
decorations = "buttonless"  # "buttonless", "transparent", "none" or "full" (see below)

[colors]
foreground = "#d4d4d4"
background = "#1c1c1c"
cursor = "#d4d4d4"
# cursor_text = "#1c1c1c"   # text under the block cursor; defaults to background
selection = "#3e4a5c"
palette = [
  "#1c1c1c", "#e06c75", "#98c379", "#e5c07b", "#61afef", "#c678dd", "#56b6c2", "#c8c8c8",
  "#5c6370", "#ff7a85", "#b5e890", "#ffd88a", "#82c4ff", "#de96f0", "#7ad4de", "#ffffff",
]

[terminal]
# shell = "/bin/zsh"        # defaults to $SHELL, run as a login shell
args = []
# working_directory = "~"   # defaults to $HOME
scrollback = 10000
cursor_style = "block"      # "block", "beam" or "underline"
cursor_blink = true
scroll_multiplier = 3.0
copy_on_select = false
```

`decorations` picks the window frame on macOS:

- `buttonless`: no visible title bar or buttons; drag the window by the strip
  along its top (double-click it to zoom)
- `transparent`: like `buttonless`, with the traffic-light buttons
- `none`: no title bar or border at all, square corners; move the window with
  Cmd+drag
- `full`: the standard title bar (dark when the background is dark)

## Finding your way around

| File | What's in it |
| --- | --- |
| `src/main.rs` | Windows, the event loop, keyboard shortcuts, mouse and selection |
| `src/term.rs` | Terminal state and escape-sequence handling (the xterm subset) |
| `src/input.rs` | Key and mouse events → bytes for the program |
| `src/renderer.rs` | wgpu setup, glyph atlas, building each frame |
| `src/shader.wgsl` | The one shader: instanced rects and glyphs |
| `src/font.rs` | Font lookup, fallback, shaping and rasterizing (swash) |
| `src/boxdraw.rs` | Procedurally drawn line and block characters |
| `src/pty.rs` | Starting the shell on a pseudo-terminal |
| `src/config.rs` | Config file and defaults |

Things deliberately left out: tabs and splits (use tmux), IME composition,
images, hyperlinks, and the kitty keyboard protocol.

`cargo test` runs the terminal-emulation and key-encoding tests.

1	`# leaf`
2
3	`A small, no-frills terminal emulator for macOS, rendered on the GPU with`
4	`[wgpu](https://wgpu.rs). It does what vim, tmux, less and a shell need and`
5	`not much else: no tabs, splits, profiles, plugins or scripting. The whole`
6	`thing is ~4,000 lines of Rust meant to be read and changed.`
7
8	`## Build and run`
9
10	```sh
11	`cargo run --release`
12	`make app # target/release/Leaf.app`
13	`make install # copies it to /Applications`
14	```
15
16	`The icon is the leaf from [Yarndings 20](https://fonts.google.com/specimen/Yarndings+20)`
17	(SIL Open Font License). `make icon FONT=path/to/font.ttf GLYPH=h` redraws
18	`macos/Leaf.icns` from any glyph of any font.
19
20	`## What it supports`
21
22	`- 16, 256 and 24-bit color; bold, italic, dim, underline, strikethrough, inverse`
23	`- Any installed font by family name (or a font file path), with real bold/italic`
24	`faces and automatic fallback for CJK, emoji and symbols`
25	- Programming ligatures (`->`, `!=`, `>=` ... in fonts like Berkeley Mono, Fira
26	`Code or JetBrains Mono), via text shaping`
27	`- Combining characters (accents, Vietnamese tone marks, emoji variation selectors)`
28	`- Box-drawing, block and powerline characters drawn by leaf itself, so vim`
29	`splits, tmux borders and statuslines join seamlessly`
30	`- Alternate screen, scroll regions, application cursor keys, bracketed paste,`
31	focus events, synchronized output, cursor shape changes (vim's `t_SI`/`t_EI`)
32	- Mouse reporting (vim `mouse=a`, tmux), with Shift held to select instead
33	`- Scrollback, mouse/trackpad scrolling, click-drag / double-click (word) /`
34	`triple-click (line) selection`
35	`- Text re-wraps when the window is resized`
36	`- Blinking cursor (programs like vim can switch blinking and shape)`
37	`- OSC 52 clipboard writes (e.g. vim/tmux yanking over ssh), window titles`
38	`- Multiple windows`
39
40	`## Keys`
41
42	`\| Key \| Action \|`
43	`\| --- \| --- \|`
44	`\| Cmd+C / Cmd+V \| Copy selection / paste \|`
45	`\| Cmd+N / Cmd+W \| New window / close window \|`
46	`\| Cmd+= / Cmd+- / Cmd+0 \| Bigger / smaller / default font size \|`
47	`\| Cmd+K \| Clear scrollback \|`
48	`\| Cmd+← / Cmd+→ \| Start / end of line \|`
49	`\| Option+← / Option+→ \| Back / forward a word \|`
50	`\| Cmd+Backspace / Option+Backspace \| Delete to start of line / previous word \|`
51	`\| Cmd+Delete / Option+Delete \| Delete to end of line / next word \|`
52	`\| Cmd+↑ / Cmd+↓ \| Scroll back / forward a line \|`
53	`\| Cmd or Shift + PageUp / PageDown \| Scroll back / forward a page \|`
54	`\| Cmd or Shift + Home / End \| Top / bottom of scrollback \|`
55	\| Option+key \| Sent as Meta (Esc+key); see `option_as_alt` \|
56	`\| Cmd+drag \| Move the window from anywhere in it \|`
57
58	`The line-editing keys work like iTerm's "Natural Text Editing" preset: they send`
59	`the shell's (readline/zsh) bindings Ctrl-A, Ctrl-E, Ctrl-U, Ctrl-W, Ctrl-K, Esc-b,`
60	`Esc-f and Esc-d, as iTerm does. In vim's insert mode only the Backspace ones`
61	`(Ctrl-U, Ctrl-W) mean the same thing.`
62
63	`Mouse wheel scrolls the scrollback; in full-screen programs without mouse`
64	`support (less, man) it sends arrow keys instead.`
65
66	`## Configuration`
67
68	`~/.config/leaf/config.toml` is read at startup. Everything is optional; these
69	`are the defaults:`
70
71	```toml
72	`[font]`
73	`family = "Menlo" # family name, or a path like "~/fonts/Foo.ttf"`
74	`size = 14.0 # points`
75	`line_height = 1.0 # multiplier`
76	`fallback = [] # extra families for missing glyphs, e.g. ["Symbols Nerd Font Mono"]`
77	`builtin_box_drawing = true # draw ─│┌ ▀█ etc. instead of using the font`
78	`ligatures = true`
79
80	`[window]`
81	`columns = 100`
82	`rows = 30`
83	`padding = 6.0 # points`
84	`option_as_alt = "both" # "both", "left", "right" or "none" (Option types special characters)`
85	`decorations = "buttonless" # "buttonless", "transparent", "none" or "full" (see below)`
86
87	`[colors]`
88	`foreground = "#d4d4d4"`
89	`background = "#1c1c1c"`
90	`cursor = "#d4d4d4"`
91	`# cursor_text = "#1c1c1c" # text under the block cursor; defaults to background`
92	`selection = "#3e4a5c"`
93	`palette = [`
94	`"#1c1c1c", "#e06c75", "#98c379", "#e5c07b", "#61afef", "#c678dd", "#56b6c2", "#c8c8c8",`
95	`"#5c6370", "#ff7a85", "#b5e890", "#ffd88a", "#82c4ff", "#de96f0", "#7ad4de", "#ffffff",`
96	`]`
97
98	`[terminal]`
99	`# shell = "/bin/zsh" # defaults to $SHELL, run as a login shell`
100	`args = []`
101	`# working_directory = "~" # defaults to $HOME`
102	`scrollback = 10000`
103	`cursor_style = "block" # "block", "beam" or "underline"`
104	`cursor_blink = true`
105	`scroll_multiplier = 3.0`
106	`copy_on_select = false`
107	```
108
109	`decorations` picks the window frame on macOS:
110
111	- `buttonless`: no visible title bar or buttons; drag the window by the strip
112	`along its top (double-click it to zoom)`
113	- `transparent`: like `buttonless`, with the traffic-light buttons
114	- `none`: no title bar or border at all, square corners; move the window with
115	`Cmd+drag`
116	- `full`: the standard title bar (dark when the background is dark)
117
118	`## Finding your way around`
119
120	`\| File \| What's in it \|`
121	`\| --- \| --- \|`
122	\| `src/main.rs` \| Windows, the event loop, keyboard shortcuts, mouse and selection \|
123	\| `src/term.rs` \| Terminal state and escape-sequence handling (the xterm subset) \|
124	\| `src/input.rs` \| Key and mouse events → bytes for the program \|
125	\| `src/renderer.rs` \| wgpu setup, glyph atlas, building each frame \|
126	\| `src/shader.wgsl` \| The one shader: instanced rects and glyphs \|
127	\| `src/font.rs` \| Font lookup, fallback, shaping and rasterizing (swash) \|
128	\| `src/boxdraw.rs` \| Procedurally drawn line and block characters \|
129	\| `src/pty.rs` \| Starting the shell on a pseudo-terminal \|
130	\| `src/config.rs` \| Config file and defaults \|
131
132	`Things deliberately left out: tabs and splits (use tmux), IME composition,`
133	`images, hyperlinks, and the kitty keyboard protocol.`
134
135	`cargo test` runs the terminal-emulation and key-encoding tests.