hjkl_vim_types/

lib.rs

//! Vim vocabulary types for the hjkl editor.
//!
//! The enums that grow as vim coverage does (`Pending`, `Motion`,
//! `LastChange`, `InsertEntry`) are `#[non_exhaustive]`, so a new variant is
//! not a breaking change for a crate matching on them. `hjkl-vim` must still
//! handle every variant: building with `--cfg hjkl_exhaustive` drops the
//! attribute and the wildcard arms `hjkl-vim` carries for it, so CI fails on an
//! unhandled variant.

// ─── Modes & parser state ───────────────────────────────────────────────────

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Mode {
    #[default]
    Normal,
    Insert,
    Visual,
    VisualLine,
    /// Column-oriented selection (`Ctrl-V`). Unlike the other visual
    /// modes this one doesn't use tui-textarea's single-range selection
    /// — the block corners live in [`VimState::block_anchor`] and the
    /// live cursor. Operators read the rectangle off those two points.
    VisualBlock,
}

#[derive(Debug, Clone, PartialEq, Eq, Default)]
#[cfg_attr(not(hjkl_exhaustive), non_exhaustive)]
pub enum Pending {
    #[default]
    None,
    /// Operator seen; still waiting for a motion / text-object / double-op.
    /// `count1` is any count pressed before the operator.
    Op { op: Operator, count1: usize },
    /// Operator + 'i' or 'a' seen; waiting for the text-object character.
    OpTextObj {
        op: Operator,
        count1: usize,
        inner: bool,
    },
    /// Operator + 'g' seen (for `dgg`).
    OpG { op: Operator, count1: usize },
    /// Bare `g` seen in normal/visual — looking for `g`, `e`, `E`, …
    G,
    /// Bare `f`/`F`/`t`/`T` — looking for the target char.
    Find { forward: bool, till: bool },
    /// Operator + `f`/`F`/`t`/`T` — looking for target char.
    OpFind {
        op: Operator,
        count1: usize,
        forward: bool,
        till: bool,
    },
    /// Operator + `'` (`linewise`) or `` ` `` — looking for the mark name.
    OpMark { op: Operator, linewise: bool },
    /// `r` pressed — waiting for the replacement char.
    Replace,
    /// Visual mode + `i` or `a` pressed — waiting for the text-object
    /// character to extend the selection over.
    VisualTextObj { inner: bool },
    /// Bare `z` seen — looking for `z` (center), `t` (top), `b` (bottom).
    Z,
    /// `m` pressed — waiting for the mark letter to set.
    SetMark,
    /// `'` pressed — waiting for the mark letter to jump to its line
    /// (lands on first non-blank, linewise for operators).
    GotoMarkLine,
    /// `` ` `` pressed — waiting for the mark letter to jump to the
    /// exact `(row, col)` stored at set time (charwise for operators).
    GotoMarkChar,
    /// `"` pressed — waiting for the register selector. The next char
    /// (`a`–`z`, `A`–`Z`, `0`–`9`, or `"`) sets `pending_register`.
    SelectRegister,
    /// `q` pressed (not currently recording) — waiting for the macro
    /// register name. The macro records every key after the chord
    /// resolves, until a bare `q` ends the recording.
    RecordMacroTarget,
    /// `@` pressed — waiting for the macro register name to play.
    /// `count` is the prefix multiplier (`3@a` plays the macro 3
    /// times); 0 means "no prefix" and is treated as 1.
    PlayMacroTarget { count: usize },
    /// `[` pressed in Normal/Visual mode — waiting for the second key.
    /// Resolves `[[` → `SectionBackward`, `[]` → `SectionEndBackward`.
    SquareBracketOpen,
    /// `]` pressed in Normal/Visual mode — waiting for the second key.
    /// Resolves `]]` → `SectionForward`, `][` → `SectionEndForward`.
    SquareBracketClose,
    /// Operator + `[` pending — waiting for second key to pick section motion.
    OpSquareBracketOpen { op: Operator, count1: usize },
    /// Operator + `]` pending — waiting for second key to pick section motion.
    OpSquareBracketClose { op: Operator, count1: usize },
    /// `s` / `S` in Normal mode with `motion_sneak=true` — waiting for
    /// the first character of the two-char digraph.
    /// `forward=true` → `s`; `forward=false` → `S` (backward).
    SneakFirst { forward: bool, count: usize },
    /// First sneak char captured; waiting for the second char to complete
    /// the digraph and jump.
    SneakSecond {
        c1: char,
        forward: bool,
        count: usize,
    },
    /// Operator + `s` / `S` pending — waiting for the first char of the
    /// two-char sneak digraph (e.g. `d` then `s` then `a` then `b` = `dsab`).
    OpSneakFirst {
        op: Operator,
        count1: usize,
        forward: bool,
    },
    /// Operator + sneak first char captured; waiting for the second char.
    OpSneakSecond {
        op: Operator,
        count1: usize,
        c1: char,
        forward: bool,
    },
}

