diff options
| -rw-r--r-- | README.md | 194 |
1 files changed, 21 insertions, 173 deletions
@@ -1,178 +1,26 @@ # 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. +A text environment in the acme tradition: columns of panes, each a tag line +over a body that is a file, a live terminal, a PDF or an image. The mouse +carries meaning (left selects, middle executes, right looks), the keyboard +is helix's, and every session serves its panes as a 9P filesystem, so any +program that opens files can drive it. -One core, five frontends. The core owns editing, layout, rendering, and the -filesystem namespace. Frontends translate native input into `pardes.Event`, -present `pardes.Surface`, and perform host effects such as spawning processes. +Install the terminal build with Zig 0.16: `zig build -Dplatform=tty +--prefix ~/.local` puts `pardes` in `~/.local/bin` (a bare `zig build` builds +the SDL window too and installs both there). Run `pardes`, or `pardes FILE`. -Every session serves its panes, columns and tags as a 9P control filesystem, -as acme does ([docs/fs.md](docs/fs.md)). `pardes FILE` run in a pane opens -FILE in that session; `EDITOR='pardes --wait'` makes it your editor -([forwarding](docs/fs.md#connecting)). `Tty9p` opens a terminal with the -tree mounted ([docs/v9fs.md](docs/v9fs.md)). +Read next: the [guide](docs/typ/guide.typ) (10 minutes), the +[cheatsheet](docs/typ/cheatsheet.typ) (3 minutes), then +[scripting](docs/typ/scripting.typ) (5 minutes); the +[reference](docs/typ/reference.typ) and [themes](docs/typ/themes.typ) when +you need them. They build into one PDF with `typst compile --root . +--ignore-system-fonts docs/typ/book.typ`, and `zig build cheatsheet +-Dplatform=tty --prefix DIR` renders the cheatsheet to +`DIR/share/doc/pardes/cheatsheet.pdf` (the committed copy is +[docs/typ/cheatsheet-a4.pdf](docs/typ/cheatsheet-a4.pdf)). Inside pardes, +`Tutor` walks through the same ground. -Fifteen [native themes](docs/themes.md) lead a ring of ports and imports; -`Themes` lists them. `Recent` (`SPC f r`) lists files opened lately, closed -ones too, and reopens one at its last place. `Mini path` opens a braille -minimap. Settings and the startup file are in [docs/config.md](docs/config.md). - -## 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). -Optional 9P-over-QUIC support (`-Dquic=true`) uses system OpenSSL 3.6+ and -pkg-config. - -## Build - -``` -zig build -``` - -A bare `zig build` builds both native shells and **installs** them into -`~/.local/bin` (`pardes`, the terminal shell; `pardes-gui`, the SDL window; -`pardes-v9fs`, the Tty9p helper). `--prefix <dir>` installs elsewhere, except -`--prefix zig-out`, which counts as no prefix. With `-Dplatform=<shell>` the -default prefix is `zig-out`. Test, benchmark and run steps build what they -need without installing. - -`pardes --version` prints `pardes <version>`, plus the commit for release -builds and the `~/.local` install (`-Dstamp-commit=true` forces it). -`pardes --help` lists every flag. - -| 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 -Dplatform=web -Dtarget=wasm32-freestanding -Ddump=<dump.zon>` | a freestanding wasm core plus vanilla JavaScript ([docs/web.md](docs/web.md)) | -| `zig build -Dplatform=macos` | an AppKit and CoreText app over a static `libpardes.a` ([docs/macos.md](docs/macos.md)) | -| `zig build -Dplatform=esp32p4` | a freestanding riscv32 editor object for ESP32-P4, using a 384 KiB heap | - -Firmware images are built in the sibling `../05-zig-p4` toolchain, which needs -ESP-IDF register headers. After building the editor object here, `zig build --Dpardes` there links `src/esp32p4/app.zig`. The separate GPIO 9P image uses -`zig build -Dapp=../02-pardes-code/src/esp32p4_9p.zig` there; its fixed GPIO -namespace is in `src/esp32p4_gpio.zig`. - -## Detached sessions - -``` -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 -``` - -The detached core owns panes, shells and files; frontends come and go. See -[docs/detached.md](docs/detached.md). - -## Tests - -``` -zig build unit-test module and shell unit tests -zig build test-build compile the unit-test programs without running them -zig build unit-profile test request time and process memory as JSONL -zig build unit-profile-test profiler timing, failure and timeout checks -zig build core-test core tests without native shell tests -zig build pane-test pane and namespace integration tests -zig build syntax-test tree-sitter tests without building the editor -zig build syntax deterministic per-byte highlighting snapshots -zig build syntax-bench highlighting latency and allocation counts -zig build perf-test benchmark validation without compiling the editor -zig build lspbench-check require every configured language probe to be correct -zig build lspbench-test language benchmark omission and expectation gates -zig build history-test historical measurement and comparison tests -zig build fs-test real sessions and mounts over 9P -zig build agent-session-test interactive session driver checks over 9P -zig build fs-bench-test filesystem benchmark option checks without the editor -zig build 9p-test freestanding protocol tests -zig build quic-test -Dquic=true optional QUIC transport tests -zig build snap scripted input traces against frozen golden grids -zig build snap-driver-test retry evidence, strict failures and fixture isolation -zig build monkey random snapshot scripts hunting panics (not a gate) -zig build monkey-test the monkey's generator and panic detector -zig build hxdiff differential suite against helix's own behaviour -zig build hxdiff-test comparator, allocation and CLI regression checks -zig build hxdiff-live compare against a freshly run hx-harness -zig build hxdiff-update update reference results only after comparison passes -zig build hxparity file-pane vs pty-pane editing parity -zig build hxgolf every helix-golf example, step by step, against helix -zig build mupdf-check compile, link, render and search docs/design.pdf -zig build web-snap browser highlighting and touch interactions -zig build web-driver-test browser driver timeouts and cleanup -zig build web-e2e Chrome-driven DOM end-to-end suite -``` - -- `-Dtest-filter=<text>` applies to every unit-test binary; a filter that - matches nothing fails. `-Dtest-rebuild` forces fresh Zig test compilation. -- `snap -- --record=DIR` writes snapshots without touching goldens, - `snap -- --update` replaces goldens, `snap -- --no-retry` makes the first - failure decisive. Snapshot scripts can use `snap9p` to capture core cells - through 9P. -- `zig build monkey -Dplatform=tty -- <seeds> [steps] [--from=N] [--out=DIR] - [--keep]` writes one random script per seed, runs it through pardes-snap - and keeps any script that panics (in `/tmp/pardes-monkey` by default); a - seed always makes the same script. Each crash found gets a fix and a - regression script in `test/snapshots/`. -- `zig build hxdiff -- --strict cases.jsonl reference.jsonl [waivers.jsonl]` - runs custom differential cases; without `--strict` and a reference it only - emits results. Live helix steps take `-Dhelix-harness=<path>`, - `HX_HARNESS`, or `hx-harness` on PATH. -- Benchmarks (`perf`, `pdf-bench`, `pdf-scroll-bench`, `pdf-sections-bench`, - `lspbench`, `fs-bench`) accept `-- --json`; measure with - `-Doptimize=ReleaseFast`. `perf -- --base old.json` refuses reports whose - build metadata differs. -- `zig build history -- run 'ancestors(@, 2)' DIR -- zig build unit-test` - records a command's output and cold/warm runtimes across revisions (`jj - status` first: pending edits are not snapshotted); `history -- compare - a.json b.json 1.20` fails past that runtime ratio (`--snapshots`, - `--benchmarks` for stricter checks). Output directories are never - overwritten. -- `python3 -B test/agent_session.py <pardes> --ready 'text' --min-rows N -- - command args` drives an interactive command in a private shell and checks - it through 9P (`--gui-grid` for GUI builds). - -## Documentation - -Start with `src/panes.zig` (and the pane kinds it names, `src/File.zig`, -`src/Terminal.zig`, ...), `src/layout.zig`, and `src/fs.zig` for ownership and -operations, and `src/pardes.zig` for input, with one file per thing beside it -(`edit.zig`, `normal.zig`, `look.zig`, `exec.zig`, `mouse.zig`, ...). - -| file | subject | -|---|---| -| `docs/fs.md` | the 9P control filesystem: every file, error and limit | -| `docs/config.md` | settings, the startup file, dumps, build options | -| `docs/tags.md` | tags, columns, and where new panes go | -| `docs/detached.md` | one core, many frontends | -| `docs/v9fs.md` | Tty9p: a terminal with the tree kernel-mounted | -| `docs/cloud9.md` | the 9P library and the posted-9P registry | -| `docs/selections.md`, `docs/helix-keys.md` | the normal-mode model and the helix key map | -| `docs/themes.md`, `docs/effects.md` | themes and visual effects | -| `docs/lsp.md` | language servers | -| `docs/web.md`, `docs/macos.md` | the browser and macOS shells | -| `docs/design.typ` | architecture sketch (`docs/design.pdf` is a test fixture and may lag it) | -| `docs/divergences.md`, `docs/open-questions.md` | bookmarks off `main`; undecided questions | -| other `docs/*.md` | design and research notes (`render-pipeline`, `lsp-evaluation`, `ui-review`, ...) | - -`next-steps.txt` is a wishlist with a status header; `transactions.txt` -records one open structural gap against helix and the waiver that proves it. - -## Layout - -``` -src/ core events (pardes.zig), panes, edit, look, exec, layout, fs, syntax -src/ninep/ the 9P control tree -src/detached/ the wire, the detached core, the frontend client -src/lsp/ the language-server client and its seam -test/ harnesses, snapshot goldens, helix cases -build/ build-time helpers (the snapshot suite) -docs/ see above -``` +Contributors: [building](docs/typ/building.typ) has the platforms, build +options, tests, release gates and how the core, the shells and the 9P +server fit together. |