1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
# pardes
A text environment in the acme tradition: columns of panes, each pane a tag line
plus a body, where the body is a live terminal, a file, an image, or a PDF. The
mouse carries meaning — left selects, middle executes, right looks — and
everything on screen is text that is equally alive, whether a shell printed it or
you typed it.
One program, five thin shells. The core is a library in the way ghostty-vt is a
library: you feed it events, it returns a surface and a list of effects, and it
performs no IO itself. Everything a shell does is translate native input into
`pardes.Event`, render `pardes.Surface`, and perform `pardes.Effect`.
## Requirements
Zig **0.16.0** (`build.zig.zon` pins `minimum_zig_version`). Dependencies are
fetched and pinned by the manifest; no system package is required for the
terminal build. The SDL shell builds SDL3 and FreeType from source. Native PDF
support builds MuPDF and is on by default (`-Dmupdf=false` to drop it).
## Build
```
zig build
```
That is the whole of it, and it is an *install*: it builds both native shells and
puts them in `~/.local/bin`.
```
~/.local/bin/pardes the terminal shell (libvaxis)
~/.local/bin/pardes-gui the SDL3 window
```
Override with `--prefix <dir>`. Six development binaries install under
`<prefix>/dev` so they never land on a `PATH` by accident: `perf`,
`fs-bench`, `lspbench`, `pdf-scroll-bench`, `hxdiff` and the isolated build.
The other steps below build what they need and install nothing.
```
pardes --version e.g. pardes 0.0.1 (e61bbb2e86bd)
pardes --help every flag
```
The version comes from `build.zig.zon`'s `.version`; the commit is read from
`git` at configure time and is simply absent when there is no repository to ask.
## The five platforms
| build | what it is |
|---|---|
| `zig build` | the terminal shell and the SDL window, together |
| `zig build -Dplatform=tty` | the terminal shell alone |
| `zig build -Dplatform=gui` | the SDL3 window alone |
| `zig build web` | a freestanding wasm core plus vanilla JavaScript, rendered as HTML/CSS |
| `zig build -Dplatform=macos` | an AppKit and CoreText app over a static `libpardes.a` |
| `zig build -Dplatform=esp32p4 -Desp32p4-firmware` | firmware for an ESP32-P4: a freestanding riscv32 object driving libvaxis down a UART, in 384 KiB of heap |
The board build needs an ESP-IDF checkout for its register headers, and adds
`esp32p4-flash`, `esp32p4-attach`, `esp32p4-run`, `esp32p4-reset`,
`esp32p4-image-size`, `esp32p4-image-check` and `esp32p4-test`.
## Detached sessions
A shell need not be in the same process as the core.
```
pardes --detach=work a core with no terminal of its own
pardes --attach=work become a frontend of it
pardes-gui --attach=work ...the SDL window can attach too
```
Several frontends may be attached at once and all see the same screen. The
detached core performs every effect that needs a disk or a process table, so its
pane shells outlive every frontend; a frontend keeps only what needs the human's
own display. From inside the editor, `Attach` and `Detach` do the same thing as
words. See `docs/detached.md`.
## Tests
```
zig build unit-test module and shell unit tests
zig build snap scripted input traces against frozen golden grids
zig build hxdiff differential suite against helix's own behaviour
zig build hxparity file-pane vs pty-pane editing parity
zig build mupdf-check compile, link, render and search docs/design.pdf
zig build web-snap browser touch/LOOK snapshots
zig build web-e2e Chrome-driven DOM end-to-end suite
```
`snap` and `hxdiff` take `-- --update` and explicit case files respectively. The
benchmark steps — `perf`, `pdf-bench`, `pdf-scroll-bench`, `pdf-sections-bench`,
`lspbench`, `fs-bench` — all accept `-- --json`.
## Documentation
`docs/design.pdf` (from `docs/design.typ`) is the architecture document and the
place to start. It is also a test fixture: `mupdf-check` renders and searches it.
| file | subject |
|---|---|
| `docs/design.typ` | architecture: the seams, the data model, the build graph |
| `docs/detached.md` | one core, many frontends, over a unix socket |
| `docs/config.md` | build options and runtime configuration |
| `docs/acme-fs.md` | the acme control filesystem (`--fs`) |
| `docs/lsp.md` | the in-process ZLS backend |
| `docs/lsp-evaluation.md` | why that backend, measured against the alternatives |
| `docs/helix-keys.md` | the helix-compatible key model and its differential suite |
| `docs/macos.md` | the native macOS shell, its bundle and its signing |
| `docs/web.md` | the browser shell |
| `docs/ghostty-macos-notes.md` | notes on the ghostty dependency |
| `docs/ideas.typ` | scratch notes; nothing compiles it, and it says so |
`next-steps.txt` is a wishlist with a status header saying which items have
shipped; `transactions.txt` records one open structural gap against helix, and
says which waiver proves it is still open.
## Layout
```
src/ the core (pardes.zig) and one module per platform
src/detached/ the wire, the detached core, the frontend client
src/lsp/ the in-process language backend
test/ harnesses, snapshot goldens, helix cases
build/ build-time helpers (the snapshot suite)
docs/ see above
```
|
