lattice_grammar/

builtins.rs

//! Built-in motions, text objects, and operators that ship native (off the
//! WASM boundary; per DESIGN.md §5.5.2 "built-ins stay native").
//!
//! This is the vim catalog: `w` / `b` / `e`, `f` / `t` and their repeats,
//! `{` / `}`, `gg` / `G`, `%`, `n` / `*`, marks, `H` / `M` / `L`, `gj` /
//! `gk`; the operators `d` / `c` / `y` / `<` / `>` / `=` / `gq` / `gU` /
//! `gu` / `g~` / `zf` / `r`; and the `i` / `a` text objects. [`populate`]
//! registers them all into a [`CommandRegistry`] under namespaced names
//! (`motion:word-forward`, `operator:delete`, `text-object:inner-word`) and
//! returns their ids as [`Builtins`].
//!
//! Every builtin is an ordinary registry entry: the dispatcher, `:describe-*`
//! and plugins see it exactly as they see a plugin-contributed motion.
//! Adding one is a registration here and a keymap binding; no dispatcher
//! wiring. Evaluators never touch host state directly: what a motion needs
//! from the host (folds, marks, viewport, last search) arrives through the
//! resolver traits on [`GrammarEnv`](crate::GrammarEnv), and what an operator
//! does is returned as an [`Effect`].
//!
//! Tree-sitter structural objects (`af` / `ac` / …) are registered by
//! `lattice-syntax`, not here: they need a parse this crate cannot see, and
//! reach it only through [`ScopeResolver`](crate::ScopeResolver).

use lattice_protocol::edit::Edit;
use lattice_protocol::position::{Position, Range as ProtoRange};
use std::sync::Arc;

use crate::cancel::CheckCancelled;
use crate::effect::{Effect, YankKind};
use crate::error::CommandError;
use crate::registry::{
    CommandRegistry, FindKind, MotionContext, MotionId, MotionResult, MotionSpec, OperatorContext,
    OperatorId, OperatorSpec, TextObjectContext, TextObjectId, TextObjectSpec,
};

/// Register every native built-in motion, operator and text object into
/// `registry`, and return their ids.
///
/// Call once per registry, at boot. Each call mints fresh ids, so calling
/// it twice re-registers every name onto new ids (the name index then
/// points at the second set). Also tags `w` / `W` as word-forward motions
/// (see [`CommandRegistry::tag_word_forward_motion`]).
///
/// # Examples
///
/// `dw` on `hello world`: the delete operator with a word-forward target.
///
/// ```
/// use lattice_core::{BufferId, Document};
/// use lattice_grammar::{
///     Args, CancellationToken, CommandInvocation, CommandRegistry, Effect, Target, builtins,
///     execute,
/// };
/// use lattice_protocol::position::Position;
///
/// let mut registry = CommandRegistry::new();
/// let b = builtins::populate(&mut registry);
/// assert_eq!(registry.id_by_name("motion:word-forward"), Some(b.word_forward.0));
///
/// let mut doc = Document::from_text("hello world");
/// let dw = CommandInvocation::of(b.delete.0).with_target(Target::Motion(b.word_forward, Args::None));
/// let effect = execute(
///     &registry,
///     &mut doc,
///     BufferId(0),
///     Position::ZERO,
///     dw,
///     &CancellationToken::never(),
/// )
/// .unwrap();
///
/// // The operator edited the document in place and reports the edit plus
/// // the yank into the unnamed register.
/// assert_eq!(doc.text().to_string(), "world");
/// assert!(matches!(effect, Effect::Many(ref parts) if parts.len() == 2));
/// ```
pub fn populate(registry: &mut CommandRegistry) -> Builtins {
    let word_forward = registry.register_motion(
        "motion:word-forward",
        "Move to the start of the next word.",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            exclusive: true,
            apply: Arc::new(motion_word_forward),
            args_schema: vec![],
        },
    );
    let word_backward = registry.register_motion(
        "motion:word-backward",
        "Move to the start of the previous word (vim's `b`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            exclusive: true,
            apply: Arc::new(motion_word_backward),
            args_schema: vec![],
        },
    );
    let word_end = registry.register_motion(
        "motion:word-end",
        "Move to the last byte of the current or next word (vim's `e`). Inclusive.",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            exclusive: false,
            apply: Arc::new(motion_word_end),
            args_schema: vec![],
        },
    );
    let first_non_blank = registry.register_motion(
        "motion:first-non-blank",
        "Move to the first non-whitespace byte of the current line (vim's `^`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            // `^` is exclusive in vim. (Was mis-registered inclusive while
            // the dispatcher ignored the flag; now honoured, so it must be
            // correct.)
            exclusive: true,
            apply: Arc::new(motion_first_non_blank),
            args_schema: vec![],
        },
    );
    let find_char_forward = registry.register_motion(
        "motion:find-char-forward",
        "Move to the next occurrence of `args.char` on the current line (vim's `f`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            exclusive: false,
            apply: Arc::new(motion_find_char_forward),
            args_schema: vec![],
        },
    );
    let find_char_backward = registry.register_motion(
        "motion:find-char-backward",
        "Move to the previous occurrence of `args.char` on the current line (vim's `F`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            // EXCLUSIVE, which is what vim says (`:h F`) and what `dF` has
            // always DONE here. It was registered inclusive, and the
            // backward-inclusive branch of `motion_to_range` happened to
            // produce the exclusive range anyway — two errors cancelling.
            // VM.3b fixed that branch, so this has to say what it means.
            exclusive: true,
            apply: Arc::new(motion_find_char_backward),
            args_schema: vec![],
        },
    );
    let till_char_forward = registry.register_motion(
        "motion:till-char-forward",
        "Move to one byte before the next occurrence of `args.char` (vim's `t`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            exclusive: false,
            apply: Arc::new(motion_till_char_forward),
            args_schema: vec![],
        },
    );
    let till_char_backward = registry.register_motion(
        "motion:till-char-backward",
        "Move to one byte after the previous occurrence of `args.char` (vim's `T`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            // Exclusive, per `:h T` — see `find_char_backward` above.
            exclusive: true,
            apply: Arc::new(motion_till_char_backward),
            args_schema: vec![],
        },
    );
    let big_word_forward = registry.register_motion(
        "motion:big-word-forward",
        "Move to the start of the next WORD (vim's `W` -- whitespace-delimited).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            exclusive: true,
            apply: Arc::new(motion_big_word_forward),
            args_schema: vec![],
        },
    );
    // Vim word-motion special case (`:help word-motions`): under an
    // operator, `dw` / `cw` / `yw` on the last word of a line stop at the
    // line end instead of reaching into the next line's first word. Tag
    // both word-forward motions so the operator range resolver applies it.
    registry.tag_word_forward_motion(word_forward);
    registry.tag_word_forward_motion(big_word_forward);

    let big_word_backward = registry.register_motion(
        "motion:big-word-backward",
        "Move to the start of the previous WORD (vim's `B`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            exclusive: true,
            apply: Arc::new(motion_big_word_backward),
            args_schema: vec![],
        },
    );
    let big_word_end = registry.register_motion(
        "motion:big-word-end",
        "Move to the last byte of the current or next WORD (vim's `E`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            exclusive: false,
            apply: Arc::new(motion_big_word_end),
            args_schema: vec![],
        },
    );
    let paragraph_forward = registry.register_motion(
        "motion:paragraph-forward",
        "Move to the next paragraph boundary -- the next blank line at or after the cursor (vim's `}`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: true,
            // `}` is exclusive in vim (`d}` does not include the blank line).
            exclusive: true,
            apply: Arc::new(motion_paragraph_forward),
            args_schema: vec![],
        },
    );
    let paragraph_backward = registry.register_motion(
        "motion:paragraph-backward",
        "Move to the previous paragraph boundary (vim's `{`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: true,
            // `{` is exclusive in vim.
            exclusive: true,
            apply: Arc::new(motion_paragraph_backward),
            args_schema: vec![],
        },
    );
    let sentence_forward = registry.register_motion(
        "motion:sentence-forward",
        "Move to the start of the next sentence (vim's `)`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: true,
            // `)` is exclusive in vim.
            exclusive: true,
            apply: Arc::new(motion_sentence_forward),
            args_schema: vec![],
        },
    );
    let sentence_backward = registry.register_motion(
        "motion:sentence-backward",
        "Move to the start of the previous sentence (vim's `(`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: true,
            // `(` is exclusive in vim.
            exclusive: true,
            apply: Arc::new(motion_sentence_backward),
            args_schema: vec![],
        },
    );
    let char_left = registry.register_motion(
        "motion:char-left",
        "Move one byte to the left within the current line.",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            // `h` is exclusive in vim. (Backward motion, so behaviour is
            // unchanged either way, but the registration should be correct.)
            exclusive: true,
            apply: Arc::new(motion_char_left),
            args_schema: vec![],
        },
    );
    let char_right = registry.register_motion(
        "motion:char-right",
        "Move one byte to the right within the current line.",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            exclusive: true,
            apply: Arc::new(motion_char_right),
            args_schema: vec![],
        },
    );
    let line_up = registry.register_motion(
        "motion:line-up",
        "Move one line up.",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::Keep,
            jump: false,
            // `k` only ever travels backward, so exclusive here reproduces
            // exactly the range `dk` / `d<C-u>` / `d<PageUp>` produced before
            // VM.3b fixed the backward-inclusive branch.
            //
            // The honest answer is that `k` is LINEWISE in vim and `dk` should
            // take both whole lines. The engine has no linewise-motion-target
            // expansion yet (see `motion_rows`' note), and `MotionSpec` has no
            // flag for it — `linewise` is decided per RESULT. Until that gap
            // closes, `exclusive` is the only knob and this is the value that
            // does not silently change what `dk` deletes.
            exclusive: true,
            apply: Arc::new(motion_line_up),
            args_schema: vec![],
        },
    );
    let line_down = registry.register_motion(
        "motion:line-down",
        "Move one line down.",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::Keep,
            jump: false,
            exclusive: false,
            apply: Arc::new(motion_line_down),
            args_schema: vec![],
        },
    );
    let line_start = registry.register_motion(
        "motion:line-start",
        "Move to the first byte of the current line.",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            // `0` is exclusive in vim.
            exclusive: true,
            apply: Arc::new(motion_line_start),
            args_schema: vec![],
        },
    );
    let line_end = registry.register_motion(
        "motion:line-end",
        "Move to the last byte of the current line.",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::PinToEnd,
            jump: false,
            exclusive: false,
            apply: Arc::new(motion_line_end),
            args_schema: vec![],
        },
    );
    let goto_first_line = registry.register_motion(
        "motion:goto-first-line",
        "Jump to the first line of the buffer (vim's `gg`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: true,
            exclusive: false,
            apply: Arc::new(motion_goto_first_line),
            args_schema: vec![],
        },
    );
    let goto_last_line = registry.register_motion(
        "motion:goto-last-line",
        "Jump to the last line of the buffer (vim's `G`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: true,
            exclusive: false,
            apply: Arc::new(motion_goto_last_line),
            args_schema: vec![],
        },
    );

    let delete = registry.register_operator(
        "operator:delete",
        "Delete the bytes covered by the target range; yank to the unnamed register.",
        OperatorSpec {
            repeatable: true,
            apply: Arc::new(operator_delete),
            args_schema: vec![],
            blockwise_per_row: true,
            post_motion_char: false,
        },
    );
    let change = registry.register_operator(
        "operator:change",
        "Delete the bytes covered by the target range and enter Insert mode (vim's `c`).",
        OperatorSpec {
            repeatable: true,
            apply: Arc::new(operator_change),
            args_schema: vec![],
            blockwise_per_row: true,
            post_motion_char: false,
        },
    );
    let yank = registry.register_operator(
        "operator:yank",
        "Copy the bytes covered by the target range into the named register without modifying the buffer (vim's `y`).",
        OperatorSpec {
            repeatable: true,
            apply: Arc::new(operator_yank),
            args_schema: vec![],
            blockwise_per_row: true,
            post_motion_char: false,
        },
    );
    let indent_left = registry.register_operator(
        "operator:indent-left",
        "Strip leading indentation (4 spaces or one tab) from each line in the range (vim's `<`).",
        OperatorSpec {
            repeatable: true,
            apply: Arc::new(operator_indent_left),
            args_schema: vec![],
            // Linewise effect -- one batched edit covers every line
            // in the visual span, regardless of charwise / blockwise.
            blockwise_per_row: false,
            post_motion_char: false,
        },
    );
    let reindent = registry.register_operator(
        "operator:reindent",
        "Reindent each line in the range to the depth the syntax tree implies, \
         adjusting leading whitespace only (vim's `=`).",
        OperatorSpec {
            repeatable: true,
            apply: Arc::new(operator_reindent),
            args_schema: vec![],
            // Linewise: a blockwise visual collapses to one contiguous
            // range, matching `>` / `<`. Reindenting a rectangle makes
            // no sense -- indentation is a property of whole lines.
            blockwise_per_row: false,
            post_motion_char: false,
        },
    );
    let reformat = registry.register_operator(
        "operator:reformat",
        "Run the buffer's `format.reformat` chain (language server, or an external \
         formatter) over the range — the operator form of `:format` (`g=`).",
        OperatorSpec {
            repeatable: true,
            apply: Arc::new(operator_reformat),
            args_schema: vec![],
            // Linewise, like `=` and `gq`: every formatter this can
            // reach works in whole lines.
            blockwise_per_row: false,
            post_motion_char: false,
        },
    );
    let create_fold = registry.register_operator(
        "operator:create-fold",
        "Create a closed fold over the whole lines the {motion} or selection \
         covers (vim's `zf`).",
        OperatorSpec {
            // Vim's `.` doesn't repeat fold creation.
            repeatable: false,
            apply: Arc::new(operator_create_fold),
            args_schema: vec![],
            // A fold is whole lines, so a blockwise selection is one range.
            blockwise_per_row: false,
            post_motion_char: false,
        },
    );
    let reflow = registry.register_operator(
        "operator:reflow",
        "Reflow each paragraph in the range to `textwidth`, keeping indentation \
         and any comment leader (vim's `gq` and `gw`, which are one operator here).",
        OperatorSpec {
            repeatable: true,
            apply: Arc::new(operator_reflow),
            args_schema: vec![],
            // Linewise, like `=`: filling is a property of whole lines,
            // and a blockwise visual collapses to one contiguous range
            // rather than reflowing a rectangle.
            blockwise_per_row: false,
            post_motion_char: false,
        },
    );
    let indent_right = registry.register_operator(
        "operator:indent-right",
        "Prepend 4 spaces to each line in the range (vim's `>`).",
        OperatorSpec {
            repeatable: true,
            apply: Arc::new(operator_indent_right),
            args_schema: vec![],
            blockwise_per_row: false,
            post_motion_char: false,
        },
    );
    let upper = registry.register_operator(
        "operator:upper",
        "Uppercase ASCII letters in the range (vim's `gU`).",
        OperatorSpec {
            repeatable: true,
            apply: Arc::new(operator_upper),
            args_schema: vec![],
            blockwise_per_row: false,
            post_motion_char: false,
        },
    );
    let lower = registry.register_operator(
        "operator:lower",
        "Lowercase ASCII letters in the range (vim's `gu`).",
        OperatorSpec {
            repeatable: true,
            apply: Arc::new(operator_lower),
            args_schema: vec![],
            blockwise_per_row: false,
            post_motion_char: false,
        },
    );
    let toggle_case = registry.register_operator(
        "operator:toggle-case",
        "Toggle case of ASCII letters in the range (vim's `g~`).",
        OperatorSpec {
            repeatable: true,
            apply: Arc::new(operator_toggle_case),
            args_schema: vec![],
            blockwise_per_row: false,
            post_motion_char: false,
        },
    );
    let search = registry.register_operator(
        "operator:search",
        "Project-search for the text spanned by the motion / text object (Lattice's `g/`).",
        OperatorSpec {
            repeatable: false,
            apply: Arc::new(operator_search),
            args_schema: vec![],
            blockwise_per_row: false,
            post_motion_char: false,
        },
    );
    let replace_char = registry.register_operator(
        "operator:replace-char",
        "Overwrite each non-newline char in the range with the captured char (vim's `r{char}` and Visual `r`).",
        OperatorSpec {
            repeatable: true,
            apply: Arc::new(operator_replace_char),
            // Args::Char(replacement) is folded in by the keymap's
            // wildcard capture (same shape as `f{char}`, which also
            // leaves its schema empty).
            args_schema: vec![],
            // Blockwise visual `r` overwrites each row's column slice
            // independently, exactly like `d` / `y` / `c`.
            blockwise_per_row: true,
            post_motion_char: false,
        },
    );

    let inner_sentence = registry.register_text_object(
        "text-object:inner-sentence",
        "Inner sentence -- text up to the next .!? that ends a sentence (vim's `is`).",
        TextObjectSpec {
            apply: Arc::new(text_object_inner_sentence),
            args_schema: vec![],
        },
    );
    let around_sentence = registry.register_text_object(
        "text-object:around-sentence",
        "Around sentence -- inner_sentence plus trailing whitespace (vim's `as`).",
        TextObjectSpec {
            apply: Arc::new(text_object_around_sentence),
            args_schema: vec![],
        },
    );

    let inner_paragraph = registry.register_text_object(
        "text-object:inner-paragraph",
        "Inner paragraph -- the run of non-blank lines containing the cursor (vim's `ip`).",
        TextObjectSpec {
            apply: Arc::new(text_object_inner_paragraph),
            args_schema: vec![],
        },
    );
    let around_paragraph = registry.register_text_object(
        "text-object:around-paragraph",
        "Around paragraph -- inner_paragraph plus trailing blank lines (vim's `ap`).",
        TextObjectSpec {
            apply: Arc::new(text_object_around_paragraph),
            args_schema: vec![],
        },
    );

    let inner_word = registry.register_text_object(
        "text-object:inner-word",
        "Inner word -- alphanum + underscore run containing the cursor (vim's `iw`).",
        TextObjectSpec {
            apply: Arc::new(text_object_inner_word),
            args_schema: vec![],
        },
    );
    let around_word = registry.register_text_object(
        "text-object:around-word",
        "Around word -- inner_word plus trailing whitespace (vim's `aw`).",
        TextObjectSpec {
            apply: Arc::new(text_object_around_word),
            args_schema: vec![],
        },
    );
    let inner_quote_double = registry.register_text_object(
        "text-object:inner-quote-double",
        "Inner double-quoted string -- text between the surrounding `\"` chars (vim's `i\"`).",
        TextObjectSpec {
            apply: Arc::new(|ctx| text_object_inner_quote(ctx, '"')),
            args_schema: vec![],
        },
    );
    let around_quote_double = registry.register_text_object(
        "text-object:around-quote-double",
        "Around double-quoted string -- includes the surrounding `\"` chars (vim's `a\"`).",
        TextObjectSpec {
            apply: Arc::new(|ctx| text_object_around_quote(ctx, '"')),
            args_schema: vec![],
        },
    );
    let inner_quote_single = registry.register_text_object(
        "text-object:inner-quote-single",
        "Inner single-quoted string (vim's `i'`).",
        TextObjectSpec {
            apply: Arc::new(|ctx| text_object_inner_quote(ctx, '\'')),
            args_schema: vec![],
        },
    );
    let around_quote_single = registry.register_text_object(
        "text-object:around-quote-single",
        "Around single-quoted string (vim's `a'`).",
        TextObjectSpec {
            apply: Arc::new(|ctx| text_object_around_quote(ctx, '\'')),
            args_schema: vec![],
        },
    );
    let inner_quote_backtick = registry.register_text_object(
        "text-object:inner-quote-backtick",
        "Inner backtick-quoted string (vim's ``i` ``).",
        TextObjectSpec {
            apply: Arc::new(|ctx| text_object_inner_quote(ctx, '`')),
            args_schema: vec![],
        },
    );
    let around_quote_backtick = registry.register_text_object(
        "text-object:around-quote-backtick",
        "Around backtick-quoted string (vim's ``a` ``).",
        TextObjectSpec {
            apply: Arc::new(|ctx| text_object_around_quote(ctx, '`')),
            args_schema: vec![],
        },
    );
    let inner_paren = registry.register_text_object(
        "text-object:inner-paren",
        "Inside the innermost enclosing `()` pair (vim's `i(`).",
        TextObjectSpec {
            apply: Arc::new(|ctx| text_object_inner_brackets(ctx, '(', ')')),
            args_schema: vec![],
        },
    );
    let around_paren = registry.register_text_object(
        "text-object:around-paren",
        "Around the innermost enclosing `()` pair, including the brackets (vim's `a(`).",
        TextObjectSpec {
            apply: Arc::new(|ctx| text_object_around_brackets(ctx, '(', ')')),
            args_schema: vec![],
        },
    );
    let inner_bracket = registry.register_text_object(
        "text-object:inner-bracket",
        "Inside the innermost enclosing `[]` pair (vim's `i[`).",
        TextObjectSpec {
            apply: Arc::new(|ctx| text_object_inner_brackets(ctx, '[', ']')),
            args_schema: vec![],
        },
    );
    let around_bracket = registry.register_text_object(
        "text-object:around-bracket",
        "Around the innermost enclosing `[]` pair, including the brackets (vim's `a[`).",
        TextObjectSpec {
            apply: Arc::new(|ctx| text_object_around_brackets(ctx, '[', ']')),
            args_schema: vec![],
        },
    );
    let inner_tag = registry.register_text_object(
        "text-object:inner-tag",
        "Inside the innermost enclosing XML/HTML tag pair (vim's `it`).",
        TextObjectSpec {
            apply: Arc::new(text_object_inner_tag),
            args_schema: vec![],
        },
    );
    let around_tag = registry.register_text_object(
        "text-object:around-tag",
        "Around the innermost enclosing XML/HTML tag pair, including the tags (vim's `at`).",
        TextObjectSpec {
            apply: Arc::new(text_object_around_tag),
            args_schema: vec![],
        },
    );

    let inner_brace = registry.register_text_object(
        "text-object:inner-brace",
        "Inside the innermost enclosing `{}` pair (vim's `i{`).",
        TextObjectSpec {
            apply: Arc::new(|ctx| text_object_inner_brackets(ctx, '{', '}')),
            args_schema: vec![],
        },
    );
    let around_brace = registry.register_text_object(
        "text-object:around-brace",
        "Around the innermost enclosing `{}` pair, including the brackets (vim's `a{`).",
        TextObjectSpec {
            apply: Arc::new(|ctx| text_object_around_brackets(ctx, '{', '}')),
            args_schema: vec![],
        },
    );
    let inner_big_word = registry.register_text_object(
        "text-object:inner-big-word",
        "Inner WORD -- whitespace-delimited run containing the cursor (vim's `iW`).",
        TextObjectSpec {
            apply: Arc::new(text_object_inner_big_word),
            args_schema: vec![],
        },
    );
    let around_big_word = registry.register_text_object(
        "text-object:around-big-word",
        "Around WORD -- inner WORD plus trailing whitespace (vim's `aW`).",
        TextObjectSpec {
            apply: Arc::new(text_object_around_big_word),
            args_schema: vec![],
        },
    );
    let inner_angle = registry.register_text_object(
        "text-object:inner-angle",
        "Inside the innermost enclosing `<>` pair (vim's `i<`).",
        TextObjectSpec {
            apply: Arc::new(|ctx| text_object_inner_brackets(ctx, '<', '>')),
            args_schema: vec![],
        },
    );
    let around_angle = registry.register_text_object(
        "text-object:around-angle",
        "Around the innermost enclosing `<>` pair, including the brackets (vim's `a<`).",
        TextObjectSpec {
            apply: Arc::new(|ctx| text_object_around_brackets(ctx, '<', '>')),
            args_schema: vec![],
        },
    );

    // N.1.6: comment text objects (commentstring-driven; the leader is
    // injected per-buffer via `TextObjectContext.comment_syntax`).
    let inner_comment = registry.register_text_object(
        "text-object:inner-comment",
        "Inner comment -- the comment text with the first line's leader stripped (`iC`).",
        TextObjectSpec {
            apply: Arc::new(text_object_inner_comment),
            args_schema: vec![],
        },
    );
    let around_comment = registry.register_text_object(
        "text-object:around-comment",
        "A comment -- the contiguous run of comment lines including the markers (`aC`).",
        TextObjectSpec {
            apply: Arc::new(text_object_around_comment),
            args_schema: vec![],
        },
    );

    let find_repeat = registry.register_motion(
        "motion:find-repeat",
        "Repeat the last `f` / `F` / `t` / `T` in the same direction (vim's `;`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            // Not a jump: vim does not put `;` on the jump list, and it
            // usually moves only a few columns.
            jump: false,
            // Never read: `motion_find_repeat` always sets
            // `MotionResult::exclusive`, because the honest answer depends on
            // which of `f` / `F` / `t` / `T` is being repeated. Kept
            // `false` so `:describe-command` shows the common case (`;` after
            // an `f`) rather than a coin-flip.
            exclusive: false,
            apply: Arc::new(motion_find_repeat),
            args_schema: vec![],
        },
    );
    let find_repeat_reverse = registry.register_motion(
        "motion:find-repeat-reverse",
        "Repeat the last `f` / `F` / `t` / `T` in the opposite direction (vim's `,`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            exclusive: false,
            apply: Arc::new(motion_find_repeat_reverse),
            args_schema: vec![],
        },
    );

    let match_pair = registry.register_motion(
        "motion:match-pair",
        "Move to the bracket matching the first one at or after the cursor on this line (vim's `%`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            // A jump: vim records `%` on the jump list and opens a fold at the
            // far end (`foldopen` ships with `percent`).
            jump: true,
            // INCLUSIVE. `d%` deletes both brackets and everything between —
            // the defining behaviour, and the reason `exclusive: false` here is
            // load-bearing rather than a default.
            exclusive: false,
            apply: Arc::new(motion_match_pair),
            args_schema: vec![],
        },
    );
    // VM.3i: vim's `zj` / `zk`. Charwise and exclusive (vim 9.2: `dzk` from
    // 12,3 deletes "line 10\nline 11\nli"), not jumps, and "can be used after
    // an operator". They were host actions, so `dzj` and `vzj` were unbound.
    let goto_next_fold = registry.register_motion(
        "motion:goto-next-fold",
        "Move to the start of the next fold; a closed fold counts as one (vim's `zj`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            exclusive: true,
            apply: Arc::new(motion_goto_next_fold),
            args_schema: vec![],
        },
    );
    let goto_prev_fold = registry.register_motion(
        "motion:goto-prev-fold",
        "Move to the end of the previous fold; a closed fold counts as one (vim's `zk`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            exclusive: true,
            apply: Arc::new(motion_goto_prev_fold),
            args_schema: vec![],
        },
    );
    // VM.3d-2: vim's `n` / `N` / `*` / `#`. Charwise and exclusive (vim 9.2:
    // `dn` from 1,1 deletes `alpha `), and jumps. `*` / `#` repeat the search
    // exactly as `n` does: the host records the word under the cursor as the
    // search before the motion runs (`Editor::capture_search_word`), so there's
    // one word rule, not two. They were host actions, so `dn` / `vn` / `d*`
    // were unbound.
    let search_spec =
        |apply: fn(&MotionContext) -> Result<MotionResult, CommandError>| MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: true,
            exclusive: true,
            apply: Arc::new(apply),
            args_schema: vec![],
        };
    let search_next = registry.register_motion(
        "motion:search-next",
        "Repeat the last search in its own direction (vim's `n`).",
        search_spec(motion_search_next),
    );
    let search_prev = registry.register_motion(
        "motion:search-prev",
        "Repeat the last search in the opposite direction (vim's `N`).",
        search_spec(motion_search_prev),
    );
    let search_word_forward = registry.register_motion(
        "motion:search-word-forward",
        "Search forward for the word under the cursor (vim's `*`).",
        search_spec(motion_search_next),
    );
    let search_word_backward = registry.register_motion(
        "motion:search-word-backward",
        "Search backward for the word under the cursor (vim's `#`).",
        search_spec(motion_search_next),
    );
    // VM.3d-3: `g*` / `g#` — the same search without `\<` / `\>`, so it finds
    // the word inside longer ones (`g*` on `foo` hits `foobar`). Separate
    // motions rather than an argument because the PATTERN differs, and the
    // pattern is what the host builds before the motion runs.
    let search_word_forward_partial = registry.register_motion(
        "motion:search-word-forward-partial",
        "Search forward for the word under the cursor, not only whole words (vim's `g*`).",
        search_spec(motion_search_next),
    );
    let search_word_backward_partial = registry.register_motion(
        "motion:search-word-backward-partial",
        "Search backward for the word under the cursor, not only whole words (vim's `g#`).",
        search_spec(motion_search_next),
    );
    // VM.3e: vim's `'x` / `` `x ``, which were actions, so `d'a` / `v`a` were
    // unbound. `'x` is linewise and lands on the mark line's first non-blank;
    // `` `x `` is charwise and exclusive (vim 9.2: `d'a` deletes whole lines,
    // `` d`a `` stops before the mark). Both jump. The mark name arrives as
    // `Args::Char`, captured by the keymap's `{char}` wildcard as `f`'s is.
    // VM.3g-2: vim's `gj` / `gk` / `g0` / `g$`. They were host ACTIONS, so
    // `dgj`, `yg$` and `vgj` were unbound; vim composes all of them. `gj` / `gk`
    // keep the shared goal column (vim gives `j` and `gj` the same one); `g$` is
    // INCLUSIVE, the others exclusive; none is a jump.
    let display_line_down = registry.register_motion(
        "motion:display-line-down",
        "Move one display row down, keeping the screen column (vim's `gj`).",
        MotionSpec {
            jump: false,
            exclusive: true,
            // Measured in vim 9.2 (`vimcheck_gj_curswant.vim`): `gj` SETS the
            // goal from where it lands — 2,5 → 2,85 records 85, and crossing to
            // the next line records the column there — unlike `j`, which keeps
            // its goal across a short line. The asymmetry is real: `gj` recomputes
            // the virtual column for the row it reached.
            curswant: crate::registry::CurswantEffect::default(),
            apply: Arc::new(motion_display_line_down),
            args_schema: vec![],
        },
    );
    let display_line_up = registry.register_motion(
        "motion:display-line-up",
        "Move one display row up, keeping the screen column (vim's `gk`).",
        MotionSpec {
            jump: false,
            exclusive: true,
            // As `gj` above: vim records the landing column (`gk` from 2,165 →
            // 2,85 records 85).
            curswant: crate::registry::CurswantEffect::default(),
            apply: Arc::new(motion_display_line_up),
            args_schema: vec![],
        },
    );
    let display_line_start = registry.register_motion(
        "motion:display-line-start",
        "Move to the first column of the display row (vim's `g0`).",
        MotionSpec {
            jump: false,
            exclusive: true,
            curswant: crate::registry::CurswantEffect::default(),
            apply: Arc::new(motion_display_line_start),
            args_schema: vec![],
        },
    );
    let display_line_end = registry.register_motion(
        "motion:display-line-end",
        "Move to the last column of the display row (vim's `g$`).",
        MotionSpec {
            jump: false,
            exclusive: false,
            curswant: crate::registry::CurswantEffect::default(),
            apply: Arc::new(motion_display_line_end),
            args_schema: vec![],
        },
    );
    let mark_line = registry.register_motion(
        "motion:mark-line",
        "Go to the first non-blank of the line of mark `args.char` (vim's `'`).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: true,
            exclusive: false,
            apply: Arc::new(motion_mark_line),
            args_schema: vec![],
        },
    );
    let mark_exact = registry.register_motion(
        "motion:mark-exact",
        "Go to the exact position of mark `args.char` (vim's `` ` ``).",
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: true,
            exclusive: true,
            apply: Arc::new(motion_mark_exact),
            args_schema: vec![],
        },
    );
    // VM.3f: vim's `H` / `M` / `L`, which were actions, so `dL` / `yH` / `vM`
    // were unbound. Linewise jumps (vim 9.2: `dL` deletes whole lines to the
    // bottom of the window).
    let viewport_spec =
        |apply: fn(&MotionContext) -> Result<MotionResult, CommandError>| MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: true,
            exclusive: false,
            apply: Arc::new(apply),
            args_schema: vec![],
        };
    let viewport_top = registry.register_motion(
        "motion:viewport-top",
        "Go to the `count`-th line from the top of the window (vim's `H`).",
        viewport_spec(motion_viewport_top),
    );
    let viewport_middle = registry.register_motion(
        "motion:viewport-middle",
        "Go to the middle line of the window (vim's `M`).",
        viewport_spec(motion_viewport_middle),
    );
    let viewport_bottom = registry.register_motion(
        "motion:viewport-bottom",
        "Go to the `count`-th line from the bottom of the window (vim's `L`).",
        viewport_spec(motion_viewport_bottom),
    );

    Builtins {
        word_forward,
        word_backward,
        word_end,
        first_non_blank,
        find_char_forward,
        find_char_backward,
        till_char_forward,
        till_char_backward,
        big_word_forward,
        big_word_backward,
        big_word_end,
        paragraph_forward,
        paragraph_backward,
        sentence_forward,
        sentence_backward,
        char_left,
        char_right,
        line_up,
        line_down,
        line_start,
        line_end,
        goto_first_line,
        goto_last_line,
        find_repeat,
        find_repeat_reverse,
        match_pair,
        goto_next_fold,
        goto_prev_fold,
        search_next,
        search_prev,
        search_word_forward,
        search_word_backward,
        search_word_forward_partial,
        search_word_backward_partial,
        mark_line,
        display_line_down,
        display_line_up,
        display_line_start,
        display_line_end,
        mark_exact,
        viewport_top,
        viewport_middle,
        viewport_bottom,
        delete,
        change,
        yank,
        indent_left,
        reindent,
        reflow,
        reformat,
        create_fold,
        indent_right,
        upper,
        lower,
        toggle_case,
        search,
        replace_char,
        inner_paragraph,
        around_paragraph,
        inner_sentence,
        around_sentence,
        inner_word,
        around_word,
        inner_quote_double,
        around_quote_double,
        inner_quote_single,
        around_quote_single,
        inner_quote_backtick,
        around_quote_backtick,
        inner_paren,
        around_paren,
        inner_bracket,
        around_bracket,
        inner_brace,
        around_brace,
        inner_tag,
        around_tag,
        inner_big_word,
        around_big_word,
        inner_angle,
        around_angle,
        inner_comment,
        around_comment,
    }
}

