path: root/docs/helix-keys.md

# pardes ↔ helix keybinding plan

Living tracking doc for the helix-parity effort. Every key / table row in
`helix/book/src/keymap.md` appears in exactly one of the three sections
below. The keymap was read at UPSTREAM commit 278b24389 of the genizah
checkout (`~/05-genizah/helix`); that checkout now sits on the local
`pardes-harness` branch, whose three commits add only the harness, so
`book/src/keymap.md` is byte-identical at its tip (694e7dfd). As of phase 5
every helix-equivalent row in A and B is differentially verified against real
helix (see "Differential testing" at the bottom). Every waiver is named in the
row it belongs to.

**The reference helix is fixed at one commit:** the `hx-harness` built from
`694e7dfdd` on the genizah checkout's `pardes-harness` branch, which is upstream
`278b24389` (2026-06-29, `25.07-905`) plus the three harness commits. "helix"
in this document means that build, not the 25.07.1 release, which differs on
counted `Alt-(`/`Alt-)` and on `&`. Upstream master was 82 commits further on
2026-09-28 (`079a789e`); of those only `416a0e09` (continuing a comment in an
injected `comment` layer) touches the editing code, and it needs tree-sitter,
which the harness runs without.

Code map, by SYMBOL — line numbers rot, names do not. Body-normal key
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
`normalInput` in `src/normal.zig`), 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. Then it is EXECUTED: `Key` and `handleKey` in
`src/pardes.zig` (intercept order is load-bearing, see the comment there);
`handleNormal` (parses directly into `Pane.normal`), `executeNormalAction`,
`replaySels` and `multiOnce` in `src/normal.zig`; `setPaneRange` (helix range
→ pane state); and `enterInsert`, `handleInsert` / `insertKey`, `insertTab`,
`normalDelete`, `normalYank`, `pasteText`, `normalChange` in `src/edit.zig`. 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` — see "Differential testing"
at the bottom.

## Global semantic divergences (read first)

- **FULL HELIX MOTION MODEL (phase 5 decision — overrides phase 2's
  "keep point motions").** Motions select the range they traverse with
  helix's landing conventions: after `w` on "alpha beta" the anchor is
  (0,0) and the block cursor sits ON the space at col 5 (not vim's col
  6); a following `d` deletes "alpha ". Which motions select a range and
  which collapse to a point follows helix exactly (word/find/till/
  paragraph-class motions select; h/j/k/l-class char and line moves
  collapse) — the checked-in helix goldens are the ground truth, verified
  case-by-case by `zig build hxdiff`. Motion-created ranges live in
  `pane.vsel` marked IMPLICIT (`vsel.explicit = false`); `v` extend mode,
  `x`/`X` and `n`/`N` (the look-ring walk, `lookWalk`) set EXPLICIT ones.
  `d`/`c`/`y`/`~`/… act on the active selection either
  way — that is the point of the model. The pardes-specific chords
  (normal-mode Enter look / Tab execute)
  act on EXPLICIT selections only and fall back to the word under the
  cursor when the selection is implicit motion residue. Mode is reported
  "select" ONLY while `v` extend mode is on (helix keeps mode normal for
  x/%/mi-created selections).
- **Stored columns are UTF-8 byte offsets** (`cur_col`), but every modal
  cursor/range endpoint is snapped to an extended-grapheme boundary. Rendering,
  mouse input and vertical motion translate those offsets through terminal-cell
  widths, so combining sequences and wide glyphs remain single cursor cells.
  Three functions in `modal.zig` do the snapping — `graphemeStart` (repair an
  offset back onto a boundary), `nextGrapheme`, `prevGrapheme` — each with an
  arithmetic ASCII fast path over the UAX #29 segmenter. All three carry the
  same exclusion by hand, because GB3 is the one UAX #29 rule that joins two
  ASCII scalars: a CR takes a following LF into the same cluster. `nextGrapheme`
  and `prevGrapheme` did not spell it out and so disagreed with `graphemeStart`
  by exactly one byte on a CRLF file — a head could step to the offset between
  CR and LF and be repaired straight back. Fixed; the test "GB3 keeps CR-LF one
  cluster for every grapheme step" is what holds the three in agreement.
- **Terminal panes: shell output is immutable.** Edit ops only ever
  drop/alter typed insertion runs. All "To implement" edit ops follow the
  same rule (motion/selection parts work on the full motion surface; the
  mutating half is file-pane only or run-only).
- **Soft wrap is a toggle** (`Wrap`, `SPC t w`, on by default), and the
  visual/textual pair is assigned the other way round from helix: `j`/`k` are
  TEXTUAL file lines, `gj`/`gk` follow the automatic breaks. A file pane's `j`
  is expected to move one line of the FILE; helix makes `j` the visual one and
  `gj` the textual one. With the toggle off a line is one visual row and the
  two pairs are the same motion.
- **Undo is snapshot-per-edit-op / per-insert-session**, not a
  transaction log. `.` and macros replay KEYS (`Macro.zig`), not
  edits, so they need none.

## A. Implemented today

Parity column (phase 5): **helix-verified** = matched field-by-field
(text/mode/cursor/anchor) against the helix goldens by `zig build hxdiff`;
**pardes-specific** = key helix leaves unbound (or a deliberate pardes
binding) — cannot mismatch a golden; **waived** = corpus-covered divergence
with a reason in `test/hxcases/waivers.jsonl`; **out of corpus** = helix's
own key and meaning, but the work leaves the core as an EFFECT the headless
differential has no shell to perform — the clipboard commands, the
language-backend queries, and the shell pipe.

| Key | Behavior (pardes today) | Notes / quirks vs helix | Parity |
| --- | --- | --- | --- |
| `h` `j` `k` `l`, arrows | char left/right, line up/down — collapse the selection to a point (helix) | `j`/`k` are TEXTUAL lines even under soft wrap (`gj`/`gk` are the visual pair — the reverse of helix's assignment, see the divergence above); sticky col, phantom-line-blocked | helix-verified (unwrapped) |
| `w` `b` `e` | select to next word start / prev word start / next word end | full helix model incl. landing conventions (block cursor one before the next word after `w`) and newline/punct/EOF edges | helix-verified |
| `W` `B` `E` | long-word (WORD) variants | same | helix-verified |
| `Home` / `End` | line start / line end | matches `goto_line_start` / `goto_line_end` | helix-verified |
| `0` / `^` | line start / first non-ws | pardes extras: helix leaves both unbound (it spells them `gh`/`gs`), so they collide with nothing. Line end is helix's own `gl` and End. `0` is a count digit while a count is pending | pardes-specific |
| `G` | bare `G` is a **no-op**; `<n>G` = goto line n | vim-ism removed (phase 5): helix `goto_line` only acts with a count; `ge` is goto-last-line | helix-verified |
| `gg` / `<n>gg` | goto first line / line n | | helix-verified |
| `ge` | goto last content line | matches `goto_last_line` (ignores the trailing empty line) | helix-verified |
| `gh` / `gl` | line start / line end (last char, not the newline) | | helix-verified |
| `Ctrl-d` / `Ctrl-u` | half page down/up, cursor follows | matches `page_cursor_half_down/up` | helix-verified |
| `Ctrl-f` | full page down | matches `page_down`; file panes only get `Ctrl-b` (see next row) | helix-verified |
| `Ctrl-b` | file panes: full page up. Terminal panes: **toggle raw tty/editor mode** (`opts.tty_toggle`, configurable; `Shift-Esc` also enters). In raw tty Shift-Esc goes to the child | tty toggle is pardes-specific and wins on terminals; harness `pane:"tty"` cases avoid `Ctrl-b` | helix-verified (file) / pardes-specific (tty) |
| `PageUp` / `PageDown` | full page | matches helix `page_up`/`page_down` (view scroll + cursor snap to the scrolloff edge) | helix-verified |
| `zt` / `zz` / `zb` | scroll current line to top / center / bottom | matches `align_view_top/center/bottom` (helix harness pins scrolloff to pardes' 3) | helix-verified |
| `Z` | sticky view mode: the `z` keys stay armed after each until Esc, which only leaves the mode; other keys do nothing meanwhile | helix's sticky view node | helix-verified |
| `zm` | scroll the unwrapped view so the cursor's column is in its middle | helix `align_view_middle`; with soft wrap on there is no horizontal scroll, and nothing happens | out of corpus (the harness's text never scrolls sideways) |
| `i` `a` | insert at selection start / after selection end | helix semantics: `i` before the selection, `a` selects and appends after it | helix-verified |
| `I` `A` | insert at first non-ws / line end | matches `insert_at_line_start` / `insert_at_line_end` | helix-verified |
| `o` `O` | open line below / above, copying the current line's indent levels; `<n>o` opens n | matches `open_below`/`open_above` | helix-verified |
| `v` | select (extend) mode: motions extend from the fixed anchor; `v` again exits KEEPING the selection | mode "select" is reported only while this is on (helix keeps mode normal for x/%/mi selections) | helix-verified |
| `x` / `<n>x` | select current line / extend one (n) line(s) down, char-range through the newline, cursor ON the `\n` | col-0 vim-ism removed (phase 5); matches `extend_line_below`, mode stays normal | helix-verified |
| `d` | delete selection (implicit or explicit); bare cursor = the 1-wide selection | always yanks (`Alt-d` noyank in B); terminals: drops typed runs only | helix-verified |
| `c` | change (delete + insert mode); linewise selections open a fresh indented line | same shape as `d` | helix-verified |
| `y` | yank each range's text into the register (`"<reg>` names one, else `"`), one value per range | line-yank vim-ism removed (phase 5); yank keeps selection AND cursor (helix). The system clipboard is `"+y` / `SPC y`, helix's own split: a `d` of one character never clobbers what the desktop holds | helix-verified |
| `u` / `U` | undo / redo | restores the pre-edit selection (helix); snapshot granularity, `Alt-u`/`Alt-U` are the same two: helix walks a history tree by time with them, and pardes's history is linear, so earlier and later ARE undo and redo | helix-verified |
| `p` (normal) | paste the register after each range: value i at range i, the last value repeated when there are fewer | helix `paste_impl`. `"+p` asks the system clipboard (`SPC p`); on a tty that read is OSC 52, which most terminals refuse: an honest no-op rather than a paste of the wrong text | helix-verified |
| `Esc` (body normal) | clear a pending modal prefix / exit select mode, keeping the selection, then run `Last`: hop to the pane you were in before this one, whichever kind it was, exactly like `SPC j j` — so held down it alternates between two panes, two files as readily as a file and its shell. A PDF pane is the ONE exception: there Esc is the document's own cancel (drop the mouse selection and the search overlay, stay where you are reading) and `Shift-Esc` is the hop out, while raw tty only intercepts unmodified Esc at a detected shell prompt | Pardes-specific focus binding layered on helix's cleanup. A leader path, tag, topbar or search owns Esc while it is active; raw tty forwards it | pardes-specific (cleanup helix-verified) |
| `Esc` (insert) | back to normal mode, cursor right after the insertion (no vim left-step) | | helix-verified |
| `Enter` (normal) | acme **look** chord: EXPLICIT selection, else file-ish word under cursor | pardes-specific, keep (helix normal-mode Enter unbound). Covers helix `gf`. Implicit motion residue falls back to the cursor word | pardes-specific |
| `Tab` (normal) | acme **execute** chord | pardes-specific, keep; explicit-selection rule as Enter | pardes-specific |
| `:` (normal, body or tag) | in the body, focuses the pane's tag in normal mode at its remembered cursor (the first time, on `Save`); in the tag, goes back to the body; in a column or workspace tag, back to the active pane. The tag's normal and insert modes ARE the body's: every motion, selection, edit and undo works there, and `0` goes to the line's start, the path's. Tab runs the word under the cursor or the selection and Enter looks it up (in a column or workspace tag Enter runs it too), and either hands the keyboard back to the body first. Clicks choose a new cursor position and type into the tag. | Each tag keeps its own cursor during the session. The computed path/marker/page is reachable and yankable but read-only: an edit into it is refused, and typing into a file's path drafts a new name. File-name changes are staged as described in [editable tags](tags.md). | pardes-specific |
| `Ctrl-w k` / `SPC w k` (pane with nothing above) | focuses its column's tag, then the workspace tag. `Ctrl-w j` walks back to the panes, `Ctrl-w h`/`l` walk the column tags. Headers edit exactly as a pane tag does. | Column commands target that column's active pane, or its first pane when coming from elsewhere. Workspace and column text are independently editable and persist in dumps. See [editable tags](tags.md). | pardes-specific |
| `Ctrl-w` + `h/j/k/l`/arrows | directional pane focus prefix — editor normal mode only | pardes' own window handling (helix window mode skipped, section C). Runs the SAME `Left`/`Down`/`Up`/`Right` builtins `SPC w h/j/k/l` runs; Raw **tty** mode forwards Ctrl-w to the child. Insert mode owns `Ctrl-w` = delete-word-back, so a tag being TYPED into swallows it; from a tag in normal mode it moves focus to the neighbour's BODY, as from a body, and from the top pane `Up` reaches the column and workspace tags | pardes-specific |
| `Alt-n` | new terminal below (outside raw tty) | shadows helix `Alt-n` (select next sibling), which pardes spells `Alt-right` alone | pardes-specific |
| `Alt-c` | move active terminal to a fresh column (outside raw tty) | helix `Alt-c` is change-noyank; the pardes window op wins (do-not-touch contract). `Alt-d` + `i` covers the behavior | waived (`alt-c-window-op`) |
| `Space` (normal, body) | starts the pardes LEADER: a key path runs the same builtin words used by tags and the topbar. The main groups are `f` files, `h` docs, `c` columns, `t` toggles/effects, `a` panel animations, `s` session, `j` jumps, `l` language, and `w` directional focus; `SPC ?` lists every path and `<prefix> ?` lists one group in `+Help`. Neither `Exit` (quits the editor, acme's Exit) nor `Kill` (stops the commands pardes typed into terminals, acme's Kill) has a leader path: both are the topbar's and the root `ctl`'s. The pending path appears on the active pane's transient body/message row. Esc or an unmapped key abandons it. Paths, Help rows, and dispatch are all generated from the builtin registry at comptime; the leader applies only to a BODY in normal mode because tags and tty programs own their input | pardes-specific; helix spends Space on pickers/LSP (section C), while pardes uses acme-style executable words |
| `SPC y` `SPC Y` `SPC p` `SPC P` `SPC R` | helix's clipboard menu on helix's own letters: yank the selection to the system clipboard (`ClipYank`) or the PRIMARY selection alone (`ClipYankMain`), paste the system clipboard after (`ClipPaste`) / before (`ClipPasteBefore`) the selection, replace the selection with it (`ClipReplace`) | the same as `"+y`, `"+p`, `"+P`, `"+R`: register `+` (and `*`) IS the desktop's clipboard, the only register that reaches it. `SPC y` writes `+` alone, as helix's does, not the default register too. Builtins rather than bare chords because a leader path names a builtin: they land in Help's index and are executable words like every other verb. The clipboard holds one text, so N values go out joined by newlines, as helix sends them. On a tty the write is OSC 52 out and the READ is OSC 52 back, which many terminals refuse or gate — so `SPC y` works there and `SPC p` can be a no-op | out of corpus |
| a paste from the OUTER terminal | one `Event.paste`, spliced in at the cursor | the tty shell enables bracketed paste and coalesces `paste_start`..`paste_end` into a single event; before that the bytes arrived as individual key presses and normal mode RAN them, which is how a pasted `d` deleted a line. The bytes deliberately never enter the yank register — clipboard and default register are separate stores in both directions | pardes-specific |
| `/` (any pane) | pardes' own plain-substring search into a `+Search` output buffer: the pattern is typed on a line of its own on the pane's notice band, Enter fills the buffer, and its rows are ordinary look targets. Enter also GOES to the first row — the buffer is focused and then the step `n` is and the look Enter is run in it (`Pardes.lookFirstHit`), so `/foo` lands on the first hit with the matched span selected. A pattern that matched nothing opens its empty buffer and moves nothing | KEEP, do not touch; not in the corpus (helix `/` is regex search). Find and Grep answer with OTHER files and deliberately do NOT jump. The stepping half is the next row | pardes-specific |
| `n` / `N` (any pane) | MOTION, not a jump: move the SELECTION to the next / previous look-able text and open NOTHING. Enter — the look chord — on what it leaves selected is what opens it | KEEP, do not touch; not in the corpus (helix's `n`/`N` walk regex search hits). What a step selects is the pane's GRAIN (`output_pane.Grain`, read in `Pardes.lookSpanIn`): in FREE TEXT — a terminal, a file, a PDF, a prose answer buffer — the largest whitespace-delimited run `look.resolve` can act on (`look.lookableSpan`, wrapper punctuation peeled off both ends), several to a line; in a RESULTS BUFFER one stop per ROW, the largest run its head resolves as (`look.lookableLineSpan`), because a row there IS one location and the words after it are the match rather than a second place to go; in a COMMAND list the whole line. The walk is a RING across PANES: every pane that has performed a Look, most recent first (`Pardes.look_src`), then the output buffers that have not, newest first, and only when both are empty the active pane. Exhausting a pane enters the next at its first (forward) / last (backward) span and the end wraps to the start, so `N` is the exact inverse of `n`. What it lands on becomes an EXPLICIT `vsel` with the cursor on its FIRST column, in the pane the walk focuses. ONE motion in every pane kind and every buffer kind — a PDF steps the `+Search` buffer its own search filled, `n` to select the row and Enter to jump. The single thing a buffer may change is that grain, and it changes it by BEING a kind of buffer rather than by a branch: `output_pane.Traits.steps` (a list of locations) makes a step take one row at a time, and `Traits.commands` makes it take the WHOLE LINE, because a command list (`Themes`/`Fonts`) holds words to run and there is no path inside `Theme gruvbox` to pick out. Tab on what `n` selected wears the theme, which is the same middle click on the row is. `]d`/`[d` are helix's diagnostic motions, a different binding, and they do still jump to each diagnostic (`docs/lsp.md`) | pardes-specific |
| insert: printable text | file: real edit; terminal: typed run splice | | helix-verified (file) |
| insert: `Enter` | newline; keeps the current full indent levels and adds one 4-space logical tab when the text before the cursor ends in `(`, `[`, `{`, or `)` (including `})`) | plain lines match `insert_newline`; delimiter heuristic is pardes-specific | helix-verified (plain) / pardes-specific (delimiter) |
| insert: `Backspace` (+ `Shift-Backspace`) | delete prev char, joins lines at col 0; in a line's leading blanks, back to the previous 4-column indent stop (a whole unit when on one; a tab still goes alone) | matches `delete_char_backward` and its dedent; `Ctrl-h` alias in B | helix-verified |
| insert: `Up` `Down` `Left` `Right` | move cursor | matches helix's "not recommended" insert arrows | helix-verified |
| `gd` `gD` `gy` `gi` `gr` | LSP definition / declaration / type-definition / implementation / references. ONE answer jumps straight there; several fill `+Search`, where n/N walk and Enter opens | in-process ZLS (`src/lsp/lsp_zls.zig`), `.zig` only — on a file the backend does not speak these do nothing at all, with no error row. Ctrl+left-click is the mouse spelling of `gd` | out of corpus |
| `]d` `[d` / `]D` `[D` | step the diagnostics list / go to its last or first; if no list is up, asking the backend for one is part of the press | | out of corpus |
| `=` | `format_selections` — writes a `- old` / `+ new` diff into `+Lsp` | deliberate divergence: the seam returns ROWS, not edits, so this SHOWS the formatting instead of applying it. Not in the corpus, so there is no waiver to name — the query leaves the core as an effect the headless harness has no shell to perform | out of corpus |
| `Ctrl-o` / `Ctrl-i` | jumplist back / forward (also Mouse4 / Mouse5 in SDL, macOS and web); successful navigation clears selections in both panes and places the cursor at the saved location; raw tty forwards both to the child — the `Back` / `Forward` builtins, also on `SPC j o` / `SPC j i`, with `SPC j l` rendering the stack as a buffer; a closed file's entry stays, marked `(closed)`, and a jump to it opens the file again at its place | helix binds both keys (`jump_backward` / `jump_forward`) but to a POSITION jumplist; pardes' stack is over panes and focus, so the keys agree and the semantics do not. `Ctrl-i` and Tab are the same byte under the legacy encoding; there Tab keeps meaning execute, and the pair only separates where the host speaks the kitty keyboard protocol | pardes-specific |
| `\|` | pipe every selection through `/bin/sh -c`: its bytes in on stdin, its stdout replacing them, one undo across all cursors | helix's own key and meaning; the command is typed into the pane's tag after a bare `\|` marker rather than into a popup | out of corpus |
| `A-\|` | the same, and the output is DISCARDED — the text is not touched at all | helix `shell_pipe_to`. For a command run for its effect. Marker `\|-` | out of corpus |
| `!` | run with NO stdin, insert the output BEFORE each selection | helix `shell_insert_output`. Runs ONCE and every cursor gets that one answer, as helix does — ten cursors and `date` give ten identical stamps. Marker `!` | out of corpus |
| `A-!` | the same, appended AFTER each selection | helix `shell_append_output`. Marker `!+` | out of corpus |
| `$` | keep only the selections a shell command exits 0 on: each range's text on its stdin, one run per range, its output discarded; the primary stays if kept, else the last kept range takes over, and keeping none changes nothing | helix `shell_keep_pipe`. The runner's answer is all or nothing, so the command runs as `(cmd) >/dev/null; echo $?` and the status comes back as the output. Marker `$` | out of corpus |
| `Q` / `"<reg>Q` | record the keys that follow into `@` (or the named register) until the next `Q`; kept as helix writes a macro, in key notation (`xt,S=<ret>_<A-(>`), so `"@p` pastes it and a yanked text can be replayed | helix `record_macro` | helix-verified |
| `q` / `<n>q` / `"<reg>q` | type a register's keys again, n times. Replayed keys go to the modal handling only: Esc does not hop panes, Enter and Tab neither look nor execute, and Space does not open the leader | helix `replay_macro`; `Macro.zig`, `Pardes.replayKeys` | helix-verified |
| `.` / `<n>.` | repeat the last insert session: the normal command that entered it once, the keys typed n times, then leave insert mode the way it was left | helix `repeat_last_insert`; the same key log as macros | helix-verified |

## B. To implement

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.

`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>`. `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,
`replaceRange`/`replaceChars`, `changeCase`, `joinLine`, `indentLines`,
`adjustNumber`, `deleteSpan`, `advanceBy` — each with inline tests that
`zig build unit-test` runs.

### Counts

| Key | Behavior | Notes | Status |
| --- | --- | --- | --- |
| `<n>` digit prefix | count for motions (h/j/k/l/arrows, w/b/e/W/B/E, gj/gk), `x`, `f/t` family + `Alt-.`, `G`/`gg`, `g|`, `]p`/`[p`, `]Space`/`[Space`, `J`, `>`/`<`, `Ctrl-a`/`Ctrl-x` | `0` stays line-start when NO count is pending, count-digit otherwise. `Pane.count` accumulator, capped at 0xffff (ponytail). Digits are literal char args while a prefix waits (`f4` finds '4'). Any non-prefix key consumes the count; prefix setters carry it into their continuation | helix-verified (phase 5) |
| `<n>G`, `<n>gg` | goto line n (1-based, clamped), col 0 | plain `G` is a no-op like helix (vim-ism removed in phase 5; `ge` = last line) | helix-verified (phase 5) |

### Movement

| Key | Behavior | Notes | Status |
| --- | --- | --- | --- |
| `f<ch>` / `F<ch>` | find next / prev char (on it) | NOT confined to current line. `pending` holds the waiting op (`f`/`F`/`t`/`T`); ASCII targets only (byte columns — ponytail); not found = no move | helix-verified (phase 5) |
| `t<ch>` / `T<ch>` | till next / prev char (one short of it) | `modal.findChar` handles all four + counts (nth occurrence, till applied after) | helix-verified (phase 5) |
| `Alt-.` | repeat last `f`/`t`/`F`/`T` motion (`Pane.find_op`/`find_ch`), takes a count | decision: repeats ONLY the find family, not `m`/`[`/`]` (helix extends it there; marginal) | helix-verified (phase 5) |
| `g|`, `<n>g|` | goto column n (1 = line start), clamped to the line | | helix-verified (phase 5) |
| `gs` | goto first non-whitespace | alias of the `^` handler | helix-verified (phase 5) |
| `g.` | go to where the last edit ended (a deletion's start, an insertion's end), every range there, extending in select mode | helix `goto_last_modification`. The position is `Text.last_edit`, set by `edit.setEditText` from where the old and new texts part; helix's is the last history revision's, so with nothing edited yet pardes stays put where the harness's helix goes to the end of its setup text | helix-verified |
| `gw` | label the words in view (two word characters or more) with two letters each, nearest the cursor first, one forward and one back in turn; typing a label selects its word (stretching the selection to it in select mode), any other key takes the labels away | helix `goto_word`, alphabet a-z (`config.jump_label_alphabet`). The labels are painted over the body's cells in `body_layer.renderBody`, in the selection colours; the words live on `Pane.jump` | helix-verified |
| `gt` / `gc` / `gb` | goto screen top / center / bottom | view-relative (`pane.scroll()` + `pane.rows`), column kept (clamped) | helix-verified (phase 5) |
| `gj` / `gk` | VISUAL line down / up (+ count) | follows the wrapped body's own breaks (`file_pane.visualRow`, the same walk `fillBody` renders), keeping the goal column INSIDE the row; the last row of a line steps into the next line's first. Wrap off = one row per line, and this IS `j`/`k`. helix assigns the pair the other way round (its `j` is the visual one) | pardes-specific |
| `PageUp` / `PageDown` | FULL page (was half) | `Ctrl-u`/`Ctrl-d` stay the half-page pair | helix-verified (phase 5) |

### Changes

| Key | Behavior | Notes | Status |
| --- | --- | --- | --- |
| `r<ch>` | replace selection/char with `<ch>`, newlines kept | terminals: replaces the typed-run byte under the cursor if any, else no-op — one code path for both kinds, since `normalReplaceChar` goes through `Pardes.editText`/`setEditText`, which route to a file's content or to `term_pane`'s typed-run overlay | helix-verified (phase 5) |
| `R` | replace selection (or cursor char) with the yank register; pasted text becomes the selection in the direction the replaced one had (head on its last char, or its first when backward) | uses the INTERNAL yank (`p.yank`), no clipboard round trip — `SPC R` is the system-clipboard twin; empty register = no-op; terminals: no-op | helix-verified (phase 5) |
| `~` | switch case of selection/char, selection kept | terminals: run byte only | helix-verified (phase 5) |
| `` ` `` | selection to lowercase | terminals: run byte only | helix-verified (phase 5) |
| ``Alt-` `` | selection to uppercase | terminals: run byte only | helix-verified (phase 5) |
| `J` | join lines in selection (or cur+next; helix ignores the count) | helix semantics: the newline + next line's leading whitespace collapse to ONE space (first line untrimmed); selection and cursor STAY where they were (vim's cursor-on-the-space removed in phase 5); terminals: no-op | helix-verified (phase 5) |
| `Alt-J` | join like `J`, then select the spaces the join put in (one bare cursor each); a join that put none in keeps the selection | helix `join_selections_space`. `J` and `Alt-J` are one edit over every range, so a line two ranges share is joined once | helix-verified |
| `>` / `<` | indent / unindent selected lines (count times) | width = `modal.INDENT_W` = **4 spaces** (helix harness pins its no-language indent style to Spaces(4) to match); `<` also takes one leading tab as a level; empty lines never indented (helix); selection kept, positions mapped through the edit (phase 5) | helix-verified (phase 5) |
| `Ctrl-a` / `Ctrl-x` | increment / decrement the decimal int under the cursor by count | helix-style: under the cursor only (no vim forward scan), `-` handled, i64 saturating, zero-padding width preserved (phase 5); cursor to the last digit, selection kept; terminals: no-op | helix-verified (phase 5) |
| `Alt-d` | delete without yanking | `normalDelete(yank=false)` | helix-verified (phase 5) |
| `Alt-c` | change without yanking | **skipped (phase 2)**: the pardes `Alt-c` window op (move pane to fresh column, any mode) wins — it's load-bearing global UX and the parent contract forbids touching it. `Alt-d` + `i` covers the behavior. Corpus-covered and waived (`alt-c-window-op`) | waived (phase 5) |
| `P` | paste before | same yank-register path as `p` | helix-verified (phase 5) |
| `p`/`P` semantics | yank ending `\n` pastes as whole lines below/above the SELECTION's line span; else inline at the selection's outer edge. The paste (× count) becomes the selection, head on its last char (helix) | terminals keep the run-splice-at-cursor path (before/after collapses). Pinned by yankpaste.snap and the hxdiff yp cases | helix-verified (phase 5) |

### Selection manipulation

| Key | Behavior | Notes | Status |
| --- | --- | --- | --- |
| `;` | collapse selection to cursor | drops vsel/msel, cursor stays | helix-verified (phase 5) |
| `Alt-;` | flip anchor and head | vsel: swap cursor ↔ anchor; msel: cursor to the other end (r0/r1 swapped to keep the cursor-at-r1 invariant) | helix-verified (phase 5) |
| `Alt-:` | make every range point forward | helix `ensure_selections_forward` | helix-verified |
| `Alt-o`/`Alt-up`, `Alt-i`/`Alt-down`, `Alt-p`/`Alt-left`, `Alt-right`, `Alt-a`, `Alt-I`, `Alt-e`, `Alt-b` | walk the file's syntax tree from every range: grow to the enclosing node (and remember what it grew from), shrink back to that or to the first child, the previous / next sibling (anonymous ones included, so often a comma), every named sibling or child, the enclosing named node's end / start (stretching to it in select mode) | helix `expand_selection` and kin, on a whole-file parse (`File.node_tree`) made on the first such key after an edit and reused until the next; a range the tree says nothing about, and every range of a file without a grammar, stays. Checked against the installed hx on JSON (`normal.zig` test): the harness runs without grammars, so it only proves the plain-text no-op | helix-verified (plain text), hx-checked (JSON) |
| `]f [f ]t [t ]a [a ]c [c ]T [T ]e [e ]x [x`, `mi`/`ma` + `f t a c T e x` | function, class, argument, comment, test, entry, element: jump to the next one starting after the cursor / the previous one ending before it (count times; select mode stretches to it), or select the smallest one around the cursor, inside or around | helix `goto_ts_object` / `textobject_treesitter`, from helix's own `textobjects.scm` vendored in `vendor/queries` (MPL-2.0), with its `#eq?`/`#match?` predicates; `syntax.objectAt`/`objectNext` on the file's kept parse. Zig's query is helix's ported by hand to the zig grammar pardes builds, and a node that ends in its line's newline (that grammar's comments) is taken without it, as helix's grammars have it. Grammars without a query (fortran, markdown, powershell) or whose query does not compile against pardes's grammar (erlang) have none, and the keys do nothing there. Checked against the installed hx on Python, JSON and Zig (`normal.zig` test) | hx-checked |
| `%` | select whole buffer | vsel anchor 0,0, cursor on the buffer's last char | helix-verified (phase 5) |
| `X` | snap selection to line bounds | vsel → msel over its row span; bare cursor → 1-line msel; msel: already line-wise, no-op | helix-verified (phase 5) |
| `Alt-x` | shrink selection to line bounds | vsel only: partial first/last lines drop out; nothing left collapses the selection; msel: no-op | helix-verified (phase 5) |

### Multiple cursors

helix's `Selection` is a LIST of ranges with a primary index. pardes keeps the
PRIMARY where it always was (`cur_row`/`cur_col` + `vsel`) and the other ranges
in `Pane.sels`; an ordinary key is REPLAYED once per range (`replaySels`), so
every motion and operator above works at every cursor without being rewritten.
With one cursor nothing is replayed and nothing changed. The result contract
grew `sels` + `primary`, emitted only when there is more than one range.

| Key | Behavior | Notes | Status |
| --- | --- | --- | --- |
| `C` / `Alt-C` / `<n>C` | copy the selection to the next / previous line | helix `copy_selection_on_line`, incl. skipping lines too short to hold the column. **Byte columns, not visual ones** (a TAB counts as one) | helix-verified |
| `,` / `Alt-,` | keep only the primary / remove the primary | `Alt-,` on a lone cursor is a no-op (helix errors) | helix-verified |
| `)` / `(` / `<n>)` | rotate the primary forward / backward (wrapping) | ranges unchanged, only which one is primary | helix-verified |
| `Alt-s` | split the selection on newlines | helix `split_on_newline`; the newlines themselves drop out, primary becomes 0 (helix's own TODO) | helix-verified |
| `Alt-minus` / `Alt-_` | merge all ranges into one / merge the consecutive ones | helix `merge_selections` / `merge_consecutive_ranges` | helix-verified |
| `_` | trim whitespace off both ends of every range | empty and all-whitespace ranges drop; nothing left = collapse + keep primary (helix) | helix-verified |
| `<n>o` / `<n>O` | open n lines, one cursor per line | helix `open` with a count; this is why the `o-count` golden gained a `sels` field | helix-verified |
| every motion/operator | acts at every cursor | replayed last-range-first, so an edit never disturbs a range still waiting; each pass's result is remembered as a distance from the END of the text, which an earlier edit cannot move | helix-verified (56 msel-* cases) |
| `y` with several ranges | one value per range, pasted back value i at range i by `p`/`P`/`R` and insert `Ctrl-r`; the acme cut/paste chords and a paste into a terminal take the values joined by newlines | `Registers.zig` | helix-verified |
| `"<reg>` | the next command's register: any character names one of its own. Computed ones: `_` swallows writes and reads nothing (`"_d`), `#` is each range's number from 1, `.` each range's text, `%` the file's name, `/` the last `s`/`S` pattern; `+`/`*` the system clipboard. A count typed before `"` stays the command's | helix `select_register` | helix-verified |
| insert `Ctrl-r <reg>` | type this range's value of the register (`Ctrl-r #` numbers the cursors). Esc after `Ctrl-r` only cancels it. `Ctrl-r +` reads what pardes last put on the clipboard, not the desktop's | helix `insert_register` | helix-verified |
| insert mode with a selection | every range is carried through each edit as helix maps it (`Range::map`): typing at the head of an `i` range slides it, typing at the end of an `a` range stretches it, Enter slides or stretches it by what the cursor moved, and an arrow key collapses it. Esc after `a` pulls each range's end back one character (helix `restore_cursor`) | `edit.insertKey`, `Text.restore_cursor` | helix-verified |
| `&` | align selections into columns: the k-th range of each line is column k, and spaces go in before each range until its head reaches the column's widest head, in display cells (`File.rawDisplayCol`) | helix `align_selections` as of the harness's helix (25.07.1 grouped columns differently). A range over several lines refuses. A TAB counts as `tab_width` cells, not up to the next stop | helix-verified |
| `Alt-)` / `Alt-(` / `<n>Alt-)` | rotate the CONTENTS of the selections forward / back by one range (n ranges), in one edit; each range comes back over the text it now holds and the primary moves with its text | helix `rotate_selection_contents_*` as of the harness's helix: 25.07.1 read the count as a GROUP size instead (rotate by one within each run of n ranges) and left the primary where it was, which is what helix-golf's `invert_dictionary_2` relies on | helix-verified |

Anything that reaches outside the buffer — a builtin, a language query — runs
once from the primary and drops back to a single cursor rather than firing per
range (`multiOnce`). Undo restores the primary from the snapshot and leaves the
other cursors where they are (`FileSnap` holds one range).

### Regex selection (`s` / `S`) — the interactive pair

Both arm the prompt the same way `/` does — the pattern is typed after a
marker on the prompt's own line in the notice band, no popup — and both
re-run on EVERY keystroke, from
the selection the prompt opened on (`Pane.sel_snap`). That is what makes the
selection a live preview, what makes typing a pattern one character at a time
land where pasting it whole would, and what makes Esc a plain restore. Enter
re-runs the final pattern down the same path, so a submit can never disagree
with what is on screen. Pressed in a tag, column tag or workspace tag they
select in that tag's own text, and so does `|` pipe it; `/` searches the
body wherever it is pressed (`Pane.prompt_for`). Engine: **mvzr** (`build.zig.zon`), a bytecode VM that
compiles a runtime pattern with no allocator, called the way sam searches
(`src/regexp.zig`, shared with a pane's `addr` file): each line is its own
haystack, so `^` and `$` match at every line's start and end and `.` never
crosses a newline, and a pattern naming `\n` runs over the whole selection.
Where helix's `^` is only the selection's start, this is sam's. mvzr
backtracks without bound of its own, so the step budget docs/fs.md gives
for `addr` holds here too: a search that runs out of it (about 300 ms)
keeps the matches it found so far.

| Key | Behavior | Notes | Status |
| --- | --- | --- | --- |
| `s<pat>` Enter | select every match INSIDE each range | helix `select_on_matches`; a match sitting right off a range's end is dropped (what `\b` and empty matches produce there). No match, no pattern, or one that will not compile = the selection is left alone (helix's "nothing selected") | helix-verified |
| `S<pat>` Enter | split each range on its matches | helix `split_on_matches`; the pieces BETWEEN the matches, including the empty one a leading match produces | helix-verified |
| `s`/`S` then Esc | back to the selection the prompt opened on | the empty pattern applies nothing, so cancelling IS the restore — one path, not a second one | helix-verified |
| an all-lowercase pattern | matches case-blind | helix's smart-case. mvzr has no such flag, so the surface is lowercased instead (ASCII folding is byte-for-byte, so the offsets are identical) | helix-verified |
| `^` and `$` | hold at every line's start and end | helix compiles with `multi_line(true)`; pardes gets the same by searching each line as its own haystack (`src/regexp.zig`) | helix-verified |
| `.` | never matches a newline | as the Rust regex crate: a pattern without `\n` searches line by line, and one that names `\n` has its `.`s made `[^\n]` (`src/regexp.zig`) | helix-verified |
| many matches | up to `memory.limits.selections` ranges: 1024 on the desktop, 64 on the board; matches past it are dropped | helix has no limit. The room for them is allocated when a second range appears and given back at one range, so a single cursor costs nothing | helix-verified up to the limit |
| `K<pat>` / `Alt-K<pat>` Enter | keep only the ranges a match starts inside / only those none does; primary 0, and keeping none leaves the selection alone | helix `keep_selections` / `remove_selections`, on the same prompt as `s`/`S` (markers `Keep /`, `Remove /`). The range is searched as `s` searches it, line by line with its lines' context, where helix matches the range's text alone: a `^` right at a range that starts mid-line matches in helix and not here | helix-verified |

### `Ctrl-c` — toggle comments

| Key | Behavior | Notes | Status |
| --- | --- | --- | --- |
| `Ctrl-c` | comment or uncomment every line the WHOLE selection touches | helix `toggle_comments`. One decision for the whole set — one uncommented non-blank line and everything gets commented — which is why it is a `wholeKey` and not a per-cursor replay | helix-verified |
| … at several cursors | each line once, in order | helix's `min_next_line`: two cursors on one line comment it once | helix-verified |
| … with mixed indents | the token goes in at the SHALLOWEST indent in the set | helix's `min`, quirks included: a deeper line is commented mid-whitespace | helix-verified |
| … uncommenting | one space after the token goes too, unless some line lacks it | helix's `margin` | helix-verified |
| … blank lines | skipped entirely, and they do not vote on commented-or-not | helix | helix-verified |
| which token | by file EXTENSION, from `config.comment_tokens` | the same notion of "language" `src/syntax.zig` picks grammars with. No extension (a terminal, an output buffer) or an unlisted one gets `config.comment_token_default` = `#`, which is helix's own `DEFAULT_COMMENT_TOKEN` and therefore what the oracle answers | helix-verified |
| block comments (`/* */`) | **skipped**: helix only reaches them when a language declares block tokens and no line tokens; every language in the table has a line comment |

### Match mode (`m` prefix) — plain-text, no tree-sitter

| Key | Behavior | Notes | Status |
| --- | --- | --- | --- |
| `mm` | goto matching bracket | dumb text scan with nesting for `()[]{}<>`; ON a bracket only (no TS "nearest pair"); works on terminals via the motion surface | helix-verified (phase 5) |
| `mi<pair>` / `ma<pair>` | select inside / around textobject | pairs `( ) [ ] { } < >` nesting-aware multi-line; quotes `' " `` ` `` ` **line-scoped** (plain-text strings don't span lines); `w`/`W` word run (+trailing ws around, leading if none); `p` blank-line block (+trailing blanks around). Empty inside (`()`) = no-op. Selections work on terminals; `Pane.pending2` holds the i/a/s/r/d sub-key | helix-verified (phase 5) |
| `ms<ch>` | surround selection (or cursor char) with the `<ch>` pair; wrap incl. pair becomes the selection, keeping the direction it had | either bracket names its pair; any other ASCII char wraps with itself; file panes only | helix-verified (phase 5) |
| `mr<from><to>` | replace enclosing `<from>` pair chars with `<to>`'s | `Pane.pending_ch` holds `<from>` while `<to>` pends; file panes only | helix-verified (phase 5) |
| `md<ch>` | delete the enclosing `<ch>` pair chars | file panes only | helix-verified (phase 5) |

### View mode (`z` prefix) additions

| Key | Behavior | Notes | Status |
| --- | --- | --- | --- |
| `zj` / `zk` (+ `zdown`/`zup`) | scroll view down / up one line, cursor untouched | `pane.scrollBy(±1)` | helix-verified (phase 5) |
| `zc` | center (alias of `zz`) | | helix-verified (phase 5) |
| `z Ctrl-d` / `z Ctrl-u` | half page with cursor | aliases of the bare handlers | helix-verified (phase 5) |
| `z Ctrl-f` / `z Ctrl-b` / `z PageUp` / `z PageDown` | full page | aliases | helix-verified (phase 5) |

### Unimpaired (plain-text subset)

| Key | Behavior | Notes | Status |
| --- | --- | --- | --- |
| `]p` / `[p` | next / prev paragraph (+ count) | helix `goto_next/prev_paragraph`: selects to the boundary (anchor at the origin), blank-line-delimited blocks, count iterates | helix-verified (phase 5) |
| `]Space` / `[Space` | add `<n>` blank lines below the selection's last line / above its first, the selection staying on its text | file panes only (shell output immutable) | helix-verified (phase 5) |

### Insert mode

All the mutating insert keys follow the pane split: file panes edit content
(`modal.deleteSpan` for the kills), terminal panes edit ONLY the typed run at
the cursor (word = space-delimited within the run). Ctrl-h/j/d are normalized
to Backspace/Enter/Delete and re-dispatched at the top of `handleInsert`. The
text-insert path now requires no ctrl/alt so modifier combos can't leak their
text.

| Key | Behavior | Notes | Status |
| --- | --- | --- | --- |
| `Ctrl-w` / `Alt-Backspace` | delete word backward (ws then word-class run; at col 0 = the ordinary backspace join) | resolved per proposal: focus prefix restricted to normal/tty; insert owns `Ctrl-w` | helix-verified (phase 5) |
| `Alt-d` / `Alt-Delete` | delete word forward (word run + trailing ws; at EOL eats the newline) | | helix-verified (phase 5) |
| `Ctrl-u` | kill to line start | | helix-verified (phase 5) |
| `Ctrl-k` | kill to line end | | helix-verified (phase 5) |
| `Ctrl-h` | delete prev char (Backspace alias) | | helix-verified (phase 5) |
| `Ctrl-d` / `Delete` | delete next char; at line end joins the next line up | `Key.delete` (0xF0009) added + `mapKey` in tty.zig/gui.zig (vaxis + SDLK) + `forwardKey` sends `ESC[3~` in tty mode | helix-verified (phase 5) |
| `Ctrl-j` | insert newline (Enter alias) | | helix-verified (phase 5) |
| `Home` / `End` | line start / line end past-the-last-char (`goto_line_end_newline`) | file panes (terminal insert cursor rides its run, as before) | helix-verified (phase 5) |
| `PageUp` / `PageDown` | cursor page up / down, col kept (clamped to line) | file panes | helix-verified (phase 5) |
| `Tab` | indent to the next 4-column stop with SPACES (`insertTab`, `edit.zig`: `pad = INDENT_W - col % INDENT_W`) — no `\t` byte ever reaches the file | helix's Spaces indent style; helix smart-tab skipped. After a `.` in a file the backend speaks, Tab instead asks for completion and only indents if the answer is empty (section A) | helix-verified (phase 5) |
| insert `Tab` after text / `Shift-Tab` | in a file with a grammar, Tab after text on its line leaves the syntax node the cursor is in (to the enclosing named node's end); Shift-Tab always indents | helix `smart_tab` / `insert_tab`. The reference pins smart tab off, so a file without a grammar indents as the harness's helix does, where stock helix would do nothing there. Smart tab is checked against the installed hx on JSON (`normal.zig` test) | helix-verified (plain text), hx-checked (JSON) |
| insert `Ctrl-s` | commit an undo checkpoint: `u` after the session goes back to the text as it was here, a second `u` to before the session | helix `commit_undo_checkpoint`; a snapshot pushed mid-session | helix-verified |

## C. Skipped

| Key(s) | Helix behavior | Reason |
| --- | --- | --- |
| `?`, `*`, `Alt-*` | rsearch / selection-as-pattern | search — pardes has its own `/` (plain substring into an output buffer, kept as-is) and an `n`/`N` that SELECTS the next look-able text instead of walking match hits; helix regex search machinery not wanted |
| `Space` mode: `f F e . b j g G ' w c C Alt-c / ?` | pickers, global search, palette | pickers and the command palette do not exist here — but the KEY is taken: pardes' own leader runs the acme builtins (section A). Two halves of helix's space mode DO exist and are in section A: the clipboard menu (`<space>y Y p P R`, helix's letters on helix's leader) and the LSP menu, moved one prefix deeper to `SPC l k/r/a/h/s/S/d/D` because `d`, `k`, `s` and `h` were already pardes' most-pressed keys |
| Popup `Ctrl-u`/`Ctrl-d`, Completion menu, Signature help tables | LSP popups | LSP |
| Picker table (all rows), Prompt table (all rows) | picker / prompt internals | pickers — pardes' tag line is its own one-line editor |
| `gn` `gp` `ga` `gm` | next/prev/alternate buffer | buffer nav — pardes panes aren't a buffer list |
| Window mode table: `Ctrl-w` + `w v s t f F h j k l q o H J K L ns nv` (+ Ctrl variants) | splits/window management | window mode — pardes has its own Ctrl-w focus + Alt-n/Alt-c + mouse layout drags |
| `]g [g ]G [G` | git change jumps | **deferred by decision**: needs a diff base per file (jj `@-` or git HEAD, fetched by the host on open and save) and line hunks from diffz; the design is written up, the work waits |
| insert `Ctrl-x` | completion menu | completion exists, but not as a popup: insert-mode Tab straight after a `.` opens a buffer of candidate DECLARATIONS (section A). helix's menu itself is skipped |
| `Ctrl-s` (normal) | save jumplist position | jumplist itself is implemented (`Ctrl-o`/`Ctrl-i`, section A); only the explicit save point is skipped |
| `:` | command mode | side-effects/file-ops — pardes builtins live in the tag, and `:` is bound to focusing it (section A) |
| `gf` | goto file under selection | covered by pardes Enter-look |
| `Ctrl-z` | suspend | pardes IS the terminal multiplexer |
| Select/extend mode section (prose) | `v` turns all motions into extenders, `n`/`N` keep selections | implemented for motions (phase 5: `pane.select` + the fixed anchor, differential-verified — see the `v` row in A); helix's search-`n`/`N` extension doesn't apply (pardes' `n`/`N` is the look-ring motion, which REPLACES the selection with the span it lands on) |

## Differential testing (phase 5)

pardes is diffed key-for-key against real helix (checkout
`~/05-genizah/helix`, branch `pardes-harness`) over a shared JSON-Lines
case corpus. Both sides speak the same contract: a case is
`{"name","pane","text","keys"}` (helix key notation; `pane` is
`"file"`/`"tty"`, ignored by helix), a result is the full final buffer
text, the mode (`normal`/`insert`/`select` — select only for `v` extend
mode), and the block-cursor positions of the primary selection's head
(`cursor`) and other end (`anchor`), 0-based row + byte col. With more than
one selection the result line grows two more fields — `sels`, every range in
document order measured the same way, and `primary`, the index of the one
`cursor`/`anchor` describe. Both are omitted at one selection, which is why
every golden written before multiple cursors existed is still byte-for-byte
valid.

Files (all in `test/hxcases/`):

- `cases.jsonl` — the corpus: 481 cases (360 file + 121 tty). Every
  helix-equivalent row of sections A and B has at least a typical and an
  edge case; pure navigation/selection bindings get a `pane:"tty"` twin
  (same text/keys — helix on that text IS the oracle for tty navigation
  parity). No tty twins for content-mutating ops (shell output is
  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 `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.
- `waivers.jsonl` — named exemptions, each with a reason. One live one:
  `alt-c-window-op` (the pardes window op deliberately shadows helix
  change-noyank). `wiX-edit-drops-sel` and `msel-append` went when insert
  mode began carrying every range through its edits, `msel-yank-paste` with
  registers of one value per range, `sel-regex-caret` and
  `sel-regex-dot-newline` when `s`/`S` began searching line by line.
- `parity.jsonl` — 80 further cases, used only by the parity gate below.
- `parity-waivers.jsonl` — 19 named exemptions for the parity gate, in three
  classes: one deliberate pardes binding (`ctrl-b-page`, since `Ctrl-b` IS the
  tty toggle), eight pty VIEWPORT divergences (a terminal's view cannot scroll
  below the vt's live grid bottom, so the cursor snaps into a different
  scrolloff band — no text differs), and five case texts a pty cannot hold
  verbatim (a literal TAB the emulator expands, a file with no trailing
  newline, an all-whitespace last row the dump trims). One more,
  `dot-append-count`: `a` at a file's end grows it by a newline (helix
  append_mode), which a terminal's text, not the editor's to grow, does not.
  The sticky-view cases join the viewport class.
- `golf.jsonl` + `golf-goldens.jsonl` — every example on helix-golf
  (github.com/nik-rev/helix-golf, imported at d78c18c): one case per numbered
  step of each walkthrough, its keys being the command up to and including
  that step, so the first failing case names the step that diverges. A
  step that starts over with `%` also gets `-fromNN` cases replaying the rest
  of the command from helix's own text there, so a later step is still
  tested when an earlier one misses. The goldens are
  `hx-harness test/hxcases/golf.jsonl`; `zig build hxgolf` runs them.
  `golf-waivers.jsonl` pins the seven `reverse_golf_example` steps from `""N`
  on: they walk the search register with `*`, `N` and `n`, which in pardes
  are the acme look ring, by decision. All ten examples reproduce their published result in hx 25.07.1 under
  the site's own conditions (a file of the example's language, auto-pairs
  on). Under the harness two do not, and their goldens are the harness's
  anyway, which pardes follows: `csv_to_sql` needs auto-pairs (off in the
  harness and absent in pardes) to close its `VALUES (`, and
  `invert_dictionary_2` needs 25.07.1's `<count>Alt-(` (rotate within groups
  of count) where the reference helix rotates by count.
- `smoke.jsonl` — 20 cases referenced by nothing in the tree: no build step,
  no script. Either wire it up or delete it.

The pardes half is `test/hxdiff.zig`, which builds `pardes-hxdiff` and drives
the core headlessly at 80x24 (22 body rows, matching helix's 22 text rows).

Run it:

    zig build hxdiff        # cases + goldens + waivers, field-by-field;
                            # unwaivered mismatch = per-case report + exit 1
    zig build hxdiff -- test/hxcases/cases.jsonl   # results to stdout, no diff
    zig build hxparity      # the SAME binary in --parity mode: cases.jsonl
                            # + parity.jsonl, each case run twice over the
                            # same text and keys (once in a file pane, once
                            # in a pty pane), both result lines must match.
                            # No goldens — the file pane IS the oracle, so
                            # "editing a shell pane behaves like editing a
                            # file" cannot drift. The case's own "pane" field
                            # is ignored; exemptions in parity-waivers.jsonl
    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-
completion off, scrolloff pinned to pardes' 3, no-language indent style
pinned to Spaces(4), smart-tab off, and the buffer-setup transaction
committed as its own undo revision. Build:
`cargo build --release -p helix-term --features helix-term/integration --bin hx-harness`.

Raw TTY input keeps Ctrl-b for the terminal/editor toggle and unmodified Escape at a detected shell
prompt for `Last`. Other Ctrl/Alt chords, modified Escape, and clipboard shortcut
keys go to the child. Use `Mode` in the tag to leave raw input in place.

Completed mouse rectangles keep their source text when jump navigation scrolls
the pane. Wrapped pieces stay separate copied rows. Changing file content or
reflowing a terminal to a new width clears these rectangles.

File clicks place the editing cursor at the nearest valid insertion position:
blank columns stop at the line end, rows below the file stop on its last row,
and wide glyphs or tabs stay on their character boundary. Clicking while
inserting keeps insert mode. Terminal overlays still support virtual spaces.

In a raw TTY pane, finishing a mouse drag keeps the exact rectangular text
as the Pardes selection and internal yank register. Switch to editor mode
with Ctrl-B to inspect or yank it with `y`; returning to TTY preserves it
without moving the shell's input cursor. In another TTY pane, hold select
(left) and tap look (right) to paste it using the existing chord.