# 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
```