/// The ids of every native built-in, as returned by [`populate`].
///
/// A typed shortcut for callers that hold the populated registry and need a
/// specific builtin without a name lookup (the keystroke parser, the
/// host's keymap wiring, tests, benches). Every field is also reachable by
/// its registered name through [`CommandRegistry::id_by_name`]; the doc on
/// each field gives that name and the vim key it implements. `Default`
/// yields placeholder ids that name nothing, for code that needs a value
/// before the registry is populated.
#[derive(Debug, Clone, Copy, Default)]
pub struct Builtins {
    /// `motion:word-forward` — vim's `w`: start of the next word (3-way word/punct/blank classes). Exclusive; tagged word-forward so `dw` / `cw` stop at the line end.
    pub word_forward: MotionId,
    /// `motion:word-backward` — vim's `b`: start of the previous word.
    pub word_backward: MotionId,
    /// `motion:word-end` — vim's `e`: last byte of the current or next word. Inclusive.
    pub word_end: MotionId,
    /// `motion:first-non-blank` — vim's `^`: first non-blank byte of the line. Exclusive.
    pub first_non_blank: MotionId,
    /// `motion:find-char-forward` — vim's `f{char}`: next `args.char` on the line, landing on it. Inclusive.
    pub find_char_forward: MotionId,
    /// `motion:find-char-backward` — vim's `F{char}`: previous `args.char` on the line, landing on it.
    pub find_char_backward: MotionId,
    /// `motion:till-char-forward` — vim's `t{char}`: one byte before the next `args.char` on the line.
    pub till_char_forward: MotionId,
    /// `motion:till-char-backward` — vim's `T{char}`: one byte after the previous `args.char` on the line.
    pub till_char_backward: MotionId,
    /// `motion:big-word-forward` — vim's `W`: start of the next whitespace-delimited WORD. Tagged word-forward, like `w`.
    pub big_word_forward: MotionId,
    /// `motion:big-word-backward` — vim's `B`: start of the previous WORD.
    pub big_word_backward: MotionId,
    /// `motion:big-word-end` — vim's `E`: last byte of the current or next WORD.
    pub big_word_end: MotionId,
    /// `motion:paragraph-forward` — vim's `}`: the next blank line (paragraph boundary). A jump.
    pub paragraph_forward: MotionId,
    /// `motion:paragraph-backward` — vim's `{`: the previous paragraph boundary. A jump.
    pub paragraph_backward: MotionId,
    /// `motion:sentence-forward` — vim's `)`: start of the next sentence. A jump.
    pub sentence_forward: MotionId,
    /// `motion:sentence-backward` — vim's `(`: start of the previous sentence. A jump.
    pub sentence_backward: MotionId,
    /// `motion:char-left` — vim's `h`: one character left, within the line (steps whole UTF-8 scalars).
    pub char_left: MotionId,
    /// `motion:char-right` — vim's `l`: one character right, within the line.
    pub char_right: MotionId,
    /// `motion:line-up` — vim's `k`: one line up, aiming at the goal column (keeps `curswant`).
    pub line_up: MotionId,
    /// `motion:line-down` — vim's `j`: one line down, aiming at the goal column (keeps `curswant`).
    pub line_down: MotionId,
    /// `motion:line-start` — vim's `0`: first byte of the line. Exclusive.
    pub line_start: MotionId,
    /// `motion:line-end` — vim's `$`: end of the line; pins the goal column to end-of-line.
    pub line_end: MotionId,
    /// `motion:goto-first-line` — vim's `gg` (`{count}gg` goes to that line). Linewise jump.
    pub goto_first_line: MotionId,
    /// `motion:goto-last-line` — vim's `G` (`{count}G` goes to that line). Linewise jump.
    pub goto_last_line: MotionId,
    /// VM.3c: vim's `;` and `,` — repeat the last `f` / `F` / `t` / `T` in
    /// the same or the opposite direction. Motions for the same reason `%` is:
    /// vim composes them (`d;`) and extends a selection with them.
    pub find_repeat: MotionId,
    /// `motion:find-repeat-reverse` — vim's `,`: the last find, reversed (see [`FindKind::reversed`](crate::FindKind::reversed)).
    pub find_repeat_reverse: MotionId,
    /// VM.3b: vim's `%`. A MOTION, not an action — vim composes it
    /// (`d%` deletes a bracketed span, `v%` selects one), and it took being
    /// typed as an action for `d%` and `v%` to be silently unbound here.
    pub match_pair: MotionId,
    /// VM.3i: vim's `zj` / `zk`, as the motions they are in vim.
    pub goto_next_fold: MotionId,
    /// `motion:goto-prev-fold` — vim's `zk`: end of the previous fold.
    pub goto_prev_fold: MotionId,
    /// VM.3d-2: vim's `n` / `N` / `*` / `#`, as the motions they are in vim.
    pub search_next: MotionId,
    /// `motion:search-prev` — vim's `N`: repeat the last search in the opposite direction.
    pub search_prev: MotionId,
    /// `motion:search-word-forward` — vim's `*`: search forward for the whole word under the cursor.
    pub search_word_forward: MotionId,
    /// `motion:search-word-backward` — vim's `#`: search backward for the whole word under the cursor.
    pub search_word_backward: MotionId,
    /// VM.3d-3: vim's `g*` / `g#` — the word under the cursor, matched
    /// anywhere rather than only as a whole word.
    pub search_word_forward_partial: MotionId,
    /// `motion:search-word-backward-partial` — vim's `g#`: `#` without the whole-word boundaries.
    pub search_word_backward_partial: MotionId,
    /// VM.3e: vim's `'x` / `` `x ``, as the motions they are in vim.
    pub mark_line: MotionId,
    /// VM.3g-2: vim's `gj` / `gk` / `g0` / `g$`, as the motions they are.
    pub display_line_down: MotionId,
    /// `motion:display-line-up` — vim's `gk`: one display row up, keeping the screen column.
    pub display_line_up: MotionId,
    /// `motion:display-line-start` — vim's `g0`: first column of the display row.
    pub display_line_start: MotionId,
    /// `motion:display-line-end` — vim's `g$`: last column of the display row.
    pub display_line_end: MotionId,
    /// `motion:mark-exact` — vim's `` `x ``: the exact position of mark `args.char`.
    pub mark_exact: MotionId,
    /// VM.3f: vim's `H` / `M` / `L`, as the motions they are in vim.
    pub viewport_top: MotionId,
    /// `motion:viewport-middle` — vim's `M`: the middle of the lines shown.
    pub viewport_middle: MotionId,
    /// `motion:viewport-bottom` — vim's `L`: the `count`-th line from the bottom of the window.
    pub viewport_bottom: MotionId,
    /// `operator:delete` — vim's `d`: delete the range and yank it (unnamed register, or `"x`).
    pub delete: OperatorId,
    /// `operator:change` — vim's `c`: delete the range and enter Insert mode.
    pub change: OperatorId,
    /// `operator:yank` — vim's `y`: copy the range into the register without editing.
    pub yank: OperatorId,
    /// `operator:indent-left` — vim's `<`: remove one indent unit (`shiftwidth` / `expandtab`, resolved by the host into [`OperatorContext::indent`](crate::OperatorContext::indent)) from each non-blank line.
    pub indent_left: OperatorId,
    /// `operator:indent-right` — vim's `>`: add one indent unit to each non-blank line.
    pub indent_right: OperatorId,
    /// IN.7: vim's `=` — reindent, leading whitespace only.
    pub reindent: OperatorId,
    /// RF.2: vim's `gq` and `gw` — reflow to `textwidth`. ONE operator
    /// behind both chords; they differ only in cursor placement in vim,
    /// and this preserves the cursor (`gw`'s behaviour).
    pub reflow: OperatorId,
    /// RF.6: `g=` — the operator form of `:format`. Not a vim chord;
    /// see `operator_reformat` for why it exists.
    pub reformat: OperatorId,
    /// VM.3h: vim's `zf`, as the operator it is in vim.
    pub create_fold: OperatorId,
    /// `operator:upper` — vim's `gU`: uppercase ASCII letters in the range.
    pub upper: OperatorId,
    /// `operator:lower` — vim's `gu`: lowercase ASCII letters in the range.
    pub lower: OperatorId,
    /// `operator:toggle-case` — vim's `g~`: toggle the case of ASCII letters in the range.
    pub toggle_case: OperatorId,
    /// `operator:search` — `g/` (a Lattice extension, not vim): project-search for the spanned text; emits the same `SearchTrigger` as `:search`.
    pub search: OperatorId,
    /// `operator:replace-char` — vim's `r{char}` / Visual `r`: overwrite each non-newline character in the range with `args.char`.
    pub replace_char: OperatorId,
    /// `text-object:inner-paragraph` — vim's `ip`: the run of non-blank lines around the cursor.
    pub inner_paragraph: TextObjectId,
    /// `text-object:around-paragraph` — vim's `ap`: `ip` plus trailing blank lines.
    pub around_paragraph: TextObjectId,
    /// `text-object:inner-sentence` — vim's `is`: the sentence around the cursor.
    pub inner_sentence: TextObjectId,
    /// `text-object:around-sentence` — vim's `as`: `is` plus trailing whitespace.
    pub around_sentence: TextObjectId,
    /// `text-object:inner-word` — vim's `iw`: the word around the cursor.
    pub inner_word: TextObjectId,
    /// `text-object:around-word` — vim's `aw`: `iw` plus trailing whitespace.
    pub around_word: TextObjectId,
    /// `text-object:inner-quote-double` — vim's `i"`: inside the surrounding double quotes.
    pub inner_quote_double: TextObjectId,
    /// `text-object:around-quote-double` — vim's `a"`: `i"` including the quotes.
    pub around_quote_double: TextObjectId,
    /// `text-object:inner-quote-single` — vim's `i'`: inside the surrounding single quotes.
    pub inner_quote_single: TextObjectId,
    /// `text-object:around-quote-single` — vim's `a'`: `i'` including the quotes.
    pub around_quote_single: TextObjectId,
    /// `text-object:inner-quote-backtick` — vim's ``i` ``: inside the surrounding backticks.
    pub inner_quote_backtick: TextObjectId,
    /// `text-object:around-quote-backtick` — vim's ``a` ``: ``i` `` including the backticks.
    pub around_quote_backtick: TextObjectId,
    /// `text-object:inner-paren` — vim's `i(`: inside the innermost enclosing `()`.
    pub inner_paren: TextObjectId,
    /// `text-object:around-paren` — vim's `a(`: `i(` including the parentheses.
    pub around_paren: TextObjectId,
    /// `text-object:inner-bracket` — vim's `i[`: inside the innermost enclosing `[]`.
    pub inner_bracket: TextObjectId,
    /// `text-object:around-bracket` — vim's `a[`: `i[` including the brackets.
    pub around_bracket: TextObjectId,
    /// `text-object:inner-brace` — vim's `i{`: inside the innermost enclosing `{}`.
    pub inner_brace: TextObjectId,
    /// `text-object:around-brace` — vim's `a{`: `i{` including the braces.
    pub around_brace: TextObjectId,
    /// `text-object:inner-tag` — vim's `it`: inside the innermost enclosing XML/HTML tag pair.
    pub inner_tag: TextObjectId,
    /// `text-object:around-tag` — vim's `at`: `it` including the tags.
    pub around_tag: TextObjectId,
    /// `text-object:inner-big-word` — vim's `iW`: the WORD around the cursor.
    pub inner_big_word: TextObjectId,
    /// `text-object:around-big-word` — vim's `aW`: `iW` plus trailing whitespace.
    pub around_big_word: TextObjectId,
    /// `text-object:inner-angle` — vim's `i<`: inside the innermost enclosing `<>`.
    pub inner_angle: TextObjectId,
    /// `text-object:around-angle` — vim's `a<`: `i<` including the angle brackets.
    pub around_angle: TextObjectId,
    /// `text-object:inner-comment` — `iC` (Lattice): the comment text, first line's leader stripped. Needs [`CommentSyntax`](crate::CommentSyntax) from the host.
    pub inner_comment: TextObjectId,
    /// `text-object:around-comment` — `aC` (Lattice): the contiguous run of comment lines, markers included.
    pub around_comment: TextObjectId,
}

// ---- Motion: word-forward ----

