From cb459b79ef404e43527e6252f1e6c93abdb9a3d3 Mon Sep 17 00:00:00 2001 From: Levi Neuwirth Date: Tue, 7 Jul 2026 11:00:09 -0400 Subject: [PATCH] docs(readme): overhaul for the post-1.0 state Rewrites the stale sections: the intro now names both frontends (TUI + pmacs-gpu over protocol v14) and CRDT collaboration; Status reflects the post-1.0 arcs and points at docs/roadmap-2026-07.md; 'What v0.1 ships with' becomes a current Highlights section (LSP surface, gutter modes, search, context menu, packages, MCP); adds a Running section with real daemon/attach/GPU invocations; Layout updated to the three-crate workspace and the lua_bindings/ module dir. Build feature matrix and runtime-requirements sections kept as-is (still accurate). Co-Authored-By: Claude Fable 5 --- README.md | 190 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 140 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 51cc6b1..ecd5694 100644 --- a/README.md +++ b/README.md @@ -10,23 +10,113 @@ discards the single-threaded substrate; workers, message bus, and a coroutine-based async surface are core primitives, not bolt-ons. The editor is partitioned into a long-lived **instance** (the daemon -that owns buffers, processes, and language services) and a thin -**frontend** that attaches over a typed protocol. Frontends can run -locally over a Unix socket or remotely over SSH; reconnect-on-drop -modeled on `mosh` keeps remote sessions alive across laptop suspends. +that owns buffers, processes, and language services) and thin +**frontends** that attach over a typed protocol (currently v14). Two +frontends ship today: -The first-class package is a **REPL package** written entirely against -the public Lua API: PTY-spawned shells (bash, zsh, fish, lua), an -ECMA-48 ANSI parser, multi-REPL coexistence, and scrollback management -with line/byte retention. Successful completion of an audit verifying -the package uses zero direct Rust core access was the v0.1 ship gate. +- a **TUI** (crossterm cell grid), attachable locally over a Unix + socket or remotely over SSH, with reconnect-on-drop modeled on + `mosh`; and +- **pmacs-gpu**, a GPU frontend (wgpu + winit + glyphon) that renders + from a *semantic projection* of editor state --- style spans, + decorations, inlay adornments --- rather than a character grid, and + edits optimistically against a local CRDT replica for + latency-free typing. + +Buffers are optionally CRDT-backed (`loro`, behind `--features crdt`), +so multiple frontends --- TUI and GPU, local and remote --- can edit +the same buffers concurrently with live cursor/selection presence. ## Status -**v1.0.0 --- stable.** The design described above is implemented and -working. Solo development carried the project to 1.0; public -contributions are open from this release. Use, evaluate, file issues, -and send pull requests. +**v1.0.0 --- stable core, active development.** The v1.0 gate (the +instance/frontend partition, the Lua surface, and a REPL package +audited to use zero direct Rust core access) shipped some time ago; +development since has landed the GPU frontend at near input/render +parity with the TUI, the semantic-frontend protocol (v6 → v14), the +LSP feature arc, in-buffer search, the context menu + OS clipboard, +the line-number gutter with diagnostic signs, and the package-manager +hardening pass. Current direction lives in `docs/roadmap-2026-07.md`. +Public contributions are open: use, evaluate, file issues, send pull +requests. + +## Highlights + +**Editing & UI.** CUA-style region editing plus Emacs kill/yank +bindings; linear undo/redo; incremental search, substring and regex +(`C-s` / `C-r` / `C-M-s`); line-number gutter with absolute, relative, +and hybrid modes; diagnostic gutter signs; right-click context menu; +OS clipboard integration (OSC 52 in the TUI, native in the GPU); +minibuffer with completion dropdown and per-bucket persisted history; +buffer-list mode (`C-x C-b`); self-navigable help system +(`describe-command`, `describe-key`); atomic saves (temp + rename + +parent fsync, mode-preserving). + +**Language intelligence.** LSP client with async, never-blocking +requests: diagnostics (severity-colored underlines/squiggles, gutter +signs, statusline counts, `M-g n`/`M-g p` navigation), rename with +`prepareRename`, go-to-definition including cross-file navigation, +hover, signature help, references, document symbols, code actions, +buffer formatting, semantic tokens, and inlay hints (rendered inline +in the GPU frontend). Servers are preconfigured for rust-analyzer, +clangd (C/C++), basedpyright, gopls, typescript-language-server +(TS/TSX/JS/JSX), lua-language-server, bash-language-server, taplo +(TOML), and zls (Zig). Syntax highlighting is dual-authority: +bundled tree-sitter grammars (Rust, Lua, Markdown, C, C++) paint +lexical structure and LSP semantic tokens refine it --- languages +without a bundled grammar still get full semantic coloring. A +persistent project symbol index (`.pmacs/index.json`) rides the same +worker infrastructure. + +**Collaboration & frontends.** With `--features crdt`, buffers are +CRDT-backed and any number of frontends attach to one daemon and edit +concurrently; peers see each other's cursors and selections as +translucent washes. The GPU frontend adds a live minimap (click to +jump, drag to scrub), wavy diagnostic squiggles, a status band with +live diagnostic counts, and optimistic local editing that rebases +in-flight edits through authoritative frames. + +**Extensibility.** ~37 `pmacs.*` Lua namespaces cover buffers, +windows, commands, keymaps (global/mode/buffer scope), hooks, themes +(truecolor-capable syntax palette), tree-sitter, LSP stores, async +workers, and a PTY-aware process supervisor with an ECMA-48 ANSI +parser. A package manager installs from git (`github:owner/repo`, +version/branch/commit pins) with transitive dependency resolution and +a SHA-256 lockfile. Pmacs is also an **MCP client**: packages can +spawn MCP servers and consume their tools, resources, and prompts --- +AI integrations are packages over a transport, not a built-in +feature. The bundled REPL package (PTY shells, ANSI rendering, +multi-REPL, scrollback retention) is written entirely against the +public Lua API. + +## Running + +Single-process TUI: + +```sh +pmacs [FILE] # TUI; -nw reserved for when a GUI default lands +``` + +Daemon + attached frontends (build with `--features crdt` for +multi-frontend editing and the GPU frontend): + +```sh +pmacs --daemon --socket NAME # foreground daemon; bare NAME → + # /pmacs/NAME.sock +pmacs --attach --socket NAME # TUI frontend; F12 detaches +pmacs --attach user@host # remote TUI over SSH +pmacs-gpu --attach /run/user/$UID/pmacs/NAME.sock # GPU frontend +``` + +`pmacs --attach` also understands `ssh:user@host/instance`, +`local:/path.sock`, and bare hostnames (treated as SSH). See +`pmacs --help` for the full matrix. + +User configuration is plain Lua at +`$XDG_CONFIG_HOME/pmacs/init.lua` (default `~/.config/pmacs/init.lua`), +loaded after the builtin runtime so plain assignments override +defaults --- keybindings, `pmacs.lsp.config`, theme overrides, and +package installs all live there. ## Build @@ -34,7 +124,9 @@ Builds on the toolchain pinned in `rust-toolchain.toml` (Rust `1.95.0`, edition 2024); rustup selects it automatically. ```sh -cargo build --release # produce target/release/pmacs (LuaJIT) +cargo build --release # target/release/pmacs (LuaJIT flavor) +cargo build --release --features crdt # + CRDT buffers (daemon use) +cargo build --release -p pmacs-gpu # the GPU frontend binary cargo run --release -- # build and run on a file cargo test --workspace # unit + integration tests (all crates) cargo fmt --check @@ -76,7 +168,11 @@ CI runs the matrix on every push. Release-only perf gates (M5 keystroke-to-render, M6 ingest/RSS/cancel and scrollback navigation/search) are `#[ignore]`'d during normal -test runs and exercised in CI under dedicated jobs. +test runs and exercised in CI under dedicated jobs. The GPU frontend +has headless render tests (offscreen wgpu, pixels read back) that run +in CI under lavapipe and skip gracefully on machines without a Vulkan +adapter (`PMACS_REQUIRE_GPU=1` turns a missing adapter into a hard +failure). ## Runtime requirements @@ -125,59 +221,53 @@ The Lua VM (LuaJIT or Lua 5.4) is statically vendored via `mlua`'s `vendored` feature, so there is no external Lua dependency at runtime. -## What v0.1 ships with - -- **Editor core.** Persistent rope with O(log N) edits and snapshots; - buffers with chained intercept-views; undo/redo; atomic file I/O; - crossterm-driven TUI. -- **Lua surface.** Embedded LuaJIT (or Lua 5.4) with `pmacs.command`, - `pmacs.keymap` (global / mode / buffer scopes), `pmacs.hook` - (typed kinds: all-must-succeed, first-non-nil, last-write-wins), - `pmacs.buffer`, `pmacs.window`, `pmacs.editor`. Minibuffer is itself - a buffer. `describe-key` and `describe-command` for self-introspection. -- **Async runtime.** Worker pool + message bus + coroutine-based Lua - async surface (`pmacs.async`). Cancellation is provably correct - under load. -- **Language services.** Tree-sitter highlighting and LSP integration - ride the worker/message infrastructure. Project indexing as a third - service. Symbol search across 1M+ symbols completes under a second. -- **Frontend partition.** Daemon mode with local Unix-socket transport; - cell-delta diffing on the instance side; SSH transport variant for - remote attach; reconnect-on-drop preserves session state across - laptop suspend / network drop. -- **REPL package.** A 691-line Lua package that wires the M6 ANSI - parser to PTY-spawned shells with raw-mode line discipline. Three- - region buffer (history / prompt / input) with read-only enforcement; - RET / C-c / C-d bindings; multi-REPL coexistence; scrollback - retention with line- and byte-bounded truncation. Published - alongside an audit verifying zero direct Rust core access. +The GPU frontend additionally needs a Vulkan-capable driver stack +(any real GPU driver, or lavapipe for software rendering); its font +(JetBrains Mono, OFL-licensed) is bundled into the binary. ## Layout +The workspace has three first-party crates: + ``` -src/ Rust core +src/ pmacs — the core + TUI + daemon rope.rs persistent byte-sequence backing every buffer buffer.rs buffer + view chain + undo/redo editor_core.rs cursor + commands + edit dispatch + crdt.rs loro-backed CRDT buffer state (feature `crdt`) + daemon.rs instance side of the frontend partition + attach.rs frontend side; transports + reconnect + semantic_render.rs semantic-frame producer (StyleSpans, Decorations, …) + lsp.rs language-server client + diag.rs, highlight.rs diagnostic + syntax/semantic-token rendering + syntax.rs tree-sitter integration + search.rs incremental search (substring + regex) + minibuffer.rs prompt, completion, persisted history + menu.rs context-menu model + file_io.rs atomic saves + external-modification detection async_runtime.rs worker pool + message bus process.rs PTY-aware process supervisor ansi.rs ECMA-48 parser - daemon.rs instance side of the frontend partition - attach.rs frontend side; protocol + reconnect - lsp.rs language-server client - syntax.rs tree-sitter integration - project_index.rs symbol / file indexing + project.rs, project_index.rs project detection + symbol index + packages/ resolver, fetcher, installer, lockfile, loader + mcp.rs MCP client (packages speak to MCP servers) + lua_bindings/ pmacs.* Lua surface installers text_view.rs cell-grid renderer frontend.rs crossterm TUI - lua_bindings.rs pmacs.* Lua surface installers - main.rs entry point (TUI + daemon modes) + main.rs entry point (TUI / daemon / attach modes) + +pmacs-protocol/ wire types + framing codec shared by all frontends +pmacs-gpu/ the GPU frontend (wgpu + winit + glyphon) builtin/ Lua runtime shipped with the binary commands/default.lua named commands for every editor primitive keymaps/default.lua default key bindings hooks/default.lua built-in hook definitions - runtime/ packages (async, lsp, repl, syntax) + menus/default.lua context-menu items + runtime/ async, lsp, syntax, mcp, fs runtimes + packages/repl/ the bundled REPL package +docs/ design notes, framing docs, and the roadmap tests/ integration tests (acceptance gates per milestone) ```