Refactor panes and filesystem; replace FUSE with 9P

Consolidate pane, layout, memory and host code. Serve 9P by default over Unix sockets, with runtime mounts and optional TCP/QUIC transports. Remove FUSE and obsolete proof-of-concept examples.

Fix highlighting and terminal-history performance, expand differential and stress-test infrastructure, sort navigation results while preserving the next occurrence, add syntax-colored Braille minimaps, remove SPC-k, and document 9P interaction as a repository skill.

1 files changed, 126 insertions, 22 deletions

diff --git a/README.md b/README.md
index daeac183..1fdb73bb 100644
--- a/README.md
+++ b/README.md
@@ -6,10 +6,13 @@ 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`.
+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.
+
+`Mini path` opens a braille minimap with syntax colors: two text columns by four
+lines per cell. It reads through the normal filesystem namespace; run it again
+to refresh. Mini snapshots survive Dump/Restore without rereading the source.
 
 ## Requirements
 
@@ -17,6 +20,8 @@ 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. The default Unix socket and optional TCP transport do not need it.
 
 ## Build
 
@@ -32,10 +37,8 @@ puts them in `~/.local/bin`.
 ~/.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.
+Override with `--prefix <dir>`. Test, benchmark and run steps build what they
+need without installing development binaries.
 
 ```
 pardes --version           e.g. pardes 0.0.1 (e61bbb2e86bd)
@@ -52,13 +55,15 @@ The version comes from `build.zig.zon`'s `.version`; the commit is read from
 | `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 web -Dplatform=web -Dtarget=wasm32-freestanding -Ddump=<dump.zon>` | 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 |
+| `zig build -Dplatform=esp32p4` | a freestanding riscv32 editor object for ESP32-P4, using a 384 KiB 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`.
+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; it does not link the
+editor. Its fixed GPIO namespace is in `src/esp32p4_gpio.zig`.
 
 ## Detached sessions
 
@@ -80,30 +85,129 @@ words. See `docs/detached.md`.
 
 ```
 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 config-test      configuration tests without compiling the editor