fn motion_word_forward(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    // Advance `count` words using vim's 3-way class model ([`word_class`]):
    // skip the rest of the cursor's current word (its non-blank class run),
    // then skip blanks to the next word/punct start. So `foo.bar` from `f`
    // stops on `.` (a punctuation word), not `bar`. Newlines are blanks, so
    // this crosses lines onto the first word of the next line.
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let total = bytes.len();
    let count = ctx.count.get().max(1);
    let mut idx = ctx
        .buffer
        .position_to_byte(ctx.from)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;

    for _ in 0..count {
        if idx >= total {
            break;
        }
        // Skip the rest of the current word: the run of the cursor's class,
        // unless the cursor already sits on a blank (nothing to skip here).
        let start_class = word_class(bytes[idx]);
        if start_class != WordClass::Blank {
            while idx < total && word_class(bytes[idx]) == start_class {
                idx += 1;
            }
        }
        // Skip blanks (whitespace / newlines) to the next word start.
        while idx < total && word_class(bytes[idx]) == WordClass::Blank {
            idx += 1;
        }
    }

    // At/after EOF, clamp to the end-of-buffer position (vim `w` at the last
    // word lands past the final char; `dw` then deletes through the end).
    let target = ctx
        .buffer
        .byte_to_position(idx.min(total))
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;

    Ok(MotionResult {
        curswant: None,
        target,
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

fn is_word_byte(b: u8) -> bool {
    b.is_ascii_alphanumeric() || b == b'_'
}

fn is_blank_byte(b: u8) -> bool {
    b == b' ' || b == b'\t'
}

/// "WORD" boundary in vim: any non-whitespace run is a WORD; whitespace
/// (incl. newline) separates WORDs.
fn is_big_word_byte(b: u8) -> bool {
    !b.is_ascii_whitespace()
}

/// Vim's **3-way** word classification, the boundary model for `w` / `b` /
/// `e`. A "word" is a maximal run of ONE non-blank class, so `foo.bar` is
/// three words — `foo` (Word), `.` (Punct), `bar` (Word) — and a bare `w`
/// stops on the `.` rather than skipping it. Blanks (whitespace incl.
/// newline) separate words. This is distinct from the 2-way "WORD" model
/// (`is_big_word_byte`) that `W` / `B` / `E` use.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum WordClass {
    Blank,
    Word,
    Punct,
}

fn word_class(b: u8) -> WordClass {
    if is_word_byte(b) {
        WordClass::Word
    } else if b.is_ascii_whitespace() {
        WordClass::Blank
    } else {
        WordClass::Punct
    }
}

/// The 2-way "WORD" classification for `W` / `B` / `E` and `iW` / `aW`: a
/// maximal non-whitespace run is one WORD (punctuation folds in), whitespace
/// separates them. Reuses [`WordClass`] with every non-blank byte as `Word`
/// so punctuation never splits a WORD.
fn big_word_class(b: u8) -> WordClass {
    if b.is_ascii_whitespace() {
        WordClass::Blank
    } else {
        WordClass::Word
    }
}

// ---- Motion: word-backward (vim's `b`) ----

fn motion_word_backward(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let count = ctx.count.get().max(1);
    let mut idx = ctx
        .buffer
        .position_to_byte(ctx.from)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;

    for _ in 0..count {
        if idx == 0 {
            break;
        }
        // Step one byte back, skip blanks (whitespace / newlines), then walk
        // back to the start of that word — the run of ONE non-blank class
        // ([`word_class`]), so `b` lands on a punctuation run rather than
        // skipping it.
        idx -= 1;
        while idx > 0 && word_class(bytes[idx]) == WordClass::Blank {
            idx -= 1;
        }
        let c = word_class(bytes[idx]);
        while idx > 0 && word_class(bytes[idx - 1]) == c {
            idx -= 1;
        }
    }

    let target = ctx
        .buffer
        .byte_to_position(idx)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    Ok(MotionResult {
        curswant: None,
        target,
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

// ---- Motion: word-end (vim's `e`) ----

fn motion_word_end(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let total = bytes.len();
    let count = ctx.count.get().max(1);
    let mut idx = ctx
        .buffer
        .position_to_byte(ctx.from)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;

    for _ in 0..count {
        if idx >= total.saturating_sub(1) {
            break;
        }
        // Step one byte forward, skip blanks, then advance to the last byte
        // of that word — the run of ONE non-blank class ([`word_class`]), so
        // `e` stops at the end of a punctuation run rather than skipping it.
        idx += 1;
        while idx < total && word_class(bytes[idx]) == WordClass::Blank {
            idx += 1;
        }
        if idx >= total {
            idx = total.saturating_sub(1);
            break;
        }
        let c = word_class(bytes[idx]);
        while idx + 1 < total && word_class(bytes[idx + 1]) == c {
            idx += 1;
        }
    }

    let target = ctx
        .buffer
        .byte_to_position(idx)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    Ok(MotionResult {
        curswant: None,
        target,
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

// ---- Paragraph motions (vim's `}`, `{`) ----
//
// A paragraph is a maximal run of non-blank lines. `}` lands on the
// next blank line at or after `cursor.line + 1`; `{` lands on the
// previous blank line. If no boundary exists, lands at end / start of
// buffer respectively.

fn line_is_blank(text: &str, line: u32) -> bool {
    text.split_inclusive('\n')
        .nth(line as usize)
        .map(|l| l.trim_end_matches('\n').trim().is_empty())
        .unwrap_or(true)
}

fn buffer_last_line(text: &str) -> u32 {
    let lc = text.split_inclusive('\n').count() as u32;
    if text.ends_with('\n') {
        lc.saturating_sub(2)
    } else {
        lc.saturating_sub(1)
    }
}

/// Vim's `%` — from the cursor, find the first bracket at or after it **on
/// this line**, then jump to its partner.
///
/// Two details that look like implementation choices and are actually vim's
/// semantics:
///
/// - The search for the *starting* bracket stops at the newline. `%` on a line
///   with no bracket does nothing; it does not go hunting down the buffer.
/// - Nesting is counted, not pattern-matched, so the partner of the outer `(`
///   in `(a(b)c)` is the last `)`, not the first.
///
/// Byte-indexed on the raw bytes: every bracket is ASCII, and a multi-byte
/// char cannot contain a byte that equals one, so scanning bytes can neither
/// miss a bracket nor invent one inside a UTF-8 sequence.
///
/// Finding nothing returns the cursor unmoved rather than an error — vim
/// beeps and stays put, and a `%` that failed should not make `d%` delete
/// something surprising.
fn motion_match_pair(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let unmoved = Ok(MotionResult {
        curswant: None,
        target: ctx.from,
        linewise: false,
        exclusive: None,
        notice: None,
    });
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let Ok(cursor_byte) = ctx.buffer.position_to_byte(ctx.from) else {
        return unmoved;
    };

    // The starting bracket: first one at or after the cursor, same line.
    let mut idx = cursor_byte;
    let mut found = None;
    while idx < bytes.len() && bytes[idx] != b'\n' {
        if matches!(bytes[idx], b'(' | b')' | b'[' | b']' | b'{' | b'}') {
            found = Some((idx, bytes[idx]));
            break;
        }
        idx += 1;
    }
    let Some((start, b)) = found else {
        return unmoved;
    };
    let (open, close, forward) = match b {
        b'(' => (b'(', b')', true),
        b')' => (b'(', b')', false),
        b'[' => (b'[', b']', true),
        b']' => (b'[', b']', false),
        b'{' => (b'{', b'}', true),
        b'}' => (b'{', b'}', false),
        _ => return unmoved,
    };

    let target = if forward {
        scan_forward_for_match(bytes, start, open, close)
    } else {
        scan_backward_for_match(bytes, start, open, close)
    };
    match target.and_then(|t| ctx.buffer.byte_to_position(t).ok()) {
        Some(pos) => Ok(MotionResult {
            curswant: None,
            target: pos,
            linewise: false,
            exclusive: None,
            notice: None,
        }),
        None => unmoved,
    }
}

/// Walk forward from an opening bracket to its partner, counting nesting.
/// `from` must index the opening bracket itself, so depth starts at 1 on the
/// first iteration and the partner is where it returns to 0.
fn scan_forward_for_match(bytes: &[u8], from: usize, open: u8, close: u8) -> Option<usize> {
    let mut depth = 0i32;
    let mut i = from;
    loop {
        if i >= bytes.len() {
            return None;
        }
        let b = bytes[i];
        if b == open {
            depth += 1;
        } else if b == close {
            depth -= 1;
            if depth == 0 {
                return Some(i);
            }
        }
        i += 1;
    }
}

/// The backward peer. Walks down to index 0 and checks `i == 0` before
/// decrementing, because `usize` has no -1 to detect the end with.
fn scan_backward_for_match(bytes: &[u8], from: usize, open: u8, close: u8) -> Option<usize> {
    let mut depth = 0i32;
    let mut i = from;
    loop {
        let b = bytes[i];
        if b == close {
            depth += 1;
        } else if b == open {
            depth -= 1;
            if depth == 0 {
                return Some(i);
            }
        }
        if i == 0 {
            return None;
        }
        i -= 1;
    }
}

/// VM.3f: `H` / `M` / `L` — a line of the window, linewise. Where on it follows
/// `startofline`: the first non-blank (vim's default) or, with
/// `nostartofline`, the cursor's column clamped to the line. With no window the
/// motion fails and moves nothing.
fn motion_viewport(
    ctx: &MotionContext,
    pos: crate::app_effect::ViewportPos,
) -> Result<MotionResult, CommandError> {
    let viewport = ctx.viewport.ok_or(CommandError::MotionFailed)?;
    let line = viewport
        .viewport_line(pos, ctx.count.get())
        .ok_or(CommandError::MotionFailed)?;
    let line = scrolloff_adjusted(ctx, viewport, pos, line).min(last_addressable_line(ctx.buffer));
    Ok(MotionResult {
        curswant: None,
        // VM.3j-1: the same helper `gg` / `G` use — this was an inline copy.
        target: startofline_target(ctx, line),
        linewise: true,
        exclusive: None,
        notice: None,
    })
}

/// VM.3f: keep `H` / `L` `scrolloff` lines inside the window's edges.
///
/// Vim adjusts both "unless an operator is pending" (`:h H`), and it does NOT
/// adjust at a file edge: a window showing the first line leaves `H` on it, and
/// one showing the last leaves `L` there — the margin exists to keep context on
/// screen, and past the end of the file there is none to keep. `M` is never
/// adjusted.
///
/// Measured in vim 9.2 with an 11-line window over 100 lines, `50Gzz` (top 45,
/// bottom 55): `H` → 48 and `L` → 52 with `scrolloff=3`, 45 and 55 with `0`;
/// `gg`-then-`H` → 1 and `G`-then-`L` → 100; `dH` deletes from 45, unadjusted.
fn scrolloff_adjusted(
    ctx: &MotionContext,
    viewport: &dyn crate::registry::ViewportResolver,
    pos: crate::app_effect::ViewportPos,
    line: u32,
) -> u32 {
    use crate::app_effect::ViewportPos;
    if ctx.scrolloff == 0 || ctx.operator_pending {
        return line;
    }
    // The window's own edges, which is what the margin is measured from —
    // `viewport_line` with a count of 1 is exactly "the first / last line
    // shown", so no second resolver call shape is needed.
    match pos {
        ViewportPos::Top => match viewport.viewport_line(ViewportPos::Top, 1) {
            // At the top of the FILE there is nothing above to keep in view.
            Some(top) if top > 0 => line.max(top + ctx.scrolloff),
            _ => line,
        },
        ViewportPos::Bottom => match viewport.viewport_line(ViewportPos::Bottom, 1) {
            Some(bottom) if bottom < last_addressable_line(ctx.buffer) => {
                line.min(bottom.saturating_sub(ctx.scrolloff))
            }
            _ => line,
        },
        ViewportPos::Middle => line,
    }
}

fn motion_viewport_top(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    motion_viewport(ctx, crate::app_effect::ViewportPos::Top)
}

fn motion_viewport_middle(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    motion_viewport(ctx, crate::app_effect::ViewportPos::Middle)
}

fn motion_viewport_bottom(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    motion_viewport(ctx, crate::app_effect::ViewportPos::Bottom)
}

/// VM.3e: where mark `args.char` is, clamped into the buffer (a mark on a line
/// since deleted still resolves, as the host's jump always has). vim 9.2: an
/// unset mark is E20, and the motion failing cancels an operator it feeds.
fn mark_position(ctx: &MotionContext) -> Result<Position, CommandError> {
    let name = match &ctx.args {
        crate::args::Args::Char(c) if c.is_ascii_alphanumeric() => *c,
        crate::args::Args::Char(_) => {
            return Err(CommandError::User("E78: Unknown mark".to_string()));
        }
        _ => return Err(CommandError::InvalidArgs("'/` require Args::Char")),
    };
    let Some(pos) = ctx.marks.and_then(|marks| marks.mark(name)) else {
        return Err(CommandError::User("E20: Mark not set".to_string()));
    };
    let line = pos.line.min(last_addressable_line(ctx.buffer));
    Ok(Position::new(
        line,
        pos.byte.min(line_byte_len(ctx.buffer, line)),
    ))
}

/// VM.3e: `'x` — the first non-blank of the mark's line, linewise. A count is
/// ignored, as in vim (`3'a` is `'a`).
fn motion_mark_line(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let mark = mark_position(ctx)?;
    let line_text = ctx.buffer.line(mark.line).unwrap_or_default();
    let bytes = line_text.as_bytes();
    let mut col = 0usize;
    while col < bytes.len() && is_blank_byte(bytes[col]) {
        col += 1;
    }
    let col = (col as u32).min(line_byte_len(ctx.buffer, mark.line));
    Ok(MotionResult {
        curswant: None,
        target: Position::new(mark.line, col),
        linewise: true,
        exclusive: None,
        notice: None,
    })
}

/// VM.3e: `` `x `` — the mark's exact position, charwise and exclusive.
fn motion_mark_exact(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    Ok(MotionResult {
        curswant: None,
        target: mark_position(ctx)?,
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

/// VM.3d-2: `n` (`reverse = false`) / `N` — the last search again, `count`
/// times, from one character past the cursor so the match under it isn't found
/// again. vim's rules, checked in 9.2: the target is the match START (charwise,
/// exclusive), a search that wraps says so, and a pattern with no match fails
/// with E486, which cancels an operator (`dn` deletes nothing).
fn motion_search(ctx: &MotionContext, reverse: bool) -> Result<MotionResult, CommandError> {
    use crate::modal::SearchDirection;
    let Some(last) = ctx.last_search else {
        return Err(CommandError::User(
            "E35: no previous regular expression".to_string(),
        ));
    };
    let direction = match (last.direction, reverse) {
        (SearchDirection::Forward, false) | (SearchDirection::Backward, true) => {
            SearchDirection::Forward
        }
        (SearchDirection::Backward, false) | (SearchDirection::Forward, true) => {
            SearchDirection::Backward
        }
    };
    let regex = fancy_regex::Regex::new(&last.pattern)
        .map_err(|e| CommandError::User(format!("regex: {e}")))?;
    let core_direction = match direction {
        SearchDirection::Forward => lattice_core::search::Direction::Forward,
        SearchDirection::Backward => lattice_core::search::Direction::Backward,
    };
    let mut at = ctx.from;
    let mut wrapped = false;
    for _ in 0..ctx.count.get().max(1) {
        let from = step_for_search(ctx.buffer, at, direction);
        match lattice_core::search::find(ctx.buffer, &regex, from, core_direction, ctx.cancel)? {
            Some(hit) => {
                at = hit.range.start;
                wrapped |= hit.wrapped;
            }
            None => {
                return Err(CommandError::User(format!(
                    "E486: Pattern not found: {}",
                    last.pattern
                )));
            }
        }
    }
    Ok(MotionResult {
        curswant: None,
        target: at,
        linewise: false,
        exclusive: None,
        notice: wrapped.then_some(match direction {
            SearchDirection::Forward => crate::registry::MotionNotice::SearchHitBottom,
            SearchDirection::Backward => crate::registry::MotionNotice::SearchHitTop,
        }),
    })
}

fn motion_search_next(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    motion_search(ctx, false)
}

fn motion_search_prev(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    motion_search(ctx, true)
}

/// VM.3d-2: one character in the search direction, so `n` skips the match the
/// cursor is on. The same rule as the host's `step_byte` for `repeat_search`: a
/// whole UTF-8 scalar forward (a mid-scalar offset would be snapped back onto
/// the match being skipped), across a line end to the next line's start, and
/// one byte back or to the previous line's end.
fn step_for_search(
    buffer: &lattice_core::Buffer,
    p: Position,
    direction: crate::modal::SearchDirection,
) -> Position {
    let line = buffer.line(p.line).unwrap_or_default();
    match direction {
        crate::modal::SearchDirection::Forward => {
            if p.byte < line_byte_len(buffer, p.line) {
                let mut byte = p.byte as usize + 1;
                while byte < line.len() && !line.is_char_boundary(byte) {
                    byte += 1;
                }
                Position::new(p.line, byte as u32)
            } else if p.line < last_addressable_line(buffer) {
                Position::new(p.line + 1, 0)
            } else {
                p
            }
        }
        crate::modal::SearchDirection::Backward => {
            if p.byte > 0 {
                let mut byte = (p.byte as usize - 1).min(line.len());
                while byte > 0 && !line.is_char_boundary(byte) {
                    byte -= 1;
                }
                Position::new(p.line, byte as u32)
            } else if p.line > 0 {
                Position::new(p.line - 1, line_byte_len(buffer, p.line - 1))
            } else {
                p
            }
        }
    }
}

/// VM.3i: `zj` (`forward`) / `zk` — the next fold start / previous fold end,
/// `count` times. The host decides which folds are visible (a closed fold
/// counts as one, vim's rule); this only walks the answers.
///
/// No resolver, or no edge that way, leaves the cursor where it is: vim moves
/// nothing and says nothing. A count that runs out of folds stops at the last
/// edge it reached.
fn motion_goto_fold(ctx: &MotionContext, forward: bool) -> Result<MotionResult, CommandError> {
    let mut target = ctx.from;
    if let Some(folds) = ctx.fold_resolver {
        let mut line = ctx.from.line;
        for _ in 0..ctx.count.get().max(1) {
            match folds.fold_edge(line, forward) {
                Some(edge) => {
                    line = edge;
                    target = Position::new(edge, 0);
                }
                None => break,
            }
        }
    }
    Ok(MotionResult {
        curswant: None,
        target,
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

fn motion_goto_next_fold(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    motion_goto_fold(ctx, true)
}

fn motion_goto_prev_fold(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    motion_goto_fold(ctx, false)
}

fn motion_paragraph_forward(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let text = ctx.buffer.as_string();
    let count = ctx.count.get().max(1);
    let last = buffer_last_line(&text);
    let mut line = ctx.from.line;
    for _ in 0..count {
        // Step forward at least one line.
        if line > last {
            line = last;
            break;
        }
        line = line.saturating_add(1);
        // Skip current paragraph (non-blank lines).
        while line <= last && !line_is_blank(&text, line) {
            line = line.saturating_add(1);
        }
        if line > last {
            line = last;
            break;
        }
    }
    Ok(MotionResult {
        curswant: None,
        target: Position::new(line, 0),
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

fn motion_paragraph_backward(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let text = ctx.buffer.as_string();
    let count = ctx.count.get().max(1);
    let mut line = ctx.from.line;
    for _ in 0..count {
        if line == 0 {
            break;
        }
        line = line.saturating_sub(1);
        while line > 0 && !line_is_blank(&text, line) {
            line = line.saturating_sub(1);
        }
    }
    Ok(MotionResult {
        curswant: None,
        target: Position::new(line, 0),
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

// ---- Sentence motions and text objects (vim's `)`, `(`, `is`, `as`) ----
//
// A sentence ends with `.`, `!`, or `?` followed by whitespace (or
// EOL). v1 doesn't honor vim's nuance around closing brackets / quotes
// after the punctuation; just the simple form.

fn is_sentence_end(b: u8) -> bool {
    matches!(b, b'.' | b'!' | b'?')
}

/// Find the byte offset of the start of the next sentence at or after
/// `from`. Returns the index of the first non-whitespace byte AFTER a
/// sentence-ending punctuation followed by whitespace (or the end of
/// the buffer).
fn next_sentence_start(bytes: &[u8], from: usize) -> Option<usize> {
    let mut i = from;
    while i + 1 < bytes.len() {
        if is_sentence_end(bytes[i]) && bytes[i + 1].is_ascii_whitespace() {
            // Skip the punctuation + whitespace.
            let mut j = i + 2;
            while j < bytes.len() && bytes[j].is_ascii_whitespace() {
                j += 1;
            }
            if j < bytes.len() {
                return Some(j);
            }
            return None;
        }
        i += 1;
    }
    None
}

/// Find the byte offset of the start of the previous sentence (the
/// non-whitespace byte after a previous sentence end). Returns 0 if
/// there's no earlier sentence boundary.
fn prev_sentence_start(bytes: &[u8], from: usize) -> usize {
    if from == 0 {
        return 0;
    }
    // Walk back to find a sentence-end + whitespace pattern.
    let mut i = from.saturating_sub(1);
    while i > 0 {
        if is_sentence_end(bytes[i]) && i + 1 < bytes.len() && bytes[i + 1].is_ascii_whitespace() {
            // Skip whitespace following the punctuation.
            let mut j = i + 2;
            while j < bytes.len() && bytes[j].is_ascii_whitespace() {
                j += 1;
            }
            if j < from {
                return j;
            }
        }
        i -= 1;
    }
    0
}

fn motion_sentence_forward(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let count = ctx.count.get().max(1);
    let mut idx = ctx
        .buffer
        .position_to_byte(ctx.from)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    for _ in 0..count {
        match next_sentence_start(bytes, idx) {
            Some(next) => idx = next,
            None => {
                idx = bytes.len().saturating_sub(1);
                break;
            }
        }
    }
    let target = ctx
        .buffer
        .byte_to_position(idx)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    Ok(MotionResult {
        curswant: None,
        target,
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

fn motion_sentence_backward(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let count = ctx.count.get().max(1);
    let mut idx = ctx
        .buffer
        .position_to_byte(ctx.from)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    for _ in 0..count {
        let next = prev_sentence_start(bytes, idx);
        if next == idx {
            break;
        }
        idx = next;
    }
    let target = ctx
        .buffer
        .byte_to_position(idx)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    Ok(MotionResult {
        curswant: None,
        target,
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

fn text_object_inner_sentence(ctx: &TextObjectContext) -> Result<ProtoRange, CommandError> {
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let cursor = ctx
        .buffer
        .position_to_byte(ctx.at)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    let start_byte = prev_sentence_start(bytes, cursor.saturating_add(1));
    let mut end_byte = cursor;
    while end_byte < bytes.len() {
        if is_sentence_end(bytes[end_byte]) {
            // Inner stops at the punctuation (exclusive).
            break;
        }
        end_byte += 1;
    }
    let start_pos = ctx
        .buffer
        .byte_to_position(start_byte)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    let end_pos = ctx
        .buffer
        .byte_to_position(end_byte)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    Ok(ProtoRange::new(start_pos, end_pos))
}

fn text_object_around_sentence(ctx: &TextObjectContext) -> Result<ProtoRange, CommandError> {
    let inner = text_object_inner_sentence(ctx)?;
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let inner_end_byte = ctx
        .buffer
        .position_to_byte(inner.end)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    // Around: include the trailing punctuation + whitespace.
    let mut end = inner_end_byte;
    if end < bytes.len() && is_sentence_end(bytes[end]) {
        end += 1;
    }
    while end < bytes.len() && bytes[end].is_ascii_whitespace() {
        end += 1;
    }
    let end_pos = ctx
        .buffer
        .byte_to_position(end)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    Ok(ProtoRange::new(inner.start, end_pos))
}

// ---- WORD motions (vim's W, B, E) ----

fn motion_big_word_forward(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let total = bytes.len();
    let count = ctx.count.get().max(1);
    let mut idx = ctx
        .buffer
        .position_to_byte(ctx.from)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;

    for _ in 0..count {
        if idx >= total {
            break;
        }
        // Skip the current WORD's remaining non-whitespace bytes.
        while idx < total && is_big_word_byte(bytes[idx]) {
            idx += 1;
        }
        // Skip whitespace until the next WORD start.
        while idx < total && !is_big_word_byte(bytes[idx]) {
            idx += 1;
        }
    }
    if idx >= total {
        idx = total.saturating_sub(1);
    }
    let target = ctx
        .buffer
        .byte_to_position(idx)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    Ok(MotionResult {
        curswant: None,
        target,
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

fn motion_big_word_backward(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let count = ctx.count.get().max(1);
    let mut idx = ctx
        .buffer
        .position_to_byte(ctx.from)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;

    for _ in 0..count {
        if idx == 0 {
            break;
        }
        idx -= 1;
        while idx > 0 && !is_big_word_byte(bytes[idx]) {
            idx -= 1;
        }
        while idx > 0 && is_big_word_byte(bytes[idx - 1]) {
            idx -= 1;
        }
    }
    let target = ctx
        .buffer
        .byte_to_position(idx)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    Ok(MotionResult {
        curswant: None,
        target,
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

fn motion_big_word_end(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let total = bytes.len();
    let count = ctx.count.get().max(1);
    let mut idx = ctx
        .buffer
        .position_to_byte(ctx.from)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;

    for _ in 0..count {
        if idx >= total.saturating_sub(1) {
            break;
        }
        idx += 1;
        while idx < total && !is_big_word_byte(bytes[idx]) {
            idx += 1;
        }
        if idx >= total {
            idx = total.saturating_sub(1);
            break;
        }
        while idx + 1 < total && is_big_word_byte(bytes[idx + 1]) {
            idx += 1;
        }
    }
    let target = ctx
        .buffer
        .byte_to_position(idx)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    Ok(MotionResult {
        curswant: None,
        target,
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

// ---- Motion: find-char / till-char (vim's f, F, t, T) ----
//
// Each takes `Args::Char(c)` and searches the current line. v1 ignores
// `count` (most users press `;` / `,` for repeat); count support lands
// later. Forward variants return the cursor's original line if the char
// is not found (matching vim's no-op behavior).

fn args_to_char(args: &crate::args::Args) -> Result<char, CommandError> {
    match args {
        crate::args::Args::Char(c) => Ok(*c),
        _ => Err(CommandError::InvalidArgs("f/F/t/T require Args::Char")),
    }
}

fn line_text(text: &str, line: u32) -> &str {
    text.split_inclusive('\n')
        .nth(line as usize)
        .map(|l| l.trim_end_matches('\n'))
        .unwrap_or("")
}

fn motion_find_char_forward(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let needle = args_to_char(&ctx.args)?;
    let text = ctx.buffer.as_string();
    let line = line_text(&text, ctx.from.line);
    let bytes = line.as_bytes();
    let start = (ctx.from.byte as usize).saturating_add(1);
    let mut buf = [0u8; 4];
    let needle_bytes = needle.encode_utf8(&mut buf).as_bytes();
    let nlen = needle_bytes.len();
    let mut idx = start;
    while idx + nlen <= bytes.len() {
        if &bytes[idx..idx + nlen] == needle_bytes {
            return Ok(MotionResult {
                curswant: None,
                target: Position::new(ctx.from.line, idx as u32),
                linewise: false,
                exclusive: None,
                notice: None,
            });
        }
        idx += 1;
    }
    // No match -- vim no-ops.
    Ok(MotionResult {
        curswant: None,
        target: ctx.from,
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

fn motion_find_char_backward(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let needle = args_to_char(&ctx.args)?;
    let text = ctx.buffer.as_string();
    let line = line_text(&text, ctx.from.line);
    let bytes = line.as_bytes();
    let mut buf = [0u8; 4];
    let needle_bytes = needle.encode_utf8(&mut buf).as_bytes();
    let nlen = needle_bytes.len();
    if (ctx.from.byte as usize) < nlen {
        return Ok(MotionResult {
            curswant: None,
            target: ctx.from,
            linewise: false,
            exclusive: None,
            notice: None,
        });
    }
    let mut idx = (ctx.from.byte as usize) - nlen;
    loop {
        if idx + nlen <= bytes.len() && &bytes[idx..idx + nlen] == needle_bytes {
            return Ok(MotionResult {
                curswant: None,
                target: Position::new(ctx.from.line, idx as u32),
                linewise: false,
                exclusive: None,
                notice: None,
            });
        }
        if idx == 0 {
            break;
        }
        idx -= 1;
    }
    Ok(MotionResult {
        curswant: None,
        target: ctx.from,
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

fn motion_till_char_forward(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    // `t<c>`: identical to `f<c>` but the target is one byte before the match.
    let result = motion_find_char_forward(ctx)?;
    if result.target == ctx.from {
        return Ok(result);
    }
    let target_byte = result.target.byte.saturating_sub(1);
    Ok(MotionResult {
        curswant: None,
        target: Position::new(result.target.line, target_byte),
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

fn motion_till_char_backward(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    // `T<c>`: identical to `F<c>` but the target is one byte after the match.
    let result = motion_find_char_backward(ctx)?;
    if result.target == ctx.from {
        return Ok(result);
    }
    let line_len = result
        .target
        .byte
        .saturating_add(args_to_char(&ctx.args)?.len_utf8() as u32);
    Ok(MotionResult {
        curswant: None,
        target: Position::new(result.target.line, line_len),
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

// ---- Motions: find-repeat (vim's `;` and `,`) ----

/// Repeat the last `f` / `F` / `t` / `T`, in the same direction.
///
/// VM.3c: a MOTION, not an action. Vim composes `;` (`d;` repeats the last
/// find under an operator) and extends a selection with it, and VM.1's
/// derivation only mirrors motions — so as an action it was unreachable from
/// both.
///
/// Delegates by rebuilding the context with `args` set to the remembered
/// character, rather than by re-implementing the four searches. That keeps one
/// implementation of "find a char on this line": a fix to `t`'s
/// one-byte-before rule lands in `;` for free, which is the property the old
/// host-side `do_find_repeat` had (it synthesised a `CommandInvocation`
/// against the find-char motion) and the one worth preserving across the move.
fn motion_find_repeat(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    find_repeat(ctx, false)
}

/// `,` — repeat the last find in the OPPOSITE direction.
fn motion_find_repeat_reverse(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    find_repeat(ctx, true)
}

fn find_repeat(ctx: &MotionContext, reverse: bool) -> Result<MotionResult, CommandError> {
    let Some(last) = ctx.last_find else {
        // No previous find. Vim bells; a motion that has nowhere to go
        // returns the cursor, so `d;` deletes nothing rather than something
        // arbitrary.
        return Ok(MotionResult {
            curswant: None,
            target: ctx.from,
            linewise: false,
            exclusive: None,
            notice: None,
        });
    };
    let kind = if reverse {
        last.kind.reversed()
    } else {
        last.kind
    };
    // Re-enter the real find with the remembered character in `args`. Built
    // field-by-field because `MotionContext` borrows and is neither `Clone`
    // nor constructible by struct-update from a reference.
    let sub = MotionContext {
        buffer: ctx.buffer,
        buffer_id: ctx.buffer_id,
        from: ctx.from,
        count: ctx.count,
        has_explicit_count: ctx.has_explicit_count,
        args: crate::args::Args::Char(last.target),
        cancel: ctx.cancel,
        scope_resolver: ctx.scope_resolver,
        path: ctx.path,
        syntax: ctx.syntax,
        last_find: ctx.last_find,
        fold_resolver: ctx.fold_resolver,
        last_search: ctx.last_search,
        marks: ctx.marks,
        viewport: ctx.viewport,
        nostartofline: ctx.nostartofline,
        curswant: ctx.curswant,
        display: ctx.display,
        scrolloff: ctx.scrolloff,
        operator_pending: ctx.operator_pending,
    };
    let mut result = match kind {
        FindKind::Forward => motion_find_char_forward(&sub)?,
        FindKind::Backward => motion_find_char_backward(&sub)?,
        FindKind::TillForward => motion_till_char_forward(&sub)?,
        FindKind::TillBackward => motion_till_char_backward(&sub)?,
    };
    // The whole reason `MotionResult::exclusive` exists. `;` and `,` take the
    // exclusivity of the motion they REPEAT, and the spec cannot know which
    // that is: `f` / `t` are inclusive, `F` / `T` are not. Without this,
    // `d,` after an `f` deleted one character too many.
    result.exclusive = Some(matches!(kind, FindKind::Backward | FindKind::TillBackward));
    Ok(result)
}

// ---- Motion: first-non-blank (vim's `^`) ----

fn motion_first_non_blank(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let text = ctx.buffer.as_string();
    let line_text = text
        .split_inclusive('\n')
        .nth(ctx.from.line as usize)
        .map(|l| l.trim_end_matches('\n'))
        .unwrap_or("");
    let bytes = line_text.as_bytes();
    let mut col = 0usize;
    while col < bytes.len() && is_blank_byte(bytes[col]) {
        col += 1;
    }
    Ok(MotionResult {
        curswant: None,
        target: Position::new(ctx.from.line, col as u32),
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

// ---- Motion: char-left ----

fn motion_char_left(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let count = ctx.count.get().max(1);
    let mut pos = ctx.from;
    let text = ctx.buffer.as_string();
    let line = line_text(&text, pos.line);
    // Step by whole UTF-8 scalars, not bytes: a byte-step could land mid-glyph
    // (e.g. inside `│` U+2502, 3 bytes) and produce a delete range that panics
    // ropey on a non-char-boundary slice. `min` also snaps a mis-seeded
    // starting `pos.byte` onto the line before walking.
    let mut byte = (pos.byte as usize).min(line.len());
    for _ in 0..count {
        if byte == 0 {
            break;
        }
        byte -= 1;
        while byte > 0 && !line.is_char_boundary(byte) {
            byte -= 1;
        }
    }
    pos.byte = byte as u32;
    Ok(MotionResult {
        curswant: None,
        target: pos,
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

// ---- Motion: char-right ----

fn motion_char_right(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let count = ctx.count.get().max(1);
    let mut pos = ctx.from;
    let text = ctx.buffer.as_string();
    let line = line_text(&text, pos.line);
    let line_len = line.len();
    // Step by whole UTF-8 scalars, not bytes (see `motion_char_left`): a
    // byte-step over a multibyte glyph produced a delete range ending mid-char
    // and panicked ropey's `byte_slice` on the editor actor thread.
    let mut byte = (pos.byte as usize).min(line_len);
    for _ in 0..count {
        if byte >= line_len {
            break;
        }
        byte += 1;
        while byte < line_len && !line.is_char_boundary(byte) {
            byte += 1;
        }
    }
    pos.byte = byte as u32;
    Ok(MotionResult {
        curswant: None,
        target: pos,
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

// ---- Motion: line-up / line-down ----

/// VM.3L: `k` is linewise (`dk` deletes two whole lines), and on the first
/// line it FAILS rather than returning the cursor. With linewise ranges, a
/// no-move result would make `dk` delete the current line; vim beeps and
/// deletes nothing. A count past the top clamps, as in vim (`5dk`).
fn motion_line_up(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    if ctx.from.line == 0 {
        return Err(CommandError::MotionFailed);
    }
    let count = ctx.count.get().max(1);
    let line = ctx.from.line.saturating_sub(count);
    let byte = curswant_byte(ctx, line);
    Ok(MotionResult {
        curswant: None,
        target: Position::new(line, byte),
        linewise: true,
        exclusive: None,
        notice: None,
    })
}

/// VM.3L: `j` is linewise, and on the last line it fails; see `k` above.
/// vim 9.2: `dj` on the last line leaves the buffer and register untouched,
/// and `5dj` two lines from the end clamps to the end.
fn motion_line_down(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let last = last_addressable_line(ctx.buffer);
    if ctx.from.line >= last {
        return Err(CommandError::MotionFailed);
    }
    let count = ctx.count.get().max(1);
    let line = ctx.from.line.saturating_add(count).min(last);
    let byte = curswant_byte(ctx, line);
    Ok(MotionResult {
        curswant: None,
        target: Position::new(line, byte),
        linewise: true,
        exclusive: None,
        notice: None,
    })
}

// ---- Motion: line-start / line-end ----

fn motion_line_start(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    Ok(MotionResult {
        curswant: None,
        target: Position::new(ctx.from.line, 0),
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

fn motion_line_end(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let len = line_byte_len(ctx.buffer, ctx.from.line);
    Ok(MotionResult {
        curswant: None,
        target: Position::new(ctx.from.line, len),
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

// ---- Motion: goto-first-line / goto-last-line ----

fn motion_goto_first_line(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    // `{count}gg` goes to line count (1-indexed); bare `gg` → line 1.
    let target_line = if ctx.has_explicit_count {
        let last = last_addressable_line(ctx.buffer);
        ctx.count.get().saturating_sub(1).min(last)
    } else {
        0
    };
    Ok(MotionResult {
        curswant: None,
        // VM.3j-1: the first non-blank, as vim does under `startofline`. This
        // was a hard column 0, which matched neither of vim's settings.
        target: startofline_target(ctx, target_line),
        linewise: true,
        exclusive: None,
        notice: None,
    })
}

fn motion_goto_last_line(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    // `{count}G` goes to line count (1-indexed); bare `G` → last line.
    let last = last_addressable_line(ctx.buffer);
    let target_line = if ctx.has_explicit_count {
        ctx.count.get().saturating_sub(1).min(last)
    } else {
        last
    };
    Ok(MotionResult {
        curswant: None,
        // VM.3j-1: as `gg` above.
        target: startofline_target(ctx, target_line),
        linewise: true,
        exclusive: None,
        notice: None,
    })
}

// ---- Helpers ----

fn line_byte_len(buffer: &lattice_core::Buffer, line: u32) -> u32 {
    let s = buffer.as_string();
    s.split_inclusive('\n')
        .nth(line as usize)
        .map(|l| l.trim_end_matches('\n').len() as u32)
        .unwrap_or(0)
}

/// VM.3m: `pos` brought inside the buffer it addresses — the line clamped to
/// the last one, the byte to that line's length. A yank's origin can point past
/// both after the operator ran.
fn clamp_into_buffer(buffer: &lattice_core::Buffer, pos: Position) -> Position {
    let line = pos.line.min(last_addressable_line(buffer));
    Position::new(line, pos.byte.min(line_byte_len(buffer, line)))
}

/// VM.3g-2: the goal column WITHIN a display row. vim shares `curswant`
/// between `j` and `gj` (9.2: `j gj j` keeps it), so this is the same goal read
/// modulo the wrap width.
fn display_goal(ctx: &MotionContext, wrap: u32) -> u32 {
    let wrap = wrap.max(1);
    match ctx.curswant {
        Some(crate::registry::Curswant::EndOfLine) => wrap - 1,
        Some(crate::registry::Curswant::Col(c)) => c % wrap,
        None => ctx.from.byte % wrap,
    }
}

/// VM.3g-2: vim's `gj` — one display ROW down, keeping the screen column.
/// With `wrap` off, or no renderer geometry, it IS `j`, as in vim.
///
/// Ported from `Editor::do_display_line_down` so the landing is unchanged; what
/// is new is that a count walks (vim's `2gj` moves two rows; the host action
/// ignored counts) and the goal column is the shared `curswant` rather than a
/// second, display-only one.
fn motion_display_line_down(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let Some(display) = ctx.display else {
        return motion_line_down(ctx);
    };
    let wrap = display.wrap_width();
    if wrap == 0 {
        return motion_line_down(ctx);
    }
    let last = last_addressable_line(ctx.buffer);
    let goal = display_goal(ctx, wrap);
    let mut at = ctx.from;
    // VM.3g-3: the column the LAST step aimed at, before the row's length
    // clamped it. That, not the landing, is what vim records — see
    // `MotionResult::curswant`.
    let mut aim = at.byte;
    for _ in 0..ctx.count.get().max(1) {
        let seg = at.byte / wrap;
        let segs = display.segments(at.line).max(1);
        if seg + 1 < segs {
            // another row on this same line
            let next_start = (seg + 1) * wrap;
            let next_end = ((seg + 2) * wrap).min(line_byte_len(ctx.buffer, at.line));
            aim = next_start + goal;
            let byte = aim.min(next_end.saturating_sub(1).max(next_start));
            at = Position::new(at.line, byte);
        } else if at.line < last {
            let next = at.line + 1;
            let len = line_byte_len(ctx.buffer, next);
            aim = goal;
            at = Position::new(next, goal.min(len.saturating_sub(1)));
        } else {
            // vim: `gj` on the last display row stays put — and leaves the goal
            // alone with it, so a later `gj` onto a longer row still reaches it.
            break;
        }
    }
    Ok(MotionResult {
        curswant: Some(crate::registry::Curswant::Col(aim)),
        target: at,
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

/// VM.3g-2: vim's `gk`, the mirror of [`motion_display_line_down`].
fn motion_display_line_up(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let Some(display) = ctx.display else {
        return motion_line_up(ctx);
    };
    let wrap = display.wrap_width();
    if wrap == 0 {
        return motion_line_up(ctx);
    }
    let goal = display_goal(ctx, wrap);
    let mut at = ctx.from;
    // VM.3g-3: as in `gj` — the aim, not the clamped landing.
    let mut aim = at.byte;
    for _ in 0..ctx.count.get().max(1) {
        let seg = at.byte / wrap;
        if seg > 0 {
            let prev_start = (seg - 1) * wrap;
            let actual_end = (seg * wrap).min(line_byte_len(ctx.buffer, at.line));
            aim = prev_start + goal;
            let byte = aim.min(actual_end.saturating_sub(1).max(prev_start));
            at = Position::new(at.line, byte);
        } else if at.line > 0 {
            let prev = at.line - 1;
            let len = line_byte_len(ctx.buffer, prev);
            let last_start = (display.segments(prev).max(1) - 1) * wrap;
            aim = last_start + goal;
            let byte = aim.min(len.saturating_sub(1).max(last_start));
            at = Position::new(prev, byte);
        } else {
            break;
        }
    }
    Ok(MotionResult {
        curswant: Some(crate::registry::Curswant::Col(aim)),
        target: at,
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

/// VM.3g-2: vim's `g0` — the first column of the display row. `0` without wrap.
fn motion_display_line_start(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let Some(display) = ctx.display else {
        return motion_line_start(ctx);
    };
    let wrap = display.wrap_width();
    if wrap == 0 {
        return motion_line_start(ctx);
    }
    Ok(MotionResult {
        curswant: None,
        target: Position::new(ctx.from.line, (ctx.from.byte / wrap) * wrap),
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

/// VM.3g-2: vim's `g$` — the LAST column of the display row, and inclusive, so
/// `dg$` takes that column with it (9.2: `dg$` from 2,85 deletes 85–160).
/// `$` without wrap.
fn motion_display_line_end(ctx: &MotionContext) -> Result<MotionResult, CommandError> {
    let Some(display) = ctx.display else {
        return motion_line_end(ctx);
    };
    let wrap = display.wrap_width();
    if wrap == 0 {
        return motion_line_end(ctx);
    }
    let len = line_byte_len(ctx.buffer, ctx.from.line);
    let seg_end = (((ctx.from.byte / wrap) + 1) * wrap).min(len);
    Ok(MotionResult {
        curswant: None,
        target: Position::new(ctx.from.line, seg_end.saturating_sub(1)),
        linewise: false,
        exclusive: None,
        notice: None,
    })
}

/// VM.3g-1: the column a vertical motion lands on in `line` — vim's
/// `curswant`, clamped to that line. With no goal recorded the cursor's own
/// column is the goal, which is what the first `j` after an edit does in vim.
///
/// The clamp is the whole reason the goal must be REMEMBERED rather than read
/// back off the cursor: `jj` from column 9 across a 2-column line has to return
/// to 9, and on the middle line the cursor is at 2.
fn curswant_byte(ctx: &MotionContext, line: u32) -> u32 {
    let len = line_byte_len(ctx.buffer, line);
    match ctx.curswant {
        Some(crate::registry::Curswant::EndOfLine) => len,
        Some(crate::registry::Curswant::Col(c)) => c.min(len),
        None => ctx.from.byte.min(len),
    }
}

/// VM.3j-1: where a `startofline` jump lands on the line it reached — the
/// first non-blank, or the cursor's column when the user set `nostartofline`.
///
/// vim's rule for `gg` / `G` / `H` / `M` / `L` and the page scrolls, checked in
/// 9.2 (`vimcheck_sol_pages.vim`): `G` → 40,3 with `startofline` and 40,6 with
/// `nostartofline` on a 2-indented buffer. One function so the motions can't
/// drift apart — `H` / `M` / `L` (VM.3f) answered from their own copy of it.
fn startofline_target(ctx: &MotionContext, line: u32) -> Position {
    if ctx.nostartofline {
        let len = line_byte_len(ctx.buffer, line);
        Position::new(line, ctx.from.byte.min(len))
    } else {
        first_non_blank_position(ctx.buffer, line)
    }
}

/// VM.3m: the first non-blank of `line`, where vim leaves the cursor after a
/// linewise delete (`dd`, `dk`, `2dj`).
fn first_non_blank_position(buffer: &lattice_core::Buffer, line: u32) -> Position {
    let text = buffer.line(line).unwrap_or_default();
    let col = text.bytes().take_while(|&b| is_blank_byte(b)).count() as u32;
    Position::new(line, col.min(line_byte_len(buffer, line)))
}

/// CV.3: the last line a motion or range may address — content
/// space. One of three hand-rolled copies of this before the rename;
/// all three now sit on the accessor, and this one no longer
/// materialises the whole buffer with `as_string()` to ask whether it
/// ends in a newline.
fn last_addressable_line(buffer: &lattice_core::Buffer) -> u32 {
    buffer.content_line_count().saturating_sub(1)
}

/// Extend a linewise content range to consume the trailing
/// newline so `dd` / `Ndd` reduces the buffer's line count by
/// `count` (vim semantics). When the range ends at the buffer's
/// last addressable line (no trailing newline available),
/// consume the LEADING newline before `start_line` instead --
/// otherwise the previous line would acquire a phantom newline.
/// A whole-buffer range (start at line 0 AND end at last line)
/// has no surrounding newline to claim and passes through
/// unchanged.
///
/// Used by `dd` (edit + slice). `yy` doesn't use this -- a
/// linewise yank's content always ends with `\n` regardless of
/// whether the source line had a trailing newline, so yank
/// appends `\n` to the original slice rather than walking the
/// buffer.
fn extend_linewise_range(buffer: &lattice_core::Buffer, range: ProtoRange) -> ProtoRange {
    let last = last_addressable_line(buffer);
    let end_line = range.end.line;
    if end_line < last {
        ProtoRange::new(range.start, Position::new(end_line + 1, 0))
    } else if range.start.line > 0 {
        let prev_line = range.start.line - 1;
        let prev_len = line_byte_len(buffer, prev_line);
        ProtoRange::new(Position::new(prev_line, prev_len), range.end)
    } else {
        range
    }
}

// ---- Paragraph text objects (vim's `ip`, `ap`) ----

fn text_object_inner_paragraph(ctx: &TextObjectContext) -> Result<ProtoRange, CommandError> {
    let text = ctx.buffer.as_string();
    let last_line = buffer_last_line(&text);
    let cursor_line = ctx.at.line.min(last_line);
    let blank_at_cursor = line_is_blank(&text, cursor_line);
    // Walk back to the start of the contiguous run-of-same-blank-status.
    let mut start = cursor_line;
    while start > 0 && line_is_blank(&text, start - 1) == blank_at_cursor {
        start -= 1;
    }
    // Walk forward to the end of the run.
    let mut end = cursor_line;
    while end < last_line && line_is_blank(&text, end + 1) == blank_at_cursor {
        end += 1;
    }
    let end_byte = line_byte_len(ctx.buffer, end);
    Ok(ProtoRange::new(
        Position::new(start, 0),
        Position::new(end, end_byte),
    ))
}

fn text_object_around_paragraph(ctx: &TextObjectContext) -> Result<ProtoRange, CommandError> {
    // Inner paragraph + trailing blank lines (or leading if at end of buffer).
    let inner = text_object_inner_paragraph(ctx)?;
    let text = ctx.buffer.as_string();
    let last_line = buffer_last_line(&text);
    let mut end_line = inner.end.line;
    let blank_at_inner = line_is_blank(&text, end_line);
    if !blank_at_inner {
        while end_line < last_line && line_is_blank(&text, end_line + 1) {
            end_line += 1;
        }
        let end_byte = line_byte_len(ctx.buffer, end_line);
        Ok(ProtoRange::new(
            inner.start,
            Position::new(end_line, end_byte),
        ))
    } else {
        while end_line < last_line && !line_is_blank(&text, end_line + 1) {
            end_line += 1;
        }
        let end_byte = line_byte_len(ctx.buffer, end_line);
        Ok(ProtoRange::new(
            inner.start,
            Position::new(end_line, end_byte),
        ))
    }
}

// ---- N.1.6: comment text objects (aC / iC) ----
//
// Commentstring-driven, NOT tree-sitter (works for any language with a
// known line-comment leader, even without a parse tree). `aC` = the
// contiguous run of full comment lines (markers included); `iC` = the
// comment text (the first line's leader stripped). The leader comes from
// `ctx.comment_syntax.line`, populated by the host from the active
// buffer's language. No leader (plain buffer / unknown language) or a
// cursor not on a comment line -> empty range -> the paired operator
// no-ops, matching vim's "daC with no comment does nothing".

/// True when `line`'s first non-whitespace run starts with `leader`.
/// `///` and `//!` match because they begin with `//`.
fn line_is_comment(buffer: &lattice_core::Buffer, line: u32, leader: &str) -> bool {
    buffer
        .line(line)
        .map(|t| t.trim_start().starts_with(leader))
        .unwrap_or(false)
}

/// Byte offset on `line` of the comment CONTENT: just past the leader
/// and one optional following space. `    // foo` (leader `//`) returns
/// the offset of `foo`.
fn comment_content_start(buffer: &lattice_core::Buffer, line: u32, leader: &str) -> u32 {
    let Some(text) = buffer.line(line) else {
        return 0;
    };
    let indent = text.len() - text.trim_start().len();
    let mut off = indent + leader.len();
    if text.as_bytes().get(off) == Some(&b' ') {
        off += 1;
    }
    off.min(text.len()) as u32
}

/// Shared scan for `aC` / `iC`: expand over the contiguous run of full
/// comment lines containing the cursor. `aC` (`inner = false`) starts at
/// column 0; `iC` (`inner = true`) starts after the first line's leader.
/// Both end at the last comment line's content end (matching the
/// paragraph objects' linewise-ish shape).
fn comment_text_object(ctx: &TextObjectContext, inner: bool) -> Result<ProtoRange, CommandError> {
    let Some(leader) = ctx.comment_syntax.and_then(|c| c.line.as_deref()) else {
        return Ok(ProtoRange::new(ctx.at, ctx.at));
    };
    // CV.3: content space — the phantom line ropey reports after a
    // terminating newline is not a comment line and must not be
    // walked into.
    let line_count = ctx.buffer.content_line_count();
    if leader.is_empty() || line_count == 0 {
        return Ok(ProtoRange::new(ctx.at, ctx.at));
    }
    let cursor_line = ctx.at.line.min(line_count - 1);
    if !line_is_comment(ctx.buffer, cursor_line, leader) {
        return Ok(ProtoRange::new(ctx.at, ctx.at));
    }
    let mut start = cursor_line;
    while start > 0 && line_is_comment(ctx.buffer, start - 1, leader) {
        start -= 1;
    }
    let mut end = cursor_line;
    while end + 1 < line_count && line_is_comment(ctx.buffer, end + 1, leader) {
        end += 1;
    }
    let start_byte = if inner {
        comment_content_start(ctx.buffer, start, leader)
    } else {
        0
    };
    Ok(ProtoRange::new(
        Position::new(start, start_byte),
        Position::new(end, line_byte_len(ctx.buffer, end)),
    ))
}

fn text_object_around_comment(ctx: &TextObjectContext) -> Result<ProtoRange, CommandError> {
    comment_text_object(ctx, false)
}

fn text_object_inner_comment(ctx: &TextObjectContext) -> Result<ProtoRange, CommandError> {
    comment_text_object(ctx, true)
}

// ---- Text objects ----
//
// Each text object computes a `ProtoRange` covering the relevant span
// at the cursor. Vim's text objects are inclusive of their ends; the
// dispatcher's [start, end) range is constructed to match by extending
// `end` past the last byte we want included.

/// Inner-word run shared between `iw` and `iW`. The classifier decides the
/// run: `word_class` for `iw` (vim's 3-way Word / Punct / Blank, so `iw` on
/// a `.` selects the punctuation run and `iw` on a space selects the
/// whitespace run), `big_word_class` for `iW` (2-way NonBlank / Blank, so a
/// whole `foo.bar` is one WORD). The object is the maximal run of the
/// cursor's class -- every non-EOF byte belongs to some class, so (unlike the
/// old 2-way predicate) landing on punctuation or whitespace is never a no-op.
fn text_object_inner_word_class(
    ctx: &TextObjectContext,
    classify: fn(u8) -> WordClass,
) -> Result<ProtoRange, CommandError> {
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let cursor = ctx
        .buffer
        .position_to_byte(ctx.at)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    if cursor >= bytes.len() {
        // Past EOF -- range is the cursor position alone.
        return Ok(ProtoRange::new(ctx.at, ctx.at));
    }
    let class = classify(bytes[cursor]);
    let mut start = cursor;
    while start > 0 && classify(bytes[start - 1]) == class {
        start -= 1;
    }
    let mut end = cursor;
    while end + 1 < bytes.len() && classify(bytes[end + 1]) == class {
        end += 1;
    }
    // [start, end] inclusive of word -> half-open is end + 1.
    let start_pos = ctx
        .buffer
        .byte_to_position(start)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    let end_pos = ctx
        .buffer
        .byte_to_position(end + 1)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    Ok(ProtoRange::new(start_pos, end_pos))
}

/// Around-word run shared between `aw` and `aW`. Trailing whitespace
/// extension (or leading if none) is identical for both classes --
/// vim's `aw` and `aW` both stay on the line and use space/tab as
/// the whitespace to absorb.
fn text_object_around_word_class(
    ctx: &TextObjectContext,
    classify: fn(u8) -> WordClass,
) -> Result<ProtoRange, CommandError> {
    let inner = text_object_inner_word_class(ctx, classify)?;
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let inner_end_byte = ctx
        .buffer
        .position_to_byte(inner.end)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    let mut end = inner_end_byte;
    while end < bytes.len() && (bytes[end] == b' ' || bytes[end] == b'\t') {
        end += 1;
    }
    if end == inner_end_byte {
        // No trailing whitespace -- try leading.
        let inner_start_byte = ctx
            .buffer
            .position_to_byte(inner.start)
            .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
        let mut start = inner_start_byte;
        while start > 0 && (bytes[start - 1] == b' ' || bytes[start - 1] == b'\t') {
            start -= 1;
        }
        let start_pos = ctx
            .buffer
            .byte_to_position(start)
            .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
        Ok(ProtoRange::new(start_pos, inner.end))
    } else {
        let end_pos = ctx
            .buffer
            .byte_to_position(end)
            .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
        Ok(ProtoRange::new(inner.start, end_pos))
    }
}

fn text_object_inner_word(ctx: &TextObjectContext) -> Result<ProtoRange, CommandError> {
    text_object_inner_word_class(ctx, word_class)
}

fn text_object_around_word(ctx: &TextObjectContext) -> Result<ProtoRange, CommandError> {
    text_object_around_word_class(ctx, word_class)
}

fn text_object_inner_big_word(ctx: &TextObjectContext) -> Result<ProtoRange, CommandError> {
    text_object_inner_word_class(ctx, big_word_class)
}

fn text_object_around_big_word(ctx: &TextObjectContext) -> Result<ProtoRange, CommandError> {
    text_object_around_word_class(ctx, big_word_class)
}

fn find_quote_pair(bytes: &[u8], cursor: usize, q: u8) -> Option<(usize, usize)> {
    // Restrict to the current line: walk back to start-of-line, then
    // forward, collecting quote positions; pair them naively (no escape
    // handling for v1).
    let mut line_start = cursor;
    while line_start > 0 && bytes[line_start - 1] != b'\n' {
        line_start -= 1;
    }
    let mut line_end = cursor;
    while line_end < bytes.len() && bytes[line_end] != b'\n' {
        line_end += 1;
    }
    let mut quotes = Vec::new();
    for (offset, &b) in bytes[line_start..line_end].iter().enumerate() {
        if b == q {
            quotes.push(line_start + offset);
        }
    }
    // Find a pair where the cursor is inside (or on a quote).
    let mut i = 0;
    while i + 1 < quotes.len() {
        let (l, r) = (quotes[i], quotes[i + 1]);
        if cursor >= l && cursor <= r {
            return Some((l, r));
        }
        i += 2;
    }
    None
}

fn text_object_inner_quote(ctx: &TextObjectContext, q: char) -> Result<ProtoRange, CommandError> {
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let cursor = ctx
        .buffer
        .position_to_byte(ctx.at)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    if !q.is_ascii() {
        return Err(CommandError::InvalidArgs("non-ASCII quote not supported"));
    }
    let q_byte = q as u8;
    let Some((l, r)) = find_quote_pair(bytes, cursor, q_byte) else {
        return Ok(ProtoRange::new(ctx.at, ctx.at));
    };
    // Inner: between the quotes, exclusive of both.
    let start_pos = ctx
        .buffer
        .byte_to_position(l + 1)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    let end_pos = ctx
        .buffer
        .byte_to_position(r)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    Ok(ProtoRange::new(start_pos, end_pos))
}

fn text_object_around_quote(ctx: &TextObjectContext, q: char) -> Result<ProtoRange, CommandError> {
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let cursor = ctx
        .buffer
        .position_to_byte(ctx.at)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    if !q.is_ascii() {
        return Err(CommandError::InvalidArgs("non-ASCII quote not supported"));
    }
    let q_byte = q as u8;
    let Some((l, r)) = find_quote_pair(bytes, cursor, q_byte) else {
        return Ok(ProtoRange::new(ctx.at, ctx.at));
    };
    let start_pos = ctx
        .buffer
        .byte_to_position(l)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    let end_pos = ctx
        .buffer
        .byte_to_position(r + 1)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    Ok(ProtoRange::new(start_pos, end_pos))
}

fn find_bracket_pair(bytes: &[u8], cursor: usize, open: u8, close: u8) -> Option<(usize, usize)> {
    if bytes.is_empty() {
        return None;
    }
    // Walk left to find the most recent unmatched `open`.
    let mut depth = 0i32;
    let mut i = cursor.min(bytes.len() - 1);
    let open_pos = loop {
        let b = bytes[i];
        if b == close && i != cursor {
            // Same-position cursor on a close-bracket counts as "inside",
            // not as an additional level.
            depth += 1;
        } else if b == open {
            if depth == 0 {
                break i;
            }
            depth -= 1;
        }
        if i == 0 {
            return None;
        }
        i -= 1;
    };
    // Walk right from open_pos+1 to find the matching close.
    let mut depth = 0i32;
    let mut j = open_pos + 1;
    while j < bytes.len() {
        let b = bytes[j];
        if b == open {
            depth += 1;
        } else if b == close {
            if depth == 0 {
                return Some((open_pos, j));
            }
            depth -= 1;
        }
        j += 1;
    }
    None
}

fn text_object_inner_brackets(
    ctx: &TextObjectContext,
    open: char,
    close: char,
) -> Result<ProtoRange, CommandError> {
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let cursor = ctx
        .buffer
        .position_to_byte(ctx.at)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    let Some((l, r)) = find_bracket_pair(bytes, cursor, open as u8, close as u8) else {
        return Ok(ProtoRange::new(ctx.at, ctx.at));
    };
    let start_pos = ctx
        .buffer
        .byte_to_position(l + 1)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    let end_pos = ctx
        .buffer
        .byte_to_position(r)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    Ok(ProtoRange::new(start_pos, end_pos))
}

/// Find the nearest XML/HTML tag pair enclosing the cursor. Returns
/// `(open_start, open_end, close_start, close_end)` byte offsets where
/// `open_*` covers `<tag...>` and `close_*` covers `</tag>`. v1 only
/// supports same-line tag pairs and ignores attributes.
fn find_enclosing_tag(bytes: &[u8], cursor: usize) -> Option<(usize, usize, usize, usize)> {
    // Walk back to the nearest unmatched '<...>' open tag.
    let mut i = cursor.min(bytes.len().saturating_sub(1));
    let mut depth = 0i32;
    let open_start;
    loop {
        if bytes[i] == b'>' && i > 0 && bytes[i - 1] != b'/' {
            // a `>` closing some tag (open or self-close)
            // We want to track whether it's a close-tag or open-tag.
            // For simplicity we just look back at the matching `<`.
            // Skip for now; the depth tracking happens at `<`.
        }
        if bytes[i] == b'<' {
            // Look ahead to determine if this is open or close tag.
            if i + 1 < bytes.len() && bytes[i + 1] == b'/' {
                depth += 1;
            } else if depth == 0 {
                open_start = i;
                break;
            } else {
                depth -= 1;
            }
        }
        if i == 0 {
            return None;
        }
        i -= 1;
    }
    // Find the end of the open tag.
    let mut open_end = open_start + 1;
    while open_end < bytes.len() && bytes[open_end] != b'>' {
        open_end += 1;
    }
    if open_end >= bytes.len() {
        return None;
    }
    // Extract tag name.
    let mut name_end = open_start + 1;
    while name_end < open_end
        && bytes[name_end] != b' '
        && bytes[name_end] != b'>'
        && bytes[name_end] != b'/'
    {
        name_end += 1;
    }
    let name = &bytes[open_start + 1..name_end];
    if name.is_empty() {
        return None;
    }
    // Walk forward from `open_end + 1` to find matching `</name>`.
    let close_marker: Vec<u8> = {
        let mut v = Vec::with_capacity(name.len() + 3);
        v.push(b'<');
        v.push(b'/');
        v.extend_from_slice(name);
        v.push(b'>');
        v
    };
    let mut j = open_end + 1;
    while j + close_marker.len() <= bytes.len() {
        if &bytes[j..j + close_marker.len()] == close_marker.as_slice() {
            return Some((open_start, open_end + 1, j, j + close_marker.len()));
        }
        j += 1;
    }
    None
}

fn text_object_inner_tag(ctx: &TextObjectContext) -> Result<ProtoRange, CommandError> {
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let cursor = ctx
        .buffer
        .position_to_byte(ctx.at)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    let Some((_, open_end, close_start, _)) = find_enclosing_tag(bytes, cursor) else {
        return Ok(ProtoRange::new(ctx.at, ctx.at));
    };
    let start_pos = ctx
        .buffer
        .byte_to_position(open_end)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    let end_pos = ctx
        .buffer
        .byte_to_position(close_start)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    Ok(ProtoRange::new(start_pos, end_pos))
}

fn text_object_around_tag(ctx: &TextObjectContext) -> Result<ProtoRange, CommandError> {
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let cursor = ctx
        .buffer
        .position_to_byte(ctx.at)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    let Some((open_start, _, _, close_end)) = find_enclosing_tag(bytes, cursor) else {
        return Ok(ProtoRange::new(ctx.at, ctx.at));
    };
    let start_pos = ctx
        .buffer
        .byte_to_position(open_start)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    let end_pos = ctx
        .buffer
        .byte_to_position(close_end)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    Ok(ProtoRange::new(start_pos, end_pos))
}

fn text_object_around_brackets(
    ctx: &TextObjectContext,
    open: char,
    close: char,
) -> Result<ProtoRange, CommandError> {
    let text = ctx.buffer.as_string();
    let bytes = text.as_bytes();
    let cursor = ctx
        .buffer
        .position_to_byte(ctx.at)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    let Some((l, r)) = find_bracket_pair(bytes, cursor, open as u8, close as u8) else {
        return Ok(ProtoRange::new(ctx.at, ctx.at));
    };
    let start_pos = ctx
        .buffer
        .byte_to_position(l)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    let end_pos = ctx
        .buffer
        .byte_to_position(r + 1)
        .map_err(|_| CommandError::InvalidArgs("position out of bounds"))?;
    Ok(ProtoRange::new(start_pos, end_pos))
}

// ---- Operator: delete ----
//
// Vim's `d` -- delete the bytes covered by the target range. Also yanks
// the deleted content into the unnamed register (vim's behavior). The
// returned Effect is a `Many` so callers see both the buffer mutation
// and the yank in a single dispatched commit.

fn operator_delete(ctx: &mut OperatorContext) -> Result<Effect, CommandError> {
    if ctx.range.is_empty() {
        return Ok(Effect::None);
    }
    // Slice 8.i.4.g: vim's `dd` / `Ndd` consumes the line(s) AND
    // the trailing newline so the line count drops by `count`.
    // Pure-content delete (charwise / non-linewise visual)
    // continues to leave the line structure intact, matching
    // `dw` / `d$` semantics.
    let edit_range = if ctx.linewise {
        extend_linewise_range(ctx.document.buffer(), ctx.range)
    } else {
        ctx.range
    };
    // Yank content always ends with `\n` for linewise -- the
    // register kind drives paste behaviour, but the content
    // string itself follows vim's clipboard convention. The
    // edit consumes the same range, so this keeps yank-on-
    // delete and the actual edit aligned.
    let yanked = if ctx.linewise {
        let mut s = ctx.document.buffer().slice(ctx.range)?;
        if !s.ends_with('\n') {
            s.push('\n');
        }
        s
    } else {
        ctx.document.buffer().slice(ctx.range)?
    };
    let edit = Edit::delete(edit_range);
    let applied = ctx.document.apply_edit(edit)?;
    let yank_kind = if ctx.linewise {
        YankKind::Linewise
    } else {
        YankKind::Charwise
    };
    let mut effects = vec![
        Effect::Edits(vec![applied]),
        Effect::Yank {
            register: ctx.register,
            content: yanked,
            kind: yank_kind,
            // Delete populates registers but is NOT an explicit yank —
            // it must not mirror to the system clipboard (yank-only rule).
            explicit_yank: false,
        },
    ];
    // VM.3m: after a LINEWISE delete vim puts the cursor on the first non-blank
    // of the line that moved up (`dd` from 1,6 lands on 1,5 of a 4-indented
    // line; `dk` and `2dj` likewise). A charwise delete leaves it at the edit's
    // start, which the host already does from `Effect::Edits`, so only the
    // linewise case needs saying. The buffer here is the one after the edit.
    if ctx.linewise {
        let buffer = ctx.document.buffer();
        let line = ctx.range.start.line.min(last_addressable_line(buffer));
        effects.push(Effect::CursorMove(first_non_blank_position(buffer, line)));
    }
    Ok(Effect::Many(effects))
}

// ---- Operator: change ----
//
// Vim's `c` -- delete the target range, yank it (matching delete's
// behavior), and enter Insert mode at the deleted position. Composition
// expressed in the Effect, not a flag on the spec.

fn operator_change(ctx: &mut OperatorContext) -> Result<Effect, CommandError> {
    if ctx.range.is_empty() {
        // No-op change still drops into Insert (vim does this for `cw` on
        // an empty buffer / past EOF).
        return Ok(Effect::EnterMode(crate::modal::ModalState::Insert));
    }
    let yanked = ctx.document.buffer().slice(ctx.range)?;
    let edit = Edit::delete(ctx.range);
    let applied = ctx.document.apply_edit(edit)?;
    let yank_kind = if ctx.linewise {
        YankKind::Linewise
    } else {
        YankKind::Charwise
    };
    Ok(Effect::Many(vec![
        Effect::Edits(vec![applied]),
        Effect::Yank {
            register: ctx.register,
            content: yanked,
            kind: yank_kind,
            // Change deletes + yanks the range like delete — not an
            // explicit yank, so no clipboard mirror (yank-only rule).
            explicit_yank: false,
        },
        Effect::EnterMode(crate::modal::ModalState::Insert),
    ]))
}

// ---- Operator: replace-char (vim's `r{char}` and Visual `r`) ----
//
// Overwrite each non-newline char in the target range with the captured
// replacement char, producing one `Effect::Edits` -- so both renderers
// pick it up through the standard edit path with no per-renderer arm.
//
// One body serves both entry points:
//
// * Normal `Nr{char}`: the keymap binds the range to `char_right x count`
//   (pre-clamped to the current line, exactly as `x` = delete+char_right).
//   Vim's "no-op when fewer than N chars remain" falls out of the
//   `n_chars < count` guard -- the clamped range simply holds fewer chars
//   than the requested count. Stays in Normal.
// * Visual `r{char}`: dispatched with `Range::Selection` (count defaults
//   to 1), so the guard degenerates to "no-op on an empty span" and every
//   selected char is overwritten. Blockwise routes per-row via
//   `blockwise_per_row`. The host auto-exits Visual after any operator
//   (like `d` / `c` / `y`), so no explicit mode transition is emitted.
//
// Newlines inside the range are preserved, so a charwise / linewise
// multi-line selection keeps its line structure (vim replaces characters,
// never line breaks).
fn operator_replace_char(ctx: &mut OperatorContext) -> Result<Effect, CommandError> {
    let replacement = match &ctx.args {
        crate::args::Args::Char(c) => *c,
        _ => return Err(CommandError::InvalidArgs("r requires Args::Char")),
    };
    if ctx.range.is_empty() {
        return Ok(Effect::None);
    }
    let text = ctx.document.buffer().slice(ctx.range)?;
    let n_chars = text.chars().filter(|c| *c != '\n').count() as u32;
    // Vim's `Nr{char}` requires N characters on the line; a too-large
    // count is a no-op (vim bells). For Visual the count is 1, so any
    // non-empty span replaces.
    if n_chars < ctx.count.get().max(1) {
        return Ok(Effect::None);
    }
    let replaced: String = text
        .chars()
        .map(|c| if c == '\n' { '\n' } else { replacement })
        .collect();
    let applied = ctx
        .document
        .apply_edit(Edit::replace(ctx.range, replaced))?;
    Ok(Effect::Edits(vec![applied]))
}

// ---- Operator: yank ----
//
// Vim's `y` -- copy the target range into the unnamed register without
// touching the buffer.

fn operator_yank(ctx: &mut OperatorContext) -> Result<Effect, CommandError> {
    if ctx.range.is_empty() {
        return Ok(Effect::None);
    }
    // Slice 8.i.4.g: vim's `yy` / `Nyy` yanks line(s) WITH the
    // trailing newline so the register content can be pasted
    // linewise without splicing newlines in by hand. Append `\n`
    // when missing rather than walking the buffer for the
    // trailing newline -- linewise yank on the last line still
    // gets a trailing `\n` to match the canonical convention.
    let content = if ctx.linewise {
        let mut s = ctx.document.buffer().slice(ctx.range)?;
        if !s.ends_with('\n') {
            s.push('\n');
        }
        s
    } else {
        ctx.document.buffer().slice(ctx.range)?
    };
    let kind = if ctx.linewise {
        YankKind::Linewise
    } else {
        YankKind::Charwise
    };
    // Yank ALSO populates `"0` per vim semantics. Two Effect::Yanks --
    // first the requested register (which the App layer's store_yank
    // also mirrors into the unnamed register), then "0.
    Ok(Effect::Many(vec![
        Effect::Yank {
            register: ctx.register,
            content: content.clone(),
            kind,
            // The one explicit-yank write: eligible for the clipboard
            // mirror under the `clipboard` option.
            explicit_yank: true,
        },
        Effect::Yank {
            register: crate::register::Register::Numbered(0),
            content,
            kind,
            // The `"0` mirror is a register-only bookkeeping write; the
            // primary write above already handled the clipboard.
            explicit_yank: false,
        },
        // VM.3m: vim leaves the cursor at the start of what was yanked — which
        // for `yy` / `2yy` / `yj` is where it already was, and for `yk` / `yb` /
        // `y{` / `yip` is the start of the region. `origin` is that start before
        // linewise expansion, so `yk` keeps its column.
        Effect::CursorMove(clamp_into_buffer(ctx.document.buffer(), ctx.origin)),
    ]))
}

// ---- Indent operators (>, <) ----

/// Shared body of `>` and `<`: shift every line in the range by
/// `levels` indent steps.
///
/// IN.0 replaced a hardcoded `"    "` with `ctx.indent`, which changes
/// the model as well as the width. Indentation is now measured in
/// **display columns** and the whole leading-whitespace run is
/// re-rendered, rather than bytes being spliced on or off the front:
///
/// - a tab and `tabstop` spaces are the same indent and must shift
///   identically -- a byte splice cannot see that;
/// - `expandtab` decides what the *result* is made of, so a shifted
///   line has to be re-rendered, not patched;
/// - a `shiftwidth` that is not a multiple of `tabstop` is only
///   representable if the prefix can be rebuilt as tabs-plus-remainder.
///
/// Vim behaves the same way -- `>>` normalises the indent it touches.
///
/// The whole operation lands as a single undo unit: the per-line edits
/// are built up front and committed via `apply_edit_batch`, so `2>>` or
/// a visual `>` over N lines is one `u` away from undone, not N.
fn shift_indent(ctx: &mut OperatorContext, levels: i32) -> Result<Effect, CommandError> {
    if ctx.range.is_empty() {
        return Ok(Effect::None);
    }
    let first_line = ctx.range.start.line;
    let last_line = ctx.range.end.line;
    let buffer_text = ctx.document.text();
    let lines: Vec<&str> = buffer_text.split_inclusive('\n').collect();

    // Bottom-up so earlier edits don't shift later positions when the
    // buffer applies the batch in order.
    let mut edits: Vec<Edit> = Vec::new();
    for line in (first_line..=last_line).rev() {
        let line_text = lines
            .get(line as usize)
            .map(|l| l.trim_end_matches('\n'))
            .unwrap_or("");
        // `None` covers a blank line (vim leaves those alone rather
        // than parking trailing whitespace on a line the user never
        // typed into) and a shift whose rendering is byte-identical to
        // what is already there (a no-op edit still costs an undo entry
        // and a render invalidation).
        let Some((old_len, rendered)) = ctx.indent.reindented_prefix(line_text, levels) else {
            continue;
        };
        let range = lattice_protocol::position::Range::new(
            Position::new(line, 0),
            Position::new(line, old_len as u32),
        );
        edits.push(Edit::replace(range, rendered));
    }
    if edits.is_empty() {
        return Ok(Effect::None);
    }
    let applied = ctx.document.apply_edit_batch(edits)?;
    // Restore top-down ordering for the returned AppliedEdits so
    // downstream `handle_edits` lands the cursor on the topmost
    // line, matching the previous one-edit-at-a-time behavior.
    let mut applied = applied;
    applied.reverse();
    Ok(landing_on_first_non_blank(ctx, first_line, applied))
}

/// Vim leaves the cursor on the first non-blank of the FIRST line a
/// whole-line operator touched (`:h >`), which is where `>>`, `<ip` and `=ap`
/// all end up. The edits alone land it at the edit's start — column 0 of the
/// topmost line — so the move is appended, exactly as a linewise delete does.
///
/// Read AFTER the edits: the indent that decides "first non-blank" is the one
/// the operator just wrote, not the one it replaced.
fn landing_on_first_non_blank(
    ctx: &mut OperatorContext,
    first_line: u32,
    applied: Vec<lattice_core::buffer::AppliedEdit>,
) -> Effect {
    let buffer = ctx.document.buffer();
    let line = first_line.min(last_addressable_line(buffer));
    let at = first_non_blank_position(buffer, line);
    Effect::Many(vec![Effect::Edits(applied), Effect::CursorMove(at)])
}

/// Vim's `>` -- add one indent level to each line in the range.
fn operator_indent_right(ctx: &mut OperatorContext) -> Result<Effect, CommandError> {
    shift_indent(ctx, 1)
}

/// Vim's `<` -- remove one indent level from each line in the range,
/// clamped at column 0.
fn operator_indent_left(ctx: &mut OperatorContext) -> Result<Effect, CommandError> {
    shift_indent(ctx, -1)
}

/// Vim's `=` -- reindent each line in the range to the depth the
/// structure says it should have.
///
/// **Indent-only, and that is the whole design decision** (auto-indent.md
/// §7). `=` adjusts leading whitespace and touches nothing else. It is
/// deliberately NOT wired to a formatter: LSP `rangeFormatting`, rustfmt
/// and prettier all *reformat* — they move line breaks and rewrite
/// spacing — so `=ap` would mean "rewrite this paragraph" rather than
/// "reindent it". An operator whose effect is unbounded rewriting cannot
/// be composed with motions safely, which is what makes the vim grammar
/// work at all. Full reformatting lives on `:format`.
///
/// Lines the resolver has no answer for are **left untouched** rather
/// than guessed at, so `=` over a range containing a syntax error or a
/// heredoc reindents what it understands and does not mangle the rest.
///
/// One undo unit for the whole range, like its `>` / `<` siblings.
fn operator_reindent(ctx: &mut OperatorContext) -> Result<Effect, CommandError> {
    if ctx.range.is_empty() {
        return Ok(Effect::None);
    }
    // RF.5b: `format.indent` names a non-native provider. Checked BEFORE
    // the resolver, because a chain pointing at an external indenter must
    // work on a buffer with no tree — that is most of why someone would
    // configure one.
    if !ctx.native_format.indent {
        return Ok(Effect::AppAction(
            crate::app_effect::AppEffect::FormatRange {
                intent: lattice_core::FormatIntent::Indent,
                start_line: ctx.range.start.line,
                end_line: ctx.range.end.line,
            },
        ));
    }
    let Some(resolver) = ctx.indent_resolver else {
        // No structural source: `=` is a no-op rather than a guess.
        // Falling back to the lexical bridge here would be wrong --
        // that bridge answers "where would a NEW line go", which is a
        // different question from "where does this EXISTING line
        // belong", and using it would drift a whole range toward
        // whatever the first line happened to have.
        return Ok(Effect::None);
    };
    let first_line = ctx.range.start.line;
    let last_line = ctx.range.end.line;
    let buffer_text = ctx.document.text();
    let lines: Vec<&str> = buffer_text.split_inclusive('\n').collect();

    // Bottom-up so earlier edits do not shift later positions when the
    // batch applies in order.
    let mut edits: Vec<Edit> = Vec::new();
    for line in (first_line..=last_line).rev() {
        ctx.cancel.check()?;
        let line_text = lines
            .get(line as usize)
            .map(|l| l.trim_end_matches('\n'))
            .unwrap_or("");
        // Blank lines carry no structure to align; reindenting them
        // would only add trailing whitespace.
        if lattice_core::IndentUnit::is_blank(line_text) {
            continue;
        }
        let Some(levels) = resolver.levels_for_line(line) else {
            continue;
        };
        let target = ctx.indent.shift(0, levels);
        let rendered = ctx.indent.render(target);
        let old_len = lattice_core::IndentUnit::indent_len(line_text);
        if rendered.as_bytes() == &line_text.as_bytes()[..old_len] {
            continue;
        }
        let range = lattice_protocol::position::Range::new(
            Position::new(line, 0),
            Position::new(line, old_len as u32),
        );
        edits.push(Edit::replace(range, rendered));
    }
    if edits.is_empty() {
        return Ok(Effect::None);
    }
    let applied = ctx.document.apply_edit_batch(edits)?;
    let mut applied = applied;
    applied.reverse();
    Ok(landing_on_first_non_blank(ctx, first_line, applied))
}

/// Vim's `gq` **and** `gw` — reflow the range to `textwidth`.
///
/// One operator behind two chords. In vim they differ only in cursor
/// placement (`gq` leaves it on the last formatted line, `gw` restores
/// it), which is two mnemonics for one operation and a reliable source
/// of "which one was it again". This preserves the cursor — `gw`'s
/// behaviour, because it is the one people actually want — and binds
/// both chords to it. Zed's vim keymap made the identical call.
///
/// **Reflow, not reformat.** It moves line breaks and normalises
/// interior whitespace within a paragraph; it does not reindent, reorder
/// or parse. That is what keeps it composable with motions, the same
/// property `=` is protected for in auto-indent.md §7.
///
/// A range that reflows to itself produces **no edit at all** rather
/// than an identical one — pressing `gqap` on an already-filled
/// paragraph must not push an undo step the user then has to press `u`
/// to get past.
///
/// One undo unit for the whole range, like `=` and its `>` / `<`
/// siblings.
fn operator_reflow(ctx: &mut OperatorContext) -> Result<Effect, CommandError> {
    if ctx.range.is_empty() {
        return Ok(Effect::None);
    }
    let first_line = ctx.range.start.line;

    let buffer_text = ctx.document.text();
    let all: Vec<&str> = buffer_text.split('\n').collect();
    let last_line = ctx.range.end.line.min(all.len().saturating_sub(1) as u32);
    if first_line > last_line {
        return Ok(Effect::None);
    }
    ctx.cancel.check()?;

    // RF.5b: the buffer's `format.reflow` chain says someone else owns
    // this. Hand the resolved range back rather than editing — an LSP
    // round-trip and a process spawn are both asynchronous, and the
    // grammar layer has neither client nor runtime. Same shape `g/`
    // uses to hand back a query instead of running a search.
    if !ctx.native_format.reflow {
        return Ok(Effect::AppAction(
            crate::app_effect::AppEffect::FormatRange {
                intent: lattice_core::FormatIntent::Reflow,
                start_line: first_line,
                end_line: last_line,
            },
        ));
    }

    let slice: Vec<&str> = all[first_line as usize..=last_line as usize].to_vec();
    let cfg = crate::reflow::ReflowConfig {
        textwidth: ctx.textwidth.columns(),
        line_comment: ctx.comment_syntax.and_then(|c| c.line.as_deref()),
    };
    let out = crate::reflow::reflow_range(&slice, cfg);
    ctx.cancel.check()?;

    // Identical output ⇒ no edit. Compared line by line rather than as
    // one joined string so a trailing-newline difference at the range
    // edge cannot masquerade as a change.
    if out.len() == slice.len() && out.iter().zip(slice.iter()).all(|(a, b)| a == b) {
        return Ok(Effect::None);
    }

    // One replace over the whole range. Output lines do not correspond
    // one-to-one with input lines (that is what filling means), so a
    // per-line edit set would have to encode the joins and splits
    // itself. One edit is also one undo unit by construction.
    let end_col = all
        .get(last_line as usize)
        .map(|l| l.len() as u32)
        .unwrap_or(0);
    let range = lattice_protocol::position::Range::new(
        Position::new(first_line, 0),
        Position::new(last_line, end_col),
    );
    let applied = ctx
        .document
        .apply_edit_batch(vec![Edit::replace(range, out.join("\n"))])?;
    Ok(Effect::Edits(applied))
}

/// `g=` — run the buffer's `format.reformat` chain over the range.
///
/// **Not a vim chord**, and it does not pretend to be. It exists because
/// `:format` had no operator form, so vim users reach for `gq` — the
/// only operator-shaped formatting verb available — and are then
/// disappointed when a reformatter declines to re-wrap their prose
/// (`text-reflow.md` §5). Giving the reformatter its own verb is the fix;
/// overloading `gq` is not.
///
/// Always delegates: every rung of a reformat chain is asynchronous (an
/// LSP round-trip, a process spawn), so there is nothing for the grammar
/// layer to do but hand back the range. That is why this has no native
/// branch where `=` and `gq` do.
/// VM.3h: `zf{motion}` / `{Visual}zf` — a closed fold over the whole lines the
/// range covers. Vim folds whole lines even for a charwise `v` selection.
///
/// A Visual selection or a linewise range already names whole lines, so its
/// lines are taken as they are. A `V` selection ends at its last line's
/// length, which is byte 0 when that line is empty, and the half-open rule
/// would wrongly drop it. A motion's span goes through
/// [`crate::range::span_to_whole_lines`], whose byte-0 rule is vim's
/// exclusive-linewise rule (`zf}` stops before the blank line).
fn operator_create_fold(ctx: &mut OperatorContext) -> Result<Effect, CommandError> {
    let (s, e) = (ctx.range.start, ctx.range.end);
    let whole_lines = ctx.linewise || ctx.document.selections().primary().visual.is_some();
    let (start_line, end_line) = if whole_lines {
        (s.line.min(e.line), s.line.max(e.line))
    } else {
        crate::range::span_to_whole_lines(s.line, s.byte, e.line, e.byte)
    };
    Ok(Effect::AppAction(
        crate::app_effect::AppEffect::CreateFold {
            start_line,
            end_line,
        },
    ))
}

fn operator_reformat(ctx: &mut OperatorContext) -> Result<Effect, CommandError> {
    if ctx.range.is_empty() {
        return Ok(Effect::None);
    }
    Ok(Effect::AppAction(
        crate::app_effect::AppEffect::FormatRange {
            intent: lattice_core::FormatIntent::Reformat,
            start_line: ctx.range.start.line,
            end_line: ctx.range.end.line,
        },
    ))
}

// ---- Case operators (gU, gu, g~) ----

fn case_transform_in_range<F: Fn(u8) -> u8>(
    ctx: &mut OperatorContext,
    map: F,
) -> Result<Effect, CommandError> {
    if ctx.range.is_empty() {
        return Ok(Effect::None);
    }
    let original = ctx.document.buffer().slice(ctx.range)?;
    let transformed: String = original
        .as_bytes()
        .iter()
        .map(|&b| map(b) as char)
        .collect();
    if transformed == original {
        return Ok(Effect::None);
    }
    let edit = Edit::replace(ctx.range, &transformed);
    let applied = ctx.document.apply_edit(edit)?;
    Ok(Effect::Edits(vec![applied]))
}

fn operator_upper(ctx: &mut OperatorContext) -> Result<Effect, CommandError> {
    case_transform_in_range(ctx, |b| b.to_ascii_uppercase())
}

fn operator_lower(ctx: &mut OperatorContext) -> Result<Effect, CommandError> {
    case_transform_in_range(ctx, |b| b.to_ascii_lowercase())
}

fn operator_toggle_case(ctx: &mut OperatorContext) -> Result<Effect, CommandError> {
    case_transform_in_range(ctx, |b| match b {
        b'a'..=b'z' => b - 32,
        b'A'..=b'Z' => b + 32,
        other => other,
    })
}

/// `g/` (a Lattice extension, not vim-canonical): the project-search
/// operator. Read-only -- mirrors yank's no-edit shape. It slices the text
/// the motion / text object spans and emits the SAME `SearchTrigger` effect
/// the `:search` ex-command uses, so `g/{motion}` and `:search {text}` are
/// identical by construction. The query is used verbatim (literal,
/// case-insensitive -- project search's defaults); no regex escaping. An
/// empty or whitespace-only range is a no-op -- no empty search is launched.
fn operator_search(ctx: &mut OperatorContext) -> Result<Effect, CommandError> {
    if ctx.range.is_empty() {
        return Ok(Effect::None);
    }
    let query = ctx.document.buffer().slice(ctx.range)?;
    if query.trim().is_empty() {
        return Ok(Effect::None);
    }
    Ok(Effect::AppAction(
        crate::app_effect::AppEffect::SearchTrigger { query },
    ))
}

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::panic)]
    use super::*;
    use crate::CancellationToken;
    use crate::command::{CommandInvocation, Count};
    use crate::dispatcher::execute;
    use crate::effect::Effect;
    use crate::target::Target;
    use lattice_core::Document;

    fn fixture(text: &str) -> (CommandRegistry, Builtins, Document) {
        let mut r = CommandRegistry::new();
        let b = populate(&mut r);
        let d = Document::from_text(text);
        (r, b, d)
    }

    // Pull the query out of the `g/` operator's effect (a project-search
    // trigger), panicking on any other shape.
    fn search_query(eff: Effect) -> String {
        match eff {
            Effect::AppAction(crate::app_effect::AppEffect::SearchTrigger { query }) => query,
            other => panic!("expected SearchTrigger, got {other:?}"),
        }
    }

    // ---- RF.2: the reflow operator (`gq` / `gw`) ----

    /// Run `operator:reflow` over a whole-buffer range and return the
    /// resulting text. `Range::Whole` is the operator-composition path,
    /// so this exercises the real dispatch rather than calling `apply`.
    fn reflow_whole(text: &str, textwidth: usize, leader: Option<&str>) -> (String, Effect) {
        let (registry, b, mut doc) = fixture(text);
        let cancel = CancellationToken::never();
        let cs = leader.map(|l| crate::CommentSyntax {
            line: Some(l.to_string()),
            block: None,
        });
        let env = crate::registry::GrammarEnv {
            textwidth: lattice_core::WrapWidth(textwidth),
            comment_syntax: cs.as_ref(),
            ..Default::default()
        };
        let inv = CommandInvocation::of(b.reflow.0).with_range(crate::Range::Whole);
        let eff = crate::dispatcher::execute_with_env(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 0),
            inv,
            &cancel,
            env,
        )
        .unwrap();
        (doc.text().to_string(), eff)
    }

    #[test]
    fn reflow_fills_a_paragraph_to_textwidth() {
        let (out, _) = reflow_whole("aaa bbb ccc ddd eee fff\n", 11, None);
        assert_eq!(out, "aaa bbb ccc\nddd eee fff\n");
    }

    #[test]
    fn reflow_keeps_a_comment_leader() {
        let (out, _) = reflow_whole("/// aaa bbb ccc ddd\n", 12, Some("//"));
        assert_eq!(out, "/// aaa bbb\n/// ccc ddd\n");
    }

    /// A `gq` on an already-filled paragraph must produce NO edit — not
    /// an identical one. An edit that changes nothing still pushes an
    /// undo step, so the user presses `u` and watches nothing happen,
    /// twice.
    #[test]
    fn reflow_that_changes_nothing_produces_no_edit_at_all() {
        let (out, eff) = reflow_whole("aaa bbb\n", 80, None);
        assert_eq!(out, "aaa bbb\n");
        assert!(
            matches!(eff, Effect::None),
            "an already-filled paragraph must not push an undo step, got {eff:?}"
        );
    }

    #[test]
    fn reflow_of_an_empty_range_is_a_noop() {
        let (registry, b, mut doc) = fixture("");
        let cancel = CancellationToken::never();
        let inv = CommandInvocation::of(b.reflow.0)
            .with_target(Target::TextObject(b.inner_word, crate::args::Args::None));
        let eff = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 0),
            inv,
            &cancel,
        )
        .unwrap();
        assert!(matches!(eff, Effect::None), "got {eff:?}");
    }

    /// The whole range is ONE edit, which is what makes it one undo
    /// unit. Asserted on the effect rather than by pressing `u`, because
    /// the grammar layer has no undo — the host's test does that half
    /// (RF.2's TUI peer).
    #[test]
    fn reflow_emits_one_edit_for_the_whole_range() {
        let (_, eff) = reflow_whole("aaa bbb ccc ddd\n", 7, None);
        match eff {
            Effect::Edits(edits) => assert_eq!(
                edits.len(),
                1,
                "filling joins and splits lines, so a per-line edit set would \
                 have to encode that itself; one edit is also one undo unit \
                 by construction"
            ),
            other => panic!("expected Edits, got {other:?}"),
        }
    }

    /// Reflow moves line breaks. It must NOT reindent — that is `=`'s
    /// job, and the separation is what keeps each verb composable with
    /// motions (auto-indent.md §7).
    #[test]
    fn reflow_does_not_reindent() {
        let (out, _) = reflow_whole("        aaa bbb ccc ddd\n", 20, None);
        assert_eq!(
            out, "        aaa bbb ccc\n        ddd\n",
            "the paragraph's indent is preserved verbatim, not normalised"
        );
    }

    /// `gq` and `gw` are the same operator, so the doubled and mixed
    /// forms cannot disagree: there is only one id behind all four.
    #[test]
    fn gq_and_gw_are_one_operator() {
        let (_, b, _) = fixture("x\n");
        // A single `OperatorId` exists; the two chords are bound to one
        // prefix action in the host (keymap_normal.rs). This pins the
        // grammar half: nothing here distinguishes a `gq` reflow from a
        // `gw` one, so `gqq`, `gww`, `gqw` and `gwq` cannot drift.
        assert_ne!(b.reflow.0, b.reindent.0, "reflow is not reindent");
    }

    // ---- RF.5b / RF.6: delegation to a non-native provider ----

    /// The operator id MUST come from the same registry the dispatch
    /// runs against — command ids are process-global counters, so an id
    /// minted by one `fixture()` is simply absent from another's
    /// registry and resolves as `UnknownCommand`.
    fn run_whole(
        text: &str,
        pick: impl Fn(&Builtins) -> crate::registry::OperatorId,
        native: crate::registry::NativeFormatIntents,
    ) -> Effect {
        let (registry, b, mut doc) = fixture(text);
        let op = pick(&b);
        let cancel = CancellationToken::never();
        let env = crate::registry::GrammarEnv {
            textwidth: lattice_core::WrapWidth(11),
            native_format: native,
            ..Default::default()
        };
        let inv = CommandInvocation::of(op.0).with_range(crate::Range::Whole);
        crate::dispatcher::execute_with_env(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 0),
            inv,
            &cancel,
            env,
        )
        .unwrap()
    }

    /// The default env is native for everything, so the ~40 hand-built
    /// call sites — and the shipped configuration — never delegate.
    #[test]
    fn the_default_env_formats_natively() {
        assert_eq!(
            crate::registry::NativeFormatIntents::default(),
            crate::registry::NativeFormatIntents {
                indent: true,
                reflow: true
            }
        );
    }

    /// `format.reflow` naming a non-native provider makes `gq` hand back
    /// its RANGE instead of editing — the operator cannot run an LSP
    /// round-trip or a process spawn itself.
    #[test]
    fn a_non_native_reflow_chain_hands_the_range_to_the_host() {
        let eff = run_whole(
            "aaa bbb ccc ddd\n",
            |b| b.reflow,
            crate::registry::NativeFormatIntents {
                indent: true,
                reflow: false,
            },
        );
        match eff {
            Effect::AppAction(crate::app_effect::AppEffect::FormatRange {
                intent,
                start_line,
                end_line,
            }) => {
                assert_eq!(intent, lattice_core::FormatIntent::Reflow);
                // One content line: a trailing newline is not an
                // addressable line, so `Range::Whole` is 0..=0 here.
                assert_eq!((start_line, end_line), (0, 0));
            }
            other => panic!("expected FormatRange, got {other:?}"),
        }
    }

    /// …and a native chain still edits, so delegation is opt-in rather
    /// than the new default. Asserting only the delegating case would
    /// pass with the operator ALWAYS delegating.
    #[test]
    fn a_native_reflow_chain_still_edits_in_place() {
        let eff = run_whole(
            "aaa bbb ccc ddd\n",
            |b| b.reflow,
            crate::registry::NativeFormatIntents::default(),
        );
        assert!(
            matches!(eff, Effect::Edits(_)),
            "a native chain must edit, got {eff:?}"
        );
    }

    /// `=` delegates on the SAME check, and does it before consulting
    /// the indent resolver — an external indenter is most of the reason
    /// to configure one, and it has to work on a buffer with no tree.
    #[test]
    fn a_non_native_indent_chain_delegates_without_a_tree() {
        let eff = run_whole(
            "    aaa\n",
            |b| b.reindent,
            crate::registry::NativeFormatIntents {
                indent: false,
                reflow: true,
            },
        );
        match eff {
            Effect::AppAction(crate::app_effect::AppEffect::FormatRange { intent, .. }) => {
                assert_eq!(intent, lattice_core::FormatIntent::Indent);
            }
            other => panic!("expected FormatRange, got {other:?}"),
        }
        // The env above carries NO `indent_resolver`, which is the
        // point: native `=` would no-op here, and delegation must not.
    }

    /// `g=` always delegates — every rung of a reformat chain is
    /// asynchronous, so there is no native branch for it to take.
    #[test]
    fn g_equals_always_hands_the_range_to_the_host() {
        let eff = run_whole(
            "let x=1;\n",
            |b| b.reformat,
            crate::registry::NativeFormatIntents::default(),
        );
        match eff {
            Effect::AppAction(crate::app_effect::AppEffect::FormatRange { intent, .. }) => {
                assert_eq!(intent, lattice_core::FormatIntent::Reformat);
            }
            other => panic!("expected FormatRange even with a native env, got {other:?}"),
        }
    }

    // ---- VM.3h: `zf` is an operator ----

    /// Run `operator:create-fold` from `from` with a motion target and return
    /// the fold span it asks the host for.
    fn fold_span_for_motion(
        text: &str,
        from: Position,
        pick: impl Fn(&Builtins) -> crate::registry::MotionId,
    ) -> (u32, u32) {
        let (registry, b, mut doc) = fixture(text);
        let cancel = CancellationToken::never();
        let inv = CommandInvocation::of(b.create_fold.0).with_target(
            crate::target::Target::Motion(pick(&b), crate::args::Args::None),
        );
        let eff = crate::dispatcher::execute_with_env(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            from,
            inv,
            &cancel,
            crate::registry::GrammarEnv::default(),
        )
        .expect("zf dispatches");
        match eff {
            Effect::AppAction(crate::app_effect::AppEffect::CreateFold {
                start_line,
                end_line,
            }) => (start_line, end_line),
            other => panic!("expected CreateFold, got {other:?}"),
        }
    }

    /// `zfj` folds the cursor line and the next, from column 0 as well as
    /// mid-line. Vim ground truth: `zfj` folds two lines.
    #[test]
    fn zf_j_folds_two_whole_lines() {
        let text = "one\ntwo\nthree\n";
        assert_eq!(
            fold_span_for_motion(text, Position::new(0, 0), |b| b.line_down),
            (0, 1)
        );
        assert_eq!(
            fold_span_for_motion(text, Position::new(0, 2), |b| b.line_down),
            (0, 1)
        );
    }

    /// `zf}` stops before the blank line: `}` is exclusive and ends at byte 0
    /// of it, which is vim's exclusive-linewise rule.
    #[test]
    fn zf_paragraph_forward_stops_before_the_blank_line() {
        let text = "a\nb\n\nc\n";
        assert_eq!(
            fold_span_for_motion(text, Position::new(0, 0), |b| b.paragraph_forward),
            (0, 1)
        );
    }

    /// A linewise range names whole lines, so an empty last line isn't read
    /// as a half-open end.
    #[test]
    fn zf_over_a_linewise_range_keeps_an_empty_last_line() {
        let (registry, b, mut doc) = fixture("a\n\n");
        let cancel = CancellationToken::never();
        let inv = CommandInvocation::of(b.create_fold.0).with_range(crate::Range::Whole);
        let eff = crate::dispatcher::execute_with_env(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 0),
            inv,
            &cancel,
            crate::registry::GrammarEnv::default(),
        )
        .expect("zf dispatches");
        match eff {
            Effect::AppAction(crate::app_effect::AppEffect::CreateFold {
                start_line,
                end_line,
            }) => assert_eq!((start_line, end_line), (0, 1)),
            other => panic!("expected CreateFold, got {other:?}"),
        }
    }

    #[test]
    fn g_equals_over_an_empty_range_is_a_noop() {
        let (registry, b, mut doc) = fixture("");
        let cancel = CancellationToken::never();
        let inv = CommandInvocation::of(b.reformat.0)
            .with_target(Target::TextObject(b.inner_word, crate::args::Args::None));
        let eff = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 0),
            inv,
            &cancel,
        )
        .unwrap();
        assert!(matches!(eff, Effect::None), "got {eff:?}");
    }

    #[test]
    fn search_operator_greps_word_under_cursor() {
        // g/iw -> project-search for the word under the cursor.
        let (registry, b, mut doc) = fixture("let needle = 1;\n");
        let cancel = CancellationToken::never();
        let cursor = Position::new(0, 4); // on `needle`
        let inv = CommandInvocation::of(b.search.0)
            .with_target(Target::TextObject(b.inner_word, crate::args::Args::None));
        let eff = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            cursor,
            inv,
            &cancel,
        )
        .unwrap();
        assert_eq!(search_query(eff), "needle");
    }

    #[test]
    fn search_operator_greps_quoted_string() {
        // g/i" -> project-search for the quoted-string contents.
        let (registry, b, mut doc) = fixture("let s = \"find me\";\n");
        let cancel = CancellationToken::never();
        let cursor = Position::new(0, 10); // inside the quotes
        let inv = CommandInvocation::of(b.search.0).with_target(Target::TextObject(
            b.inner_quote_double,
            crate::args::Args::None,
        ));
        let eff = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            cursor,
            inv,
            &cancel,
        )
        .unwrap();
        assert_eq!(search_query(eff), "find me");
    }

    #[test]
    fn search_operator_empty_range_is_noop() {
        // A motion that spans nothing produces no search.
        let (registry, b, mut doc) = fixture("\n");
        let cancel = CancellationToken::never();
        let cursor = Position::new(0, 0);
        let inv = CommandInvocation::of(b.search.0)
            .with_target(Target::TextObject(b.inner_word, crate::args::Args::None));
        let eff = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            cursor,
            inv,
            &cancel,
        )
        .unwrap();
        assert!(
            matches!(eff, Effect::None),
            "empty range must be a no-op, got {eff:?}"
        );
    }

    #[test]
    fn comment_object_around_keeps_markers_inner_strips_leader() {
        use crate::dispatcher::execute_with_env;
        use crate::registry::{CommentSyntax, GrammarEnv};
        // line 1 `    // first`, line 2 `    // second` form one block.
        let src = "fn f() {\n    // first\n    // second\n    let x = 1;\n}\n";
        let (registry, b, mut doc) = fixture(src);
        let cs = CommentSyntax {
            line: Some("//".to_string()),
            block: None,
        };
        let cancel = CancellationToken::never();
        let cursor = Position::new(1, 8); // on `// first`
        // The yank operator yields `Effect::Many([Yank-unnamed,
        // Yank-numbered])`; pull the content out of whichever shape.
        fn yanked(eff: Effect) -> String {
            match eff {
                Effect::Yank { content, .. } => content,
                Effect::Many(effs) => effs
                    .into_iter()
                    .find_map(|e| match e {
                        Effect::Yank { content, .. } => Some(content),
                        _ => None,
                    })
                    .expect("a Yank inside Many"),
                other => panic!("expected a Yank, got {other:?}"),
            }
        }

        // yaC -> the whole comment block (lines 1-2), markers included.
        let inv = CommandInvocation::of(b.yank.0).with_target(Target::TextObject(
            b.around_comment,
            crate::args::Args::None,
        ));
        let eff = execute_with_env(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            cursor,
            inv,
            &cancel,
            GrammarEnv {
                scope_resolver: None,
                comment_syntax: Some(&cs),
                syntax: None,
                ..Default::default()
            },
        )
        .unwrap();
        let content = yanked(eff);
        assert!(
            content.contains("// first") && content.contains("// second"),
            "aC yanks the comment block including markers, got {content:?}"
        );

        // yiC -> the comment text; the first line's leader is stripped.
        let inv = CommandInvocation::of(b.yank.0)
            .with_target(Target::TextObject(b.inner_comment, crate::args::Args::None));
        let eff = execute_with_env(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            cursor,
            inv,
            &cancel,
            GrammarEnv {
                scope_resolver: None,
                comment_syntax: Some(&cs),
                syntax: None,
                ..Default::default()
            },
        )
        .unwrap();
        let content = yanked(eff);
        assert!(
            content.starts_with("first"),
            "iC strips the first line's leader (no `//`), got {content:?}"
        );
    }

    #[test]
    fn comment_object_no_leader_is_a_noop() {
        // No comment_syntax in the env -> empty range -> the operator
        // no-ops (vim's `daC` with no comment does nothing).
        use crate::dispatcher::execute_with_env;
        use crate::registry::GrammarEnv;
        let src = "// a comment\n";
        let (registry, b, mut doc) = fixture(src);
        let cancel = CancellationToken::never();
        let inv = CommandInvocation::of(b.delete.0).with_target(Target::TextObject(
            b.around_comment,
            crate::args::Args::None,
        ));
        let eff = execute_with_env(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 3),
            inv,
            &cancel,
            GrammarEnv::default(),
        )
        .unwrap();
        assert!(matches!(eff, Effect::None), "no leader -> no-op");
        assert_eq!(doc.text(), src, "document unchanged");
    }

    #[test]
    fn populate_registers_known_builtins_by_name() {
        let mut r = CommandRegistry::new();
        let _ = populate(&mut r);
        assert!(r.lookup_by_name("motion:word-forward").is_some());
        assert!(r.lookup_by_name("operator:delete").is_some());
    }

    #[test]
    fn pre_flipped_token_short_circuits_dispatch() {
        // DESIGN.md §5.2.5: an evaluator that observes a flipped
        // token returns Cancelled and commits no Effect.
        let (registry, b, mut doc) = fixture("hello world");
        let inv = CommandInvocation::of(b.word_forward.0);
        let cancel = CancellationToken::new();
        cancel.cancel();
        let result = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &cancel,
        );
        match result {
            Err(CommandError::Cancelled) => {}
            other => panic!("expected Cancelled, got {other:?}"),
        }
        // Document state unchanged: no edits land.
        assert_eq!(doc.text(), "hello world");
    }

    #[test]
    fn fresh_token_does_not_short_circuit() {
        // Sanity-check the negative case: a fresh token leaves the
        // dispatcher's behaviour identical to the no-token path.
        let (registry, b, mut doc) = fixture("hello world");
        let inv = CommandInvocation::of(b.word_forward.0);
        let cancel = CancellationToken::new();
        let result = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &cancel,
        );
        assert!(result.is_ok());
    }

    // ---- VM.3d-2: `n` / `N` are motions ----

    const FOO: &str = "alpha foo one\nbeta two\ngamma foo three\ndelta four\n";

    fn search_effect(
        from: Position,
        reverse: bool,
        count: Option<u32>,
        last: Option<&crate::registry::LastSearch>,
    ) -> Result<Effect, CommandError> {
        let (registry, b, mut doc) = fixture(FOO);
        let id = if reverse {
            b.search_prev
        } else {
            b.search_next
        };
        let mut inv = CommandInvocation::of(id.0);
        if let Some(n) = count {
            inv = inv.with_count(crate::command::Count(n));
        }
        let env = crate::registry::GrammarEnv {
            last_search: last,
            ..Default::default()
        };
        crate::dispatcher::execute_with_env(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            from,
            inv,
            &CancellationToken::never(),
            env,
        )
    }

    fn foo_forward() -> crate::registry::LastSearch {
        crate::registry::LastSearch {
            pattern: "foo".into(),
            direction: crate::modal::SearchDirection::Forward,
        }
    }

    /// vim: `n` from 1,1 lands on the next `foo` (1,7), with no echo.
    #[test]
    fn n_moves_to_the_next_match_start() {
        let last = foo_forward();
        match search_effect(Position::new(0, 0), false, None, Some(&last)).unwrap() {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 6)),
            other => panic!("expected a plain CursorMove, got {other:?}"),
        }
    }

    /// `2n` counts; `N` reverses the search's own direction.
    #[test]
    fn a_count_repeats_and_upper_n_reverses() {
        let last = foo_forward();
        match search_effect(Position::new(0, 0), false, Some(2), Some(&last)).unwrap() {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(2, 6)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
        match search_effect(Position::new(2, 9), true, None, Some(&last)).unwrap() {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(2, 6)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    /// vim: `n` past the last match wraps to the first and says so.
    #[test]
    fn a_wrapping_n_echoes_search_hit_bottom() {
        let last = foo_forward();
        match search_effect(Position::new(2, 9), false, None, Some(&last)).unwrap() {
            Effect::Many(parts) => {
                assert!(matches!(parts[0], Effect::CursorMove(p) if p == Position::new(0, 6)));
                assert!(matches!(
                    &parts[1],
                    Effect::Echo { level: crate::effect::EchoLevel::Warn, text }
                        if text == "search hit BOTTOM, continuing at TOP"
                ));
            }
            other => panic!("expected CursorMove + Echo, got {other:?}"),
        }
    }

    /// vim: no match is E486; no previous search is E35. Both are user-facing
    /// errors, so the host echoes them and an operator commits nothing.
    #[test]
    fn a_failed_search_is_a_user_facing_error() {
        let missing = crate::registry::LastSearch {
            pattern: "zzz".into(),
            direction: crate::modal::SearchDirection::Forward,
        };
        match search_effect(Position::new(0, 0), false, None, Some(&missing)) {
            Err(CommandError::User(msg)) => assert_eq!(msg, "E486: Pattern not found: zzz"),
            other => panic!("expected E486, got {other:?}"),
        }
        match search_effect(Position::new(0, 0), false, None, None) {
            Err(CommandError::User(msg)) => assert_eq!(msg, "E35: no previous regular expression"),
            other => panic!("expected E35, got {other:?}"),
        }
    }

    // ---- VM.3g-2: `gj` / `gk` / `g0` / `g$` (vim 9.2, `vimcheck_gj.vim`) ----

    /// The vim check's buffer: a short line, a 200-column line, a short line,
    /// wrapped at 80. Byte columns here are 0-based; the vim rows quoted in the
    /// test names are 1-based, so they differ by one.
    fn wrapped_fixture() -> (CommandRegistry, Builtins, Document, WrapAt80) {
        let long: String = std::iter::repeat_n("abcdefghij", 20).collect();
        let text = format!("  short one\n{long}\n  short three");
        let (r, b, d) = fixture(&text);
        (r, b, d, WrapAt80)
    }

    struct WrapAt80;

    impl crate::registry::DisplayResolver for WrapAt80 {
        fn wrap_width(&self) -> u32 {
            80
        }
        fn segments(&self, line: u32) -> u32 {
            // 11, 200, 13 columns → 1, 3, 1 rows at width 80.
            if line == 1 { 3 } else { 1 }
        }
    }

    fn display_motion(
        pick: impl Fn(&Builtins) -> crate::registry::MotionId,
        from: Position,
        count: Option<u32>,
        wrapped: bool,
    ) -> Position {
        let (registry, b, mut doc, display) = wrapped_fixture();
        let mut inv = CommandInvocation::of(pick(&b).0);
        if let Some(n) = count {
            inv = inv.with_count(crate::command::Count(n));
        }
        let env = crate::registry::GrammarEnv {
            display: wrapped.then_some(&display as &dyn crate::registry::DisplayResolver),
            ..Default::default()
        };
        match crate::dispatcher::execute_with_env(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            from,
            inv,
            &CancellationToken::never(),
            env,
        )
        .unwrap()
        {
            Effect::CursorMove(p) => p,
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    /// vim: `gj` from 2,5 → 2,85 — the same screen column, one row down; `gk`
    /// comes back; `2gj` walks two rows (the host action ignored counts).
    #[test]
    fn gj_and_gk_move_by_display_row() {
        assert_eq!(
            display_motion(|b| b.display_line_down, Position::new(1, 4), None, true),
            Position::new(1, 84)
        );
        assert_eq!(
            display_motion(|b| b.display_line_up, Position::new(1, 84), None, true),
            Position::new(1, 4)
        );
        assert_eq!(
            display_motion(|b| b.display_line_down, Position::new(1, 4), Some(2), true),
            Position::new(1, 164)
        );
    }

    /// The goal column a motion REPORTS, which for `gj` / `gk` is not always
    /// the column it reached.
    fn display_motion_curswant(
        pick: impl Fn(&Builtins) -> crate::registry::MotionId,
        from: Position,
        curswant_in: Option<crate::registry::Curswant>,
    ) -> (Position, Option<crate::registry::Curswant>) {
        let (registry, b, mut doc, display) = wrapped_fixture();
        let slot = std::sync::Mutex::new(None);
        let env = crate::registry::GrammarEnv {
            display: Some(&display as &dyn crate::registry::DisplayResolver),
            curswant: curswant_in,
            curswant_out: Some(&slot),
            ..Default::default()
        };
        let landed = match crate::dispatcher::execute_with_env(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            from,
            CommandInvocation::of(pick(&b).0),
            &CancellationToken::never(),
            env,
        )
        .unwrap()
        {
            Effect::CursorMove(p) => p,
            other => panic!("expected CursorMove, got {other:?}"),
        };
        let reported = *slot.lock().unwrap();
        (landed, reported)
    }

    /// VM.3g-3: a CLAMPED `gj` records the column it aimed at, not the one it
    /// reached.
    ///
    /// vim 9.2 (`vimcheck_scroll_curswant.vim`), wrap 80 over a 240-char line
    /// then a 100-char line: `gj` onto the short second row lands at column 100
    /// and records `curswant` 160 — the aim. Same shape here on the 200-char
    /// fixture line: row 3 holds bytes 160..199, so `gj` from byte 159 aims at
    /// 160 + 79 = 239, lands clamped at 199, and must report 239.
    ///
    /// Recording 199 instead would lose the aim permanently: a following `j`
    /// onto a long line returns to 199 where vim returns to 239.
    #[test]
    fn a_clamped_gj_reports_the_aim_not_the_landing() {
        let (landed, reported) = display_motion_curswant(
            |b| b.display_line_down,
            Position::new(1, 159),
            Some(crate::registry::Curswant::Col(159)),
        );
        assert_eq!(landed, Position::new(1, 199), "the row ends at byte 199");
        assert_eq!(
            reported,
            Some(crate::registry::Curswant::Col(239)),
            "but the aim was 239, and that is what vim keeps"
        );
    }

    /// The unclamped case must report too, and there the aim IS the landing —
    /// which is why the simpler "set from where you landed" rule passed every
    /// test VM.3g-2 had.
    #[test]
    fn an_unclamped_gj_reports_the_column_it_reached() {
        let (landed, reported) = display_motion_curswant(
            |b| b.display_line_down,
            Position::new(1, 4),
            Some(crate::registry::Curswant::Col(4)),
        );
        assert_eq!(landed, Position::new(1, 84));
        assert_eq!(reported, Some(crate::registry::Curswant::Col(84)));
    }

    /// `gk` is the mirror, and reports on the same rule.
    #[test]
    fn gk_reports_its_aim_too() {
        let (landed, reported) = display_motion_curswant(
            |b| b.display_line_up,
            Position::new(1, 84),
            Some(crate::registry::Curswant::Col(84)),
        );
        assert_eq!(landed, Position::new(1, 4));
        assert_eq!(reported, Some(crate::registry::Curswant::Col(4)));
    }

    /// Every other motion reports NOTHING, so the host falls through to the
    /// spec's `CurswantEffect` exactly as before. A motion that started
    /// reporting by accident would silently pin the goal column.
    #[test]
    fn an_ordinary_motion_reports_no_goal() {
        let (_, reported) = display_motion_curswant(|b| b.line_down, Position::new(1, 4), None);
        assert_eq!(reported, None);
    }

    /// vim: `gj` on the last display row stays put rather than failing.
    #[test]
    fn gj_on_the_last_display_row_stays() {
        assert_eq!(
            display_motion(|b| b.display_line_down, Position::new(2, 4), None, true),
            Position::new(2, 4)
        );
    }

    /// vim: `g0` → 2,81 (the row's first column) and `g$` → 2,160 (its last).
    #[test]
    fn g0_and_g_dollar_bound_the_display_row() {
        assert_eq!(
            display_motion(|b| b.display_line_start, Position::new(1, 84), None, true),
            Position::new(1, 80)
        );
        assert_eq!(
            display_motion(|b| b.display_line_end, Position::new(1, 84), None, true),
            Position::new(1, 159)
        );
    }

    /// With `wrap` off — or no renderer geometry at all — they ARE `j` / `k` /
    /// `0`, as vim does.
    #[test]
    fn without_wrap_they_degrade_to_the_line_motions() {
        assert_eq!(
            display_motion(|b| b.display_line_down, Position::new(0, 4), None, false),
            Position::new(1, 4),
            "`gj` is `j`"
        );
        assert_eq!(
            display_motion(|b| b.display_line_start, Position::new(1, 84), None, false),
            Position::new(1, 0),
            "`g0` is `0`"
        );
    }

    /// All four SET the goal from where they land — measured in vim 9.2, and
    /// the opposite of `j` / `k`, which keep theirs across a short line. `gj`
    /// recomputes the virtual column for the row it reached, so "keep" would be
    /// wrong: after `gj` from 2,5 vim records 85, not 5.
    #[test]
    fn the_display_motions_set_the_goal_from_where_they_land() {
        use crate::registry::CurswantEffect;
        let (registry, b, _d, _w) = wrapped_fixture();
        for id in [
            b.display_line_down,
            b.display_line_up,
            b.display_line_start,
            b.display_line_end,
        ] {
            assert_eq!(
                registry.motion_curswant(id.0),
                CurswantEffect::SetFromTarget
            );
        }
        // `j` is the contrast, and it is not a display motion.
        assert_eq!(
            registry.motion_curswant(b.line_down.0),
            CurswantEffect::Keep
        );
    }

    // ---- VM.3g-1: the goal column (vim's `curswant`) ----

    const RAGGED: &str = "abcdefghijkl\nab\nabcdefghijkl\n";

    fn vertical(
        down: bool,
        from: Position,
        curswant: Option<crate::registry::Curswant>,
    ) -> Position {
        let (registry, b, mut doc) = fixture(RAGGED);
        let motion = if down { b.line_down } else { b.line_up };
        let env = crate::registry::GrammarEnv {
            curswant,
            ..Default::default()
        };
        match crate::dispatcher::execute_with_env(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            from,
            CommandInvocation::of(motion.0),
            &CancellationToken::never(),
            env,
        )
        .unwrap()
        {
            Effect::CursorMove(p) => p,
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    /// vim 9.2: `j` onto a SHORT line clamps to it, but the goal column is
    /// remembered — so the next `j` returns to column 9, not to 2. The motion's
    /// half of that is aiming at the goal rather than at the cursor.
    #[test]
    fn a_vertical_motion_aims_at_the_goal_column_not_the_cursor() {
        use crate::registry::Curswant;
        // Onto the short line: clamped.
        assert_eq!(
            vertical(true, Position::new(0, 8), Some(Curswant::Col(8))),
            Position::new(1, 2)
        );
        // Off it again, FROM the clamped column: the goal wins.
        assert_eq!(
            vertical(true, Position::new(1, 2), Some(Curswant::Col(8))),
            Position::new(2, 8)
        );
        // And upward, the same.
        assert_eq!(
            vertical(false, Position::new(1, 2), Some(Curswant::Col(8))),
            Position::new(0, 8)
        );
    }

    /// vim: after `$` the goal is MAXCOL, so every line it passes through is
    /// entered at its own end — `$jj` is at each line's end, not at a column.
    #[test]
    fn an_end_of_line_goal_lands_on_each_lines_end() {
        use crate::registry::Curswant;
        assert_eq!(
            vertical(true, Position::new(0, 12), Some(Curswant::EndOfLine)),
            Position::new(1, 2),
            "the short line's end"
        );
        assert_eq!(
            vertical(true, Position::new(1, 2), Some(Curswant::EndOfLine)),
            Position::new(2, 12),
            "and the long line's end, not the short one's column"
        );
    }

    /// With no goal recorded the cursor's own column is the goal — what the
    /// first `j` after an edit does.
    #[test]
    fn no_goal_yet_means_the_cursors_own_column() {
        assert_eq!(
            vertical(true, Position::new(0, 5), None),
            Position::new(1, 2)
        );
        assert_eq!(
            vertical(true, Position::new(1, 1), None),
            Position::new(2, 1)
        );
    }

    /// The three motions that do not simply set the goal from where they land.
    #[test]
    fn j_k_keep_the_goal_and_dollar_pins_it() {
        use crate::registry::CurswantEffect;
        let (registry, b, _doc) = fixture(RAGGED);
        assert_eq!(
            registry.motion_curswant(b.line_down.0),
            CurswantEffect::Keep
        );
        assert_eq!(registry.motion_curswant(b.line_up.0), CurswantEffect::Keep);
        assert_eq!(
            registry.motion_curswant(b.line_end.0),
            CurswantEffect::PinToEnd
        );
        // Everything else, and everything that is not a motion at all.
        assert_eq!(
            registry.motion_curswant(b.word_forward.0),
            CurswantEffect::SetFromTarget
        );
        assert_eq!(
            registry.motion_curswant(b.delete.0),
            CurswantEffect::SetFromTarget
        );
    }

    // ---- VM.3j-1: `gg` / `G` honour `startofline` ----

    /// `first_line` picks `gg`, else `G`. The motion id comes from THIS
    /// fixture's registry: command ids are globally unique, so an id taken from
    /// a second `fixture()` call is unknown to this one.
    fn sol_effect(first_line: bool, from: Position, nostartofline: bool) -> Effect {
        let (registry, b, mut doc) = fixture("  one a\n    two b\n  three c\n");
        let motion = if first_line {
            b.goto_first_line
        } else {
            b.goto_last_line
        };
        let env = crate::registry::GrammarEnv {
            nostartofline,
            ..Default::default()
        };
        crate::dispatcher::execute_with_env(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            from,
            CommandInvocation::of(motion.0),
            &CancellationToken::never(),
            env,
        )
        .unwrap()
    }

    /// vim 9.2 (`vimcheck_sol_pages.vim`): with `startofline` — the default —
    /// `gg` and `G` land on the first non-blank of their line, not column 0.
    #[test]
    fn gg_and_g_land_on_the_first_non_blank() {
        match sol_effect(true, Position::new(2, 5), false) {
            Effect::CursorMove(p) => assert_eq!(p, Position::new(0, 2)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
        match sol_effect(false, Position::new(0, 5), false) {
            Effect::CursorMove(p) => assert_eq!(p, Position::new(2, 2)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    /// vim: with `nostartofline` both keep the cursor's column, clamped.
    #[test]
    fn nostartofline_keeps_the_column_on_gg_and_g() {
        match sol_effect(true, Position::new(2, 5), true) {
            Effect::CursorMove(p) => assert_eq!(p, Position::new(0, 5)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
        match sol_effect(false, Position::new(1, 8), true) {
            Effect::CursorMove(p) => assert_eq!(p, Position::new(2, 8)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    // ---- VM.3m: where an operator leaves the cursor ----

    /// vim: `dd` from 1,6 lands on the first non-blank of the line that moved
    /// up (1,5 when that line is indented four).
    #[test]
    fn a_linewise_delete_lands_on_the_first_non_blank() {
        let (registry, b, mut doc) = fixture("  one a\n    two b\n  three c\n");
        let inv = CommandInvocation::of(b.delete.0).with_range(crate::range::Range::CurrentLine);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 5),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::Many(parts) => assert!(matches!(
                parts[parts.len() - 1],
                Effect::CursorMove(p) if p == Position::new(0, 4)
            )),
            other => panic!("expected Many, got {other:?}"),
        }
    }

    /// vim: `yk` from 2,8 lands on 1,7 — the start line, column kept. The
    /// expanded range starts at column 0, so this is `origin`, not `range`.
    #[test]
    fn a_yank_lands_on_the_start_of_what_it_yanked() {
        let (registry, b, mut doc) = fixture("  one a\n    two b\n  three c\n");
        let inv = CommandInvocation::of(b.yank.0)
            .with_target(Target::Motion(b.line_up, crate::args::Args::None));
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(1, 6),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::Many(parts) => assert!(matches!(
                parts[parts.len() - 1],
                Effect::CursorMove(p) if p == Position::new(0, 6)
            )),
            other => panic!("expected Many, got {other:?}"),
        }
    }

    // ---- VM.3f: `H` / `M` / `L` are motions ----

    fn shown(first: u32, count: u32) -> crate::registry::ShownLines {
        crate::registry::ShownLines((first..first + count).map(|l| (l, 1.0)).collect())
    }

    /// vim 9.2, a 21-row window showing lines 6–26 (1-based): `H` 6, `M` 16,
    /// `L` 26, `3H` 8, `3L` 24, and a count past the window clamps to the far
    /// edge.
    #[test]
    fn shown_lines_answer_h_m_and_l_as_vim_does() {
        use crate::app_effect::ViewportPos::{Bottom, Middle, Top};
        use crate::registry::ViewportResolver;
        let window = shown(5, 21);
        assert_eq!(window.viewport_line(Top, 1), Some(5));
        assert_eq!(window.viewport_line(Middle, 1), Some(15));
        assert_eq!(window.viewport_line(Bottom, 1), Some(25));
        assert_eq!(window.viewport_line(Top, 3), Some(7));
        assert_eq!(window.viewport_line(Bottom, 3), Some(23));
        assert_eq!(window.viewport_line(Top, 99), Some(25));
        assert_eq!(window.viewport_line(Bottom, 99), Some(5));
    }

    /// vim: `M` is top + (shown − 1) / 2 — 22 rows → +10, 23 → +11, a 6-line
    /// buffer → its 3rd line — and a tall row spends its height.
    #[test]
    fn middle_is_half_the_lines_shown_less_one() {
        use crate::app_effect::ViewportPos::Middle;
        use crate::registry::{ShownLines, ViewportResolver};
        assert_eq!(shown(0, 22).viewport_line(Middle, 1), Some(10));
        assert_eq!(shown(0, 23).viewport_line(Middle, 1), Some(11));
        assert_eq!(shown(0, 6).viewport_line(Middle, 1), Some(2));
        let mut rows: Vec<(u32, f32)> = (0..9).map(|l| (l, 1.0)).collect();
        rows[2].1 = 4.0;
        assert_eq!(ShownLines(rows).viewport_line(Middle, 1), Some(2));
        assert_eq!(ShownLines::default().viewport_line(Middle, 1), None);
    }

    /// VM.3f: `H` / `L` stop `scrolloff` lines inside the window's edges.
    ///
    /// The numbers are vim 9.2's, measured with an 11-line window over a
    /// 100-line file and the cursor centred (`50Gzz` → shows 45–55, 0-based
    /// 44–54): `H` → 48 and `L` → 52 with `scrolloff=3`, 45 and 55 with `0`.
    /// At a FILE edge vim does not adjust — `gg`-then-`H` is line 1 and
    /// `G`-then-`L` the last line — because the margin exists to keep context
    /// on screen and there is none past the end.
    #[test]
    fn h_and_l_keep_scrolloff_from_the_windows_edges() {
        use crate::app_effect::ViewportPos::{Bottom, Top};
        let long = "x\n".repeat(100);
        let (_registry, _b, doc) = fixture(&long);
        let window = shown(44, 11);
        let motion = |pos, scrolloff, operator_pending| {
            let ctx = MotionContext {
                buffer: doc.buffer(),
                buffer_id: lattice_core::BufferId(0),
                from: Position::new(49, 0),
                count: Count::default(),
                has_explicit_count: false,
                args: crate::args::Args::None,
                cancel: &CancellationToken::never(),
                scope_resolver: None,
                path: None,
                syntax: None,
                last_find: None,
                fold_resolver: None,
                last_search: None,
                marks: None,
                viewport: Some(&window as &dyn crate::registry::ViewportResolver),
                nostartofline: false,
                curswant: None,
                display: None,
                scrolloff,
                operator_pending,
            };
            motion_viewport(&ctx, pos).unwrap().target.line
        };

        assert_eq!(motion(Top, 3, false), 47, "`H` stops 3 inside the top");
        assert_eq!(
            motion(Bottom, 3, false),
            51,
            "`L` stops 3 inside the bottom"
        );
        assert_eq!(motion(Top, 0, false), 44, "`scrolloff=0` reaches the edge");
        assert_eq!(motion(Bottom, 0, false), 54);
        // `:h H`: not adjusted under a pending operator, so `dH` deletes to
        // the window's real top edge.
        assert_eq!(motion(Top, 3, true), 44, "an operator target is unadjusted");
        assert_eq!(motion(Bottom, 3, true), 54);

        // A window at the file's edges: nothing above line 0 to keep in view,
        // and nothing below the last line.
        let top_of_file = shown(0, 11);
        let ctx_at = |window: &crate::registry::ShownLines, pos| {
            let ctx = MotionContext {
                buffer: doc.buffer(),
                buffer_id: lattice_core::BufferId(0),
                from: Position::new(5, 0),
                count: Count::default(),
                has_explicit_count: false,
                args: crate::args::Args::None,
                cancel: &CancellationToken::never(),
                scope_resolver: None,
                path: None,
                syntax: None,
                last_find: None,
                fold_resolver: None,
                last_search: None,
                marks: None,
                viewport: Some(window as &dyn crate::registry::ViewportResolver),
                nostartofline: false,
                curswant: None,
                display: None,
                scrolloff: 3,
                operator_pending: false,
            };
            motion_viewport(&ctx, pos).unwrap().target.line
        };
        assert_eq!(ctx_at(&top_of_file, Top), 0, "`H` on the file's first line");
        // The window's bottom IS the last line (the fixture's trailing newline
        // makes 99 the last addressable one).
        let end_of_file = shown(89, 11);
        assert_eq!(
            ctx_at(&end_of_file, Bottom),
            99,
            "`L` on the file's last line"
        );
    }

    fn viewport_effect(nostartofline: bool, with_window: bool) -> Result<Effect, CommandError> {
        let (registry, b, mut doc) = fixture("  one\n  two\n  three\n");
        let window = shown(1, 2);
        let env = crate::registry::GrammarEnv {
            viewport: with_window.then_some(&window as &dyn crate::registry::ViewportResolver),
            nostartofline,
            ..Default::default()
        };
        crate::dispatcher::execute_with_env(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(2, 4),
            CommandInvocation::of(b.viewport_top.0),
            &CancellationToken::never(),
            env,
        )
    }

    /// `H` lands on the first non-blank, keeps the column with `nostartofline`,
    /// and with no window fails rather than guessing.
    #[test]
    fn a_viewport_motion_follows_startofline() {
        match viewport_effect(false, true).unwrap() {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(1, 2)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
        match viewport_effect(true, true).unwrap() {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(1, 4)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
        assert!(matches!(
            viewport_effect(false, false),
            Err(CommandError::MotionFailed)
        ));
    }

    // ---- VM.3e: `'x` / `` `x `` are motions ----

    const MARKS: &str = "  one a\n  two b\n\n  four d\n  five e\n  six f\n";

    fn mark_effect(
        exact: bool,
        name: char,
        marks: Option<&std::collections::HashMap<char, Position>>,
    ) -> Result<Effect, CommandError> {
        let (registry, b, mut doc) = fixture(MARKS);
        let id = if exact { b.mark_exact } else { b.mark_line };
        let inv = CommandInvocation::of(id.0).with_args(crate::args::Args::Char(name));
        let env = crate::registry::GrammarEnv {
            marks: marks.map(|m| m as &dyn crate::registry::MarkResolver),
            ..Default::default()
        };
        crate::dispatcher::execute_with_env(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 4),
            inv,
            &CancellationToken::never(),
            env,
        )
    }

    fn mark_a_at(line: u32, byte: u32) -> std::collections::HashMap<char, Position> {
        std::collections::HashMap::from([('a', Position::new(line, byte))])
    }

    /// vim: `'a` lands on the first non-blank of the mark's line; `` `a `` on
    /// the mark itself.
    #[test]
    fn a_mark_motion_targets_its_line_or_its_exact_position() {
        let marks = mark_a_at(4, 5);
        match mark_effect(false, 'a', Some(&marks)).unwrap() {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(4, 2)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
        match mark_effect(true, 'a', Some(&marks)).unwrap() {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(4, 5)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    /// vim: an unset mark is E20 — no table, or a table without that mark.
    #[test]
    fn an_unset_mark_is_e20() {
        let marks = mark_a_at(4, 5);
        for result in [
            mark_effect(false, 'b', Some(&marks)),
            mark_effect(true, 'a', None),
        ] {
            match result {
                Err(CommandError::User(msg)) => assert_eq!(msg, "E20: Mark not set"),
                other => panic!("expected E20, got {other:?}"),
            }
        }
    }

    /// A mark past the end of a buffer that has since shrunk resolves to the
    /// last position there is, rather than failing or landing out of range.
    #[test]
    fn a_mark_past_the_end_is_clamped_into_the_buffer() {
        let marks = mark_a_at(40, 9);
        match mark_effect(true, 'a', Some(&marks)).unwrap() {
            Effect::CursorMove(pos) => assert_eq!(pos.line, 5),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    // ---- VM.3i: `zj` / `zk` are motions ----

    /// Every fold open, so edges are plain starts / ends: which folds are
    /// VISIBLE is the host's rule and is tested there.
    struct OpenFolds(Vec<(u32, u32)>);

    impl crate::registry::FoldResolver for OpenFolds {
        fn fold_edge(&self, line: u32, forward: bool) -> Option<u32> {
            if forward {
                self.0.iter().map(|f| f.0).filter(|&s| s > line).min()
            } else {
                self.0.iter().map(|f| f.1).filter(|&e| e < line).max()
            }
        }
    }

    /// The layout of the vim 9.2 check: folds on lines 4–6 and 9–10 (1-based),
    /// in a 14-line buffer.
    fn vim_folds() -> OpenFolds {
        OpenFolds(vec![(3, 5), (8, 9)])
    }

    fn fold_motion(
        from: Position,
        count: Option<u32>,
        forward: bool,
        folds: Option<&OpenFolds>,
    ) -> Position {
        let text: String = (1..=14).map(|n| format!("line {n}\n")).collect();
        let (registry, b, mut doc) = fixture(&text);
        let id = if forward {
            b.goto_next_fold
        } else {
            b.goto_prev_fold
        };
        let mut inv = CommandInvocation::of(id.0);
        if let Some(n) = count {
            inv = inv.with_count(crate::command::Count(n));
        }
        let env = crate::registry::GrammarEnv {
            fold_resolver: folds.map(|f| f as &dyn crate::registry::FoldResolver),
            ..Default::default()
        };
        let effect = crate::dispatcher::execute_with_env(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            from,
            inv,
            &CancellationToken::never(),
            env,
        )
        .expect("zj / zk dispatch");
        match effect {
            Effect::CursorMove(pos) => pos,
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    /// vim: `zj` from 1,3 → 4,1; `2zj` → 9,1; `zk` from 12,3 → 10,1.
    #[test]
    fn zj_and_zk_step_to_fold_edges_at_column_zero() {
        let folds = vim_folds();
        assert_eq!(
            fold_motion(Position::new(0, 2), None, true, Some(&folds)),
            Position::new(3, 0)
        );
        assert_eq!(
            fold_motion(Position::new(0, 2), Some(2), true, Some(&folds)),
            Position::new(8, 0)
        );
        assert_eq!(
            fold_motion(Position::new(11, 2), None, false, Some(&folds)),
            Position::new(9, 0)
        );
    }

    /// vim: `zj` with no fold ahead leaves the cursor where it is. So does a
    /// caller with no fold table at all.
    #[test]
    fn zj_without_an_edge_stays_put() {
        let folds = vim_folds();
        assert_eq!(
            fold_motion(Position::new(11, 2), None, true, Some(&folds)),
            Position::new(11, 2)
        );
        assert_eq!(
            fold_motion(Position::new(0, 2), None, true, None),
            Position::new(0, 2)
        );
    }

    /// A count larger than the folds available stops at the last edge reached.
    #[test]
    fn a_count_past_the_last_fold_stops_at_the_last_edge() {
        let folds = vim_folds();
        assert_eq!(
            fold_motion(Position::new(0, 2), Some(9), true, Some(&folds)),
            Position::new(8, 0)
        );
    }

    fn repro_word_motion_punct(
        select: impl Fn(&Builtins) -> MotionId,
        text: &str,
        from: Position,
    ) -> Position {
        let (registry, b, mut doc) = fixture(text);
        let inv = CommandInvocation::of(select(&b).0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            from,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => pos,
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn word_forward_stops_at_punctuation() {
        // vim `w`: punctuation is its own word. `foo.bar` from `f` -> `.` (byte 3).
        assert_eq!(
            repro_word_motion_punct(|b| b.word_forward, "foo.bar", Position::ZERO),
            Position::new(0, 3),
        );
    }

    #[test]
    fn word_backward_stops_at_punctuation() {
        // vim `b`: from `bar` start (byte 4) -> `.` start (byte 3).
        assert_eq!(
            repro_word_motion_punct(|b| b.word_backward, "foo.bar", Position::new(0, 4)),
            Position::new(0, 3),
        );
    }

    #[test]
    fn word_end_stops_at_punctuation() {
        // vim `e`: from `f` (byte 0) lands at the end of `foo` (byte 2); a
        // second `e` (from byte 2) lands on the one-char `.` word (byte 3).
        assert_eq!(
            repro_word_motion_punct(|b| b.word_end, "foo.bar", Position::ZERO),
            Position::new(0, 2),
        );
        assert_eq!(
            repro_word_motion_punct(|b| b.word_end, "foo.bar", Position::new(0, 2)),
            Position::new(0, 3),
        );
    }

    #[test]
    fn word_forward_advances_to_next_word_start() {
        let (registry, b, mut doc) = fixture("hello world");
        let inv = CommandInvocation::of(b.word_forward.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => {
                assert_eq!(pos, Position::new(0, 6));
            }
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn word_forward_with_count_advances_by_count() {
        let (registry, b, mut doc) = fixture("one two three four");
        let inv = CommandInvocation::of(b.word_forward.0).with_count(Count(2));
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => {
                // "one two THREE four" -- two words forward from origin lands
                // at the start of "three" (byte 8).
                assert_eq!(pos, Position::new(0, 8));
            }
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn word_forward_across_newline() {
        let (registry, b, mut doc) = fixture("hello\nworld");
        let inv = CommandInvocation::of(b.word_forward.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => {
                assert_eq!(pos, Position::new(1, 0));
            }
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn delete_with_word_forward_target_dw_semantics() {
        // The classic `dw`: from origin, delete to next word start.
        // Delete now also yanks the deleted content into the unnamed
        // register, so the Effect is `Many([Edits, Yank])`.
        let (registry, b, mut doc) = fixture("hello world");
        let inv = CommandInvocation::of(b.delete.0)
            .with_target(Target::Motion(b.word_forward, crate::args::Args::None));
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::Many(parts) => {
                assert_eq!(parts.len(), 2);
                match &parts[0] {
                    Effect::Edits(applied) => {
                        assert_eq!(applied.len(), 1);
                        assert_eq!(applied[0].replaced_text, "hello ");
                    }
                    other => panic!("expected Edits at [0], got {other:?}"),
                }
                match &parts[1] {
                    Effect::Yank { content, kind, .. } => {
                        assert_eq!(content, "hello ");
                        assert_eq!(*kind, YankKind::Charwise);
                    }
                    other => panic!("expected Yank at [1], got {other:?}"),
                }
            }
            other => panic!("expected Many, got {other:?}"),
        }
        assert_eq!(doc.text(), "world");
    }

    #[test]
    fn delete_with_explicit_whole_range_deletes_buffer_and_yanks_linewise() {
        let (registry, b, mut doc) = fixture("a\nb\nc");
        let inv = CommandInvocation::of(b.delete.0).with_range(crate::range::Range::Whole);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::Many(parts) => {
                assert!(matches!(parts[0], Effect::Edits(_)));
                match &parts[1] {
                    Effect::Yank { kind, .. } => assert_eq!(*kind, YankKind::Linewise),
                    other => panic!("expected Yank at [1], got {other:?}"),
                }
            }
            other => panic!("expected Many, got {other:?}"),
        }
        assert_eq!(doc.text(), "");
    }

    #[test]
    fn delete_with_current_line_range_clears_just_that_line() {
        let (registry, b, mut doc) = fixture("aaa\nBBB\nccc");
        let cursor = Position::new(1, 0);
        let inv = CommandInvocation::of(b.delete.0).with_range(crate::range::Range::CurrentLine);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            cursor,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        // Slice 8.i.4.g: `dd` consumes BBB AND its trailing
        // newline so the line count drops by 1 (vim semantics).
        assert_eq!(doc.text(), "aaa\nccc");
    }

    #[test]
    fn unknown_command_id_errors() {
        let (registry, _, mut doc) = fixture("abc");
        let bogus = lattice_protocol::ids::CommandId::new(99_999);
        let inv = CommandInvocation::of(bogus);
        assert!(matches!(
            execute(
                &registry,
                &mut doc,
                lattice_core::BufferId(0),
                Position::ZERO,
                inv,
                &CancellationToken::never()
            ),
            Err(CommandError::UnknownCommand)
        ));
    }

    #[test]
    fn operator_without_target_or_range_errors() {
        let (registry, b, mut doc) = fixture("abc");
        let inv = CommandInvocation::of(b.delete.0);
        assert!(matches!(
            execute(
                &registry,
                &mut doc,
                lattice_core::BufferId(0),
                Position::ZERO,
                inv,
                &CancellationToken::never()
            ),
            Err(CommandError::MissingTarget)
        ));
    }

    #[test]
    fn char_left_at_origin_stays_put() {
        let (registry, b, mut doc) = fixture("abc");
        let inv = CommandInvocation::of(b.char_left.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::ZERO),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn char_right_advances_one_byte() {
        let (registry, b, mut doc) = fixture("abc");
        let inv = CommandInvocation::of(b.char_right.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 1)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn char_right_advances_whole_multibyte_scalar() {
        // `│` (U+2502) is 3 bytes. char_right must land on the next scalar
        // boundary (byte 3), never mid-glyph (byte 1), or a subsequent delete
        // panics ropey on a non-char-boundary slice.
        let (registry, b, mut doc) = fixture("│x");
        let inv = CommandInvocation::of(b.char_right.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 3)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn char_left_retreats_whole_multibyte_scalar() {
        // Cursor just after `│` (byte 3); char_left must return to byte 0,
        // not byte 2 (mid-glyph).
        let (registry, b, mut doc) = fixture("│x");
        let inv = CommandInvocation::of(b.char_left.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 3),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::ZERO),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn char_right_at_end_of_line_stays_put() {
        let (registry, b, mut doc) = fixture("ab");
        let inv = CommandInvocation::of(b.char_right.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 2),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 2)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn line_down_moves_one_line_and_clamps_byte() {
        let (registry, b, mut doc) = fixture("hello\nhi");
        let inv = CommandInvocation::of(b.line_down.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 5),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(1, 2)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    /// VM.3L: `k` on the first line fails (vim beeps) instead of returning
    /// the cursor, so `dk` there can't delete the line it's on.
    #[test]
    fn line_up_at_top_fails() {
        let (registry, b, mut doc) = fixture("a\nb");
        let inv = CommandInvocation::of(b.line_up.0);
        let result = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        );
        assert!(
            matches!(result, Err(CommandError::MotionFailed)),
            "got {result:?}"
        );
    }

    /// And `j` on the last line.
    #[test]
    fn line_down_on_the_last_line_fails() {
        let (registry, b, mut doc) = fixture("a\nb");
        let inv = CommandInvocation::of(b.line_down.0);
        let result = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(1, 0),
            inv,
            &CancellationToken::never(),
        );
        assert!(
            matches!(result, Err(CommandError::MotionFailed)),
            "got {result:?}"
        );
    }

    #[test]
    fn line_start_resets_byte_to_zero() {
        let (registry, b, mut doc) = fixture("hello world");
        let inv = CommandInvocation::of(b.line_start.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 7),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 0)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn line_end_jumps_to_line_byte_length() {
        let (registry, b, mut doc) = fixture("hello world");
        let inv = CommandInvocation::of(b.line_end.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 11)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn goto_first_line_returns_to_origin() {
        let (registry, b, mut doc) = fixture("a\nb\nc");
        let inv = CommandInvocation::of(b.goto_first_line.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(2, 0),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::ZERO),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn goto_last_line_jumps_to_last_addressable_line() {
        let (registry, b, mut doc) = fixture("a\nb\nc");
        let inv = CommandInvocation::of(b.goto_last_line.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(2, 0)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn goto_last_line_with_count_goes_to_specific_line() {
        // `3G` on a 5-line buffer → line 3 (1-indexed → row 2)
        let (registry, b, mut doc) = fixture("a\nb\nc\nd\ne");
        let inv = CommandInvocation::of(b.goto_last_line.0).with_count(Count(3));
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(2, 0)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn goto_first_line_with_count_goes_to_specific_line() {
        // `3gg` on a 5-line buffer → line 3 (1-indexed → row 2)
        let (registry, b, mut doc) = fixture("a\nb\nc\nd\ne");
        let inv = CommandInvocation::of(b.goto_first_line.0).with_count(Count(3));
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(4, 0),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(2, 0)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn x_semantics_via_delete_with_char_right_target() {
        // Vim's `x`: delete the char under the cursor (and yank it).
        let (registry, b, mut doc) = fixture("hello");
        let inv = CommandInvocation::of(b.delete.0)
            .with_target(Target::Motion(b.char_right, crate::args::Args::None));
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::Many(parts) => {
                assert!(matches!(parts[0], Effect::Edits(_)));
                assert!(matches!(parts[1], Effect::Yank { .. }));
            }
            other => panic!("expected Many, got {other:?}"),
        }
        assert_eq!(doc.text(), "ello");
    }

    // ---- word-backward (b) ----

    #[test]
    fn word_backward_from_mid_word_lands_at_start_of_word() {
        let (registry, b, mut doc) = fixture("hello world");
        // Cursor on 'r' of "world" (byte 8) -- vim's `b` lands on 'w' (byte 6).
        let inv = CommandInvocation::of(b.word_backward.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 8),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 6)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn word_backward_from_start_of_word_lands_at_start_of_previous_word() {
        let (registry, b, mut doc) = fixture("one two three");
        // Cursor on 't' of "three" (byte 8). `b` -> 't' of "two" (byte 4).
        let inv = CommandInvocation::of(b.word_backward.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 8),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 4)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn word_backward_at_origin_stays_put() {
        let (registry, b, mut doc) = fixture("hello");
        let inv = CommandInvocation::of(b.word_backward.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::ZERO),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn word_backward_crosses_newlines() {
        let (registry, b, mut doc) = fixture("foo\nbar");
        // Cursor on 'b' (line 1 byte 0). `b` -> 'f' (line 0 byte 0).
        let inv = CommandInvocation::of(b.word_backward.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(1, 0),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::ZERO),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn word_backward_with_count_jumps_count_words() {
        let (registry, b, mut doc) = fixture("one two three four");
        // Cursor on 'f' of "four" (byte 14). `2b` -> 't' of "two" (byte 4).
        let inv = CommandInvocation::of(b.word_backward.0).with_count(Count(2));
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 14),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 4)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn word_backward_lands_on_punctuation_word() {
        let (registry, b, mut doc) = fixture("alpha, beta");
        // Cursor on 'b' of "beta" (byte 7). vim `b` -> the `,` (byte 5): the
        // comma is its own word, so `b` lands on it rather than skipping to
        // "alpha". (Pre-3-class this wrongly returned byte 0.)
        let inv = CommandInvocation::of(b.word_backward.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 7),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 5)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    // ---- word-end (e) ----

    #[test]
    fn word_end_from_start_of_word_lands_at_last_byte_of_word() {
        let (registry, b, mut doc) = fixture("hello world");
        // From 'h' (byte 0) `e` -> 'o' of "hello" (byte 4).
        let inv = CommandInvocation::of(b.word_end.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 4)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn word_end_from_end_of_word_lands_at_end_of_next_word() {
        let (registry, b, mut doc) = fixture("hello world");
        // From 'o' of "hello" (byte 4) `e` -> 'd' of "world" (byte 10).
        let inv = CommandInvocation::of(b.word_end.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 4),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 10)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn word_end_at_buffer_end_stays_put() {
        let (registry, b, mut doc) = fixture("hi");
        // From 'i' (byte 1) `e` -> stays at byte 1 (no further word).
        let inv = CommandInvocation::of(b.word_end.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 1),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 1)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn word_end_crosses_newlines() {
        let (registry, b, mut doc) = fixture("foo\nbar");
        // From 'o' of "foo" (line 0 byte 2) `e` -> 'r' of "bar" (line 1 byte 2).
        let inv = CommandInvocation::of(b.word_end.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 2),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(1, 2)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn word_end_with_count_advances_by_count() {
        let (registry, b, mut doc) = fixture("one two three four");
        // From 'o' (byte 0) `2e` -> end of "two" = 'o' of "two" (byte 6).
        let inv = CommandInvocation::of(b.word_end.0).with_count(Count(2));
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 6)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    // ---- first-non-blank (^) ----

    #[test]
    fn first_non_blank_skips_leading_spaces() {
        let (registry, b, mut doc) = fixture("    hello");
        let inv = CommandInvocation::of(b.first_non_blank.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 4)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn first_non_blank_skips_leading_tabs() {
        let (registry, b, mut doc) = fixture("\t\thello");
        let inv = CommandInvocation::of(b.first_non_blank.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 2)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn first_non_blank_on_already_non_blank_line_returns_zero() {
        let (registry, b, mut doc) = fixture("hello");
        let inv = CommandInvocation::of(b.first_non_blank.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 3),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::ZERO),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn first_non_blank_on_blank_only_line_returns_end() {
        let (registry, b, mut doc) = fixture("    ");
        let inv = CommandInvocation::of(b.first_non_blank.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => {
                // No non-blank chars; cursor lands at end of line (byte 4).
                assert_eq!(pos, Position::new(0, 4));
            }
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn first_non_blank_respects_current_line() {
        let (registry, b, mut doc) = fixture("a\n  bc");
        // Cursor on line 1; first non-blank is at byte 2 of line 1.
        let inv = CommandInvocation::of(b.first_non_blank.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(1, 4),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(1, 2)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    // ---- delete + new motions composition ----

    #[test]
    fn delete_with_word_backward_target_db_semantics() {
        // `db` from past-EOL deletes the last word: word_backward from byte 11
        // lands at byte 6 (start of "world"); the [6, 11) range covers "world".
        let (registry, b, mut doc) = fixture("hello world");
        let inv = CommandInvocation::of(b.delete.0)
            .with_target(Target::Motion(b.word_backward, crate::args::Args::None));
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 11),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "hello ");
    }

    // ---- Indent operators (>, <) ----

    #[test]
    fn indent_right_current_line_prepends_four_spaces() {
        let (registry, b, mut doc) = fixture("hello");
        let inv =
            CommandInvocation::of(b.indent_right.0).with_range(crate::range::Range::CurrentLine);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "    hello");
    }

    #[test]
    fn indent_left_current_line_strips_four_spaces() {
        let (registry, b, mut doc) = fixture("    hello");
        let inv =
            CommandInvocation::of(b.indent_left.0).with_range(crate::range::Range::CurrentLine);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "hello");
    }

    #[test]
    fn indent_left_strips_partial_indent() {
        let (registry, b, mut doc) = fixture("  hello");
        let inv =
            CommandInvocation::of(b.indent_left.0).with_range(crate::range::Range::CurrentLine);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        // Only 2 spaces present; strips both.
        assert_eq!(doc.text(), "hello");
    }

    #[test]
    fn indent_left_strips_leading_tab() {
        let (registry, b, mut doc) = fixture("\thello");
        let inv =
            CommandInvocation::of(b.indent_left.0).with_range(crate::range::Range::CurrentLine);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "hello");
    }

    #[test]
    fn indent_left_no_indent_is_no_op() {
        let (registry, b, mut doc) = fixture("hello");
        let inv =
            CommandInvocation::of(b.indent_left.0).with_range(crate::range::Range::CurrentLine);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "hello");
    }

    #[test]
    fn indent_right_with_whole_range_indents_every_line() {
        let (registry, b, mut doc) = fixture("a\nb\nc");
        let inv = CommandInvocation::of(b.indent_right.0).with_range(crate::range::Range::Whole);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "    a\n    b\n    c");
    }

    // IN.0: the indent unit is resolved by the host and injected via
    // the env. These drive `>` / `<` at non-default units, which is the
    // whole point of the slice -- the tests above all run at the
    // registered defaults (shiftwidth=4, expandtab) and would pass
    // against the old hardcoded `"    "` too.
    fn indent_shift(text: &str, unit: lattice_core::IndentUnit, right: bool) -> String {
        let (registry, b, mut doc) = fixture(text);
        let op = if right { b.indent_right } else { b.indent_left };
        let inv = CommandInvocation::of(op.0).with_range(crate::range::Range::Whole);
        crate::execute_with_env(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
            crate::registry::GrammarEnv {
                indent: unit,
                ..Default::default()
            },
        )
        .unwrap();
        doc.text()
    }

    #[test]
    fn indent_right_honours_shiftwidth() {
        let sw2 = lattice_core::IndentUnit::new(2, true, 4);
        assert_eq!(indent_shift("a", sw2, true), "  a");
        let sw8 = lattice_core::IndentUnit::new(8, true, 4);
        assert_eq!(indent_shift("a", sw8, true), "        a");
    }

    #[test]
    fn indent_right_honours_noexpandtab() {
        // shiftwidth 4, tabstop 4, tabs: one level is one tab.
        let tabs = lattice_core::IndentUnit::new(4, false, 4);
        assert_eq!(indent_shift("a", tabs, true), "\ta");
        // Two levels of 4 at tabstop 8 is one tab, not two.
        let tabs8 = lattice_core::IndentUnit::new(4, false, 8);
        assert_eq!(indent_shift("    a", tabs8, true), "\ta");
    }

    #[test]
    fn a_tab_and_tabstop_spaces_dedent_identically() {
        // The defect the byte-splice model had: `<` stripped a whole
        // tab but only `shiftwidth` spaces, so these two visually
        // identical lines dedented by different amounts.
        let u = lattice_core::IndentUnit::new(2, true, 4);
        assert_eq!(indent_shift("\ta", u, false), "  a");
        assert_eq!(indent_shift("    a", u, false), "  a");
    }

    #[test]
    fn indent_right_leaves_blank_lines_alone() {
        // Vim does not indent blank lines, and doing so parks trailing
        // whitespace on lines the user never typed into.
        let u = lattice_core::IndentUnit::default();
        assert_eq!(indent_shift("a\n\nb", u, true), "    a\n\n    b");
        assert_eq!(indent_shift("a\n   \nb", u, true), "    a\n   \n    b");
    }

    #[test]
    fn dedent_at_column_zero_emits_no_edit() {
        // Not merely "no visible change" -- no edit at all, so `<` on
        // an unindented block costs no undo entry.
        let (registry, b, mut doc) = fixture("a\nb");
        let inv = CommandInvocation::of(b.indent_left.0).with_range(crate::range::Range::Whole);
        let eff = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert!(matches!(eff, Effect::None), "expected no edit, got {eff:?}");
        assert_eq!(doc.text(), "a\nb");
    }

    #[test]
    fn indent_left_with_whole_range_dedents_every_line() {
        let (registry, b, mut doc) = fixture("    a\n    b\n    c");
        let inv = CommandInvocation::of(b.indent_left.0).with_range(crate::range::Range::Whole);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "a\nb\nc");
    }

    // ---- Case operators (gU, gu, g~) ----

    #[test]
    fn upper_uppercases_word_target() {
        let (registry, b, mut doc) = fixture("hello world");
        let inv = CommandInvocation::of(b.upper.0)
            .with_target(Target::Motion(b.word_forward, crate::args::Args::None));
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        // word_forward from 0 lands at byte 6 -> [0, 6) = "hello " -> "HELLO ".
        assert_eq!(doc.text(), "HELLO world");
    }

    #[test]
    fn lower_lowercases_range() {
        let (registry, b, mut doc) = fixture("HELLO WORLD");
        let inv = CommandInvocation::of(b.lower.0).with_range(crate::range::Range::Whole);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "hello world");
    }

    #[test]
    fn toggle_case_inverts_each_letter() {
        let (registry, b, mut doc) = fixture("Hello World");
        let inv = CommandInvocation::of(b.toggle_case.0).with_range(crate::range::Range::Whole);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "hELLO wORLD");
    }

    #[test]
    fn upper_with_no_letters_is_no_op() {
        let (registry, b, mut doc) = fixture("123 !@# 456");
        let inv = CommandInvocation::of(b.upper.0).with_range(crate::range::Range::Whole);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        // No transformation needed -> Effect::None.
        assert!(matches!(effect, Effect::None));
        assert_eq!(doc.text(), "123 !@# 456");
    }

    #[test]
    fn case_operators_preserve_non_letter_bytes() {
        let (registry, b, mut doc) = fixture("foo_bar.baz");
        let inv = CommandInvocation::of(b.upper.0).with_range(crate::range::Range::Whole);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        // Underscore and dot pass through unchanged.
        assert_eq!(doc.text(), "FOO_BAR.BAZ");
    }

    // ---- Text objects ----

    fn invoke_textobj(
        op: crate::registry::OperatorId,
        tobj: crate::registry::TextObjectId,
    ) -> CommandInvocation {
        CommandInvocation::of(op.0).with_target(Target::TextObject(tobj, crate::args::Args::None))
    }

    #[test]
    fn iw_inner_word_covers_word_at_cursor() {
        // d iw on "hello world" with cursor on 'l' (byte 2) deletes "hello".
        let (registry, b, mut doc) = fixture("hello world");
        let inv = invoke_textobj(b.delete, b.inner_word);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 2),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), " world");
    }

    #[test]
    fn iw_at_start_of_word_works() {
        let (registry, b, mut doc) = fixture("hello world");
        let inv = invoke_textobj(b.delete, b.inner_word);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), " world");
    }

    #[test]
    fn iw_on_single_punctuation_deletes_it() {
        // vim `diw` on a punctuation char deletes that punctuation word.
        let (registry, b, mut doc) = fixture("foo.bar");
        let inv = invoke_textobj(b.delete, b.inner_word);
        // Cursor on the `.` (byte 3).
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 3),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "foobar");
    }

    #[test]
    fn iw_on_punctuation_covers_the_whole_run() {
        // vim `diw` on any `.` of a punctuation run deletes the whole run.
        let (registry, b, mut doc) = fixture("foo...bar");
        let inv = invoke_textobj(b.delete, b.inner_word);
        // Cursor on the middle `.` (byte 4).
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 4),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "foobar");
    }

    #[test]
    fn iw_on_whitespace_deletes_the_whitespace_run() {
        // vim `diw` on whitespace deletes the whitespace run (blanks are a
        // word class too) -- NOT a no-op.
        let (registry, b, mut doc) = fixture("hello world");
        let inv = invoke_textobj(b.delete, b.inner_word);
        // Cursor on the space (byte 5).
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 5),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "helloworld");
    }

    #[test]
    fn aw_around_word_includes_trailing_whitespace() {
        let (registry, b, mut doc) = fixture("hello world");
        let inv = invoke_textobj(b.delete, b.around_word);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 2),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        // around_word: "hello" + trailing space deleted -> "world".
        assert_eq!(doc.text(), "world");
    }

    #[test]
    fn aw_on_last_word_takes_leading_whitespace() {
        let (registry, b, mut doc) = fixture("hello world");
        let inv = invoke_textobj(b.delete, b.around_word);
        // Cursor on 'w' at byte 6 -- no trailing whitespace, so leading.
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 6),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "hello");
    }

    #[test]
    #[allow(non_snake_case)]
    fn iW_treats_punctuation_as_part_of_big_word() {
        // `iw` would split on `.`; `iW` does not because `.` is
        // non-whitespace -> part of the WORD.
        let (registry, b, mut doc) = fixture("foo.bar baz");
        let inv = invoke_textobj(b.delete, b.inner_big_word);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 2),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), " baz");
    }

    #[test]
    #[allow(non_snake_case)]
    fn iW_on_whitespace_deletes_the_whitespace_run() {
        // vim `diW` on whitespace deletes the whitespace run (blanks separate
        // WORDs but are themselves a selectable run) -- NOT a no-op.
        let (registry, b, mut doc) = fixture("hello world");
        let inv = invoke_textobj(b.delete, b.inner_big_word);
        // Cursor on the space (byte 5).
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 5),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "helloworld");
    }

    #[test]
    #[allow(non_snake_case)]
    fn aW_around_big_word_includes_trailing_whitespace() {
        let (registry, b, mut doc) = fixture("foo.bar baz");
        let inv = invoke_textobj(b.delete, b.around_big_word);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 0),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        // around_big_word: "foo.bar" + trailing space -> "baz".
        assert_eq!(doc.text(), "baz");
    }

    #[test]
    fn i_angle_covers_inside_pair() {
        let (registry, b, mut doc) = fixture("Vec<String>");
        let inv = invoke_textobj(b.delete, b.inner_angle);
        // Cursor inside angles (byte 5 = 'S' in "String").
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 5),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "Vec<>");
    }

    #[test]
    fn a_angle_covers_pair_including_brackets() {
        let (registry, b, mut doc) = fixture("Vec<String>");
        let inv = invoke_textobj(b.delete, b.around_angle);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 5),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "Vec");
    }

    #[test]
    fn i_double_quote_covers_quoted_content_only() {
        let (registry, b, mut doc) = fixture(r#"foo "bar baz" qux"#);
        let inv = invoke_textobj(b.delete, b.inner_quote_double);
        // Cursor inside quotes (byte 6 = 'a' of "bar").
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 6),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), r#"foo "" qux"#);
    }

    #[test]
    fn a_double_quote_covers_quoted_content_and_quotes() {
        let (registry, b, mut doc) = fixture(r#"foo "bar baz" qux"#);
        let inv = invoke_textobj(b.delete, b.around_quote_double);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 6),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "foo  qux");
    }

    #[test]
    fn i_single_quote_works() {
        let (registry, b, mut doc) = fixture("foo 'bar' baz");
        let inv = invoke_textobj(b.delete, b.inner_quote_single);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 6),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "foo '' baz");
    }

    #[test]
    fn i_paren_covers_inside_outermost_parens() {
        let (registry, b, mut doc) = fixture("call(arg1, arg2)");
        let inv = invoke_textobj(b.delete, b.inner_paren);
        // Cursor on 'a' of "arg2" at byte 11.
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 11),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "call()");
    }

    #[test]
    fn a_paren_includes_brackets() {
        let (registry, b, mut doc) = fixture("call(arg1, arg2)");
        let inv = invoke_textobj(b.delete, b.around_paren);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 11),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "call");
    }

    #[test]
    fn nested_parens_picks_innermost() {
        let (registry, b, mut doc) = fixture("a(b(c)d)e");
        let inv = invoke_textobj(b.delete, b.inner_paren);
        // Cursor at byte 4 ('c').
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 4),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "a(b()d)e");
    }

    #[test]
    fn i_bracket_works_for_square_brackets() {
        let (registry, b, mut doc) = fixture("arr[1, 2, 3]");
        let inv = invoke_textobj(b.delete, b.inner_bracket);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 4),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "arr[]");
    }

    #[test]
    fn i_brace_works_for_curly_braces() {
        let (registry, b, mut doc) = fixture("fn body { return 42; }");
        let inv = invoke_textobj(b.delete, b.inner_brace);
        // Cursor inside the braces.
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 12),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "fn body {}");
    }

    #[test]
    fn unmatched_bracket_is_no_op() {
        let (registry, b, mut doc) = fixture("no brackets here");
        let inv = invoke_textobj(b.delete, b.inner_paren);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 5),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "no brackets here");
    }

    #[test]
    fn ciw_change_inner_word_enters_insert() {
        let (registry, b, mut doc) = fixture("hello world");
        let inv = CommandInvocation::of(b.change.0)
            .with_target(Target::TextObject(b.inner_word, crate::args::Args::None));
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 2),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::Many(parts) => {
                assert!(matches!(
                    parts[parts.len() - 1],
                    Effect::EnterMode(crate::ModalState::Insert)
                ));
            }
            other => panic!("expected Many, got {other:?}"),
        }
        assert_eq!(doc.text(), " world");
    }

    // ---- Tag text objects (it / at) ----

    #[test]
    fn it_selects_inside_tag() {
        let (registry, b, mut doc) = fixture("<p>hello world</p>");
        let inv = CommandInvocation::of(b.delete.0)
            .with_target(Target::TextObject(b.inner_tag, crate::args::Args::None));
        // Cursor inside <p>: byte 5 ('e' of "hello").
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 5),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "<p></p>");
    }

    #[test]
    fn at_selects_around_tag() {
        let (registry, b, mut doc) = fixture("<p>hello world</p>");
        let inv = CommandInvocation::of(b.delete.0)
            .with_target(Target::TextObject(b.around_tag, crate::args::Args::None));
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 5),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "");
    }

    #[test]
    fn it_with_no_enclosing_tag_is_no_op() {
        let (registry, b, mut doc) = fixture("plain text");
        let inv = CommandInvocation::of(b.delete.0)
            .with_target(Target::TextObject(b.inner_tag, crate::args::Args::None));
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 4),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "plain text");
    }

    // ---- Sentence motions and text objects ----

    #[test]
    fn sentence_forward_advances_after_period_space() {
        let (registry, b, mut doc) = fixture("First sentence. Second sentence. Third.");
        let inv = CommandInvocation::of(b.sentence_forward.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => {
                // After "First sentence. " -> 'S' of "Second" at byte 16.
                assert_eq!(pos, Position::new(0, 16));
            }
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn sentence_backward_returns_to_previous_start() {
        let (registry, b, mut doc) = fixture("First. Second.");
        // Cursor on 'S' of "Second" at byte 7.
        let inv = CommandInvocation::of(b.sentence_backward.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 7),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::ZERO),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn dis_deletes_inner_sentence() {
        let (registry, b, mut doc) = fixture("First sentence. Second sentence.");
        // Cursor on byte 5 (inside "First sentence").
        let inv = CommandInvocation::of(b.delete.0).with_target(Target::TextObject(
            b.inner_sentence,
            crate::args::Args::None,
        ));
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 5),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        // Inner stops before the period; period stays.
        assert!(doc.text().starts_with('.'));
    }

    // ---- Paragraph motions and text objects ----

    #[test]
    fn paragraph_forward_lands_on_next_blank_line() {
        let (registry, b, mut doc) = fixture("foo\nbar\n\nbaz");
        let inv = CommandInvocation::of(b.paragraph_forward.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => {
                // First blank line is line 2.
                assert_eq!(pos, Position::new(2, 0));
            }
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn paragraph_backward_lands_on_previous_blank_line() {
        let (registry, b, mut doc) = fixture("foo\n\nbar\nbaz");
        let inv = CommandInvocation::of(b.paragraph_backward.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(3, 0),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(1, 0)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn paragraph_forward_at_end_of_buffer_clamps() {
        let (registry, b, mut doc) = fixture("foo\nbar");
        let inv = CommandInvocation::of(b.paragraph_forward.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => {
                // No blank line; lands at last addressable line.
                assert_eq!(pos.line, 1);
            }
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn dap_deletes_paragraph_with_blank_lines() {
        let (registry, b, mut doc) = fixture("foo\nbar\n\nbaz");
        let inv = CommandInvocation::of(b.delete.0).with_target(Target::TextObject(
            b.around_paragraph,
            crate::args::Args::None,
        ));
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        // Around paragraph: first non-blank run + trailing blank line.
        assert!(doc.text().contains("baz"));
    }

    #[test]
    fn dip_deletes_paragraph_only() {
        let (registry, b, mut doc) = fixture("foo\nbar\n\nbaz");
        let inv = CommandInvocation::of(b.delete.0).with_target(Target::TextObject(
            b.inner_paragraph,
            crate::args::Args::None,
        ));
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        // Inner paragraph: just the non-blank run, blank line preserved.
        assert!(doc.text().starts_with('\n') || doc.text().starts_with("\nbaz"));
    }

    // ---- WORD motions (W, B, E) ----

    #[test]
    fn big_word_forward_treats_punctuation_as_part_of_word() {
        // word_forward stops at punctuation; big_word_forward doesn't.
        let (registry, b, mut doc) = fixture("foo,bar baz");
        let inv = CommandInvocation::of(b.big_word_forward.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => {
                // From byte 0, "foo,bar" is one WORD; next WORD is "baz" at byte 8.
                assert_eq!(pos, Position::new(0, 8));
            }
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn big_word_backward_skips_to_word_start() {
        let (registry, b, mut doc) = fixture("foo,bar baz");
        // From byte 8 ('b' of "baz") `B` -> byte 0 ('f' of "foo,bar").
        let inv = CommandInvocation::of(b.big_word_backward.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 8),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::ZERO),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn big_word_end_lands_at_last_byte_of_big_word() {
        let (registry, b, mut doc) = fixture("foo,bar baz");
        let inv = CommandInvocation::of(b.big_word_end.0);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => {
                // End of "foo,bar" is byte 6 (the 'r').
                assert_eq!(pos, Position::new(0, 6));
            }
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    // ---- find-char / till-char (f, F, t, T) ----

    fn invoke_with_char(id: crate::registry::MotionId, c: char) -> CommandInvocation {
        CommandInvocation::of(id.0).with_args(crate::args::Args::Char(c))
    }

    #[test]
    fn find_char_forward_lands_on_next_occurrence_on_line() {
        let (registry, b, mut doc) = fixture("hello world");
        // From byte 0 ('h') `fo` -> 'o' of "hello" at byte 4.
        let inv = invoke_with_char(b.find_char_forward, 'o');
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 4)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn find_char_forward_skips_current_byte_so_it_advances() {
        let (registry, b, mut doc) = fixture("oxox");
        // From 'o' at byte 0, `fo` -> next 'o' at byte 2.
        let inv = invoke_with_char(b.find_char_forward, 'o');
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 2)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn find_char_forward_no_match_is_no_op() {
        let (registry, b, mut doc) = fixture("hello");
        let inv = invoke_with_char(b.find_char_forward, 'z');
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::ZERO),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn find_char_forward_does_not_cross_newlines() {
        let (registry, b, mut doc) = fixture("hello\nworld");
        // From byte 0, `fw` should NOT find 'w' on line 1.
        let inv = invoke_with_char(b.find_char_forward, 'w');
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::ZERO),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn find_char_backward_lands_on_previous_occurrence() {
        let (registry, b, mut doc) = fixture("hello world");
        // From byte 8 ('r' of "world") `Fo` -> 'o' of "world" at byte 7.
        let inv = invoke_with_char(b.find_char_backward, 'o');
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 8),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 7)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn find_char_backward_no_match_is_no_op() {
        let (registry, b, mut doc) = fixture("hello");
        let inv = invoke_with_char(b.find_char_backward, 'z');
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 4),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 4)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn till_char_forward_lands_one_byte_before_match() {
        let (registry, b, mut doc) = fixture("hello world");
        // `tw` from byte 0 -> byte 5 (space, one before 'w' at byte 6).
        let inv = invoke_with_char(b.till_char_forward, 'w');
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 5)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn till_char_backward_lands_one_byte_after_match() {
        let (registry, b, mut doc) = fixture("hello world");
        // `Th` from byte 8 -> byte 1 (one after 'h' at byte 0).
        let inv = invoke_with_char(b.till_char_backward, 'h');
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 8),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 1)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    #[test]
    fn find_char_with_no_args_errors() {
        let (registry, b, mut doc) = fixture("hello");
        // No Args::Char supplied -> InvalidArgs.
        let inv = CommandInvocation::of(b.find_char_forward.0);
        let err = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap_err();
        assert!(matches!(err, CommandError::InvalidArgs(_)));
    }

    #[test]
    fn find_char_forward_handles_unicode_target() {
        let (registry, b, mut doc) = fixture("café au lait");
        // `fé` from byte 0 -> byte 3 ('é' starts at byte 3 in "café").
        let inv = invoke_with_char(b.find_char_forward, 'é');
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::CursorMove(pos) => assert_eq!(pos, Position::new(0, 3)),
            other => panic!("expected CursorMove, got {other:?}"),
        }
    }

    // ---- change operator (c) ----

    #[test]
    fn change_with_word_forward_emits_edits_yank_and_enter_insert() {
        let (registry, b, mut doc) = fixture("hello world");
        let inv = CommandInvocation::of(b.change.0)
            .with_target(Target::Motion(b.word_forward, crate::args::Args::None));
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        // Effect::Many([Edits, Yank, EnterMode(Insert)]).
        match effect {
            Effect::Many(parts) => {
                assert_eq!(parts.len(), 3);
                assert!(matches!(parts[0], Effect::Edits(_)));
                assert!(matches!(parts[1], Effect::Yank { .. }));
                assert!(matches!(
                    parts[2],
                    Effect::EnterMode(crate::ModalState::Insert)
                ));
            }
            other => panic!("expected Effect::Many, got {other:?}"),
        }
        assert_eq!(doc.text(), "world");
    }

    #[test]
    fn change_current_line_clears_line_and_enters_insert() {
        let (registry, b, mut doc) = fixture("aaa\nBBB\nccc");
        let cursor = Position::new(1, 0);
        let inv = CommandInvocation::of(b.change.0).with_range(crate::range::Range::CurrentLine);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            cursor,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::Many(parts) => {
                assert_eq!(parts.len(), 3);
                // CurrentLine -> linewise yank.
                match &parts[1] {
                    Effect::Yank { kind, .. } => assert_eq!(*kind, YankKind::Linewise),
                    other => panic!("expected Yank at [1], got {other:?}"),
                }
                assert!(matches!(
                    parts[2],
                    Effect::EnterMode(crate::ModalState::Insert)
                ));
            }
            other => panic!("expected Effect::Many, got {other:?}"),
        }
        assert_eq!(doc.text(), "aaa\n\nccc");
    }

    #[test]
    fn change_with_line_end_target_truncates_line_and_enters_insert() {
        // `c$` from byte 5 of "hello world" leaves "hello" and enters Insert.
        let (registry, b, mut doc) = fixture("hello world");
        let inv = CommandInvocation::of(b.change.0)
            .with_target(Target::Motion(b.line_end, crate::args::Args::None));
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 5),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::Many(parts) => {
                assert_eq!(parts.len(), 3);
                assert!(matches!(
                    parts[2],
                    Effect::EnterMode(crate::ModalState::Insert)
                ));
            }
            other => panic!("expected Effect::Many, got {other:?}"),
        }
        assert_eq!(doc.text(), "hello");
    }

    // ---- replace-char operator (r{char} / Visual r) ----

    /// Helper: build a single visual selection on `doc`.
    fn set_visual(
        doc: &mut Document,
        anchor: Position,
        head: Position,
        visual: lattice_protocol::selection::VisualMode,
    ) {
        use lattice_protocol::selection::{Selection, SelectionSet};
        doc.set_selections(SelectionSet::single(Selection {
            anchor,
            head,
            visual: Some(visual),
        }));
    }

    #[test]
    fn replace_char_overwrites_single_char_under_cursor() {
        let (registry, b, mut doc) = fixture("hello");
        let inv = CommandInvocation::of(b.replace_char.0)
            .with_target(Target::Motion(b.char_right, crate::args::Args::None))
            .with_args(crate::args::Args::Char('a'));
        let eff = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert!(matches!(eff, Effect::Edits(_)));
        assert_eq!(doc.text(), "aello");
    }

    #[test]
    fn replace_char_with_count_overwrites_count_chars() {
        let (registry, b, mut doc) = fixture("hello");
        let inv = CommandInvocation::of(b.replace_char.0)
            .with_target(Target::Motion(b.char_right, crate::args::Args::None))
            .with_args(crate::args::Args::Char('a'))
            .with_count(Count(3));
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "aaalo");
    }

    #[test]
    fn replace_char_count_too_large_is_a_no_op() {
        // Vim's `3r` on a 2-char line replaces nothing (bells).
        let (registry, b, mut doc) = fixture("ab");
        let inv = CommandInvocation::of(b.replace_char.0)
            .with_target(Target::Motion(b.char_right, crate::args::Args::None))
            .with_args(crate::args::Args::Char('x'))
            .with_count(Count(3));
        let eff = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert!(matches!(eff, Effect::None));
        assert_eq!(doc.text(), "ab");
    }

    #[test]
    fn replace_char_on_empty_line_is_a_no_op() {
        let (registry, b, mut doc) = fixture("");
        let inv = CommandInvocation::of(b.replace_char.0)
            .with_target(Target::Motion(b.char_right, crate::args::Args::None))
            .with_args(crate::args::Args::Char('x'));
        let eff = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert!(matches!(eff, Effect::None));
        assert_eq!(doc.text(), "");
    }

    #[test]
    fn visual_replace_char_overwrites_selection() {
        use lattice_protocol::selection::VisualMode;
        let (registry, b, mut doc) = fixture("hello world");
        // Charwise select "hello": anchor byte 0, head byte 4
        // (inclusive-head extends to [0, 5)).
        set_visual(
            &mut doc,
            Position::new(0, 0),
            Position::new(0, 4),
            VisualMode::Charwise,
        );
        let inv = CommandInvocation::of(b.replace_char.0)
            .with_range(crate::range::Range::Selection)
            .with_args(crate::args::Args::Char('x'));
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 0),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "xxxxx world");
    }

    #[test]
    fn visual_replace_char_preserves_newlines_across_lines() {
        use lattice_protocol::selection::VisualMode;
        let (registry, b, mut doc) = fixture("ab\ncd");
        // Charwise from (0,1) through (1,0): covers "b\nc" (inclusive
        // head extends the end to (1,1)).
        set_visual(
            &mut doc,
            Position::new(0, 1),
            Position::new(1, 0),
            VisualMode::Charwise,
        );
        let inv = CommandInvocation::of(b.replace_char.0)
            .with_range(crate::range::Range::Selection)
            .with_args(crate::args::Args::Char('X'));
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 1),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        // Line structure preserved; only the two chars overwritten.
        assert_eq!(doc.text(), "aX\nXd");
    }

    #[test]
    fn visual_linewise_replace_char_overwrites_whole_lines() {
        use lattice_protocol::selection::VisualMode;
        let (registry, b, mut doc) = fixture("aaa\nbbb\nccc");
        set_visual(
            &mut doc,
            Position::new(0, 0),
            Position::new(1, 0),
            VisualMode::Linewise,
        );
        let inv = CommandInvocation::of(b.replace_char.0)
            .with_range(crate::range::Range::Selection)
            .with_args(crate::args::Args::Char('z'));
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 0),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "zzz\nzzz\nccc");
    }

    #[test]
    fn visual_blockwise_replace_char_overwrites_each_row_slice() {
        use lattice_protocol::selection::VisualMode;
        let (registry, b, mut doc) = fixture("abcd\nefgh\nijkl");
        // Block from (0,1) to (2,2): columns 1..=2 on each row.
        set_visual(
            &mut doc,
            Position::new(0, 1),
            Position::new(2, 2),
            VisualMode::Blockwise,
        );
        let inv = CommandInvocation::of(b.replace_char.0)
            .with_range(crate::range::Range::Selection)
            .with_args(crate::args::Args::Char('*'));
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 1),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "a**d\ne**h\ni**l");
    }

    #[test]
    fn replace_char_without_char_arg_errors() {
        let (registry, b, mut doc) = fixture("hello");
        let inv = CommandInvocation::of(b.replace_char.0)
            .with_target(Target::Motion(b.char_right, crate::args::Args::None));
        let err = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .expect_err("replace-char requires Args::Char");
        assert!(matches!(err, CommandError::InvalidArgs(_)));
    }

    // ---- yank operator (y) ----

    #[test]
    fn yank_with_word_forward_emits_charwise_yank_and_zero_register() {
        let (registry, b, mut doc) = fixture("hello world");
        let original_text = doc.text();
        let inv = CommandInvocation::of(b.yank.0)
            .with_target(Target::Motion(b.word_forward, crate::args::Args::None));
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        // Yank does NOT touch the buffer.
        assert_eq!(doc.text(), original_text);
        // Yank emits Many([requested-register, "0, cursor-to-origin]).
        match effect {
            Effect::Many(parts) => {
                assert_eq!(parts.len(), 3);
                match &parts[0] {
                    Effect::Yank {
                        content,
                        kind,
                        register,
                        explicit_yank,
                    } => {
                        assert_eq!(content, "hello ");
                        assert_eq!(*kind, YankKind::Charwise);
                        assert_eq!(*register, crate::register::Register::Unnamed);
                        assert!(
                            *explicit_yank,
                            "the primary yank write is clipboard-eligible"
                        );
                    }
                    other => panic!("expected Yank at [0], got {other:?}"),
                }
                match &parts[1] {
                    Effect::Yank { register, .. } => {
                        assert_eq!(*register, crate::register::Register::Numbered(0));
                    }
                    other => panic!("expected Yank(\"0) at [1], got {other:?}"),
                }
                // VM.3m: the cursor goes to the start of the yanked text, which
                // for a forward motion from 0,0 is where it already is.
                assert!(matches!(parts[2], Effect::CursorMove(p) if p == Position::ZERO));
            }
            other => panic!("expected Many, got {other:?}"),
        }
    }

    #[test]
    fn yank_with_current_line_range_emits_linewise_yank() {
        let (registry, b, mut doc) = fixture("aaa\nBBB\nccc");
        let inv = CommandInvocation::of(b.yank.0).with_range(crate::range::Range::CurrentLine);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(1, 0),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "aaa\nBBB\nccc");
        match effect {
            Effect::Many(parts) => match &parts[0] {
                Effect::Yank { content, kind, .. } => {
                    // Slice 8.i.4.g: linewise yank content always
                    // ends with `\n` so paste can splice cleanly.
                    assert_eq!(content, "BBB\n");
                    assert_eq!(*kind, YankKind::Linewise);
                }
                other => panic!("expected Yank, got {other:?}"),
            },
            other => panic!("expected Many, got {other:?}"),
        }
    }

    #[test]
    fn yank_with_whole_range_emits_linewise_full_buffer() {
        let (registry, b, mut doc) = fixture("hello\nworld");
        let inv = CommandInvocation::of(b.yank.0).with_range(crate::range::Range::Whole);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::Many(parts) => match &parts[0] {
                Effect::Yank { content, kind, .. } => {
                    // Slice 8.i.4.g: linewise yank content always
                    // ends with `\n` so paste can splice cleanly,
                    // even when the source had no trailing
                    // newline (here: `:y` of "hello\nworld").
                    assert_eq!(content, "hello\nworld\n");
                    assert_eq!(*kind, YankKind::Linewise);
                }
                other => panic!("expected Yank, got {other:?}"),
            },
            other => panic!("expected Many, got {other:?}"),
        }
    }

    #[test]
    fn yank_does_not_modify_buffer() {
        let (registry, b, mut doc) = fixture("immutable text");
        let original = doc.text();
        let inv = CommandInvocation::of(b.yank.0).with_range(crate::range::Range::Whole);
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), original);
    }

    #[test]
    fn yank_empty_range_returns_none() {
        let (registry, b, mut doc) = fixture("");
        let inv = CommandInvocation::of(b.yank.0).with_range(crate::range::Range::Whole);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        // Empty buffer / empty range -> Effect::None.
        assert!(matches!(effect, Effect::None));
    }

    // ---- delete-yanks-into-register (composite verification) ----

    #[test]
    fn delete_charwise_yanks_charwise() {
        let (registry, b, mut doc) = fixture("hello world");
        let inv = CommandInvocation::of(b.delete.0)
            .with_target(Target::Motion(b.word_forward, crate::args::Args::None));
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::Many(parts) => match &parts[1] {
                Effect::Yank { kind, content, .. } => {
                    assert_eq!(*kind, YankKind::Charwise);
                    assert_eq!(content, "hello ");
                }
                other => panic!("expected Yank, got {other:?}"),
            },
            other => panic!("expected Many, got {other:?}"),
        }
    }

    #[test]
    fn delete_linewise_yanks_linewise() {
        let (registry, b, mut doc) = fixture("aaa\nBBB\nccc");
        let inv = CommandInvocation::of(b.delete.0).with_range(crate::range::Range::CurrentLine);
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(1, 0),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::Many(parts) => match &parts[1] {
                Effect::Yank { kind, .. } => assert_eq!(*kind, YankKind::Linewise),
                other => panic!("expected Yank, got {other:?}"),
            },
            other => panic!("expected Many, got {other:?}"),
        }
    }

    #[test]
    fn delete_emits_many_with_edits_and_yank_only() {
        // Sanity: delete emits Many([Edits, Yank]) -- never EnterMode.
        let (registry, b, mut doc) = fixture("hello world");
        let inv = CommandInvocation::of(b.delete.0)
            .with_target(Target::Motion(b.word_forward, crate::args::Args::None));
        let effect = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        match effect {
            Effect::Many(parts) => {
                assert_eq!(parts.len(), 2);
                assert!(!parts.iter().any(|e| matches!(e, Effect::EnterMode(_))));
            }
            other => panic!("expected Many, got {other:?}"),
        }
    }

    #[test]
    fn delete_with_word_end_target_de_semantics() {
        // `de` from start of "hello world": word_end (`e`) is INCLUSIVE, so
        // it lands on the last char of "hello" ('o', byte 4) and the operator
        // covers that char too -- range [0, 5) -> deletes "hello", leaving
        // " world". Vim parity; previously the inclusive flag was ignored and
        // this left the trailing 'o' ("o world").
        let (registry, b, mut doc) = fixture("hello world");
        let inv = CommandInvocation::of(b.delete.0)
            .with_target(Target::Motion(b.word_end, crate::args::Args::None));
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), " world");
    }

    #[test]
    fn change_with_word_end_target_ce_is_inclusive() {
        // `ce` deletes through the end of the word (inclusive `e`), same as
        // `de` but leaving the operator in change-mode. From byte 0 of
        // "hello world" it removes "hello" -> " world".
        let (registry, b, mut doc) = fixture("hello world");
        let inv = CommandInvocation::of(b.change.0)
            .with_target(Target::Motion(b.word_end, crate::args::Args::None));
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), " world");
    }

    #[test]
    fn delete_with_find_char_target_df_is_inclusive() {
        // `dfl` deletes up to AND including the found char (inclusive `f`).
        // From byte 0 of "hello", `f` for 'l' lands on byte 2; deletion
        // covers [0, 3) -> "lo".
        let (registry, b, mut doc) = fixture("hello");
        let inv = CommandInvocation::of(b.delete.0).with_target(Target::Motion(
            b.find_char_forward,
            crate::args::Args::Char('l'),
        ));
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "lo");
    }

    #[test]
    fn dw_on_last_word_of_line_stops_at_line_end() {
        // Vim word-motion special case: `dw` on the last word of a line
        // deletes to the line end and does NOT join the next line. Cursor on
        // 'f' of "foo" (byte 6 of line 0); `w` would cross to "bar" on line 1,
        // but under the operator the range is clamped to the end of line 0.
        let (registry, b, mut doc) = fixture("hello foo\nbar");
        let inv = CommandInvocation::of(b.delete.0)
            .with_target(Target::Motion(b.word_forward, crate::args::Args::None));
        execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::new(0, 6),
            inv,
            &CancellationToken::never(),
        )
        .unwrap();
        assert_eq!(doc.text(), "hello \nbar", "dw must not cross the newline");
    }

    #[test]
    fn delete_with_motion_target_for_motion_id_kind_mismatch_is_caught() {
        // Constructing a Target::Motion from a *non-motion* command id should
        // surface a kind mismatch, not silently succeed.
        let (registry, b, mut doc) = fixture("abc");
        // Use `delete` (an operator) as if it were a motion. Should fail.
        let bogus = MotionId(b.delete.0);
        let inv = CommandInvocation::of(b.delete.0)
            .with_target(Target::Motion(bogus, crate::args::Args::None));
        let err = execute(
            &registry,
            &mut doc,
            lattice_core::BufferId(0),
            Position::ZERO,
            inv,
            &CancellationToken::never(),
        )
        .unwrap_err();
        assert!(matches!(err, CommandError::KindMismatch { .. }));
    }
}