// ─── Operator / Motion / TextObject ────────────────────────────────────────

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Operator {
    Delete,
    Change,
    Yank,
    /// `gU{motion}` — uppercase the range. Entered via the `g` prefix
    /// in normal mode or `U` in visual mode.
    Uppercase,
    /// `gu{motion}` — lowercase the range. `u` in visual mode.
    Lowercase,
    /// `g~{motion}` — toggle case of the range. `~` in visual mode
    /// (character at the cursor for the single-char `~` command stays
    /// its own code path in normal mode).
    ToggleCase,
    /// `>{motion}` — indent the line range by `shiftwidth` spaces.
    /// Always linewise, even when the motion is char-wise — mirrors
    /// vim's behaviour where `>w` indents the current line, not the
    /// word on it.
    Indent,
    /// `<{motion}` — outdent the line range (remove up to
    /// `shiftwidth` leading spaces per line).
    Outdent,
    /// `zf{motion}` / `zf{textobj}` / Visual `zf` — create a closed
    /// fold spanning the row range. Doesn't mutate the buffer text;
    /// cursor restores to the operator's start position.
    Fold,
    /// `gq{motion}` — reflow the row range to `settings.textwidth`.
    /// Greedy word-wrap: collapses each paragraph (blank-line-bounded
    /// run) into space-separated words, then re-emits lines whose
    /// width stays under `textwidth`. Always linewise, like indent.
    Reflow,
    /// `gw{motion}` — same reflow as `gq` but cursor stays at the
    /// pre-reflow `(row, col)`. If the reflow shrinks the line so the
    /// original col is past the new EOL, the col is clamped to the last
    /// char of the line (vim's behaviour). Always linewise.
    ReflowKeepCursor,
    /// `={motion}` — auto-indent the line range using shiftwidth-based
    /// bracket depth counting (v1 dumb reindent). Always linewise.
    /// See `auto_indent_range` for the algorithm and its limitations.
    AutoIndent,
    /// `!{motion}` — filter the line range through an external shell command.
    /// The range text is piped to the command's stdin; stdout replaces the
    /// range in the buffer. Non-zero exit or spawn failure returns an error
    /// to the caller without mutating the buffer.
    Filter,
    /// `gc{motion}` / `gcc` — toggle line comments on the row range.
    /// Dispatched through `Editor::toggle_comment_range` rather than the
    /// normal `run_operator_over_range` pipeline (same pattern as `Filter`).
    Comment,
    /// `g?{motion}` / `g??` / visual `g?` — ROT13 the range. Same operator
    /// shape as the case ops; only the per-char transform differs.
    Rot13,
}