+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 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 mupdf-check      compile, link, render and search docs/design.pdf
-zig build web-snap         browser touch/LOOK snapshots
+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
 ```
 
-`snap` and `hxdiff` take `-- --update` and explicit case files respectively. The
-benchmark steps — `perf`, `pdf-bench`, `pdf-scroll-bench`, `pdf-sections-bench`,
+`snap -- --record=/tmp/captures` writes independent snapshots for comparing
+binaries without changing goldens. `snap -- --update` replaces goldens;
+`snap -- --no-retry` makes the first failure decisive. Retried runs retain
+each attempt's report and mismatching grid in a fresh printed directory.
+For custom differential cases, use
+`zig build hxdiff -- --strict cases.jsonl reference.jsonl [waivers.jsonl]`.
+Without a reference, the driver only emits results; exit zero does not mean a
+comparison passed. Custom arguments must include `--strict` to check coverage.
+The benchmark steps — `perf`, `pdf-bench`, `pdf-scroll-bench`, `pdf-sections-bench`,
 `lspbench`, `fs-bench` — all accept `-- --json`.
 
+Snapshot scripts can use `snap9p` to capture core cells and styles through the
+default socket alongside the terminal emulator's independent captures.
+
+`-Dtest-filter=<text>` applies to every unit-test binary. Use
+`-Doptimize=ReleaseFast` for performance measurements. To record output and
+first/warm command runtimes across revisions, run:
+
+```
+jj status
+zig build history -- run 'ancestors(@, 2)' /tmp/pardes-history -- zig build unit-test
+zig build history -- compare /tmp/pardes-history/<before>.json /tmp/pardes-history/<after>.json 1.20
+```
+
+The history runner uses `jj run` serially, with recordings outside its isolated
+checkouts without integrating history changes. Run `jj status` before measuring
+`@`: the runner deliberately does not snapshot pending edits. `history record`
+measures current files directly. Add `run --allow-immutable`
+to measure immutable revisions. Each command runs four times; the first run is reported separately
+from the warm median. Standard output and errors are preserved for every run.
+Commands must exist in the selected revisions. The optional comparison ratio
+fails the command when runtime regresses beyond that limit. Add `--snapshots`
+to require stable, identical stdout and stderr, or `--benchmarks` to compare
+individual `syntax-bench` cases, including allocation counts; the ratio limit
+also applies to each case's cold and median time, using medians across the last
+three processes. First-process cold times are reported separately, not gated.
+All four captures must contain the same cases and input sizes. Old revisions
+need the same harness and uncached test execution for meaningful comparisons.
+The recorded Zig version identifies the recorder's compiler; record the child
+toolchain separately when comparing different compilers.
+Recordings are exclusive: use a fresh output directory to repeat a measurement.
+Existing results and partial runs are never overwritten.
+
+`perf -- --base old.json` requires matching build metadata, harness, viewport,
+repetition count, fixtures, and `--only` selection. Reports identify the compiler,
+resolved target/CPU, driver/core/dependency optimization modes, and feature flags.
+Missing or different metadata is rejected; old reports must be regenerated.
+JSON reports omit unmeasured cells. Gesture checks run
+outside the timed interval, and each process owns and removes its fixture directory.
+Hardware, machine load and runtime library versions must be matched separately.
+
+`zig build perf -Dplatform=tty -Doptimize=ReleaseFast -Dtree-sitter=zig -- --mini --json`
+measures braille generation, full highlighting plus generation, and cached Mini
+redraws separately, checking output hashes and allocation balance.
+
+`zig build perf -Doptimize=ReleaseFast -- --terminal-mib 64 --json` streams
+colored, wrapped agent-like output past the terminal history limit. It checks
+the newest text, colors and input, and measures raw redraws, modal movement,
+edit-overlay redraws and memory. Linux RSS comes from the current process image's
+`VmHWM`; allocator counts exclude the terminal library's private mappings.
+
+`python3 -B test/agent_session.py zig-out/bin/pardes --ready 'ready text' --min-rows 20000 -- command args`
+runs a caller-selected interactive command in a private POSIX shell and checks
+its history and an unsubmitted input probe through 9P. Use an owned copy of any
+saved conversation.
+Reports contain counts, hashes and 9P observation times, not conversation text
+or physical keyboard latency. GUI builds need `--gui-grid`.
+
+`test-build -Dtest-rebuild` forces fresh Zig test compilation while retaining
+cached C dependencies. Use a disposable local cache for repeated cold-build
+experiments. Ordinary `unit-test` always runs its tests, even with cached builds.
+`unit-profile` measures the request-to-result interval, including test-runner
+communication, and reports whole-process time and memory separately.
+Filtered test steps fail if no named test matches, even when import guards pass.
+
+The default differential suites require exact case coverage and reject stale
+waivers. Each waiver pins both the reference and editor result. Live Helix
+steps use `-Dhelix-harness=<path>`, `HX_HARNESS`, or `hx-harness` on PATH.
+
 ## 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.
+Start with `src/panes.zig`, `src/layout.zig`, and `src/fs.zig` for ownership and
+operations, and `src/pardes.zig` for input. `docs/design.typ` is the architecture
+sketch; `docs/design.pdf` is a retained rendering/search fixture and may lag 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/fs.md` | default 9P service, Look resolution, and named mounts |
+| `docs/lsp.md` | in-process ZLS and external language servers |
 | `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 |
@@ -118,9 +222,9 @@ says which waiver proves it is still open.
 ## Layout
 
 ```
-src/            the core (pardes.zig) and one module per platform
+src/            core events (pardes.zig), panes, layout, fs, syntax
 src/detached/   the wire, the detached core, the frontend client
-src/lsp/        the in-process language backend
+src/lsp/        ZLS and external language-server backends
 test/           harnesses, snapshot goldens, helix cases
 build/          build-time helpers (the snapshot suite)
 docs/           see above