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]>

1 files changed, 16 insertions, 6 deletions

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.