Every range lives through insert mode, carried through each edit

Insert mode dropped the selection on the first key and restored only the
primary's appended-over span on Esc. Now each insert-mode edit is made at the
bare cursor as before, and the range is then carried through it with helix's
Range::map rules: typing slides an i range and stretches an a range, Enter
(which now also drops the blanks before the cursor, as helix does) slides or
stretches by what the cursor moved, and an arrow collapses. The replay gives
every other range the same. Esc after a pulls each range's end back by one
(helix restore_cursor), which replaces Text.append_at. The wiX-edit-drops-sel
and msel-append waivers are gone.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

2 files changed, 38 insertions, 20 deletions

diff --git a/docs/helix-keys.md b/docs/helix-keys.md
index 90efc463..35f62765 100644
--- a/docs/helix-keys.md
+++ b/docs/helix-keys.md
@@ -7,10 +7,17 @@ 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). Five of the six waivers are
-named in the row they belong to; the sixth, `wiX-edit-drops-sel`, belongs to no
-single key — it is the anchor-only divergence every insert-mode edit shares —
-and is described in the Files list at the bottom instead.
+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
@@ -227,7 +234,7 @@ grew `sels` + `primary`, emitted only when there is more than one range.
 | `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 |
-| `a` … `Esc` with several ranges | the primary's appended-over span is restored; the others collapse to bare cursors | `Pane.append_at` is a single field. Waived (`msel-append`) | waived |
+| 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 |
 
@@ -389,11 +396,11 @@ Files (all in `test/hxcases/`):
   (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. Three live ones:
-  `wiX-edit-drops-sel` and `msel-append` (helix maps selections through
-  insert-mode edits, pardes does not) and `alt-c-window-op` (the pardes
-  window op deliberately shadows helix change-noyank). `msel-yank-paste`
-  went with registers of one value per range; `sel-regex-caret` and
+- `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` — 14 named exemptions for the parity gate, in three
@@ -412,10 +419,11 @@ Files (all in `test/hxcases/`):
   tested when an earlier one misses. The goldens are
   `hx-harness test/hxcases/golf.jsonl`; `zig build hxgolf` runs them. 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 pins two do not: `csv_to_sql` needs auto-pairs to
-  close its `VALUES (`, and `invert_dictionary_2` needs 25.07's
-  `<count>Alt-(` (rotate within groups of count) where the harness's newer
-  helix rotates by count.
+  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.
 
diff --git a/docs/selections.md b/docs/selections.md
index 0f000e2c..c08ccb14 100644
--- a/docs/selections.md
+++ b/docs/selections.md
@@ -3,6 +3,8 @@
 How normal mode holds and changes its selections, and where that differs from
 helix's `Selection` (a list of ranges over gap offsets, with a primary index).
 Key-by-key behaviour is in docs/helix-keys.md; this is the model underneath.
+"helix" here is the reference build docs/helix-keys.md names: `hx-harness`
+at `694e7dfdd`, upstream `278b24389`.
 
 ## What a selection is
 
@@ -25,8 +27,9 @@ plus up to 63 others.
   `s`, `n`/`N`, ...) rather than left behind by a motion. Only pardes reads
   it: the look (Enter) and execute (Tab) chords act on explicit selections
   and on the word under the cursor otherwise.
-- `select` is `v` extend mode. `append_at` remembers where an `a` began, so
-  Esc can give back the range it appended over.
+- `select` is `v` extend mode. `restore_cursor` says the insert session
+  began with `a`, so Esc gives each range back the character it was
+  stretched by.
 
 `Text.setRanges` is the one writer of a whole selection: it sorts by start,
 merges ranges that overlap or share a start (helix `normalize`), follows the
@@ -67,6 +70,17 @@ A parsed action has a scope (`modal.Normal.Action.scope`).
   look) runs once from the primary and drops back to one cursor
   (`normal.multiOnce`).
 
+## Insert mode
+
+Each range lives on through insert mode. Every insert-mode edit happens at
+the cursor, so `edit.insertKey` runs it on the bare cursor and then carries
+the range through what it did to the text, with helix's `Range::map` rules:
+at an insertion, a backward range's head and an empty range move past it
+and a forward range's head stays before it, so typing slides an `i` range
+and stretches an `a` range. Enter slides or stretches the range by what the
+cursor moved; an arrow key collapses it. The other ranges get the same by
+the replay.
+
 ## Undo, registers, repeat
 
 - One keystroke is one undo step however many ranges it edited: only the
@@ -86,10 +100,6 @@ A parsed action has a scope (`modal.Normal.Action.scope`).
 
 ## Where it differs from helix
 
-- Insert mode: helix maps every range through each keystroke's edit, so a
-  range an `i`/`a` started from stretches over what is typed and keeps its
-  anchor. Here only the cursor cells move, and after Esc only the primary's
-  `append_at` span comes back (waivers `wiX-edit-drops-sel`, `msel-append`).
 - Direction of a one-character range: both of its cells are the same cell,
   so it has none. helix can flip one (`Alt-;`) and the commands that read
   the head (`&`, the next extend) see the difference.