summaryrefslogtreecommitdiff
path: root/docs/helix-keys.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-09-06 18:11:36 -0300
committerGabriel Schneider <[email protected]>2026-09-07 13:59:12 -0300
commit60367d8fe23f6af98ec28e3cf6c2094dfe332df0 (patch)
tree310fc734173cf771881f4691c71909135fadde97 /docs/helix-keys.md
parentfa82cac885cb4738fe36d1e49b4749b5a3e31a4a (diff)
downloadpardes-60367d8fe23f6af98ec28e3cf6c2094dfe332df0.tar.gz
pardes-60367d8fe23f6af98ec28e3cf6c2094dfe332df0.zip
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.
Diffstat (limited to 'docs/helix-keys.md')
-rw-r--r--docs/helix-keys.md26
1 files changed, 13 insertions, 13 deletions
diff --git a/docs/helix-keys.md b/docs/helix-keys.md
index 048d8397..dcd5b7cb 100644
--- a/docs/helix-keys.md
+++ b/docs/helix-keys.md
@@ -13,21 +13,20 @@ single key — it is the anchor-only divergence every insert-mode edit shares �
and is described in the Files list at the bottom instead.
Code map, by SYMBOL — line numbers rot, names do not. Body-normal key
-RECOGNITION is `src/normal_input.zig`: a pure state machine over `Role` (one
+RECOGNITION is `modal.Normal` in `src/modal.zig`: a state machine over `Role` (one
per bound command, matched against `src/config.zig`'s chord lists by
`Pardes.normalInput`), a `Prefix`, a `MatchSub` and a count, emitting a
semantic `Action` that both the text and PDF adapters consume. It knows
nothing about panes or text. `src/pardes.zig` then EXECUTES: `Key`,
`handleKey` (intercept order is load-bearing, see the comment there),
-`handleNormal` (marshals `Pane`'s compact fields in and out of
-`normal_input.State` through `paneNormalState` / `putPaneNormalState`),
+`handleNormal` (parses directly into `Pane.normal`),
`executeNormalAction`, `setPaneRange` (helix range → pane state),
`enterInsert`, `handleInsert` / `insertKey`, `insertTab`, `normalDelete`,
-`normalYank`, `normalPaste`, `normalChange`, `replaySels`, `multiOnce`. Undo
-and redo are per pane kind, in `file_pane` and `term_pane`. Pure text math:
+`normalYank`, `pasteText`, `normalChange`, `replaySels`, `multiOnce`. Undo
+and redo live in `panes.File` and `panes.Terminal`. Pure text math:
`src/modal.zig` (the `hx*` family is the helix-semantics layer: gap offsets +
ranges over the flat text). Differential harness: `test/hxdiff.zig` +
-`test/hxcases/*.jsonl` + `test/hxcases/regen.sh` — see "Differential testing"
+`test/hxcases/*.jsonl` — see "Differential testing"
at the bottom.
## Global semantic divergences (read first)
@@ -147,13 +146,10 @@ Status: `todo` → set to `done (phase N)` as rows land. All rows verified
against keymap.md. Edit ops on terminal panes obey the immutable-output
rule (typed runs only) — same as `d`/`c` today.
-Phase 2's recognition state is now `normal_input.State`: a count (accumulator,
+`Pane.normal` holds `modal.Normal.State`: a count (accumulator,
capped 0xffff), a `Prefix` (`g` `z` `m` `f` `F` `t` `T` `r` `]` `[`), a
`MatchSub` (m-mode's `i`/`a`/`s`/`r`/`d`) and one `held_char` for `mr`'s
-`<from>`. `Pane` keeps the same four fields it always did — `count`,
-`pending`, `pending2`, `pending_ch` — but purely as compact per-pane storage,
-marshalled in and out by `paneNormalState` / `putPaneNormalState`; the
-comments on them say so. `find_op`/`find_ch` (the `Alt-.` repeat target) stay
+`<from>`. `find_op`/`find_ch` (the `Alt-.` repeat target) stay
on `Pane`, because the parser emits `repeat_find` without remembering what was
found. Pure text math in `modal.zig`: `findChar`, `matchBracket`,
`paragraphFwd`/`paragraphBwd`/`paragraphRange`, textobject/surround ranges,
@@ -379,7 +375,7 @@ Files (all in `test/hxcases/`):
immutable) or doc-marked terminal no-ops. tty case texts keep motions
inside the content (the tty motion surface trims trailing blank rows,
so ge/G-to-last-line style assertions stay off tty).
-- `goldens.jsonl` — checked-in helix results, regenerated by `regen.sh`
+- `goldens.jsonl` — checked-in helix results, regenerated by `zig build hxdiff-update`
(runs the `hx-harness` binary from the helix checkout; override with
`$HX_HARNESS`). Only needed when cases change — the diff itself runs
offline.
@@ -417,7 +413,11 @@ Run it:
# "editing a shell pane behaves like editing a
# file" cannot drift. The case's own "pane" field
# is ignored; exemptions in parity-waivers.jsonl
- sh test/hxcases/regen.sh # regenerate goldens
+ zig build hxdiff-live # compare a fresh reference without changing goldens
+ zig build hxdiff-update # update goldens only after the live comparison passes
+
+Set `-Dhelix-harness=/path/to/hx-harness` or `HX_HARNESS`; otherwise these
+steps look for `hx-harness` on PATH.
The helix half (`hx-harness`) lives on the `pardes-harness` branch:
a full headless `Application` with LSP/tree-sitter/auto-pairs/word-