# Selections

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.

## What a selection is

Every `Text` (src/Text.zig) has its own: a pane's body, its tag, a prompt's
answer, a column's or the workspace's tag. A selection is one primary range
plus up to 63 others.

- The PRIMARY is where the cursor always was: `cur_row`/`cur_col` is the
  head, `vsel.row`/`vsel.col` the anchor while `vsel.active`, and a bare
  cursor (inactive `vsel`) is the one-character range under it. `msel` is
  the older whole-line form (`r0`..`r1`), kept for search-result highlights.
- The others are `sels[0..nsel]`, each a `SelRange` of head and anchor plus
  its own `j`/`k` goal column, in document order. The primary is not in the
  list; `Text.ranges` slots it in and returns its index.
- Ends are CELLS, the characters a block cursor sits on, where helix's are
  gaps between characters. `Text.cellRange`, `cellOffRange` and `rangeCells`
  convert. A range covers at least one character, as in helix (min width 1),
  so there are no empty ranges.
- `vsel.explicit` says the selection was made on purpose (`v`, `x`, `%`,
  `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.

`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
primary through the merges, and keeps the first 64. `setRange` writes one
range and drops the others.

## Making, splitting, merging, rotating, removing

- Made several by `C`/`Alt-C` (copy to the next/previous line), `s` (every
  match inside each range), `S` (the pieces between matches), `Alt-s` (one
  per line), `<n>o`/`<n>O`, and `Alt-J` (the spaces a join put in). `s`/`S`
  re-run on every keystroke from the selection the prompt opened on
  (`Pane.sel_snap`); Esc is that snapshot restored.
- `Alt-minus` merges all into one, `Alt-_` the consecutive ones, `_` trims
  whitespace (dropping all-blank ranges).
- `)`/`(` rotate which range is primary; `Alt-)`/`Alt-(` rotate the TEXT
  between ranges, the primary moving with its text.
- `,` keeps only the primary, `Alt-,` removes it (the next range takes over).
- After `s`, `S` and `Alt-s` the primary is the first range, which is
  helix's behaviour (its own TODO), not a choice.

## How a command reaches every range

A parsed action has a scope (`modal.Normal.Action.scope`).

- `per_selection` (motions, `d`, `c`, `y`, `p`, `r`, `~`, `>`, `ms`, ...):
  `normal.replaySels` runs the ONE-range handler once per range, last range
  first, each pass seeing a single selection. A pass's result is stored as
  distances from the END of the text, which an edit at an earlier range
  cannot move; `setRanges` then puts them back together. The mode, prefix
  and select state that survive are the primary's pass. Insert-mode keys are
  replayed the same way.
- `once` (the `multi` family, `s`/`S`, `J`/`Alt-J`, `Alt-(`/`Alt-)`, `&`,
  `Ctrl-c`, undo/redo, builtins, search): one function takes `Text.ranges`,
  makes one edit and hands the mapped ranges to `setRanges`, the way a helix
  command builds one transaction.
- Anything that reaches outside the text (a builtin, a language query, a
  look) runs once from the primary and drops back to one cursor
  (`normal.multiOnce`).

## Undo, registers, repeat

- One keystroke is one undo step however many ranges it edited: only the
  first replay pass records (`pushUndo`).
- An undo snapshot (`File.Snapshot`) holds the content and the PRIMARY
  range. Undo puts the primary back and leaves the other ranges where they
  were; helix restores the whole selection of that revision.
- Registers (`Registers.zig`) hold one value per range. A yank under the
  replay fills slot `Pardes.multi_index` of `multi_count`, and `p`, `P`, `R`
  and insert `Ctrl-r` read slot i at range i, the last value standing in
  for missing ones. `"<reg>` names the register (`Pardes.register` for the
  length of one command); `_ # . % /` are computed or special and `+`/`*`
  is the system clipboard. The acme chords and a paste into a terminal read
  the default register joined by newlines.
- `Alt-.` repeats the last `f`/`t`/`F`/`T`. There is no `.` and there are no
  macros.

## 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.
- Count: at most 64 ranges; matches past that are dropped silently.
- `n`/`N` walk the look ring (acme), not regex search hits, and there is no
  `*`; helix-golf's `*`, `""N` and `n` do not apply.
- `s`/`S` match as sam does (docs/helix-keys.md, "Regex selection"): each
  line is its own haystack, so `^`/`$` hold at every line and a class like
  `\s` does not reach the newline unless the pattern names `\n`.
- Undo restores only the primary (above).