#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(not(hjkl_exhaustive), non_exhaustive)]
pub enum Motion {
    Left,
    Right,
    /// `<Space>` — right-motion that wraps to the next line at EOL (vim's
    /// default `whichwrap=b,s`). Distinct from `Right`/`l` which never wrap.
    SpaceFwd,
    /// `<BS>` — left-motion that wraps to the previous line's last char at BOL
    /// (`whichwrap=b`). Distinct from `Left`/`h` which never wrap.
    BackspaceBack,
    Up,
    Down,
    WordFwd,
    BigWordFwd,
    WordBack,
    BigWordBack,
    WordEnd,
    BigWordEnd,
    /// The word-end motion `cw` / `cW` runs instead of `w` / `W` when the
    /// cursor is on a non-blank (`:h cw`). It is NOT `e` / `E`: vim calls
    /// `end_word()` with its `stop` flag set, so a first iteration that
    /// starts on the last character of a word does not move — `cw` there
    /// changes just that character, where `ce` runs on to the next word's
    /// end. `big` picks `cW` over `cw`.
    ChangeWordEnd {
        big: bool,
    },
    /// `ge` — backward word end.
    WordEndBack,
    /// `gE` — backward WORD end.
    BigWordEndBack,
    LineStart,
    /// `<Home>` — column 0, as `0` (`LineStart`), except that it does not
    /// open a closed fold: vim's `nv_home` runs `nv_pipe`, which has no
    /// `'foldopen'` check.
    Home,
    FirstNonBlank,
    LineEnd,
    FileTop,
    FileBottom,
    Find {
        ch: char,
        forward: bool,
        till: bool,
    },
    FindRepeat {
        reverse: bool,
    },
    MatchBracket,
    /// `[(` / `])` / `[{` / `]}` — jump to the previous/next unmatched bracket
    /// of the given kind. `open` is the open char (`(` or `{`); `forward` picks
    /// the close (`)`/`}`) when true, the open when false.
    UnmatchedBracket {
        forward: bool,
        open: char,
    },
    WordAtCursor {
        forward: bool,
        /// `*` / `#` use `\bword\b` boundaries; `g*` / `g#` drop them so
        /// the search hits substrings (e.g. `foo` matches inside `foobar`).
        whole_word: bool,
    },
    /// `n` / `N` — repeat the last `/` or `?` search.
    SearchNext {
        reverse: bool,
    },
    /// `H` — cursor to viewport top (plus `count - 1` rows down).
    ViewportTop,
    /// `M` — cursor to viewport middle.
    ViewportMiddle,
    /// `L` — cursor to viewport bottom (minus `count - 1` rows up).
    ViewportBottom,
    /// `g_` — last non-blank char on the line.
    LastNonBlank,
    /// `gM` — cursor to the middle char column of the current line
    /// (`floor(chars / 2)`). Vim's variant ignoring screen wrap.
    LineMiddle,
    /// `gm` — cursor to the middle of the *screen* line: column
    /// `min(viewport_width / 2, last_col)`. Differs from `gM` (char-middle).
    ScreenLineMiddle,
    /// `g0` — first character of the *screen* line: the start of the wrap
    /// segment holding the cursor under wrap, the first visible column
    /// without it.
    ScreenLineStart,
    /// `g^` — first non-blank character from the screen line's start on
    /// (the line's last character when only blanks follow).
    ScreenLineFirstNonBlank,
    /// `g$` — last character of the screen line; inclusive under an
    /// operator, and the NUL past the line's end in Visual when the line
    /// ends on that screen line.
    ScreenLineEnd,
    /// `{` — previous paragraph (preceding blank line, or top).
    ParagraphPrev,
    /// `}` — next paragraph (following blank line, or bottom).
    ParagraphNext,
    /// `(` — previous sentence boundary.
    SentencePrev,
    /// `)` — next sentence boundary.
    SentenceNext,
    /// `gj` — `count` visual rows down (one screen segment per step
    /// under `:set wrap`; falls back to `Down` otherwise).
    ScreenDown,
    /// `gk` — `count` visual rows up; mirror of [`Motion::ScreenDown`].
    ScreenUp,
    /// `[[` — backward to the previous `{` at column 0 (C section header).
    /// Charwise exclusive; count-aware.
    SectionBackward,
    /// `]]` — forward to the next `{` at column 0. Charwise exclusive.
    SectionForward,
    /// `[]` — backward to the previous `}` at column 0 (C section end).
    /// Charwise exclusive; count-aware.
    SectionEndBackward,
    /// `][` — forward to the next `}` at column 0. Charwise exclusive.
    SectionEndForward,
    /// `+` / `<CR>` — first non-blank of the next line. Linewise.
    FirstNonBlankNextLine,
    /// `-` — first non-blank of the previous line. Linewise.
    FirstNonBlankPrevLine,
    /// `_` — first non-blank of `count-1` lines down (count=1 = current line). Linewise.
    FirstNonBlankLine,
    /// `{count}|` — jump to column `count` on the current line (1-based;
    /// no count or count=0 → column 1 → index 0). Clamped to line length.
    GotoColumn,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextObject {
    Word {
        big: bool,
    },
    Quote(char),
    Bracket(char),
    Paragraph,
    /// `it` / `at` — XML/HTML-style tag pair. `inner = true` covers
    /// content between `>` and `</`; `inner = false` covers the open
    /// tag through the close tag inclusive.
    XmlTag,
    /// `is` / `as` — sentence: a run ending at `.`, `?`, or `!`
    /// followed by whitespace or end-of-line. `inner = true` covers
    /// the sentence text only; `inner = false` includes trailing
    /// whitespace.
    Sentence,
}

/// Classification determines how operators treat the range end.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RangeKind {
    /// Range end is exclusive (end column not included). Typical: h, l, w, 0, $.
    Exclusive,
    /// Range end is inclusive. Typical: e, f, t, %.
    Inclusive,
    /// Whole lines from top row to bottom row. Typical: j, k, gg, G.
    Linewise,
}

// ─── Dot-repeat storage ────────────────────────────────────────────────────

/// Information needed to replay a mutating change via `.`.
#[derive(Debug, Clone)]
#[cfg_attr(not(hjkl_exhaustive), non_exhaustive)]
pub enum LastChange {
    /// Operator over a motion.
    OpMotion {
        op: Operator,
        motion: Motion,
        count: usize,
        inserted: Option<String>,
        /// The explicit register the original change used (`"adw`), if any.
        /// See [`LastChange::LineOp::register`].
        register: Option<char>,
    },
    /// Operator over a text-object.
    OpTextObj {
        op: Operator,
        obj: TextObject,
        inner: bool,
        inserted: Option<String>,
        /// The explicit register the original change used (`"adiw`), if any.
        /// See [`LastChange::LineOp::register`].
        register: Option<char>,
    },
    /// Operator over the motion to mark `ch` (`d'a` when `linewise`, else
    /// ``d`a``). Replays against the mark's position at repeat time.
    OpMark {
        op: Operator,
        ch: char,
        linewise: bool,
        inserted: Option<String>,
        /// See [`LastChange::LineOp::register`].
        register: Option<char>,
    },
    /// `dd`, `cc`, `yy` with a count.
    LineOp {
        op: Operator,
        count: usize,
        inserted: Option<String>,
        /// The explicit register (`"add`, `"ayy`, ...) the original change
        /// used, if any. `.` must reuse it (`:h redo-register`) rather than
        /// falling back to the unnamed register.
        register: Option<char>,
    },
    /// `x`, `X` with a count.
    CharDel {
        forward: bool,
        count: usize,
        /// The explicit register the original change used (`"ax`), if any.
        /// See [`LastChange::LineOp::register`].
        register: Option<char>,
    },
    /// `r<ch>` with a count.
    ReplaceChar { ch: char, count: usize },
    /// `~` with a count.
    ToggleCase { count: usize },
    /// `J` with a count.
    JoinLine { count: usize },
    /// `p` / `P` (and `gp`/`gP`, `]p`/`[p`) with a count.
    Paste {
        before: bool,
        count: usize,
        /// `gp` / `gP` — leave the cursor just after the pasted text.
        cursor_after: bool,
        /// `]p` / `[p` — reindent the pasted block to the current line.
        reindent: bool,
        /// The explicit register the original paste read (`"ap`), if any.
        /// See [`LastChange::LineOp::register`].
        register: Option<char>,
    },
    /// `D` (delete to EOL).
    DeleteToEol {
        inserted: Option<String>,
        /// The explicit register the original delete wrote (`"aD`), if any.
        /// See [`LastChange::LineOp::register`].
        register: Option<char>,
    },
    /// `o` / `O` + the inserted text.
    OpenLine {
        above: bool,
        inserted: String,
        /// `[count]o` opens `count` lines, each with `inserted`.
        count: usize,
    },
    /// `i`/`I`/`a`/`A` + inserted text.
    InsertAt {
        entry: InsertEntry,
        inserted: String,
        count: usize,
        /// `<BS>` presses that went past the insert's start; `.` replays
        /// them before `inserted`, once per counted copy.
        backspaces: usize,
    },
    /// `dgn` / `cgn` (and `gN` forms) — operate on the next search match.
    /// `inserted` is filled on Esc for the `cgn` change form so `.` retypes it.
    GnOp {
        op: Operator,
        forward: bool,
        inserted: Option<String>,
        /// The explicit register the original change used (`"acgn`), if any.
        /// See [`LastChange::LineOp::register`].
        register: Option<char>,
    },
    /// `R{text}<Esc>` — replace (overstrike) mode. `.` re-overtypes `text`.
    ReplaceMode { text: String },
    /// A visual-mode operator (`v`/`V` + `d`/`c`/`</>`/`~`/`u`/`U`/`?`).
    /// vim (`:h v_.`) replays over a same-SIZE region anchored at the
    /// current cursor rather than the original absolute range — `extent`
    /// captures that size. `inserted` is filled on Esc for the `c` form so
    /// `.` retypes it (same `AfterChange` patch site as `OpMotion` /
    /// `OpTextObj` / `LineOp`).
    ///
    /// `d` / `c` / `~`/`u`/`U`/`g?` from Visual — charwise, linewise, AND
    /// blockwise (`VisualExtent::Block`). Block `c` fills `inserted` at its
    /// own `BlockChange` finish site (`comment.rs`), mirroring the charwise
    /// `AfterChange` patch.
    VisualOp {
        op: Operator,
        extent: VisualExtent,
        inserted: Option<String>,
        /// The explicit register the original change used (`vll"ad`), if
        /// any. See [`LastChange::LineOp::register`].
        register: Option<char>,
        /// Shift levels of a `>` / `<` (`Vj2>` shifts two `'shiftwidth'`s,
        /// and so does its `.`); 1 for every other operator.
        levels: usize,
    },
    /// Charwise (`v`) / linewise (`V`) `r{ch}` — dot-repeat re-replaces a
    /// same-SIZE region anchored at the cursor (`:h v_.`), mirroring
    /// `VisualBlockReplace` for the block case. `r` has no `Operator`, so it
    /// rides its own variant instead of `VisualOp`. `extent` is a
    /// `VisualExtent::Char` or `VisualExtent::Line` captured from the live
    /// selection.
    VisualReplace { ch: char, extent: VisualExtent },
    /// Visual-BLOCK `r{ch}` — dot-repeat re-replaces a same-size rectangle
    /// anchored TOP-LEFT at the cursor. `r` has no `Operator`, so it rides
    /// its own variant instead of `VisualOp`. `to_eol` preserves a `$`-ragged
    /// right edge (`:h v_b_$`).
    VisualBlockReplace {
        ch: char,
        rows: usize,
        cols: usize,
        to_eol: bool,
    },
    /// Visual-BLOCK `I` / `A` — dot-repeat re-inserts `text` at the block's
    /// left (`append == false`) or right (`append == true`) edge over a
    /// same-size rectangle anchored TOP-LEFT at the cursor. `cols` is the
    /// block width (`A` appends `cols` columns past the cursor); `to_eol`
    /// preserves a `$`-ragged right edge (`A` only, `:h v_b_$`).
    VisualBlockInsert {
        text: String,
        rows: usize,
        cols: usize,
        to_eol: bool,
        append: bool,
    },
}

/// Size of a visual-mode selection, captured for `LastChange::VisualOp`
/// dot-repeat (`:h v_.`). Vim's rule: characterwise replays over the same
/// number of lines, with the same character width on the last line;
/// linewise replays over the same number of lines.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum VisualExtent {
    /// Charwise (`v`). `lines == 1`: `width` is the raw selected char count,
    /// and replay selects exactly `width` chars starting at the cursor.
    /// `lines > 1`: the first replay line runs from the cursor's column to
    /// ITS OWN end of line, middle lines are taken whole, and the last line
    /// takes its first `width` chars (measured from column 0, matching the
    /// original selection's last-line char count).
    Char { lines: usize, width: usize },
    /// Linewise (`V`). Replay is exactly `[count]dd`-equivalent: `lines`
    /// rows starting at the cursor's row.
    Line { lines: usize },
    /// Blockwise (`<C-v>`). Replay reconstructs a `rows` × `cols` rectangle
    /// with its TOP-LEFT corner at the cursor (`:h v_.` for blocks), then
    /// re-runs the operator. `to_eol` preserves a `$`-ragged right edge
    /// (`:h v_b_$`) — every row then resolves its own EOL instead of the
    /// fixed `cols` width.
    Block {
        rows: usize,
        cols: usize,
        to_eol: bool,
    },
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(not(hjkl_exhaustive), non_exhaustive)]
pub enum InsertEntry {
    I,
    A,
    ShiftI,
    ShiftA,
    /// `gI` — insert at column 0, before any indent.
    GShiftI,
}

/// Tracks which kind of horizontal jump was last performed so `;` / `,`
/// can dispatch to the correct repeat handler.
///
/// - `FindChar` — last horizontal motion was `f`/`F`/`t`/`T`; `;`/`,`
///   repeats via `Motion::FindRepeat`.
/// - `Sneak` — last horizontal motion was `s`/`S` sneak; `;`/`,` repeats
///   via `apply_sneak` with the stored digraph.
/// - `None` — no horizontal motion yet; `;`/`,` are no-ops for both.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum LastHorizontalMotion {
    #[default]
    None,
    FindChar,
    Sneak,
}

#[derive(Debug, Clone)]
pub struct InsertSession {
    pub count: usize,
    /// Min/max row visited during this session. Widens on every key.
    pub row_min: usize,
    pub row_max: usize,
    /// O(1) rope snapshot of the full buffer at session entry. Used to
    /// diff the affected row window at finish without being fooled by
    /// cursor navigation through rows the user never edited.
    /// `ropey::Rope::clone` is Arc-clone — no byte copying.
    pub before_rope: ropey::Rope,
    pub reason: InsertReason,
    /// (row, col) where the insert session began (char-indexed). Abbreviation
    /// expansion uses `start_col` as `mincol` — only chars at or after this
    /// column on `start_row` are eligible as part of the `lhs` match, so
    /// pre-existing buffer text is never consumed by expansion.
    pub start_row: usize,
    pub start_col: usize,
    /// `<BS>` / `<C-h>` presses that deleted at or before the insert's start
    /// (vim's `Insstart`). Each one moves `start_row` / `start_col` back to
    /// where it left the cursor, as vim moves `Insstart`, and `.` replays
    /// them before retyping, as vim's redo buffer does.
    pub backspaces: usize,
    /// Characters those `backspaces` removed, net of any spaces a
    /// `'softtabstop'` delete put back — what the typed text's length is
    /// measured against when the session ends.
    pub deleted: isize,
    /// The line breaks `'formatoptions'` `t` put in while typing, oldest
    /// first. vim's redo holds the typed keys, not the breaks, so the
    /// session takes them back out when it reads what was typed.
    pub wraps: Vec<InsertWrap>,
}

/// One auto-wrap break made during an insert session: where its line break
/// went, and what it replaced.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct InsertWrap {
    /// Char offset of the inserted line break in the buffer at the time.
    pub at: usize,
    /// The run of blanks the break replaced.
    pub blanks: String,
    /// Characters of indent put in after the break.
    pub indent: usize,
}

#[derive(Debug, Clone)]
pub enum InsertReason {
    /// Plain entry via i/I/a/A — recorded as `InsertAt`.
    Enter(InsertEntry),
    /// Entry via `o`/`O` — records OpenLine on Esc.
    Open { above: bool },
    /// Entry via an operator's change side-effect. Retro-fills the
    /// stored last-change's `inserted` field on Esc.
    AfterChange,
    /// Entry via `C` (delete to EOL + insert).
    DeleteToEol,
    /// Entry via an insert triggered during dot-replay — don't touch
    /// last_change because the outer replay will restore it.
    ReplayOnly,
    /// `I` or `A` from VisualBlock: insert the typed text at `col` on
    /// rows in `top..=bot`. `col` is the start column for `I`, the
    /// one-past-block-end column for `A`.
    ///
    /// `pad` distinguishes the two vim behaviours at rows shorter than
    /// `col` (`:h v_b_I` vs `:h v_b_A`): `A` pads short rows with spaces
    /// so the appended text still lines up (`pad: true`); `I` skips rows
    /// that don't reach `col` entirely — no padding, no insert on that
    /// row (`pad: false`).
    ///
    /// `cursor_col` is where the cursor lands on Esc — the block's LEFT
    /// edge for both `I` and `A` (verified against real nvim: `A`'s
    /// cursor does NOT land at the append/typed position, `col`, once
    /// the block is more than one column wide). For `I`, `cursor_col ==
    /// col` (its insertion point already IS the left edge); for `A` they
    /// differ whenever the block spans more than one column.
    BlockEdge {
        top: usize,
        bot: usize,
        col: usize,
        pad: bool,
        cursor_col: usize,
        /// Top row's char count BEFORE the `A` pad was applied. Recorded at
        /// construction so `finish_insert_session` can remove exactly the
        /// pad's bytes (`pre_pad_len..col`) on an empty Esc — the pad itself
        /// is never recorded as an undo step, so its range must be stashed
        /// here rather than derived from the (already padded) live buffer.
        pre_pad_len: usize,
        /// Undo-stack depth recorded just before the caller's `push_undo` for
        /// this block command. An empty block-`A` pushes a no-op undo
        /// boundary; when it is still the most recent one (depth == this + 1
        /// at Esc — nothing else pushed mid-session, and the push was not
        /// suppressed by an enclosing undo group), `finish_insert_session`
        /// consumes it so the no-op command leaves the undo tree untouched.
        undo_depth_before: usize,
    },
    /// `c` from VisualBlock: block content deleted, then user types
    /// replacement text replicated across all block rows on Esc. Cursor
    /// advances to the last typed char after replication (unlike BlockEdge
    /// which leaves cursor at the insertion column).
    BlockChange { top: usize, bot: usize, col: usize },
    /// `R` — Replace mode. Each typed char overwrites the cell under
    /// the cursor instead of inserting; at end-of-line the session
    /// falls through to insert (same as vim).
    Replace,
}

/// Saved visual-mode anchor + cursor for `gv` (re-enters the last
/// visual selection). `mode` carries which visual flavour to
/// restore; `anchor` / `cursor` mean different things per flavour:
///
/// - `Visual`     — `anchor` is the char-wise visual anchor.
/// - `VisualLine` — `anchor.0` is the `visual_line_anchor` row;
///   `anchor.1` is unused.
/// - `VisualBlock`— `anchor` is `block_anchor`, `block_vcol` is the
///   sticky vcol that survives j/k clamping.
#[derive(Debug, Clone, Copy)]
pub struct LastVisual {
    pub mode: Mode,
    pub anchor: (usize, usize),
    pub cursor: (usize, usize),
    pub block_vcol: usize,
}