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 <noreply@anthropic.com>
This commit is contained in:
parent
1670233057
commit
cb459b79ef
190
README.md
190
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 →
|
||||
# <runtime>/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 -- <file> # 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)
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue