scrive_core/

document.rs

//! The document aggregate: the buffer plus its edit history and every derived
//! view (selections, decorations, highlight cache, brackets, folds, find).
//!
//! [`Document`] is the public choke point for changing text. Every edit goes
//! through [`Document::edit`]/[`Document::edit_grouped`], which run the
//! transaction engine and record the inverse for undo — so a caller can never
//! mutate the buffer behind history's back. The one invariant this module rests
//! on: every position-tracked derived fact rides a committed edit's patch
//! through the single mover `rebase_views`, on both the forward path and
//! undo/redo, so no two copies of one position can drift apart.

use core::ops::Range;

use std::borrow::Cow;

use crate::bracket::Brackets;
use crate::buffer::{Buffer, EolFlavor, LoadError, Revision, Snapshot};
use crate::change_log::ChangeLog;
use crate::coords::{Bias, Point};
use crate::decorations::{
    DecorationId, DecorationKind, DecorationStore, Diagnostic, DiagnosticsOutcome, Severity,
    Stickiness, TrackedRange,
};
use crate::display_map::{BufferRow, DisplayRow};
use crate::find::{FindQuery, FindState};
use std::cell::{Ref, RefCell};

use crate::fold_map::{FoldMap, FoldSet};
use crate::highlight::{HighlightCache, HighlightEngine, HighlightSpan, SyntaxDef, TokenTheme};
use crate::history::{GroupingHint, History};
use crate::movement::{self, ColumnDir, Granularity, Motion};
use crate::patch::Patch;
use crate::selection::{Selection, SelectionId, SelectionSet};
use crate::transaction::{apply, Committed, EditOp, TransactionError};

/// A text document: buffer + undo history + selections + every derived view.
#[derive(Debug)]
pub struct Document {
    pub(crate) buffer: Buffer,
    history: History,
    pub(crate) selections: SelectionSet,
    /// The anchored rectangle while in column (box) selection mode. `Some`
    /// only between consecutive Ctrl+Shift+Alt+Arrow presses; any other action
    /// clears it, leaving the box as an ordinary multi-cursor set.
    column: Option<ColumnSelection>,
    /// The incremental syntax-highlight cache, present once the app injects
    /// a grammar+theme via [`Document::set_syntax`]. Spliced on every commit.
    highlight: Option<HighlightCache>,
    /// Matched brackets — spliced incrementally on every edit; drives bracket
    /// colorization and the matching-bracket highlight.
    brackets: Brackets,
    /// Tracked-range decoration store: diagnostic squiggles, find matches, and
    /// snippet stops. Rides every forward edit's patch in the commit path so
    /// positions stay reunited with content (one store, one mover).
    decorations: DecorationStore,
    /// Auto-close provenance is store-as-truth: the `AutoClosePair` decorations
    /// in THIS store ARE the live pairs (one per caret that auto-closed, so
    /// multi-caret), each spanning `[open char start, close char start)`. It is
    /// its OWN [`DecorationStore`], separate from `decorations`, because a pair
    /// is a small (≤ caret-count), self-invalidating, per-gesture set: giving it
    /// a dedicated store keeps every arm/clear/validate O(pairs) instead of
    /// scanning the bulk (10k-find-match / diagnostic) store. There is no
    /// separate handle to keep in sync — the store itself is the truth: the
    /// pairs ride every edit through the one mover (`rebase_views` moves this
    /// store beside `decorations`), `validate_autoclose` drops the ones no caret
    /// still occupies, and emptiness is read straight off the store
    /// (`!self.autoclose.is_empty()`).
    autoclose: DecorationStore,
    /// Active code folds — **view state**, never on the buffer or the undo
    /// stack. Rides the commit-path patch mover (see `rebase_views`) like a
    /// decoration, so folds survive edits and undo/redo with no fold-specific
    /// resync. Queried per frame through a `FoldMap` (never stored).
    folds: FoldSet,
    /// Find view-state: the active query, the active match's decoration id, and
    /// the coverage/cap bookkeeping. The match set itself lives ONLY in
    /// `decorations` (the sorted `FindMatch` set IS the set) and is repaired
    /// eagerly per commit via `rebase_views`. Idle until `set_find_query`.
    find: FindState,
    /// The language's line-comment prefix (e.g. `//`), injected by the app
    /// like the grammar — the core ships no language knowledge. `None`
    /// makes [`Document::toggle_line_comment`] a no-op.
    line_comment: Option<String>,
    /// String / char-literal delimiters for comment/string-aware bracket matching
    /// (opt-in per language, via [`Document::set_bracket_lexing`]). With the line
    /// comment they form the [`BracketConfig`](crate::BracketConfig); all empty ⇒
    /// purely structural bracket matching (the original behavior, zero overhead).
    bracket_string_delims: Vec<u8>,
    bracket_char_delim: Option<u8>,
    /// The expand-selection ladder: each [`Document::expand_selection`]
    /// pushes the pre-expansion set so `shrink_selection` can walk back down.
    /// Transient like `column` — any other gesture or edit clears it.
    expand_stack: Vec<SelectionSet>,
    /// Monotonic reveal-request counter: bumped by actions that move the caret
    /// programmatically — outside the widget's own input path — so the widget
    /// can autoscroll to the new caret. The view compares it to its last-seen
    /// value and reveals once on a change (a generation counter rather than an
    /// `Option<request>`, since a `&Document` renderer can't take or clear a
    /// request at layout). Verbs bump it via [`Document::request_reveal`] ONLY
    /// when they actually changed something — a no-op F8 or bracket jump never
    /// scrolls.
    reveal_seq: u64,
    /// The strategy of the last reveal request.
    reveal_mode: RevealMode,
    /// Opt-in incremental-change log. Off by default (zero overhead per edit);
    /// when [`Document::observe_changes`] enables it, every applied step —
    /// forward edit, undo, redo — is appended for a host to
    /// [`drain`](Document::drain_changes), e.g. to mirror edits to a language
    /// server as `textDocument/didChange`. Fed only by `rebase_views` (it rides
    /// in [`Views`]), the one mover every mutation route shares.
    changes: ChangeLog,
    /// Memoized [`FoldMap`]. The render path queries it ~20× per frame, so it is
    /// cached rather than rebuilt (a fresh build is O(folds), which at document
    /// scale with everything collapsed would stall scrolling). A fold toggle
    /// ([`FoldSet::generation`]) or a line-count change rebuilds from scratch; a
    /// no-line-change edit shifts the cached map in place via
    /// [`FoldMap::apply_patch`] (driven by [`Document::edit_grouped`]), so plain
    /// typing over a document-scale fold set costs O(edit), not an O(folds)
    /// rebuild per keystroke. Because it is shifted incrementally it could in
    /// principle drift, so the drift oracle
    /// (`fold_map_cache_matches_a_fresh_build_across_changes`) deep-equals it
    /// against a fresh build to keep it honest.
    fold_cache: RefCell<FoldMapCache>,
}

/// The document's memoized [`FoldMap`] plus the `(buffer revision, fold
/// generation)` key it was built at.
#[derive(Debug)]
struct FoldMapCache {
    key: (u64, u64),
    map: FoldMap,
}

/// How a reveal request should autoscroll the view to the newest caret.
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum RevealMode {
    /// Fit the newest caret with the margin band, but HOLD the viewport if any
    /// cursor is already on screen — a multi-cursor op (select-all-occurrences,
    /// multi-cursor typing) must not scroll away from cursors the user can
    /// already see. Identical to a plain fit for a single caret.
    Fit,
    /// Always fit the newest caret, even when other cursors are on screen — a
    /// deliberate jump to a just-added cursor (Ctrl+D add-next-occurrence).
    FitForce,
    /// Center the target row (find / diagnostic navigation).
    Center,
}

/// The two corners of a column (box) selection, in DISPLAY space:
/// display *cells*, not byte columns — tabs and collapsed inline folds make
/// the two disagree, and the box is a visual rectangle. Every spanned row
/// resolves the same two cells through the one click inverse
/// ([`FoldMap::hit_row`]), clamping to its own content, so the box stays
/// rectangular over ragged lines and shrinks exactly when the active corner
/// moves back toward the anchor.
#[derive(Copy, Clone, Debug)]
struct ColumnSelection {
    anchor: CellCorner,
    active: CellCorner,
}

/// One box corner: a buffer row (visible when the corner was placed) and a
/// *virtual* display cell — the cell may sit past the row's content.
#[derive(Copy, Clone, Debug)]
struct CellCorner {
    row: u32,
    cell: u32,
}

impl Document {
    /// Load `text` as a new document (see [`Buffer::new`] for the load
    /// contract: size limit, CRLF normalization, EOL-flavor detection). Starts
    /// with a single caret at the top.
    ///
    /// [`Buffer::new`]: crate::Buffer::new
    pub fn new(text: &str) -> Result<Self, LoadError> {
        let buffer = Buffer::new(text)?;
        let brackets = Brackets::match_text(&buffer.text());
        Ok(Self {
            buffer,
            history: History::new(),
            selections: SelectionSet::new(0),
            column: None,
            highlight: None,
            brackets,
            decorations: DecorationStore::new(),
            autoclose: DecorationStore::new(),
            folds: FoldSet::new(),
            find: FindState::new(),
            line_comment: None,
            bracket_string_delims: Vec::new(),
            bracket_char_delim: None,
            expand_stack: Vec::new(),
            reveal_seq: 0,
            reveal_mode: RevealMode::Fit,
            changes: ChangeLog::default(),
            // Seed with a never-matching key so the first `fold_map()` builds it.
            fold_cache: RefCell::new(FoldMapCache { key: (u64::MAX, u64::MAX), map: FoldMap::empty() }),
        })
    }

    /// The memoized fold projection — buffer rows ↔ display rows, hidden
    /// interiors, hit-testing. Rebuilt from scratch only when the buffer revision
    /// or the [`FoldSet`] generation changed since the cached build; otherwise the
    /// cached map is returned untouched, so the render path's ~20 per-frame calls
    /// cost O(1) instead of O(folds) each. The one owner every fold query flows
    /// through.
    #[must_use]
    pub fn fold_map(&self) -> Ref<'_, FoldMap> {
        self.ensure_fold_map();
        Ref::map(self.fold_cache.borrow(), |c| &c.map)
    }

    /// Rebuild the fold cache iff its inputs changed, leaving it current. Split
    /// from [`fold_map`](Self::fold_map) so a caller that also needs `&mut` on a
    /// sibling field (e.g. `move_carets` mutating `selections`) can freshen the
    /// cache and then borrow `fold_cache` and that field disjointly — instead of
    /// building a throwaway O(folds) `FoldMap::new` per keystroke.
    fn ensure_fold_map(&self) {
        let key = (self.buffer.revision().0, self.folds.generation());
        if self.fold_cache.borrow().key != key {
            let map = FoldMap::new(&self.folds, &self.brackets, &self.buffer);
            *self.fold_cache.borrow_mut() = FoldMapCache { key, map };
        }
    }

    /// Ask the view to reveal the newest selection: bump the generation
    /// and record the strategy ([`RevealMode`]). The ONE way a core verb
    /// requests autoscroll; call it only after actually changing state.
    fn request_reveal(&mut self, mode: RevealMode) {
        self.reveal_seq += 1;
        self.reveal_mode = mode;
    }

    /// The [`RevealMode`] of the pending reveal request.
    #[must_use]
    pub fn reveal_mode(&self) -> RevealMode {
        self.reveal_mode
    }

    /// Inject the language's line-comment prefix (e.g. `"//"`) — app-supplied
    /// configuration, like [`Document::set_syntax`]; `None` disables
    /// toggle-comment.
    pub fn set_line_comment(&mut self, prefix: Option<&str>) {
        self.line_comment = prefix.map(str::to_owned);
        // The line comment feeds comment-aware bracket matching too, so brackets
        // inside `// …` stop being matched/colored/folded — rebuild once.
        self.rebuild_brackets();
    }

    /// Configure comment/string-aware bracket matching: `string_delims` (e.g.
    /// `b'"'`) open strings and `char_delim` (e.g. `b'\''`) opens a char literal,
    /// so brackets inside them are not matched (colored, folded, indent-guided).
    /// Line comments come from [`set_line_comment`](Document::set_line_comment).
    /// All constructs are line-local; this rebuilds the bracket set (O(n), for a
    /// setup-time config change, never per edit).
    pub fn set_bracket_lexing(&mut self, string_delims: Vec<u8>, char_delim: Option<u8>) {
        self.bracket_string_delims = string_delims;
        self.bracket_char_delim = char_delim;
        self.rebuild_brackets();
    }

    /// The comment/string skip config derived from the language settings.
    fn bracket_config(&self) -> crate::bracket::BracketConfig {
        crate::bracket::BracketConfig {
            line_comments: self.line_comment.iter().cloned().collect(),
            string_delims: self.bracket_string_delims.clone(),
            char_delim: self.bracket_char_delim,
        }
    }

    /// Rebuild the whole bracket set under the current config — O(n), for a config
    /// change only.
    fn rebuild_brackets(&mut self) {
        let cfg = self.bracket_config();
        self.brackets = crate::bracket::Brackets::match_text_with(&self.buffer.text(), &cfg);
    }

    /// The injected line-comment prefix, if any.
    #[must_use]
    pub fn line_comment(&self) -> Option<&str> {
        self.line_comment.as_deref()
    }

    /// Read-only access to the underlying buffer (text, lines, coordinates,
    /// snapshots).
    #[must_use]
    pub fn buffer(&self) -> &Buffer {
        &self.buffer
    }

    /// The current selection set (carets and ranges).
    #[must_use]
    pub fn selections(&self) -> &SelectionSet {
        &self.selections
    }

    /// Replace the selection set (e.g. a mouse click placing a caret, or a
    /// host's go-to-definition). Host offsets are untrusted, so every endpoint
    /// is clipped to the buffer: past-end offsets clamp to the end, a ranged
    /// selection snaps outward to whole chars ([`Bias::Left`] start,
    /// [`Bias::Right`] end), and a caret inside a char snaps `Left` to its
    /// start; selections the clamp lands on one offset merge.
    pub fn set_selections(&mut self, mut selections: SelectionSet) {
        self.reset_transient();
        // The one door a host-built set walks through. Undo/redo's restore
        // installs history's own sets, captured against this exact text, so it
        // bypasses this (`restore_selections`) rather than paying a re-clip.
        selections.clip_to(&self.buffer);
        self.selections = selections;
    }

    /// Move (or, with `extend`, drag) every caret by `motion`. Vertical
    /// motion is fold-aware: the caret steps display rows, skipping folds.
    pub fn move_carets(&mut self, motion: Motion, extend: bool) {
        self.reset_transient();
        // Read the MEMOIZED fold map, not a throwaway `FoldMap::new` per arrow
        // press: a fresh build is O(folds), which janks at document scale with
        // everything collapsed. Freshen the cache, then borrow `fold_cache` and
        // `selections` disjointly.
        self.ensure_fold_map();
        let tab = self.tab_size();
        let cache = self.fold_cache.borrow();
        movement::move_selections(&mut self.selections, &self.buffer, &cache.map, tab, motion, extend);
    }

    /// Add a bare caret at `offset` — the Alt+Click add-caret gesture.
    /// Merges into any selection it touches via the set's merge rule. The
    /// offset is clipped first: past the end clamps to the end, and inside a
    /// char snaps [`Bias::Left`] to its start.
    pub fn add_caret(&mut self, offset: u32) {
        self.reset_transient();
        self.selections.add_caret(self.buffer.clip_offset(offset, Bias::Left));
    }

    /// Ctrl+D. If the newest selection is an empty caret, select the word
    /// surrounding it; otherwise add the next literal occurrence of the newest
    /// selection's text as a new (and now newest) selection — scanning forward
    /// from its end, wrapping to the document start, skipping already-selected
    /// ranges. No word / no further match ⇒ no change. Selection-only, no edit.
    pub fn add_next_occurrence(&mut self) {
        self.reset_transient();
        let newest = *self.selections.newest();
        if newest.is_empty() {
            // First press: expand the caret to its word. `add_selection` mints a
            // newer id, so the range absorbs the caret and becomes the newest.
            if let Some((ws, we)) = movement::surrounding_word(&self.buffer, newest.head()) {
                if ws != we {
                    self.selections.add_selection(ws, we);
                    // Ctrl+D jumps to the just-added cursor even if others are on
                    // screen — a deliberate FitForce, not the hold-if-visible Fit
                    // that select-all-occurrences uses.
                    self.request_reveal(RevealMode::FitForce);
                }
            }
            return;
        }
        // Read just the needle, not the whole rope: reading the selection alone
        // keeps each press O(needle), never O(document).
        let needle = self.buffer.slice(newest.start()..newest.end()).into_owned();
        let len = needle.len() as u32;
        // Taken-check by binary search over the selection starts (already sorted
        // by start), not an O(carets) linear `any` per candidate.
        let taken: Vec<(u32, u32)> =
            self.selections.all().iter().map(|s| (s.start(), s.end())).collect();
        let is_taken = |s: u32| {
            taken.binary_search_by_key(&s, |&(st, _)| st).is_ok_and(|i| taken[i].1 == s + len)
        };
        // Next literal occurrence at/after the caret, wrapping to the start —
        // windowed over the buffer, never materializing it.
        let from = newest.end();
        let found = scan_from(&self.buffer, &needle, from, self.buffer.len(), &is_taken)
            .or_else(|| scan_from(&self.buffer, &needle, 0, from, &is_taken));
        if let Some((start, end)) = found {
            self.selections.add_selection(start, end);
            // Reveal the newly added cursor (FitForce — jump even if other
            // cursors are already on screen).
            self.request_reveal(RevealMode::FitForce);
        }
    }

    /// Ctrl+Shift+\: move each caret to its matching bracket. Adjacent to
    /// a matched bracket (the [`Brackets::active_pair`] rule — left of the
    /// caret preferred), the caret crosses to the SAME side of the partner, so
    /// a second press returns it. With no adjacent bracket it jumps to the
    /// innermost enclosing pair's closer. No bracket in reach ⇒ the
    /// caret stays. Collapses selections to carets (a plain motion).
    pub fn jump_to_bracket(&mut self) {
        self.reset_transient();
        let targets: Vec<u32> = self
            .selections
            .all()
            .iter()
            .map(|s| {
                let head = s.head();
                if let Some((b, partner)) = self.brackets.active_pair(head) {
                    if head == b + 1 {
                        partner + 1
                    } else {
                        partner
                    }
                } else if let Some((_, close)) = self.brackets.enclosing_pair(head) {
                    close
                } else {
                    head
                }
            })
            .collect();
        let moved =
            targets.iter().zip(self.selections.all()).any(|(&t, s)| t != s.head() || !s.is_empty());
        self.selections = SelectionSet::from_offsets(&targets);
        for &t in &targets {
            self.unfold_to_reveal(t); // a jump lands on a visible position
        }
        if moved {
            self.request_reveal(RevealMode::Fit); // a bracket hop Fit-reveals
        }
    }

    /// Shift+Alt+Right: grow every selection one structural step — caret
    /// → word → bracket contents → bracket pair → outward, ending at the whole
    /// document — pushing the previous set so [`Document::shrink_selection`]
    /// can walk back down. Fully expanded is a no-op (nothing pushed). The
    /// ladder clears on any other gesture or edit. Selection-only.
    pub fn expand_selection(&mut self) {
        self.reset_gesture();
        let before: Vec<(u32, u32)> =
            self.selections.all().iter().map(|s| (s.start(), s.end())).collect();
        let ranges: Vec<(u32, u32)> =
            before.iter().map(|&(s, e)| self.expanded_range(s, e)).collect();
        if ranges == before {
            return;
        }
        let newest_id = self.selections.newest().id;
        let newest = self
            .selections
            .all()
            .iter()
            .position(|s| s.id == newest_id)
            .expect("the newest selection is in its own set");
        self.expand_stack.push(self.selections.clone());
        self.selections = SelectionSet::from_ranges(&ranges, newest);
        self.request_reveal(RevealMode::Fit); // keep the growing head in view
    }

    /// Shift+Alt+Left: step back down the expansion ladder — restore the
    /// set exactly as it was before the matching expand. Empty ladder ⇒ no-op.
    pub fn shrink_selection(&mut self) {
        self.reset_gesture();
        if let Some(prev) = self.expand_stack.pop() {
            self.selections = prev;
            self.request_reveal(RevealMode::Fit);
        }
    }

    /// One structural expansion step for `[start, end]`: an empty caret
    /// grows to its word; otherwise the innermost pair whose contents contain
    /// the range supplies the rung — its contents first, then (already filled)
    /// the pair including its brackets, whose own enclosing pair is one level
    /// out. Outside every pair: the whole document.
    fn expanded_range(&self, start: u32, end: u32) -> (u32, u32) {
        if start == end {
            if let Some((ws, we)) = movement::surrounding_word(&self.buffer, start) {
                if ws != we {
                    return (ws, we);
                }
            }
        }
        if let Some((open, close)) = self.brackets.enclosing_pair_of_range(start, end) {
            let contents = (crate::row_layout::gap_left_edge(open), close);
            if contents != (start, end) {
                return contents;
            }
            return (open, close + 1);
        }
        (0, self.buffer.len())
    }

    /// Ctrl+Alt+↑/↓: add a caret one display row above/below EVERY
    /// existing caret, keeping the current set — the stack-a-column gesture.
    /// Each landing resolves like a click at that caret's visual column (the
    /// `movement::caret_one_display_row` rule → `hit_row`), so tabs, chips,
    /// and collapsed folds behave exactly as plain vertical movement; a caret
    /// already on the first/last display row adds nothing, and a landing on an
    /// existing caret merges via the set's rule. Selection-only. (Landings on
    /// short lines clamp; the visual goal column is not carried across
    /// presses — a deliberate simplification.)
    pub fn add_caret_vertical(&mut self, down: bool) {
        self.reset_transient();
        let folds = FoldMap::new(&self.folds, &self.brackets, &self.buffer);
        let tab = self.tab_size();
        let delta = if down { 1 } else { -1 };
        let heads: Vec<u32> = self.selections.all().iter().map(Selection::head).collect();
        let mut added = false;
        for head in heads {
            if let Some(off) = movement::caret_one_display_row(&self.buffer, &folds, tab, head, delta)
            {
                self.selections.add_caret(off);
                added = true;
            }
        }
        if added {
            self.request_reveal(RevealMode::Fit); // keep the newest caret in view
        }
    }

    /// Ctrl+Shift+L: select EVERY occurrence of the newest selection's
    /// text as a multi-cursor set, seeding from the word under a bare caret
    /// (like Ctrl+D) — the multi-cursor rename: select all, type once.
    /// Single-pass: ONE scan collects every non-overlapping occurrence (the
    /// same `match_indices` rule `find_next_occurrence` uses), skips
    /// already-taken selection ranges, and adds the rest in cyclic order —
    /// forward from the seed, wrapping — so the final `newest` (the reveal
    /// target) is the last occurrence in that order. Selection-only, no edit.
    pub fn select_all_occurrences(&mut self) {
        self.reset_transient();
        let newest = *self.selections.newest();
        if newest.is_empty() {
            let Some((ws, we)) = movement::surrounding_word(&self.buffer, newest.head()) else {
                return;
            };
            if ws == we {
                return;
            }
            self.selections.add_selection(ws, we);
        }
        let newest = *self.selections.newest();
        // Existing selections stay in the set; an occurrence already covered by
        // one merges into it (normalize dedups), so the taken filter only needs
        // to skip re-listing them — an O(occurrences) HashSet probe, not an
        // O(occurrences × selections) `Vec::contains`.
        let existing: Vec<(u32, u32)> =
            self.selections.all().iter().map(|s| (s.start(), s.end())).collect();
        let taken: std::collections::HashSet<(u32, u32)> = existing.iter().copied().collect();
        let occurrences: Vec<(u32, u32)> = {
            let text = self.buffer.text();
            let needle = &text[newest.start() as usize..newest.end() as usize];
            if needle.is_empty() {
                return;
            }
            let len = needle.len() as u32;
            text.match_indices(needle)
                .map(|(i, _)| (i as u32, i as u32 + len))
                .filter(|occ| !taken.contains(occ))
                .collect()
        };
        if occurrences.is_empty() {
            // Every match is already selected — the set is unchanged; just reveal.
            let head = self.selections.newest().head();
            self.unfold_to_reveal(head);
            self.request_reveal(RevealMode::Fit);
            return;
        }
        // Build the whole set in one shot: `from_ranges` runs a SINGLE normalize
        // (O(m log m)); adding occurrences one at a time would re-normalize on
        // every insert (O(m²)). Reveal target = the last occurrence in the
        // forward-cyclic order (`[wrap.., ..wrap]`), the one nearest before the
        // seed, so the viewport reveal lands where the user expects.
        let wrap = occurrences.partition_point(|&(s, _)| s < newest.end());
        let reveal = (wrap + occurrences.len() - 1) % occurrences.len();
        let base = existing.len();
        let mut ranges = existing;
        ranges.extend_from_slice(&occurrences);
        self.selections = SelectionSet::from_ranges(&ranges, base + reveal);
        // The newest occurrence may sit inside a collapsed fold — unfold it
        // and Fit-reveal, so the reveal lands on a visible position rather
        // than a hidden one the widget could not scroll to.
        let head = self.selections.newest().head();
        self.unfold_to_reveal(head);
        self.request_reveal(RevealMode::Fit);
    }

    /// Every live find match becomes a selection (the find bar's
    /// select-all-matches, Alt+Enter) — the multi-cursor "replace all": select
    /// every match, type once. The active match
    /// (or the first) becomes the newest selection, so the caret stays where
    /// find navigation left it. No live matches ⇒ `false`, nothing changes.
    pub fn select_find_matches(&mut self) -> bool {
        let ranges: Vec<(u32, u32)> =
            self.find_matches_in(0..u32::MAX).map(|(r, _)| (r.start, r.end)).collect();
        if ranges.is_empty() {
            return false;
        }
        let newest = (self.active_find_match().unwrap_or(0) as usize).min(ranges.len() - 1);
        self.selections = SelectionSet::from_ranges(&ranges, newest);
        self.reset_transient(); // a jump-class change: seals undo, clears box state
        // The active match must be visible (matches hidden in folds stay as
        // selections — typing into them expands via the edit path).
        let head = self.selections.newest().head();
        self.unfold_to_reveal(head);
        self.request_reveal(RevealMode::Center); // find-family jumps center
        true
    }

    /// Collapse a multi-cursor set (or a single range) to one caret — the primary
    /// (oldest) cursor. The Escape gesture.
    pub fn collapse_selections(&mut self) {
        self.reset_transient();
        self.selections.collapse_to_primary();
    }

    /// Select the whole document — one selection from the start to the end, head
    /// at the end (Ctrl+A). Selection-only, no edit; an empty buffer stays a
    /// single caret at 0.
    pub fn select_all(&mut self) {
        self.reset_transient();
        let end = self.buffer.len();
        self.selections.set_single(Selection::from_anchor(SelectionId(0), 0, end));
    }

    /// Clear transient per-gesture state — the column (box) anchor, the
    /// expand-selection ladder, and the auto-close provenance — and **seal the
    /// open undo group**: every caret move, click, or jump is an undo-group
    /// boundary, so typing after it never merges with the run before it.
    /// Called by every selection-changing verb that isn't a type/backspace (a
    /// plain type keeps the provenance so overtype works, and stays mergeable).
    /// One owner: a new selection verb gets the boundary by calling this, never
    /// by sealing directly.
    fn reset_transient(&mut self) {
        self.expand_stack.clear();
        self.reset_gesture();
    }

    /// [`reset_transient`](Self::reset_transient) minus the expand ladder —
    /// for the expand/shrink verbs themselves, which own that stack but are
    /// still selection gestures (box exit, provenance drop, undo boundary).
    fn reset_gesture(&mut self) {
        self.column = None;
        self.clear_autoclose();
        self.history.seal();
    }

    /// Record fresh auto-close provenance for the given `[open, close)`
    /// pairs — one `AutoClosePair` decoration each, added in ONE batch (a
    /// multi-caret keystroke pairs at every caret; per-item adds would be
    /// quadratic). `AlwaysGrows` so typing at the caret (on the close boundary)
    /// pushes the close along while the open stays put; the store then moves them
    /// through every edit. The pairs live in their OWN [`autoclose`](Self::autoclose)
    /// store (≤ caret-count items), so this batch add is O(pairs), never O(decorations).
    pub(crate) fn add_autoclose_pairs(&mut self, pairs: impl IntoIterator<Item = (u32, u32)>) {
        self.autoclose.add_sorted_batch(
            pairs.into_iter().map(|(open, close)| open..close),
            DecorationKind::AutoClosePair,
            Stickiness::AlwaysGrows,
        );
    }

    /// Every live provenance range `[open_char_start, close_char_start)`, in
    /// ascending order — empty when no pair is active. The pairs are
    /// disjoint, so the ends are ascending too (overtype relies on this).
    /// O(pairs): the own store holds only `AutoClosePair`, so no kind filter is
    /// needed.
    pub(crate) fn autoclose_ranges(&self) -> Vec<Range<u32>> {
        self.autoclose.iter().map(|r| r.range.clone()).collect()
    }

    /// Drop ALL auto-close provenance (its decorations). O(pairs): the own store
    /// holds only the ≤(caret-count) pairs, so this empties it directly — no
    /// whole-`decorations` retain, and no dirty flag to reset.
    pub(crate) fn clear_autoclose(&mut self) {
        if self.autoclose.is_empty() {
            return; // no live pair — nothing to take
        }
        self.autoclose.take_matching_in(0..u32::MAX, |_| true);
    }

    /// Drop each provenance pair no caret still validly occupies — its line
    /// changed, or no caret sits in `(open, close]`. Reads the *rebased* pairs,
    /// so it runs after the commit mover. The carets are sorted, so each pair is
    /// probed in O(log carets); the scan is over the own store (≤ caret-count),
    /// so validate is O(pairs · log carets), independent of `decorations`.
    pub(crate) fn validate_autoclose(&mut self) {
        if self.autoclose.is_empty() {
            return; // no live pair — nothing to validate
        }
        let carets: Vec<u32> = self.selections.all().iter().map(|s| s.head()).collect();
        let Self { autoclose, buffer, .. } = self;
        autoclose.take_matching_in(0..u32::MAX, |r| {
            debug_assert!(
                matches!(r.kind, DecorationKind::AutoClosePair),
                "the autoclose store holds only AutoClosePair provenance",
            );
            let (start, end) = (r.range.start, r.range.end);
            let one_line = buffer.offset_to_point(start).row == buffer.offset_to_point(end).row;
            // A caret validly occupies the pair when it is in (open, close].
            let occupied = one_line && {
                let i = carets.partition_point(|&h| h <= start);
                i < carets.len() && carets[i] <= end
            };
            !occupied // remove the pair no caret occupies
        });
    }

    /// Drag-select from `origin` to `head` at the given `granularity`. Char
    /// is a plain range; Word/Line extend by whole units and keep the origin unit
    /// fully selected even when the drag reverses past it (the tail flips to the
    /// far edge of the origin unit). `head == origin` selects just the origin
    /// unit — the double/triple-click initial selection. Replaces the set.
    /// Both offsets are clipped first, like a caret: past the end clamps to the
    /// end, and inside a char snaps [`Bias::Left`] to its start.
    pub fn drag_select(&mut self, granularity: Granularity, origin: u32, head: u32) {
        self.reset_transient();
        // Clip before the unit scans: the word scan reads chars at `origin`
        // and `head`, and a mid-char read is a panic, not a wrong answer.
        let origin = self.buffer.clip_offset(origin, Bias::Left);
        let head = self.buffer.clip_offset(head, Bias::Left);
        let (anchor, head) = match granularity {
            Granularity::Char => (origin, head),
            Granularity::Word => {
                extend_by_unit(self.word_unit(origin), self.word_unit(head), origin, head)
            }
            Granularity::Line => {
                extend_by_unit(self.line_unit(origin), self.line_unit(head), origin, head)
            }
        };
        self.selections.set_single(Selection::from_anchor(SelectionId(0), anchor, head));
    }

    /// The word range surrounding `offset`, or a bare caret there in whitespace.
    fn word_unit(&self, offset: u32) -> (u32, u32) {
        movement::surrounding_word(&self.buffer, offset).unwrap_or((offset, offset))
    }

    /// The line range at `offset`, including the trailing newline (or to line
    /// end on the final line). THE whole-line unit — triple-click drag and the
    /// whole-line Copy/Cut/Paste verbs all read this one rule.
    pub(crate) fn line_unit(&self, offset: u32) -> (u32, u32) {
        let row = self.buffer.offset_to_point(offset).row;
        let start = self.buffer.point_to_offset(Point::new(row, 0));
        let end = if row + 1 < self.buffer.line_count() {
            self.buffer.point_to_offset(Point::new(row + 1, 0))
        } else {
            self.buffer.point_to_offset(Point::new(row, self.buffer.line_len(row)))
        };
        (start, end)
    }

    /// Column (box) selection — Ctrl+Shift+Alt+Arrow. The first press anchors
    /// at the primary caret; each press steps the *active* corner by `dir` and
    /// rebuilds one selection per spanned row, from the anchor cell to the active
    /// cell. Stepping the active corner back toward the anchor shrinks the box.
    /// Display-space end to end: corners are display CELLS, so the box stays
    /// visually rectangular across tabs and collapsed inline folds; vertical
    /// steps walk display rows (a collapsed fold is one step, not one per hidden
    /// row); and cells are virtual (unbounded right), so a box can reach past
    /// short lines and still select the full width of longer ones. Selection-only;
    /// any other action exits the mode, leaving the box as a multi-cursor set.
    pub fn column_select(&mut self, dir: ColumnDir) {
        // A box gesture is a selection change, so it is an undo-group boundary
        // and it invalidates the expand ladder — but it must KEEP `self.column`,
        // so it can't go through `reset_transient`.
        self.history.seal();
        self.expand_stack.clear();
        let folds = FoldMap::new(&self.folds, &self.brackets, &self.buffer);
        let tab = self.tab_size();
        let mut col = self.column.unwrap_or_else(|| {
            let corner = self.caret_corner(&folds, tab);
            ColumnSelection { anchor: corner, active: corner }
        });
        col.active = Self::step_corner(&folds, col.active, dir);
        self.column = Some(col);
        self.rebuild_column_box(&folds, tab, col);
    }

    /// Mouse box (column) selection — Shift+Alt+drag. Sets the box from an
    /// `anchor` and `active` corner, each `(visible buffer row, display cell)`;
    /// the widget derives the row from the one row inversion and the cell from
    /// the one virtual-cell rounding rule ([`crate::row_layout::virtual_cell`]).
    /// Cells are *virtual* (unclamped by line): the box clamps each row to its
    /// own content, so a drag past short lines still selects the full width of
    /// longer ones. Same selection-only semantics as `column_select`; any other
    /// action exits the mode. Shares `Document.column`, so a keyboard box then
    /// continues it. A corner row past the document clamps to the last row
    /// (the cell, being virtual, is kept as given).
    pub fn column_drag(&mut self, anchor: (u32, u32), active: (u32, u32)) {
        // Same boundary + ladder rule as `column_select`.
        self.history.seal();
        self.expand_stack.clear();
        let folds = FoldMap::new(&self.folds, &self.brackets, &self.buffer);
        // Clamp the rows before they are stored: the box builds one selection
        // per row it spans, so an unclamped host row would cost (and allocate)
        // per *requested* row, and survive as the anchor a keyboard box steps
        // from. Cells need no clamp — every row resolves them through
        // `hit_row`, which clamps to that row's content.
        let last = self.buffer.line_count() - 1;
        let col = ColumnSelection {
            anchor: CellCorner { row: anchor.0.min(last), cell: anchor.1 },
            active: CellCorner { row: active.0.min(last), cell: active.1 },
        };
        self.column = Some(col);
        self.rebuild_column_box(&folds, self.tab_size(), col);
    }

    /// The primary caret's box corner: its rendered position — the one owner of
    /// display geometry, [`FoldMap::display_position`] — as a `(visible buffer
    /// row, display cell)`
    /// pair. A caret on a collapsed fold's closing tail anchors on the header
    /// row it renders on. (Fold-time ejection keeps carets visible, so the
    /// hidden-offset fallback to the raw buffer point is belt and braces.)
    fn caret_corner(&self, folds: &FoldMap, tab: u32) -> CellCorner {
        let head = self.selections.newest().head();
        match folds.display_position(&self.buffer, head, tab) {
            Some(p) => CellCorner {
                row: folds.to_buffer_row(p.row).0,
                cell: crate::row_layout::virtual_cell(p.x.cells()),
            },
            None => {
                let p = self.buffer.offset_to_point(head);
                let layout = folds.row_layout(&self.buffer, BufferRow(p.row), tab);
                CellCorner { row: p.row, cell: layout.display_cell(p.col) }
            }
        }
    }

    /// Step a box corner one unit in `dir`, in display space: vertical steps
    /// walk display rows — a collapsed fold is hopped in one step — and clamp
    /// to the document; the left cell saturates at 0; the right cell is
    /// unbounded so it can reach past short lines.
    fn step_corner(folds: &FoldMap, c: CellCorner, dir: ColumnDir) -> CellCorner {
        let d = folds.to_display_row(BufferRow(c.row)).index();
        let row_at = |d: u32| folds.to_buffer_row(DisplayRow(d)).0;
        match dir {
            ColumnDir::Up => CellCorner { row: row_at(d.saturating_sub(1)), cell: c.cell },
            ColumnDir::Down => {
                CellCorner { row: row_at((d + 1).min(folds.max_display_row().index())), cell: c.cell }
            }
            ColumnDir::Left => CellCorner { row: c.row, cell: c.cell.saturating_sub(1) },
            // Saturating: a host corner may already sit at the largest cell.
            ColumnDir::Right => CellCorner { row: c.row, cell: c.cell.saturating_add(1) },
        }
    }

    /// Install the box `col` as the selection set: one selection per spanned
    /// *display* row (a collapsed fold's hidden rows get none), each corner cell
    /// resolved to its byte offset through the one click inverse
    /// ([`FoldMap::hit_row`]: tab snapping, chip resolution, header gap/tail) —
    /// so the box selects exactly what its rectangle crosses on screen, clamped
    /// to each row's content. The active row's selection is the newest
    /// (autoscroll target).
    fn rebuild_column_box(&mut self, folds: &FoldMap, tab: u32, col: ColumnSelection) {
        let da = folds.to_display_row(BufferRow(col.anchor.row)).index();
        let dv = folds.to_display_row(BufferRow(col.active.row)).index();
        let (d0, d1) = (da.min(dv), da.max(dv));
        let mut ranges = Vec::with_capacity((d1 - d0 + 1) as usize);
        let mut newest = 0;
        for d in d0..=d1 {
            let row = folds.to_buffer_row(DisplayRow(d));
            let anchor_off = folds.hit_row(&self.buffer, row, col.anchor.cell as f32, Bias::Left, tab);
            let head_off = folds.hit_row(&self.buffer, row, col.active.cell as f32, Bias::Left, tab);
            if d == dv {
                newest = ranges.len();
            }
            ranges.push((anchor_off, head_off));
        }
        self.selections = SelectionSet::from_ranges(&ranges, newest);
    }

    /// The full document text (LF-only). Shorthand for `self.buffer().text()`
    /// — a **cold-path** whole-text read: O(document), never call it per-frame
    /// or per-keystroke.
    #[must_use]
    pub fn text(&self) -> Cow<'_, str> {
        self.buffer.text()
    }

    /// The current revision.
    #[must_use]
    pub fn revision(&self) -> Revision {
        self.buffer.revision()
    }

    /// An immutable snapshot for a background consumer (the compile thread).
    /// O(1) — a rope clone; the consumer pays for what it reads.
    #[must_use]
    pub fn snapshot(&self) -> Snapshot {
        self.buffer.snapshot()
    }

    /// Apply a batch of edits as one discrete transaction (its own undo step).
    ///
    /// This is the common programmatic path. For keystroke-level edits that
    /// should merge into one undo unit, use [`Document::edit_grouped`].
    /// Returns the [`Committed`] result (forward patch + change records); an
    /// empty/no-op batch changes nothing and records no undo step.
    pub fn edit(&mut self, ops: Vec<EditOp>) -> Result<Committed, TransactionError> {
        self.edit_grouped(ops, GroupingHint::discrete())
    }

    /// Apply a batch of edits with an explicit [`GroupingHint`]: the
    /// verbs layer uses this so a typing run collapses to one undo step.
    ///
    /// The selections rebase through the edit, and that rebased set is what
    /// [`redo`](Document::redo) restores for this unit; the set ahead of the
    /// unit is what [`undo`](Document::undo) restores.
    pub fn edit_grouped(
        &mut self,
        ops: Vec<EditOp>,
        hint: GroupingHint,
    ) -> Result<Committed, TransactionError> {
        self.edit_placing(ops, hint, |_, _| None)
    }

    /// THE commit path — [`edit_grouped`](Document::edit_grouped) plus a caret
    /// placement. `place` sees the committed forward patch and the post-edit
    /// document — buffer, rebased selections, every view already moved (the
    /// find set repaired) — and returns the selections the edit leaves (`None`
    /// keeps the rebased set); it runs only for an edit that changed text.
    ///
    /// Placement lives INSIDE the commit, not after it returns, because history
    /// records each unit's after-selections with the transaction: a verb that
    /// assigned `self.selections` once this returned would show its carets but
    /// leave redo restoring the rebased ones. The contract, exactly: every core
    /// verb whose edit leaves the selections anywhere but the rebased set places
    /// them here (`run_edit`, auto-close, surround, Enter, insert-line, move and
    /// copy line, [`replace_next`](Document::replace_next)'s advance), so redo
    /// restores what the verb showed. A selection set once a commit has returned
    /// is a separate selection gesture, outside the unit. One known exception
    /// does that on purpose: scrive-iced's `CodeEditor::accept_completion`
    /// inserts through [`insert_text`](Document::insert_text), then selects the
    /// snippet's first tab stop (or its final caret) itself — so redoing an
    /// accepted snippet restores the caret after the inserted text, not the
    /// stop. Core has no snippet-insert verb to place that through, and the
    /// tab-stop session it would select into is widget state that history does
    /// not restore either.
    pub(crate) fn edit_placing(
        &mut self,
        ops: Vec<EditOp>,
        hint: GroupingHint,
        place: impl FnOnce(&Patch, &Document) -> Option<SelectionSet>,
    ) -> Result<Committed, TransactionError> {
        self.column = None; // any text edit exits column-select mode…
        self.expand_stack.clear(); // …and invalidates the expand ladder
        // The selections ahead of the edit — what undo restores — captured
        // before the patch rebases them, and only when this edit opens a unit:
        // a keystroke merging into an open run keeps the run's first before-set,
        // so it needs (and clones) nothing here.
        let sel_before = (!self.history.merges(hint)).then(|| self.selections.clone());
        // The (revision, fold generation) the fold cache would need to be at to
        // shift it in place instead of rebuilding — captured before the edit.
        let pre_fold_key = (self.buffer.revision().0, self.folds.generation());
        let committed = apply(&mut self.buffer, ops)?;
        if !committed.is_empty() {
            // Whether the edit added or removed a bracket character — the
            // reconcile gate below, read from the applied (forward) + inverse ops
            // the transaction already owns, so no `ops.clone()` is needed to see
            // the forward text. History records both (by move) at the end.
            let bracket_edit = committed
                .forward_ops()
                .iter()
                .chain(committed.inverse_ops())
                .any(|op| op.text.bytes().any(crate::bracket::is_bracket_byte));
            // Programmatic edits shift carets through the patch; the verbs layer
            // overrides this with precise post-edit caret placement.
            self.selections.rebase(committed.patch());

            let tab = self.tab_size();
            // Comment/string-aware bracket config, cloned before the `&mut self`
            // views borrow so the mover can consult it.
            let bracket_cfg = self.bracket_config();
            // Rebase every derived view through the patch — the single mover,
            // shared verbatim with undo/redo (see `rebase_views`). The auto-close
            // provenance is an `AutoClosePair` decoration, so it rides here too —
            // no hand-rebasing; the fold reveal and the change log ride inside it
            // too.
            let region = rebase_views(
                &mut Views {
                    highlight: &mut self.highlight,
                    brackets: &mut self.brackets,
                    decorations: &mut self.decorations,
                    autoclose: &mut self.autoclose,
                    folds: &mut self.folds,
                    find: &mut self.find,
                    changes: &mut self.changes,
                },
                &self.buffer,
                tab,
                &committed,
                &bracket_cfg,
            );

            // Now that the provenance decoration has ridden the patch, drop it if
            // the caret has left the pair — after the rebase, not before.
            self.validate_autoclose();
            // Drop folds the edit invalidated (e.g. a deleted closing brace) so a
            // modification can't leave rows hidden with no chevron — but ONLY when
            // a bracket CHARACTER was added or removed. If none was, the bracket
            // sequence is unchanged (same chars, merely shifted), so the matching
            // automaton produces the identical pairing — no fold can lose its
            // pair, and reconcile would drop nothing. This skips the whole step
            // for plain typing AND for Enter (a line change with no bracket char).
            // When a bracket DID change, `region` (empty ⇒ shift-only, i.e. not
            // structural) bounds the work to the folds the edit's re-matched rows
            // could touch, not all folds. Any fold whose interior an edit touched
            // was already expanded above.
            if bracket_edit && !region.is_empty() {
                self.reconcile_folds_in(region);
            }
            // Keep the memoized FoldMap current without the per-keystroke O(folds)
            // rebuild: if the cache was current before this edit AND the edit
            // added/removed no fold (generation unchanged — expand/reconcile can
            // bump it), shift it through the patch in place. A line change (or a
            // stale cache, or a fold add/remove) invalidates for a rebuild on the
            // next `fold_map()`. The `pre_fold_key` guard makes a mid-edit
            // `fold_map()` rebuild (which would move the key) fall back safely
            // rather than double-apply the patch.
            {
                let mut cache = self.fold_cache.borrow_mut();
                if cache.key == pre_fold_key
                    && self.folds.generation() == pre_fold_key.1
                    && cache.map.apply_patch(committed.patch(), &self.buffer)
                {
                    cache.key = (self.buffer.revision().0, pre_fold_key.1);
                } else {
                    cache.key = (u64::MAX, u64::MAX);
                }
            }
            // The verb's caret placement replaces the rebased set — after the
            // autoclose validation above, which judges the pairs by the REBASED
            // carets (the order verbs had when they placed carets post-return).
            if let Some(placed) = place(committed.patch(), self) {
                self.selections = placed;
            }
            // Record history LAST, moving the forward + inverse op batches out of
            // `committed` with no clone (rebase_views already used its borrow of
            // the inverse; the fold-cache borrow above has been dropped, freeing
            // `&mut self` for `history`), with the selections on either side of
            // the unit. The returned `Committed` keeps only the patch — the sole
            // part callers (the verbs layer) read.
            let (patch, forward, inverse) = committed.into_ops();
            self.history.record(forward, inverse, hint, sel_before, &self.selections);
            return Ok(Committed::from_patch(patch));
        }
        Ok(committed)
    }

    /// Enable or disable the incremental-change log. Off by default so the common
    /// path pays nothing; a host mirroring edits to a language server
    /// (`textDocument/didChange`) turns it on — taking the current
    /// [`text`](Document::text) as its starting copy — and drains
    /// [`drain_changes`](Document::drain_changes) after each edit, undo, or
    /// redo. Turning it off clears any pending log. For full-document sync, leave
    /// this off and re-read [`snapshot`](Document::snapshot) instead.
    pub fn observe_changes(&mut self, on: bool) {
        self.changes.set_observing(on);
    }

    /// Drain the incremental-change log: every applied change since the last
    /// drain — forward edits, undo, and redo alike — as `EditOp` deltas in
    /// **sequential replay order**: each op's `range` is in the coordinates of
    /// the document as left by the previous op, so applying them one by one, in
    /// order, to the text the host last saw yields exactly
    /// [`text`](Document::text) — the shape of a language server's
    /// content-change array. Empty unless
    /// [`observe_changes`](Document::observe_changes) is on.
    #[must_use]
    pub fn drain_changes(&mut self) -> Vec<EditOp> {
        self.changes.drain()
    }

    /// Undo the most recent undo unit, restoring the selections from before it
    /// — every caret of a multi-cursor edit, and for a merged typing run the set
    /// from before its first keystroke. Returns `false` if there is nothing to
    /// undo.
    ///
    /// Each reverted step threads its patch through `rebase_views` — the exact
    /// mover forward edits use — so highlight, brackets, and every decoration
    /// (diagnostics, find matches, snippet stops) stay consistent with no
    /// undo-specific resync per feature. The fields are destructured so the
    /// per-step callback can borrow the views while history borrows the buffer.
    pub fn undo(&mut self) -> bool {
        self.reset_transient();
        let tab = self.tab_size();
        let bracket_cfg = self.bracket_config();
        let Self {
            history, buffer, highlight, brackets, decorations, autoclose, folds, find, changes, ..
        } = self;
        let mut views = Views { highlight, brackets, decorations, autoclose, folds, find, changes };
        let restored = history.undo(buffer, |committed, buffer| {
            // The one mover — highlight, brackets, decorations, folds (position +
            // fold reveal) all ride it, so undo needs no per-feature resync.
            rebase_views(&mut views, buffer, tab, committed, &bracket_cfg);
        });
        let Some(selections) = restored else { return false };
        // Reverting text can invalidate a fold's bracket pair too — reconcile once
        // the buffer/brackets are settled, same as the forward edit path, and
        // BEFORE the restore below ejects carets against the surviving folds.
        self.reconcile_folds();
        self.restore_selections(selections);
        true
    }

    /// Redo the most recently undone unit — the [`undo`](Document::undo) mirror,
    /// through the same `rebase_views` mover — restoring the selections the
    /// unit left (a verb's caret placement included). Returns `false` if
    /// nothing to redo.
    pub fn redo(&mut self) -> bool {
        self.reset_transient();
        let tab = self.tab_size();
        let bracket_cfg = self.bracket_config();
        let Self {
            history, buffer, highlight, brackets, decorations, autoclose, folds, find, changes, ..
        } = self;
        let mut views = Views { highlight, brackets, decorations, autoclose, folds, find, changes };
        let restored = history.redo(buffer, |committed, buffer| {
            // The same one mover as `undo` (folds ride it, position + fold reveal).
            rebase_views(&mut views, buffer, tab, committed, &bracket_cfg);
        });
        let Some(selections) = restored else { return false };
        self.reconcile_folds();
        self.restore_selections(selections);
        true
    }

    /// Install a selection set history recorded — undo's before-set or redo's
    /// after-set. The offsets need no rebasing (the buffer is byte-identical to
    /// the state they were captured in), but the folds may differ: one collapsed
    /// since the capture can hide a restored caret (the mover expanded the folds
    /// hiding the reverted edit itself, but a caret elsewhere in the set gets no
    /// such reveal), so restore ejects through the same pass a fold gesture uses.
    /// The widget's caret autoscroll then follows the newest restored selection.
    fn restore_selections(&mut self, selections: SelectionSet) {
        self.selections = selections;
        self.eject_hidden_carets();
    }

    /// Whether the document differs from the last [`Document::mark_saved`].
    #[must_use]
    pub fn is_dirty(&self) -> bool {
        self.history.is_dirty()
    }

    /// Record the current state as saved (clears the dirty flag).
    pub fn mark_saved(&mut self) {
        self.history.mark_saved();
    }

    /// Whether there is an edit to [`undo`](Document::undo).
    #[must_use]
    pub fn can_undo(&self) -> bool {
        self.history.can_undo()
    }

    /// Whether there is an edit to [`redo`](Document::redo) along the current
    /// branch.
    #[must_use]
    pub fn can_redo(&self) -> bool {
        self.history.can_redo()
    }

    /// How many redo branches diverge from the current position: 1 in the
    /// classic single-line case, ≥2 at a fork where an undo was followed by a
    /// *divergent* edit — the branching undo tree retains the branch you undid
    /// out of rather than discarding it, so it stays reachable.
    #[must_use]
    pub fn redo_branch_count(&self) -> usize {
        self.history.redo_branch_count()
    }

    /// Steer the next [`redo`](Document::redo) to the `index`-th redo branch
    /// (0 = oldest), returning `false` if out of range. The chosen branch also
    /// becomes the default thereafter. Plain redo (without selecting) always
    /// follows the most-recent branch, so single-line undo is unchanged.
    pub fn select_redo_branch(&mut self, index: usize) -> bool {
        self.history.select_redo_branch(index)
    }

    /// Cap undo history at `limit` units on the current line (`None` = the
    /// default, unbounded), dropping older units and any branch that diverged
    /// before the kept window. Opt-in: a host that wants bounded undo memory
    /// calls this; by default nothing is ever pruned.
    pub fn set_undo_limit(&mut self, limit: Option<usize>) {
        self.history.set_max_undo(limit);
    }

    /// How many undo steps are currently reachable — the depth of `undo`
    /// (bounded by [`set_undo_limit`](Document::set_undo_limit) when set).
    #[must_use]
    pub fn undo_depth(&self) -> usize {
        self.history.undo_depth()
    }

    /// Serialize for saving, re-expanding LF to the given flavor.
    #[must_use]
    pub fn serialize(&self, flavor: EolFlavor) -> String {
        self.buffer.serialize(flavor)
    }

    /// Attach a syntax highlighter. The grammar and theme are app-supplied
    /// (scrive-core is language-agnostic). The cache starts sized to the current
    /// line count, every line dirty; call [`Document::tokenize_highlight`] before
    /// reading spans, and it re-splices on every edit. A mid-session grammar
    /// swap carries the previous retention-window aim forward, so the currently
    /// visible rows are re-highlighted immediately even though nothing visible
    /// moved to re-trigger the widget's viewport report.
    pub fn set_syntax(&mut self, syntax: SyntaxDef, theme: TokenTheme) {
        let aim = self.highlight.as_ref().map(HighlightCache::window_aim);
        let mut cache = HighlightCache::new(syntax, theme, self.buffer.line_count());
        if let Some(aim) = aim {
            cache.set_window(aim);
        }
        self.highlight = Some(cache);
    }

    /// Swap the highlight theme, keeping the grammar and cache sizing. The
    /// whole cache invalidates; colors repaint on the next `tokenize_highlight`
    /// (old colors show meanwhile — see [`HighlightCache::set_theme`]). No-op
    /// without a highlighter.
    pub fn set_theme(&mut self, theme: TokenTheme) {
        if let Some(cache) = self.highlight.as_mut() {
            cache.set_theme(theme);
        }
    }

    /// The tracked-range decoration store. Exposed so an app-level owner —
    /// e.g. a snippet session registering one range per tab stop — can
    /// drive it through the store's handle API. The store rides edits
    /// automatically: every transaction patches it before change events fire.
    #[must_use]
    pub fn decorations(&self) -> &DecorationStore {
        &self.decorations
    }

    /// Mutable [`decorations`](Document::decorations) for a decoration owner.
    /// Host ranges are untrusted, so the store is handed out with the current
    /// text lent to it: every range it stores until the next edit is clipped to
    /// the buffer by the one range rule — past-end ends clamp to the end, a
    /// non-empty range snaps outward to whole chars ([`Bias::Left`] start,
    /// [`Bias::Right`] end), an empty one `Left` to its char's start.
    pub fn decorations_mut(&mut self) -> &mut DecorationStore {
        // O(1): the lent copy shares the rope's structure; the next commit's
        // mover drops it before the text can differ (see the store's doc).
        self.decorations.lend_text(&self.buffer);
        &mut self.decorations
    }

    /// How many live auto-close provenance pairs the own store holds — the
    /// store-as-truth count, for tests that pin the provenance lifetime.
    #[cfg(test)]
    #[must_use]
    pub(crate) fn autoclose_pair_count(&self) -> usize {
        self.autoclose.len()
    }

    /// The active code folds — read access for building a per-frame
    /// [`FoldMap`].
    #[must_use]
    pub fn folds(&self) -> &FoldSet {
        &self.folds
    }

    /// Mutable access to the fold set (e.g. `clear`). Folds are view state:
    /// mutating them records nothing on the undo stack. Row-based fold/unfold go
    /// through the convenience methods below (they need the buffer too).
    pub fn folds_mut(&mut self) -> &mut FoldSet {
        &mut self.folds
    }

    /// Fold the multi-line bracket pair opening on `header` and closing on
    /// `last`. A fold is keyed by that pair's opening-bracket offset. Nesting is
    /// allowed (folds may sit inside or around others). Returns `false` if no such
    /// foldable pair exists or it is already folded. Records nothing on the undo
    /// stack — folds are view state.
    pub fn fold(&mut self, header: BufferRow, last: BufferRow) -> bool {
        match self.opener_of(header.0, last.0) {
            Some(open) => self.folds.fold(open),
            None => false,
        }
    }

    /// Unfold the fold whose header (opener row) is `header`. Returns whether one
    /// was removed.
    pub fn unfold(&mut self, header: BufferRow) -> bool {
        match self.folded_opener_on(header.0) {
            Some(open) => self.folds.unfold(open),
            None => false,
        }
    }

    /// Fold if `header` has no active fold, else unfold it (the gutter-chevron /
    /// `Ctrl+Shift+[`,`]` action).
    pub fn toggle_fold(&mut self, header: BufferRow, last: BufferRow) -> bool {
        match self.folded_opener_on(header.0) {
            Some(open) => self.folds.unfold(open),
            None => self.fold(header, last),
        }
    }

    /// The opening-bracket offset of the collapsed fold whose opener sits on
    /// buffer row `header`, if any. Openers are offset-sorted, so this is the
    /// first fold at/after the row start that still lies on the row — an O(log)
    /// probe, so a gutter unfold click never scans every fold.
    fn folded_opener_on(&self, header: u32) -> Option<u32> {
        let start = self.buffer.point_to_offset(Point::new(header, 0));
        let end = if header + 1 >= self.buffer.line_count() {
            self.buffer.len() + 1 // sentinel: an opener at the final byte is on the row
        } else {
            self.buffer.point_to_offset(Point::new(header + 1, 0))
        };
        self.folds.first_at_or_after(start).filter(|&o| o < end)
    }

    /// The opening-bracket offset of the foldable pair spanning rows
    /// `(header, last)`, if one exists.
    fn opener_of(&self, header: u32, last: u32) -> Option<u32> {
        // A pair headed on `header` has its opener on that row — window there.
        self.foldable_pairs_in_rows(header..header + 1)
            .into_iter()
            .find(|&(_, _, h, l)| h == header && l == last)
            .map(|(o, ..)| o)
    }

    /// Every foldable bracket pair as `(open_offset, close_offset, header_row,
    /// last_row)`, in document order — the bracket-anchored source for folds. A
    /// pair is foldable when it has a *non-empty* interior: multi-line (a block)
    /// or single-line with something between the brackets (an inline fold).
    fn foldable_pairs(&self) -> Vec<(u32, u32, u32, u32)> {
        self.foldable_pairs_from(&self.brackets.all())
    }

    /// `Document::foldable_pairs` restricted to pairs whose **opening bracket**
    /// lies on a buffer row in `rows` — the windowed twin for the fold mouse
    /// hot paths (gutter hover/click, Ctrl+hover boxes), so they cost
    /// O(brackets in the window) instead of a whole-document scan per
    /// mouse-move on a large document. Since a pair's `header` is
    /// its opener's row, this returns exactly the pairs headed in `rows` (their
    /// closer may lie far below — that offset is carried in the bracket, no
    /// second scan). A pair *enclosing* `rows` from above is intentionally not
    /// returned (its opener is elsewhere); callers that only test `header ==
    /// row` (block_opener_on_row, the gutter chevron) are exact, and the
    /// Ctrl+hover affordance widens `rows` with a slack for near-enclosing
    /// blocks.
    ///
    /// Public because the widget's plain-hover chip hit-test
    /// (`collapsed_chip_at`) needs exactly this: every foldable pair — inline
    /// `[ … ]` and block `{ … }` alike — headed on the pointer's single row, so
    /// it can test that row's chips instead of scanning every fold in the
    /// document (an O(folds) `HeaderLayout` build per frame at scale).
    pub fn foldable_pairs_in_rows(&self, rows: Range<u32>) -> Vec<(u32, u32, u32, u32)> {
        let start = self.buffer.point_to_offset(Point::new(rows.start, 0));
        let end = if rows.end >= self.buffer.line_count() {
            self.buffer.len() + 1 // sentinel: a bracket at the final byte is inside
        } else {
            self.buffer.point_to_offset(Point::new(rows.end, 0))
        };
        self.foldable_pairs_from(&self.brackets.in_range(start..end))
    }

    /// The shared body of `Document::foldable_pairs` and its windowed twin.
    fn foldable_pairs_from(&self, brackets: &[crate::bracket::Bracket]) -> Vec<(u32, u32, u32, u32)> {
        brackets
            .iter()
            .filter_map(|b| {
                let close = b.partner.filter(|_| b.open)?;
                // The shared foldability rule: a non-empty interior.
                crate::row_layout::pair_has_interior(b.offset, close).then(|| {
                    let header = self.buffer.offset_to_point(b.offset).row;
                    let last = self.buffer.offset_to_point(close).row;
                    (b.offset, close, header, last)
                })
            })
            .collect()
    }

    /// Toggle the fold whose opening bracket is at byte offset `opener` (a
    /// gutter-chevron click or `Ctrl+Shift+[`/`]`). Returns whether it changed.
    /// When it *folds*, any caret the fold would hide is ejected to the gap's
    /// entry edge so it never sits on collapsed text: an inline pair
    /// pulls it to `opener+1` (just after `[`), a block to the header line's
    /// end (just before the `…` placeholder). A host `opener` is clipped first
    /// (past the end clamps to the end; inside a char snaps [`Bias::Left`] to
    /// its start), so a fold is never keyed off the buffer's char grid.
    pub fn toggle_fold_opener(&mut self, opener: u32) -> bool {
        // An opener is a bracket, which is ASCII, so a clipped mid-char offset
        // can never be one — the clip only keeps a bad host offset in range.
        let opener = self.buffer.clip_offset(opener, Bias::Left);
        let changed = self.folds.toggle(opener);
        if changed {
            // A fold toggle is a gesture that can MOVE carets (the ejection
            // below), so it takes the same boundary as every selection verb:
            // seal the undo group, drop the box anchor / expand ladder /
            // auto-close provenance — otherwise a stale expand ladder could
            // restore a caret into the collapsed fold.
            self.reset_transient();
        }
        if changed && self.folds.is_folded(opener) {
            // Eject every caret the fold just hid, so typing can never edit
            // invisible text — the batch gesture's own pass, reading the
            // one hiding owner (`entry_edge_if_hidden`) off the MEMOIZED map:
            // the toggle bumped the fold generation, so this build is the one
            // the next render reads, not a throwaway the render repeats. A
            // caret hidden by an enclosing collapsed fold lands on that fold's
            // (visible) entry edge rather than this one's.
            self.eject_hidden_carets();
        }
        changed
    }

    /// The document's tab-stop width — the ONE owner every consumer (core
    /// projections and the widget's pixel layer alike) consults. Fixed at the
    /// [`crate::display_map::default_tab_size`] for now; when it becomes
    /// configurable, the change is one whole-document edit and no
    /// caller-side constant exists to drift.
    #[must_use]
    pub fn tab_size(&self) -> u32 {
        crate::display_map::default_tab_size()
    }

    /// The opener offset of the widest *multi-line* pair whose header is buffer
    /// row `row` — the block a gutter chevron on that row folds.
    #[must_use]
    pub fn block_opener_on_row(&self, row: u32) -> Option<u32> {
        // Windowed to the row's brackets (a pair headed on `row` has its opener
        // on `row`) — O(brackets on the row), not a whole-document scan per
        // gutter click.
        self.foldable_pairs_in_rows(row..row + 1)
            .into_iter()
            .filter(|&(_, _, h, l)| h == row && l > h)
            .max_by_key(|&(_, _, h, l)| l - h)
            .map(|(o, ..)| o)
    }

    /// The opener of the innermost foldable pair enclosing **or touching** the
    /// primary caret whose collapsed state matches `want_folded` — the
    /// `Ctrl+Shift+[` (fold, `false`) / `Ctrl+Shift+]` (unfold, `true`) target.
    /// A caret directly before the opening bracket or after the closing one
    /// counts (the bracket-highlight adjacency). Includes single-line inline
    /// pairs, disambiguated by the caret's byte offset (rows can't tell two
    /// `[..]` apart).
    #[must_use]
    pub fn fold_opener_at_caret(&self, want_folded: bool) -> Option<u32> {
        self.fold_opener_at(self.selections.newest().head(), want_folded)
    }

    /// The innermost foldable pair enclosing or touching `caret` whose collapsed
    /// state matches `want_folded` — the per-caret core of the fold chords.
    /// Costs O(distance to the innermost target), NOT O(leftward siblings): a
    /// touching pair (the innermost possible) is found by an O(log) lookup, and
    /// otherwise the enclosing walk early-stops at the first match — so
    /// [`Self::fold_at_carets`] over N carets stays O(N · local), not O(N²).
    fn fold_opener_at(&self, caret: u32, want_folded: bool) -> Option<u32> {
        let is_target = |open: u32, close: u32| {
            crate::row_layout::pair_has_interior(open, close)
                && self.folds.is_folded(open) == want_folded
        };
        // Touching pairs are the innermost possible (an encloser is strictly
        // larger, since it contains the touch): the caret ON a foldable opener,
        // or just past a foldable closer. Pick the smaller-extent match.
        let touch_left = self.brackets.foldable_partner(caret).map(|close| (caret, close));
        let touch_right = caret
            .checked_sub(1)
            .and_then(|o| self.brackets.at(o))
            .filter(|b| !b.open)
            .and_then(|b| b.partner.map(|open| (open, b.offset)));
        if let Some((open, _)) = [touch_left, touch_right]
            .into_iter()
            .flatten()
            .filter(|&(o, c)| is_target(o, c))
            .min_by_key(|&(o, c)| c - o)
        {
            return Some(open);
        }
        // Otherwise the innermost ENCLOSING foldable pair, early-stopping.
        self.brackets.innermost_enclosing_where(caret, is_target)
    }

    /// Fold (`unfold == false`) or unfold (`unfold == true`) the innermost
    /// foldable block enclosing or touching EACH caret — the multi-cursor
    /// `Ctrl+Shift+[` / `Ctrl+Shift+]`. Distinct target blocks act once (two
    /// carets in one block don't cancel each other), and every opener is resolved
    /// BEFORE any toggle — safe because folding moves no byte offset. Returns
    /// whether anything changed.
    pub fn fold_at_carets(&mut self, unfold: bool) -> bool {
        let mut openers: Vec<u32> = self
            .selections
            .all()
            .iter()
            .filter_map(|s| self.fold_opener_at(s.head(), unfold))
            .collect();
        openers.sort_unstable();
        openers.dedup();
        if openers.is_empty() {
            return false;
        }
        // A fold gesture is a boundary like every selection verb (seal undo, drop
        // the box anchor / expand ladder / auto-close provenance) — ONCE. Then
        // toggle ALL folds in one batch and eject carets in one pass. Per-fold
        // `toggle_fold_opener` is O(folds) each (a sorted-Vec insert plus a
        // FoldMap rebuild), so folding one at a time would make a document-scale
        // "collapse all" O(folds²); the batch keeps it linear.
        self.reset_transient();
        if unfold {
            self.folds.unfold_all(&openers);
        } else {
            self.folds.fold_all(openers.iter().copied());
        }
        self.eject_hidden_carets();
        true
    }

    /// Pull every caret out of a newly-hidden fold gap to the fold's entry edge
    /// — THE ejection pass, shared by every gesture that can hide a caret (a
    /// fold toggle, a batch fold, undo/redo's restore), each caret probed in
    /// O(log folds) by the one hiding test, [`FoldMap::entry_edge_if_hidden`].
    /// It reads the MEMOIZED map (`ensure_fold_map`), never a throwaway
    /// `FoldMap::new`: its callers have just changed the fold generation or the
    /// text, so the memo rebuilds here once and the next render reads that
    /// build instead of paying a second O(folds) one.
    fn eject_hidden_carets(&mut self) {
        if self.folds.is_empty() {
            return;
        }
        self.ensure_fold_map();
        let Self { selections, buffer, fold_cache, .. } = self;
        let cache = fold_cache.borrow();
        selections.map_each(|s| {
            if let Some(entry) = cache.map.entry_edge_if_hidden(buffer, s.head()) {
                s.move_to_caret(entry);
            }
        });
    }

    /// Every *collapsible* bracket pair — foldable (non-empty interior) and not
    /// already collapsed — as `(open, close, header, last)`, document order. The
    /// candidate set for the Ctrl+hover affordance: a pair already folded is
    /// excluded (there is nothing left to collapse). Includes both multi-line
    /// blocks and single-line inline pairs, so one gesture reaches either.
    #[must_use]
    pub fn collapsible_pairs(&self) -> Vec<(u32, u32, u32, u32)> {
        self.foldable_pairs().into_iter().filter(|&(open, ..)| !self.folds.is_folded(open)).collect()
    }

    /// [`Document::collapsible_pairs`] restricted to pairs headed on buffer rows
    /// in `rows` — the windowed query the Ctrl+hover affordance uses per
    /// mouse-move instead of a whole-document scan on a large document.
    /// The caller widens `rows` with a slack so a pair whose header sits just
    /// above the viewport still arms; a block taller than that slack enclosing
    /// the pointer is the accepted miss (fold it from its header chevron or the
    /// `Ctrl+Shift+[` chord instead).
    #[must_use]
    pub fn collapsible_pairs_in_rows(&self, rows: Range<u32>) -> Vec<(u32, u32, u32, u32)> {
        self.foldable_pairs_in_rows(rows)
            .into_iter()
            .filter(|&(open, ..)| !self.folds.is_folded(open))
            .collect()
    }

    /// The opener of the innermost collapsible pair whose interior contains byte
    /// `offset` (`open < offset < close`) — the Ctrl+hover / Ctrl+Click target.
    /// Innermost = smallest byte span, so a pointer inside nested
    /// collapsibles resolves to the tightest one (an inline array over its
    /// enclosing block). `None` when the offset sits in no collapsible interior.
    #[must_use]
    pub fn collapsible_at(&self, offset: u32) -> Option<u32> {
        self.collapsible_pairs()
            .into_iter()
            .filter(|&(open, close, _, _)| open < offset && offset < close)
            .min_by_key(|&(open, close, _, _)| close - open)
            .map(|(o, ..)| o)
    }

    /// Drop collapsed folds whose opener is no longer a live foldable open bracket
    /// — e.g. an edit deleted or unmatched a block's brackets. Called from the
    /// edit / undo / redo paths once brackets are re-matched. Because a fold's
    /// extent is re-derived from the live brackets (never stored), there is nothing
    /// to heal — a fold either still opens a foldable pair or it is dropped. No-op
    /// when nothing is folded.
    fn reconcile_folds(&mut self) {
        if self.folds.is_empty() {
            return;
        }
        // Check each folded opener DIRECTLY (a matched open bracket with a
        // non-empty interior) via an O(log) bracket lookup, instead of
        // building the whole-document `foldable_pairs()`. Reconcile runs on
        // every commit, so this keeps a keystroke while a fold is active off an
        // O(brackets) whole-document scan.
        let brackets = &self.brackets;
        self.folds.reconcile(|o| {
            brackets
                .foldable_partner(o)
                .is_some_and(|close| crate::row_layout::pair_has_interior(o, close))
        });
    }

    /// Test hook: run the whole-set reconcile (the undo/redo path's version) so a
    /// test can assert the edit-path windowed reconcile left nothing for it to do.
    #[cfg(test)]
    pub(crate) fn force_whole_reconcile(&mut self) {
        self.reconcile_folds();
    }

    /// Windowed reconcile for the edit path: drop only folds the edit's re-matched
    /// `region` could have broken. A fold's foldability changes only if its opener
    /// or closer bracket was re-scanned, and every re-scanned bracket lies in the
    /// bracket engine's replayed rows — so an affected fold's `[opener, closer]`
    /// must INTERSECT that span. `region` already extends its left edge down to the
    /// outermost enclosing opener (the seed stack — see `BracketOps::reconcile_lo`),
    /// so every such fold has its OPENER in `region`: a single binary-searched
    /// window, no separate enclosing walk. This is [`reconcile_folds`]'s O(local)
    /// twin — the whole-set version stays on the undo/redo path, which spans many
    /// steps and so has no single region.
    fn reconcile_folds_in(&mut self, region: core::ops::Range<u32>) {
        if self.folds.is_empty() {
            return;
        }
        let candidates: Vec<u32> = self.folds.openers_in(region);
        let brackets = &self.brackets;
        self.folds.reconcile_only(&candidates, |o| {
            brackets
                .foldable_partner(o)
                .is_some_and(|close| crate::row_layout::pair_has_interior(o, close))
        });
    }

    /// Every foldable `(header, last)` row range — the source for gutter chevrons
    /// and fold commands. Derived from the matched-bracket pass: each *multi-line*
    /// matched pair (`{}`/`()`/`[]`) becomes a range from its opener row to its
    /// closer row. At most one range per header row (the widest), sorted by header.
    #[must_use]
    pub fn foldable_ranges(&self) -> Vec<(BufferRow, BufferRow)> {
        let mut ranges: Vec<(BufferRow, BufferRow)> = self
            .brackets
            .all()
            .iter()
            .filter_map(|br| {
                let close = br.partner.filter(|_| br.open)?;
                let header = self.buffer.offset_to_point(br.offset).row;
                let last = self.buffer.offset_to_point(close).row;
                (last > header).then_some((BufferRow(header), BufferRow(last)))
            })
            .collect();
        // Keep the widest range per header row (largest `last`).
        ranges.sort_by_key(|r| (r.0, core::cmp::Reverse(r.1)));
        ranges.dedup_by_key(|r| r.0);
        ranges
    }

    /// [`Document::foldable_ranges`] restricted to headers on buffer rows in
    /// `rows` — the gutter chevrons' per-frame query: two partition points over
    /// the sorted bracket Vec ([`Brackets::in_range`]) instead of a
    /// whole-document scan per frame.
    /// Same widest-per-header dedup; hidden in-window headers are the
    /// caller's to cull (its `visible_y` already does).
    #[must_use]
    pub fn foldable_ranges_in_rows(&self, rows: Range<u32>) -> Vec<(BufferRow, BufferRow)> {
        let start = self.buffer.point_to_offset(Point::new(rows.start, 0));
        let end = if rows.end >= self.buffer.line_count() {
            self.buffer.len() + 1 // sentinel: a bracket at the final byte is inside
        } else {
            self.buffer.point_to_offset(Point::new(rows.end, 0))
        };
        let mut ranges: Vec<(BufferRow, BufferRow)> = self
            .brackets
            .in_range_iter(start..end)
            .filter_map(|br| {
                let close = br.partner.filter(|_| br.open)?;
                let header = self.buffer.offset_to_point(br.offset).row;
                let last = self.buffer.offset_to_point(close).row;
                (last > header).then_some((BufferRow(header), BufferRow(last)))
            })
            .collect();
        ranges.sort_by_key(|r| (r.0, core::cmp::Reverse(r.1)));
        ranges.dedup_by_key(|r| r.0);
        ranges
    }

    /// Bring the highlight cache current up to buffer line `target` (a viewport's
    /// last line). Lazy and incremental — end-state convergence bounds the work
    /// to the edited lines. No-op without a highlighter.
    pub fn tokenize_highlight(&mut self, target: u32) {
        // `self.highlight` and `self.buffer` are disjoint fields, so both
        // borrow. The buffer is handed in as a line ACCESSOR — never an
        // all-lines Vec — and each call is budget-capped; the app's idle sweep
        // resumes at [`Document::highlight_frontier`] until convergence.
        let buffer = &self.buffer;
        let Some(cache) = self.highlight.as_mut() else { return };
        cache.tokenize_until(target, crate::highlight::HIGHLIGHT_MAX_LINES_PER_CALL, |r| {
            buffer.line(r)
        });
    }

    /// The next row highlight work would touch — a dirty row, or a window
    /// row awaiting a refill after [`Document::set_highlight_window`] moved
    /// the retention window (highlight virtualization). `None` when there is
    /// nothing to do — or when no grammar is injected. The app's idle sweep
    /// polls this to drive budgeted [`Document::tokenize_highlight`] calls
    /// and to stop when idle (an idle document does zero highlight work).
    #[must_use]
    pub fn highlight_frontier(&self) -> Option<u32> {
        self.highlight.as_ref().and_then(HighlightCache::pending)
    }

    /// Aim the highlight retention window at `rows` (the visible buffer rows;
    /// the cache pads by [`crate::highlight::HIGHLIGHT_WINDOW_SLACK`] and
    /// evicts outside it). Spans and per-line states are retained only there;
    /// elsewhere sparse checkpoints keep every row re-derivable, so a fully
    /// swept document holds memory proportional to the window, not the line
    /// count. Call on viewport change, then drive
    /// [`Document::tokenize_highlight`] as usual. No-op without a grammar.
    pub fn set_highlight_window(&mut self, rows: Range<u32>) {
        if let Some(cache) = self.highlight.as_mut() {
            cache.set_window(rows);
        }
    }

    /// Cached highlight spans for a buffer row — `None` if untokenized or no
    /// highlighter is attached (the renderer falls back to the plain text color).
    #[must_use]
    pub fn highlight_line_spans(&self, row: u32) -> Option<&[HighlightSpan]> {
        self.highlight.as_ref().and_then(|c| c.line_spans(row))
    }

    /// A `Send + Sync` handle to the highlighter's grammar + theme, for the
    /// app's off-thread parallel/speculative sweep. `None` without a grammar.
    /// Pair with [`Document::snapshot`] (an O(1) rope clone) and
    /// [`crate::tokenize_segment`] on a worker, then feed results back through
    /// [`Document::absorb_highlight`].
    #[must_use]
    pub fn highlight_engine(&self) -> Option<HighlightEngine> {
        self.highlight.as_ref().map(HighlightCache::engine)
    }

    /// Ingest a segment tokenized off-thread (the parallel/speculative sweep).
    /// Returns `false` — absorbing **nothing** — if the segment is stale on
    /// either axis:
    ///
    /// - `revision` no longer matches the document (an edit landed since the
    ///   snapshot the segment was computed from), or
    /// - it was tokenized by an engine other than the highlighter's current
    ///   one — a [`set_theme`](Document::set_theme) or
    ///   [`set_syntax`](Document::set_syntax) since
    ///   [`highlight_engine`](Document::highlight_engine) was fetched (neither
    ///   moves the revision), or a standalone [`HighlightEngine::new`].
    ///
    /// Either way the app drops the result and re-dispatches — after
    /// re-fetching `highlight_engine` if the revision still matches. On a
    /// match, forwards to `HighlightCache::absorb`:
    ///
    /// - `verified` — the coordinator chained this segment from row 0, so its
    ///   start state is TRUE: its checkpoints merge, its window spans/states are
    ///   written, and its rows leave the dirty frontier (replacing the
    ///   foreground walk).
    /// - `!verified` — viewport speculation from a guessed fresh start: only
    ///   still-dirty window rows get its spans, no checkpoints are planted, and
    ///   the frontier still re-verifies those rows per-line (converging in O(1)
    ///   if the guess was right).
    ///
    /// Already-absorbed work is never lost to a later edit: it lives in the
    /// cache and rides `rebase_views`' `on_commit` splices like every other
    /// derived fact — only *in-flight* results are dropped by the revision
    /// check.
    pub fn absorb_highlight(
        &mut self,
        revision: Revision,
        seg: crate::SegmentTokens,
        verified: bool,
    ) -> bool {
        if revision != self.buffer.revision() {
            return false;
        }
        let Some(cache) = self.highlight.as_mut() else { return false };
        cache.absorb(seg, verified)
    }

    /// The matched brackets — kept current on every edit. Drives
    /// bracket-pair colorization and the matching-bracket highlight.
    #[must_use]
    pub fn brackets(&self) -> &Brackets {
        &self.brackets
    }

    /// Publish a diagnostic set from the app's debounced compile loop.
    ///
    /// The compiler ran against the snapshot at `revision`; if the buffer has
    /// since moved on this returns [`DiagnosticsOutcome::Stale`] having installed
    /// nothing — the previous squiggles keep riding edits via stickiness until
    /// the next publish (no stale set is placed). On a current revision the whole
    /// diagnostic set is replaced wholesale; spans are first clipped to the
    /// buffer: clamped to its length (an inverted span collapses to its end),
    /// then snapped to char boundaries — outward for a non-empty span
    /// ([`Bias::Left`] start, [`Bias::Right`] end), `Left` for an empty one.
    /// Zero-width spans survive — the squiggle enforces its one-cell minimum at
    /// draw time.
    pub fn set_diagnostics(&mut self, revision: Revision, diags: Vec<Diagnostic>) -> DiagnosticsOutcome {
        let current = self.buffer.revision().0;
        // A compiler's span is host arithmetic (often UTF-16 → byte), so it can
        // split a char: the store clips each one against the text
        // `decorations_mut` lends it — the one door every host range into the
        // store takes — after its own revision gate.
        self.decorations_mut().set_diagnostics(revision.0, current, diags)
    }

    /// Diagnostics overlapping the byte `range`, for squiggle rendering:
    /// `(span, severity, message)`, position and content reunited from the store,
    /// in ascending `(start, id)` order. The renderer clips to its visible rows.
    pub fn diagnostics_in(
        &self,
        range: Range<u32>,
    ) -> impl Iterator<Item = (Range<u32>, Severity, std::sync::Arc<str>)> + '_ {
        // The store yields owned tracked ranges (its delta-gap encoding has no
        // absolute range to borrow), so the message rides out as its shared
        // `Arc<str>` — an owner bump, not a copy.
        self.decorations.decorations_in(range).filter_map(|r| {
            let TrackedRange { range, kind, .. } = r;
            match kind {
                DecorationKind::Diagnostic { severity, message, .. } => {
                    Some((range, severity, message))
                }
                _ => None,
            }
        })
    }

    /// Set (or clear with `None`) the find query, scanning synchronously.
    /// Never scrolls and drops the active match; the app calls [`find_next`] after
    /// if it wants reveal-as-you-type. `now_ms` is the injected clock. This is the
    /// one whole-document find op — every subsequent edit repairs the set
    /// incrementally through the commit mover.
    ///
    /// [`find_next`]: Document::find_next
    pub fn set_find_query(&mut self, query: Option<FindQuery>, now_ms: u64) {
        self.find.set_query(query, &self.buffer, &mut self.decorations, now_ms);
    }

    /// The active find query, or `None` if find is idle.
    #[must_use]
    pub fn find_query(&self) -> Option<&FindQuery> {
        self.find.query()
    }

    /// Restrict find to a byte range — **find in selection** — or clear the
    /// restriction with `None`. Re-scans synchronously: the scope is part of
    /// what matches, not a display filter, so every consumer (navigation, the
    /// N-of-M count, [`replace_all`](Document::replace_all)) honors it without
    /// knowing it exists.
    ///
    /// The scope then rides every edit's patch like any other derived position,
    /// growing when text is typed at its edges and dropping if it collapses. The
    /// range is clipped to the buffer first — clamped to its length, snapped
    /// outward to whole chars ([`Bias::Left`] start, [`Bias::Right`] end) — and
    /// an empty result clears the scope rather than pinning zero matches.
    pub fn set_find_scope(&mut self, scope: Option<Range<u32>>, now_ms: u64) {
        let scope = scope.map(|r| self.buffer.clip_range(r));
        self.find.set_scope(scope, &self.buffer, &mut self.decorations, now_ms);
    }

    /// The live find-in-selection scope, if any — for the view to shade it.
    #[must_use]
    pub fn find_scope(&self) -> Option<Range<u32>> {
        self.find.scope()
    }

    /// Why the current find pattern does not parse, if it does not — for the
    /// find bar to show.
    ///
    /// This is not an error path: with the regex option on, every prefix of a
    /// pattern being typed (`(`, `[a-`) is invalid, so find simply reports zero
    /// matches and carries the reason until the pattern parses again.
    #[must_use]
    pub fn find_pattern_error(&self) -> Option<&str> {
        self.find.pattern_error()
    }

    /// Whole-word occurrences of the word under the newest caret WITHIN the
    /// byte range `within` — the passive occurrence wash (the reading aid for
    /// tracing a PID/label through a script). The window keeps this per-frame
    /// query O(viewport): the widget passes its visible byte range; tests pass
    /// `0..u32::MAX` (the window is clipped like any host range: clamped, and
    /// snapped outward to whole chars). Every
    /// match must be a WHOLE word, judged by the same
    /// `movement::surrounding_word` rule that seeds Ctrl+D — checked against
    /// the full buffer, so a window edge can never fake a word boundary. Empty
    /// when the newest selection is non-empty or the caret is off-word. A pure
    /// per-frame query (the `FoldMap` precedent): no tracked state, nothing to
    /// rebase on the undo path.
    #[must_use]
    pub fn caret_word_occurrences(&self, within: Range<u32>) -> Vec<Range<u32>> {
        let newest = self.selections.newest();
        if !newest.is_empty() {
            return Vec::new();
        }
        let Some((ws, we)) = movement::surrounding_word(&self.buffer, newest.head()) else {
            return Vec::new();
        };
        if ws == we {
            return Vec::new();
        }
        let word = self.buffer.slice(ws..we);
        let Range { start: base, end } = self.buffer.clip_range(within);
        let hay = self.buffer.slice(base..end);
        let mut out = Vec::new();
        let mut from = 0usize;
        while let Some(i) = hay[from..].find(&*word) {
            let start = base + (from + i) as u32;
            let match_end = start + word.len() as u32;
            // Whole-word: the match must BE its own surrounding word.
            if movement::surrounding_word(&self.buffer, start) == Some((start, match_end)) {
                out.push(start..match_end);
            }
            from = from + i + word.len();
        }
        out
    }

    /// How many matches the current query has — the *live* count. The store IS
    /// the match set: there is no shadow handle list to disagree with it, so this
    /// is the O(1) root-summary `find_count`, not an O(matches) walk. Empty
    /// matches never persist (`FindMatch` is `EmptyPolicy::Drop`), so the count
    /// equals the rendered `start < end` set.
    #[must_use]
    pub fn find_match_count(&self) -> usize {
        self.decorations.find_count()
    }

    /// The active match's position among the live matches, in document order, if
    /// one is active and still present — consistent with
    /// [`find_match_count`](Document::find_match_count) for an "N of M" display.
    /// O(log M) from the active handle's tracked start: its rank is the number of
    /// finds starting before it, not an O(M) `position` scan.
    #[must_use]
    pub fn active_find_match(&self) -> Option<u32> {
        self.find.active_start().map(|s| self.decorations.find_rank_before(s) as u32)
    }

    /// Find matches overlapping the byte `range`, for highlight rendering:
    /// `(span, is_active)`, in ascending order. Collapsed (empty) matches are
    /// skipped — an edit may zero one before the next re-scan purges it.
    pub fn find_matches_in(&self, range: Range<u32>) -> impl Iterator<Item = (Range<u32>, bool)> + '_ {
        let active = self.find.active_id();
        self.decorations.decorations_in(range).filter_map(move |r| match &r.kind {
            DecorationKind::FindMatch if r.range.start < r.range.end => {
                Some((r.range.clone(), Some(r.id) == active))
            }
            _ => None,
        })
    }

    /// Fill the scrollbar-overview lanes for the ascending byte-offset bucket
    /// `bounds`. The widget passes the `P + 1` boundaries it gets by inverting its
    /// own `round(y)` pixel map, so bucket `b` holds exactly the decorations whose
    /// mark lands on track pixel `b`. Per bucket `b`: `sev_out[b]` = `(encoded max
    /// Diagnostic severity, byte offset of the first severest one)` — `(0, 0)`
    /// when empty; `find_out[b]` = the start offset of the first
    /// [`DecorationKind::FindMatch`], or `None`. Both lanes are the O(P + log M)
    /// summary reduce, never a per-frame whole-store walk.
    /// `overview_reduce_equals_linear_scan` (decorations.rs) is the correctness
    /// authority.
    pub fn overview_marks(
        &self,
        bounds: &[u32],
        sev_out: &mut Vec<(u8, u32)>,
        find_out: &mut Vec<Option<u32>>,
    ) {
        self.decorations.diagnostic_overview(bounds, sev_out);
        self.decorations.find_overview(bounds, find_out);
    }

    /// Refill a **capped** find set, debounced — driven from the widget's
    /// `update()` each event. Returns whether it scanned.
    ///
    /// The match set is repaired eagerly at every commit, so there is no stale
    /// set to rescan; the only remaining job is re-growing a capped set's
    /// coverage after matches inside it died. Anything else is a no-op — idle
    /// documents do zero work here.
    pub fn maybe_rescan_find(&mut self, now_ms: u64) -> bool {
        self.find.maybe_rescan(&self.buffer, &mut self.decorations, now_ms)
    }

    /// Select the next find match from the caret, wrapping: sets the selection to
    /// the match (head at end), seals the undo group, and returns the match range
    /// for the widget to reveal (autoscroll). `None` when there are no matches.
    pub fn find_next(&mut self, now_ms: u64) -> Option<Range<u32>> {
        self.step_find(true, now_ms)
    }

    /// Select the previous find match from the caret, wrapping — the
    /// [`find_next`](Document::find_next) mirror.
    pub fn find_prev(&mut self, now_ms: u64) -> Option<Range<u32>> {
        self.step_find(false, now_ms)
    }

    /// Replace the active find match with `replacement`, then advance to the
    /// next match, wrapping — the Replace verb. Returns the match left selected,
    /// or `None` when there is nowhere to go.
    ///
    /// Replaces only when the newest selection IS the active match — the state
    /// [`find_next`](Document::find_next) leaves behind. Otherwise it merely
    /// navigates, so the first press selects and the second replaces: text is
    /// never overwritten before it has been shown. One transaction ⇒ one undo
    /// step, and the match set needs no resync — it rides the commit through the
    /// shared view-rebase mover like any other edit.
    /// `preserve_case` (the replace bar's `AB` toggle) re-cases the replacement
    /// to the match it lands on, by VS Code's rule — an ALL-CAPS match takes an
    /// upper-cased replacement, a Capitalized one a capitalized one, a camelCase
    /// one a lower first letter, and `-`/`_` segments are re-cased one by one.
    pub fn replace_next(
        &mut self,
        replacement: &str,
        preserve_case: bool,
        now_ms: u64,
    ) -> Option<Range<u32>> {
        self.find.maybe_rescan(&self.buffer, &mut self.decorations, now_ms);
        let extent = {
            let sel = self.selections.newest();
            sel.start()..sel.end()
        };
        // Armed only when the selection IS the active match. An empty selection
        // can never be one (`FindMatch` is `EmptyPolicy::Drop`), but the guard
        // states it rather than relying on that.
        let armed = !extent.is_empty()
            && self.find.active_range(&self.decorations).is_some_and(|r| r == extent);
        if armed {
            // The replacement is resolved through the one owner of that rule
            // (regex templating + preserve-case), bounded to this match.
            let text = self
                .find
                .replacements(&self.buffer, extent.clone(), replacement, preserve_case)
                .into_iter()
                .next()
                .map_or_else(|| replacement.to_string(), |(_, t)| t);
            // Advance INSIDE the commit: the next match the replace selects is
            // the unit's after-set, so redo restores the selection the user saw,
            // not the caret rebased over the replacement. The pick reads the
            // post-edit document, whose match set the commit already repaired
            // around the replacement. (`step_find` would first try a capped
            // set's debounced refill; the edit's own refill waits for the next
            // `maybe_rescan_find` — the set is exact up to its coverage.)
            let mut picked = None; // the next match, as `place` picked it
            let ops = vec![EditOp::new(extent, text)];
            let committed = self.edit_placing(ops, GroupingHint::discrete(), |_, doc| {
                let sel = doc.selections.newest();
                let target = FindState::pick(sel.head(), sel.start()..sel.end(), &doc.decorations, true);
                let placed = target.as_ref().map(|(_, range)| {
                    let mut set = doc.selections.clone();
                    select_match(&mut set, range);
                    set
                });
                picked = target;
                placed
            });
            match committed {
                // A rejected transaction must not read as a replace.
                Err(_) => return None,
                // `place` runs exactly for an edit that changed text, so a
                // non-empty commit is one whose `picked` is the real pick.
                Ok(c) if !c.is_empty() => return self.land_on_match(picked),
                // A replacement equal to its match commits nothing (`place`
                // never ran): it still advances, through the ordinary
                // navigation below.
                Ok(_) => {}
            }
        }
        self.step_find(true, now_ms)
    }

    /// Replace **every** match of the current query with `replacement` in one
    /// transaction — the Replace All verb. Returns how many were replaced.
    ///
    /// **One transaction ⇒ one undo step.** Matches are disjoint by
    /// construction, so the batch satisfies the engine's no-overlap rule for
    /// free — [`TransactionError::Overlap`] cannot fire here.
    ///
    /// Scans the query's range itself (the whole document, or the
    /// find-in-selection scope) rather than reading the live match set: that set
    /// is capped at [`FIND_MATCH_CAP`] and is only a *prefix of that range*, so
    /// an "all" built from it would silently stop at the cap and leave the tail
    /// untouched. That scan is whole-range — the same class as
    /// [`set_find_query`](Document::set_find_query), and legitimate for the same
    /// reason: a discrete user action, never a keystroke.
    ///
    /// Cost, honestly: one [`EditOp`] per match, each owning its own copy of
    /// `replacement`, so a query with millions of hits allocates proportionally
    /// before it commits. Bounded by the match count and paid once per press.
    ///
    /// `preserve_case` (the replace bar's `AB` toggle) re-cases each replacement
    /// to the match it lands on, by VS Code's rule — an ALL-CAPS match takes an
    /// upper-cased replacement, a Capitalized one a capitalized one, a camelCase
    /// one a lower first letter, and `-`/`_` segments are re-cased one by one.
    ///
    /// [`FIND_MATCH_CAP`]: crate::find::FIND_MATCH_CAP
    pub fn replace_all(&mut self, replacement: &str, preserve_case: bool) -> usize {
        // Scoped find replaces only inside its range — the scan bound is the one
        // place that has to know, so every other path inherits it.
        let within = self.find.scope().unwrap_or(0..self.buffer.len());
        let plan = self.find.replacements(&self.buffer, within, replacement, preserve_case);
        if plan.is_empty() {
            // Find idle, an unparsed pattern, or no matches ⇒ no transaction,
            // no undo step.
            return 0;
        }
        let n = plan.len();
        let ops = plan.into_iter().map(|(r, t)| EditOp::new(r, t)).collect();
        if self.edit(ops).is_err() {
            return 0;
        }
        n
    }

    /// Shared find-navigation body.
    fn step_find(&mut self, forward: bool, now_ms: u64) -> Option<Range<u32>> {
        // The set is always current at every commit; the one freshness concern
        // left is a capped set with room to refill, which the debounced refill
        // handles opportunistically before navigating.
        self.find.maybe_rescan(&self.buffer, &mut self.decorations, now_ms);
        let sel = self.selections.newest();
        let target = FindState::pick(sel.head(), sel.start()..sel.end(), &self.decorations, forward);
        self.land_on_match(target)
    }

    /// Navigation's landing, shared by [`step_find`](Self::step_find) and
    /// [`replace_next`](Self::replace_next): make the [`FindState::pick`]ed
    /// match active (no match ⇒ clear the active one, selection untouched),
    /// select it, and take a jump's boundary, unfold and reveal.
    fn land_on_match(&mut self, target: Option<(DecorationId, Range<u32>)>) -> Option<Range<u32>> {
        let range = self.find.activate(target)?;
        // A replace has already placed this exact selection inside its commit;
        // re-placing it is a no-op there, and the one rule either way.
        select_match(&mut self.selections, &range);
        self.reset_transient(); // clears gesture state + seals (a jump is a boundary)
        // A match inside a collapsed fold unfolds its chain first — the
        // reveal below must land on a VISIBLE position.
        self.unfold_to_reveal(range.start);
        self.unfold_to_reveal(range.end);
        self.request_reveal(RevealMode::Center); // find navigation centers
        Some(range)
    }

    /// F8 / Shift+F8: select the next/previous diagnostic from the
    /// newest selection's start, wrapping — the compile-loop navigation:
    /// jump, read the message (hover), fix, F8 again. Selects the
    /// diagnostic's span, expands any fold hiding it, and bumps the reveal
    /// generation (a jump-class action, like find navigation). `None` — and
    /// no movement — when the document has no live diagnostics.
    pub fn next_diagnostic(&mut self, forward: bool) -> Option<Range<u32>> {
        // Walk in (start, end) lexicographic order from the CURRENT selection's
        // span, so two diagnostics sharing a start offset are both reachable —
        // a plain `start >` comparison would loop forever between them.
        let sel = self.selections.newest();
        let anchor = (sel.start(), sel.end());
        let mut all: Vec<Range<u32>> = self.diagnostics_in(0..u32::MAX).map(|(r, ..)| r).collect();
        all.sort_by_key(|r| (r.start, r.end));
        let target = if forward {
            all.iter().find(|r| (r.start, r.end) > anchor).or_else(|| all.first())
        } else {
            all.iter().rev().find(|r| (r.start, r.end) < anchor).or_else(|| all.last())
        }?
        .clone();
        self.selections
            .set_single(Selection::from_anchor(SelectionId(0), target.start, target.end));
        self.reset_transient(); // a jump is an undo-group boundary
        self.unfold_to_reveal(target.start);
        self.unfold_to_reveal(target.end);
        self.request_reveal(RevealMode::Center); // diagnostic jumps center
        Some(target)
    }

    /// Unfold every collapsed fold hiding `offset`, innermost-first, until the
    /// offset renders: a jump-class caret placement — find navigation, bracket
    /// jump, select-all-matches — must land on a VISIBLE position. The jump twin
    /// of the edit path's `expand_folds_touched`. Visibility is judged by the one
    /// owner ([`FoldMap::display_position`]); already-visible offsets (a
    /// collapsed tail, a chip edge) unfold nothing.
    fn unfold_to_reveal(&mut self, offset: u32) -> bool {
        let tab = self.tab_size();
        let mut any = false;
        loop {
            let fm = FoldMap::new(&self.folds, &self.brackets, &self.buffer);
            // "Visible" for a JUMP is stricter than "renders somewhere":
            // `display_position` clips a chip-hidden column to the chip's
            // center, so an offset inside a collapsed INLINE fold still gets a
            // position — but the text itself is hidden, and a jump target must
            // be readable, so the gap rule is checked too.
            let renders = fm.display_position(&self.buffer, offset, tab).is_some();
            // Only the inline fold opening just before `offset` can hide it (roots
            // are disjoint) — an O(log) tree probe, not a full-set scan.
            let chip_hidden = fm.inline_fold_before(offset).is_some_and(|f| f.hides_caret_at(offset));
            if renders && !chip_hidden {
                return any;
            }
            // Peel the innermost collapsed pair containing the offset, then
            // re-check — an outer unfold can expose a collapsed inner fold.
            let target = self
                .folds
                .iter()
                .filter_map(|open| self.brackets.foldable_partner(open).map(|c| (open, c)))
                .filter(|&(open, close)| open < offset && offset < close)
                .min_by_key(|&(open, close)| close - open);
            let Some((open, _)) = target else {
                return any; // hidden for a non-fold reason — nothing to peel
            };
            self.folds.unfold(open);
            any = true;
        }
    }

    /// The reveal-request generation. The view autoscrolls to the newest
    /// selection whenever this changes — the bridge that lets app-driven find
    /// navigation scroll a match into view without the widget's input path.
    #[must_use]
    pub fn reveal_seq(&self) -> u64 {
        self.reveal_seq
    }
}

/// Expand every fold whose **hidden** content the committed edit touched:
/// an edit must never change text the user cannot see, so the fold opens to
/// reveal it. Edits in a fold's *visible* parts — a block header's line, its
/// closing tail, just outside an inline pair's brackets — leave it folded; an
/// edit that swallows a fold's brackets entirely is dropped by
/// `reconcile_folds` instead. Shared by the commit path and undo/redo (a free
/// fn for the same borrow reason as `rebase_views`), so undoing into a folded
/// region reveals the reverted text identically.
fn expand_folds_touched(
    folds: &mut FoldSet,
    brackets: &Brackets,
    buffer: &Buffer,
    tab: u32,
    committed: &Committed,
) {
    if folds.is_empty() || committed.patch().is_empty() {
        return;
    }
    // Only a fold that ENCLOSES or TOUCHES an edit endpoint can hide that edit.
    // Their openers lie in `[lo, last]`: `last` (the rightmost endpoint) bounds
    // them on the right since an enclosing opener is `<=` the point, and `lo` —
    // the outermost folded pair enclosing/touching the FIRST endpoint — bounds
    // them on the left (an enclosing fold can open far to the left, but no farther
    // than the first point's outermost encloser). One windowed enclosing walk
    // finds `lo`; the fold set is then a binary-searched slice, so the whole scan
    // is O(folds in the edit span), NOT O(carets · folds-before-each) — a
    // leftward enclosing walk per caret would make select-all → fold → type scale
    // with that product. The `FoldMap` built from just these folds is identical to
    // the full map for these offsets (a non-enclosing fold cannot hide them), so
    // the reveal decision is unchanged.
    let mut pts: Vec<u32> = Vec::with_capacity(committed.patch().edits().len() * 2);
    for e in committed.patch().edits() {
        pts.push(e.new.start);
        pts.push(e.new.end);
    }
    pts.sort_unstable();
    pts.dedup();
    let (first, last) = (pts[0], *pts.last().expect("edits() is non-empty here"));
    let lo = brackets
        .enclosing_or_touching(first)
        .into_iter()
        .filter(|&(o, _)| folds.is_folded(o))
        .map(|(o, _)| o)
        .min()
        .unwrap_or(first);
    // The folded pairs in the window that actually enclose/touch a point —
    // exactly the enclosing/touching set, found by one point probe per windowed
    // fold (`∃ p in [o, c+1]`) rather than a per-caret enclosing walk.
    let candidates: Vec<(u32, u32)> = folds
        .openers_in(lo..last.saturating_add(1))
        .iter()
        .filter_map(|&o| {
            let c = brackets.foldable_partner(o)?;
            let touches =
                pts.partition_point(|&p| p < o) < pts.partition_point(|&p| p <= c.saturating_add(1));
            touches.then_some((o, c))
        })
        .collect();
    if candidates.is_empty() {
        return;
    }
    let mut sub = crate::fold_map::FoldSet::new();
    for &(open, _) in &candidates {
        sub.fold(open);
    }
    let fold_map = crate::fold_map::FoldMap::new(&sub, brackets, buffer);
    // The block test — is any edit endpoint hidden in a collapsed gap? — reads only
    // the point and the map, never the candidate, so all block candidates share one
    // answer; compute it once (O(points · log folds)) instead of re-scanning every
    // edit for every candidate, which would be O(carets²) even when nothing is
    // hidden.
    let any_hidden = pts.iter().any(|&p| fold_map.display_position(buffer, p, tab).is_none());
    // Inline candidates test their own bracket span against the edit STARTS (only a
    // start reveals an inline pair): "∃ start in (opener, close]", binary-searched.
    let mut starts: Vec<u32> = committed.patch().edits().iter().map(|e| e.new.start).collect();
    starts.sort_unstable();
    let touched: Vec<u32> = candidates
        .iter()
        .filter(|&&(opener, close)| {
            let single = buffer.offset_to_point(opener).row == buffer.offset_to_point(close).row;
            if single {
                // Content edited/inserted anywhere inside the pair reveals it; at
                // `[` itself or past `]` doesn't — a start in (opener, close].
                starts.partition_point(|&s| s <= close) > starts.partition_point(|&s| s <= opener)
            } else {
                // Block: `display_position` is `None` exactly in the gap; an edit
                // straddling INTO the gap has an endpoint there, one swallowing the
                // whole fold broke the pair. Candidate-independent (see above).
                any_hidden
            }
        })
        .map(|&(opener, _)| opener)
        .collect();
    for opener in touched {
        folds.unfold(opener);
    }
}

/// The derived views that ride a committed patch — bundled so `rebase_views`
/// and its callers name the set once instead of threading five loose `&mut`s
/// (and so undo/redo can build it from the destructured `Document` fields). Every
/// position-tracked fact the editor shows lives here; adding one is a field here
/// plus one line in `rebase_views`, and it is then consistent on all edit paths.
struct Views<'a> {
    highlight: &'a mut Option<HighlightCache>,
    brackets: &'a mut Brackets,
    decorations: &'a mut DecorationStore,
    /// The auto-close provenance store — a SEPARATE [`DecorationStore`] moved
    /// beside `decorations` so a forward edit's pairs rebase for free (and undo/redo
    /// inherit the move, though `reset_transient` empties it there first).
    autoclose: &'a mut DecorationStore,
    folds: &'a mut FoldSet,
    find: &'a mut FindState,
    /// The incremental-change log — not a position, but the same "must see
    /// every applied step on every edit path" shape, so it rides the one mover
    /// rather than being fed per route (feeding it from the forward path alone
    /// is how undo/redo once went unlogged).
    changes: &'a mut ChangeLog,
}

/// The single position-mover for a committed edit — rebase every derived view
/// through its patch. Taking [`Views`] (not `&mut Document`) is what lets both
/// the commit path and undo/redo run the *same* update: undo/redo destructure
/// `self` so this can borrow the views while `history` borrows the buffer. A new
/// derived fact is added to `Views` and moved here once, staying consistent
/// across both paths with no per-feature resync on the undo path.
/// Returns whether the bracket structure changed (not a pure offset shift) — the
/// caller uses it to skip [`Document::reconcile_folds`] on a structure-neutral
/// edit, whose folds provably can't have lost their pair (see the reconcile call
/// site).
fn rebase_views(
    views: &mut Views,
    buffer: &Buffer,
    tab: u32,
    committed: &Committed,
    bracket_cfg: &crate::bracket::BracketConfig,
) -> core::ops::Range<u32> {
    // Highlight cache: splice the transaction's per-edit line spans (built
    // below). The size invariant (new_size = old_size − old_count + new_count)
    // keeps each edit's `old_lines` provably in-bounds. Only the actually-edited
    // lines are invalidated — NOT the first-to-last covering range — so a
    // scattered multi-caret edit doesn't over-invalidate the lines between.
    if let Some(cache) = views.highlight.as_mut() {
        let edits = committed.patch().edits();
        if !edits.is_empty() {
            // Per-edit pre-edit line spans `(pre_start, old_lines, new_lines)`,
            // ascending and coalesced disjoint, so the highlight commit
            // invalidates only the actually-edited lines — not the whole
            // first-to-last covering range (which would over-invalidate the
            // lines between scattered multi-caret edits). `old_lines` comes from
            // each edit's replaced text (its inverse op); `new_lines` from the
            // post-edit buffer.
            let mut spans: Vec<(u32, u32, u32)> = Vec::with_capacity(edits.len());
            let mut acc: i64 = 0;
            for (e, inv) in edits.iter().zip(committed.inverse_ops()) {
                let post_sr = buffer.offset_to_point(e.new.start).row;
                let post_er = buffer.offset_to_point(e.new.end).row;
                let new_lines = post_er - post_sr + 1;
                let old_lines = inv.text.bytes().filter(|&b| b == b'\n').count() as u32 + 1;
                let pre_start = (i64::from(post_sr) - acc) as u32;
                acc += i64::from(new_lines) - i64::from(old_lines);
                match spans.last_mut() {
                    // Same-line / touching edits share a pre-edit line — coalesce
                    // so the span list stays disjoint (the merge walks need it).
                    Some(last) if pre_start < last.0 + last.1 => {
                        let merged_end = (last.0 + last.1).max(pre_start + old_lines);
                        let combined_delta = (i64::from(last.2) - i64::from(last.1))
                            + (i64::from(new_lines) - i64::from(old_lines));
                        last.1 = merged_end - last.0;
                        last.2 = (i64::from(last.1) + combined_delta) as u32;
                    }
                    _ => spans.push((pre_start, old_lines, new_lines)),
                }
            }
            // Checkpoints, dense window, and dirty runs all ride the per-edit
            // spans — the window stays aimed at the viewport (only edited rows
            // invalidated), so a scattered multi-caret edit's wide covering range
            // never drains or repositions it.
            debug_assert_eq!(
                spans.iter().map(|&(_, o, n)| i64::from(n) - i64::from(o)).sum::<i64>(),
                i64::from(buffer.line_count()) - i64::from(cache.line_count()),
                "per-edit line deltas must sum to the buffer's line-count change",
            );
            cache.on_commit_patch(&spans);
        }
    }
    // Brackets: splice through the patch (the incremental engine; `match_text`
    // remains the load-time constructor and the tests' oracle). It returns the
    // reconcile window — the re-matched byte span, or `0..0` when only offsets
    // shifted (no structure changed) — the reconcile-skip signal below.
    let reconcile_region = views.brackets.apply_edit(committed.patch(), buffer, bracket_cfg);
    // Decorations: the one eager mover for ALL bulk kinds — diagnostics, find
    // matches, snippet stops — ride here, so undo/redo need no per-decoration
    // handling.
    views.decorations.apply_patch(committed.patch());
    // Auto-close provenance rides the SAME mover on its own store (per-range
    // independence makes the split byte-identical to keeping the pairs in
    // `decorations`). On forward edits this rebases the live pairs for free; on
    // undo/redo `reset_transient`→`clear_autoclose` has emptied it first, so this
    // is a no-op there — keeping it in the one mover means no edit path can ever
    // leave a pair stranded at a stale offset.
    views.autoclose.apply_patch(committed.patch());
    // The find repair rides the same commit hook, AFTER the store move (it needs
    // post-patch positions) — the match set is re-verified in a window around
    // each edit, so it is always current and undo/redo inherit the repair with no
    // find-specific resync.
    views.find.on_commit(committed.patch(), buffer, views.decorations);
    // Folds ride the same mover: shift on edits above, drop when the interior
    // is deleted — so folds survive edits and undo/redo with zero fold-specific
    // code (they travel the undo/redo closure forward and backward like a
    // decoration).
    views.folds.apply_patch(committed.patch());
    // Fold reveal rides the one mover too (after the position shift above): an
    // edit into HIDDEN text expands its fold — an edit must never alter text the
    // user cannot see. Threaded here, not hand-called per edit path, so undo/redo
    // inherit it and no edit path can forget it. (`reconcile_folds` — dropping
    // folds whose pair an edit broke — stays a once-per-transaction step on each
    // path: it can't run per-step inside history's callback. Order is immaterial:
    // expand skips broken-pair folds, the only ones reconcile drops.)
    expand_folds_touched(views.folds, views.brackets, buffer, tab, committed);
    // The change log rides here too, so a forward edit, each undo step, and each
    // redo step are all logged by this one line (a no-op unless observing).
    views.changes.record(committed);
    // The re-matched byte region (POST-edit) — the reconcile window (see
    // `reconcile_folds_in`). Empty (`0..0`) on a shift-only edit, which re-scanned
    // nothing, so `is_empty()` is exactly the "structure unchanged" signal.
    reconcile_region
}

/// Extend a unit-granular drag: keep the origin unit fully selected, with the
/// head at the far edge of the unit containing `head`. A forward drag anchors at
/// the origin unit's start; a backward drag anchors at its end (the tail flips),
/// so the origin word/line is never partially deselected.
fn extend_by_unit(origin_unit: (u32, u32), head_unit: (u32, u32), origin: u32, head: u32) -> (u32, u32) {
    let (os, oe) = origin_unit;
    let (hs, he) = head_unit;
    if head >= origin {
        (os, he.max(oe))
    } else {
        (oe, hs.min(os))
    }
}

/// Select a find match: the whole set collapses to ONE selection over `range`,
/// head at its end — the rule navigation lands by, and the placement a
/// replace's commit records, so the two cannot disagree.
fn select_match(set: &mut SelectionSet, range: &Range<u32>) {
    set.set_single(Selection::from_anchor(SelectionId(0), range.start, range.end));
}

/// First untaken literal (case-sensitive, non-overlapping like
/// `str::match_indices`) occurrence of `needle` whose global start lies in
/// `[lo, hi)`, or `None`. Windowed over the buffer's ranged reads with a
/// `k−1`-byte tail overlap so a match straddling a window seam is caught, and
/// **never materializes the document** (so each Ctrl+D press is O(scanned),
/// never O(document)). Byte-identical to a whole-text `match_indices` scan for
/// non-self-overlapping needles — the Ctrl+D case, where selections are
/// word-shaped and never self-overlap; a self-overlapping needle may differ in
/// match phase near a seam. Pinned by
/// `windowed_next_occurrence_equals_whole_text_scan`.
fn scan_from(
    buffer: &Buffer,
    needle: &str,
    lo: u32,
    hi: u32,
    is_taken: &impl Fn(u32) -> bool,
) -> Option<(u32, u32)> {
    let k = needle.len() as u64;
    if k == 0 || lo >= hi {
        return None;
    }
    let len = buffer.len();
    let window = u64::from(crate::buffer::SCAN_WINDOW).max(k * 2); // ≥ 2k ⇒ always advances
    let mut pos = lo;
    while u64::from(pos) + k <= u64::from(len) {
        let win_end = buffer
            .clip_offset((u64::from(pos) + window).min(u64::from(len)) as u32, Bias::Right);
        let slice = buffer.slice(pos..win_end);
        let mut last_end: Option<u32> = None;
        for (i, _) in slice.match_indices(needle) {
            let start = pos + i as u32;
            if u64::from(start) >= u64::from(hi) {
                return None; // matches only grow — nothing left in [lo, hi)
            }
            last_end = Some(start + k as u32);
            if !is_taken(start) {
                return Some((start, start + k as u32));
            }
        }
        if win_end >= len {
            break;
        }
        // Resume through the one owner of the seam rule ([`Buffer::scan_resume`])
        // — shared verbatim with find's `scan_buffer`.
        pos = buffer.scan_resume(pos, win_end, k as u32, last_end);
    }
    None
}

/// The next untaken literal occurrence of `needle` in `text` at or after byte
/// `from`, wrapping to the start; skips ranges already in `taken` (every
/// occurrence shares `needle.len()`). `None` if `needle` is empty or every
/// occurrence is already selected. Non-overlapping (`match_indices`) — the
/// whole-text `#[cfg(test)]` oracle that [`scan_from`]'s windowed scan is
/// checked against (`windowed_next_occurrence_equals_whole_text_scan`).
#[cfg(test)]
fn find_next_occurrence(text: &str, needle: &str, from: u32, taken: &[(u32, u32)]) -> Option<(u32, u32)> {
    if needle.is_empty() {
        return None;
    }
    let len = needle.len() as u32;
    let is_taken = |start: u32| taken.iter().any(|&(s, e)| s == start && e == start + len);
    let mut wrapped: Option<u32> = None;
    for (idx, _) in text.match_indices(needle) {
        let start = idx as u32;
        if is_taken(start) {
            continue;
        }
        if start >= from {
            return Some((start, start + len));
        }
        if wrapped.is_none() {
            wrapped = Some(start); // first candidate before `from`, used on wrap
        }
    }
    wrapped.map(|start| (start, start + len))
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::history::{GroupingHint, OpClass};

    fn doc(s: &str) -> Document {
        Document::new(s).unwrap()
    }

    fn typ(op: OpClass) -> GroupingHint {
        GroupingHint::mergeable(op)
    }

    /// The incremental brackets must deep-equal a from-scratch match of the
    /// live text — the bracket oracle, at Document level.
    fn assert_brackets_fresh(d: &Document) {
        let fresh = crate::bracket::Brackets::match_text(&d.text());
        assert_eq!(d.brackets().all(), fresh.all(), "incremental brackets diverged from scratch");
    }

    #[test]
    fn brackets_ride_edits_and_undo_redo_through_the_one_mover() {
        // A random walk of edits, undos, and redos: after EVERY step the
        // incremental bracket structure must equal a from-scratch match —
        // proving the one-mover claim (rebase_views runs the splice on the
        // forward path AND per undo/redo step; no bracket-specific resync
        // exists anywhere).
        let mut d = doc("fn a() {\n    x[0] = (1 + 2);\n}\n");
        let mut rng = 0xC0FFEEu64;
        let mut next = move |m: u64| {
            rng ^= rng << 13;
            rng ^= rng >> 7;
            rng ^= rng << 17;
            rng % m
        };
        let inserts = ["{", "}", "(", ")", "[", "]", "\n", "x", "{}", "([)", "\n}\n"];
        for i in 0..200 {
            match next(4) {
                0 | 1 => {
                    let at = next(d.buffer().len() as u64 + 1) as u32;
                    let at = d.buffer().clip_offset(at, crate::Bias::Left);
                    let text = inserts[next(inserts.len() as u64) as usize];
                    let _ = d.edit(vec![EditOp::insert(at, text)]);
                }
                2 => {
                    let a = next(d.buffer().len() as u64 + 1) as u32;
                    let a = d.buffer().clip_offset(a, crate::Bias::Left);
                    let b = (a + 1 + next(4) as u32).min(d.buffer().len());
                    let b = d.buffer().clip_offset(b, crate::Bias::Right);
                    if a < b {
                        let _ = d.edit(vec![EditOp::delete(a..b)]);
                    }
                }
                _ => {
                    if next(2) == 0 {
                        d.undo();
                    } else {
                        d.redo();
                    }
                }
            }
            assert_brackets_fresh(&d);
            let _ = i;
        }
    }

    #[test]
    fn edit_undo_redo_round_trip() {
        let mut d = doc("hello");
        d.edit(vec![EditOp::new(0..5, "world")]).unwrap();
        assert_eq!(d.text(), "world");
        assert!(d.undo());
        assert_eq!(d.text(), "hello");
        assert!(d.redo());
        assert_eq!(d.text(), "world");
        // Nothing left to redo.
        assert!(d.undo());
        assert!(!d.undo()); // stack empty
        assert_eq!(d.text(), "hello");
    }

    #[test]
    fn programmatic_batch_puts_caret_after_all_text_inserted_at_it() {
        // Regression (fails-first): a formatter-style batch whose edits TOUCH at
        // the caret — replace "b" (1..2) and insert at 2 — must carry a caret at 2
        // past everything inserted there, not leave it splitting the batch's
        // output (X|Y). The caret rides `Patch::map_many` with Right bias.
        let mut d = doc("abcd");
        d.set_selections(SelectionSet::from_offsets(&[2]));
        d.edit(vec![EditOp::new(1..2, "X"), EditOp::insert(2, "Y")]).unwrap();
        assert_eq!(d.text(), "aXYcd");
        assert_eq!(d.selections().newest().head(), 3, "caret after X and Y");
    }

    #[test]
    fn a_new_edit_invalidates_redo() {
        let mut d = doc("");
        d.edit(vec![EditOp::insert(0, "a")]).unwrap();
        d.edit(vec![EditOp::insert(1, "b")]).unwrap(); // "ab"
        d.undo(); // "a"
        d.edit(vec![EditOp::insert(1, "X")]).unwrap(); // "aX" — diverges
        assert_eq!(d.text(), "aX");
        assert!(!d.redo(), "redo must be cleared by the divergent edit");
        assert_eq!(d.text(), "aX");
    }

    #[test]
    fn a_retained_branch_is_reachable_from_the_fork() {
        // Branching undo: the branch `a_new_edit_invalidates_redo` discards
        // is not gone — it is RETAINED as a sibling. Plain redo still does nothing
        // at the tip of the new branch, but undoing back to the fork exposes both
        // branches and either is selectable. A two-stack history could not do this
        // (a divergent edit would clear the redo stack); the branching tree keeps
        // both reachable.
        let mut d = doc("");
        d.edit(vec![EditOp::insert(0, "a")]).unwrap();
        d.edit(vec![EditOp::insert(1, "b")]).unwrap(); // "ab"
        d.undo(); // "a"
        d.edit(vec![EditOp::insert(1, "X")]).unwrap(); // "aX" — diverges, "b" kept
        assert!(!d.redo(), "plain redo does nothing at the tip of the new branch");
        // Undo back to the fork exposes BOTH branches.
        assert!(d.undo());
        assert_eq!(d.text(), "a");
        assert_eq!(d.redo_branch_count(), 2, "the 'b' and 'X' branches both survive");
        assert!(d.can_redo());
        // Steer to the older, retained branch (index 0 = 'b') and redo into it.
        assert!(d.select_redo_branch(0));
        assert!(d.redo());
        assert_eq!(d.text(), "ab", "the retained 'b' branch is fully reachable");
        // The newer branch is still there too.
        assert!(d.undo());
        assert!(d.select_redo_branch(1));
        assert!(d.redo());
        assert_eq!(d.text(), "aX");
    }

    #[test]
    fn opt_in_undo_limit_bounds_reach_and_keeps_recent() {
        // Opt-in pruning: with a limit of 3, older units drop while the most
        // recent 3 stay reachable and the text is untouched. The default (no
        // limit) prunes nothing — every other undo test above relies on that.
        let mut d = doc("");
        d.set_undo_limit(Some(3));
        for (i, ch) in "abcde".chars().enumerate() {
            d.edit(vec![EditOp::insert(i as u32, ch.to_string())]).unwrap();
        }
        assert_eq!(d.text(), "abcde");
        assert_eq!(d.undo_depth(), 3, "only the last 3 units are retained");
        assert!(d.undo()); // "abcd"
        assert!(d.undo()); // "abc"
        assert!(d.undo()); // "ab"
        assert_eq!(d.text(), "ab");
        assert!(!d.undo(), "the pruned units ('a','b' inserts) are gone");
        assert!(!d.can_undo());
        // Redo still runs forward from the pruned base.
        assert!(d.redo());
        assert_eq!(d.text(), "abc");
    }

    #[test]
    fn pruning_preserves_branches_within_the_window() {
        // The arena rebuild must remap children/preferred_child — a fork inside
        // the kept window survives pruning with both branches still selectable.
        let mut d = doc("");
        d.edit(vec![EditOp::insert(0, "a")]).unwrap(); // "a"
        d.edit(vec![EditOp::insert(1, "b")]).unwrap(); // "ab"
        d.undo(); // back to "a"; the "b" branch is retained
        d.edit(vec![EditOp::insert(1, "X")]).unwrap(); // "aX"; "a" is now a fork
        // Limit 1 makes the fork the new base, keeping BOTH of its child branches.
        d.set_undo_limit(Some(1));
        assert_eq!(d.undo_depth(), 1);
        assert!(d.undo()); // back to the fork ("a")
        assert_eq!(d.text(), "a");
        assert_eq!(d.redo_branch_count(), 2, "both branches survived the rebuild");
        assert!(d.select_redo_branch(0));
        assert!(d.redo());
        assert_eq!(d.text(), "ab", "the retained branch is still reachable after a prune");
    }

    #[test]
    fn typing_run_merges_into_one_undo_step() {
        // Five keystrokes with mergeable Type hints → one undo removes them all.
        let mut d = doc("");
        for (i, ch) in "hello".chars().enumerate() {
            d.edit_grouped(vec![EditOp::insert(i as u32, ch.to_string())], typ(OpClass::Type))
                .unwrap();
        }
        assert_eq!(d.text(), "hello");
        assert!(d.undo());
        assert_eq!(d.text(), "", "the whole typing run undoes as one unit");
        assert!(d.redo());
        assert_eq!(d.text(), "hello", "and redoes as one unit");
    }

    /// Every selection as `(tail, head)`, document order — direction included,
    /// so a restored range must face the way it did.
    fn spans(d: &Document) -> Vec<(u32, u32)> {
        d.selections().all().iter().map(|s| (s.tail(), s.head())).collect()
    }

    #[test]
    fn undo_restores_every_caret_of_a_multi_cursor_edit() {
        // Fails-first: undo replaced the set with ONE caret at the reverted
        // region's start, so three carets came back as `[(0, 0)]`.
        let mut d = doc("a b c");
        d.set_selections(SelectionSet::from_offsets(&[0, 2, 4]));
        d.type_char('X');
        assert_eq!(d.text(), "Xa Xb Xc");
        assert!(d.undo());
        assert_eq!(d.text(), "a b c");
        assert_eq!(spans(&d), vec![(0, 0), (2, 2), (4, 4)], "undo restores the pre-edit carets");
    }

    #[test]
    fn redo_restores_the_carets_the_edit_left() {
        // Fails-first: redo landed ONE caret at the re-applied region's end.
        let mut d = doc("a b c");
        d.set_selections(SelectionSet::from_offsets(&[0, 2, 4]));
        d.type_char('X');
        assert!(d.undo());
        assert!(d.redo());
        assert_eq!(d.text(), "Xa Xb Xc");
        assert_eq!(spans(&d), vec![(1, 1), (4, 4), (7, 7)], "redo restores the post-edit carets");

        // The after-set is the VERB's placement, not the set rebased through the
        // patch: auto-close parks each caret between its pair (2, 6, 10), where a
        // rebase would have carried it past the closer (3, 7, 11).
        let mut p = doc("a b c");
        p.set_selections(SelectionSet::from_offsets(&[1, 3, 5]));
        p.type_char('(');
        assert_eq!(p.text(), "a() b() c()");
        let placed = spans(&p);
        assert_eq!(placed, vec![(2, 2), (6, 6), (10, 10)]);
        assert!(p.undo());
        assert!(p.redo());
        assert_eq!(spans(&p), placed, "redo restores the verb's caret placement");

        // Ranged sets restore with their direction, both ways: surround keeps
        // each selection on its interior.
        let mut s = doc("ab cd");
        s.set_selections(SelectionSet::from_ranges(&[(2, 0), (3, 5)], 1));
        let before = spans(&s);
        s.type_char('(');
        assert_eq!(s.text(), "(ab) (cd)");
        let after = spans(&s);
        assert_eq!(after, vec![(1, 3), (6, 8)]);
        assert!(s.undo());
        assert_eq!(spans(&s), before, "undo restores both ranges, the reversed one reversed");
        assert!(s.redo());
        assert_eq!(spans(&s), after, "redo restores the surround's interiors");
    }

    #[test]
    fn a_merged_typing_run_restores_the_selections_from_before_the_run() {
        // Type over two selections, then keep typing: the run merges into ONE
        // unit, and that unit's undo restores the selections from before the
        // FIRST keystroke — the two ranges — not the carets ahead of the last
        // keystroke (which would be (2, 6) here, mid-"xy").
        let mut d = doc("foo bar baz");
        d.set_selections(SelectionSet::from_ranges(&[(0, 3), (8, 11)], 1));
        let before = spans(&d);
        for ch in "xyz".chars() {
            d.type_char(ch);
        }
        assert_eq!(d.text(), "xyz bar xyz");
        let after = spans(&d);
        assert_eq!(after, vec![(3, 3), (11, 11)]);
        assert!(d.undo());
        assert_eq!(d.text(), "foo bar baz", "one undo reverts the whole run");
        assert!(!d.can_undo());
        assert_eq!(spans(&d), before, "undo restores the selections from before the run");
        assert!(d.redo());
        assert_eq!(spans(&d), after, "redo restores the carets after the run's last keystroke");
    }

    #[test]
    fn restored_carets_are_ejected_from_a_fold_collapsed_since() {
        // A caret parked inside a block rides an edit elsewhere; the block is
        // then folded (ejecting the LIVE caret, while history's copies keep the
        // hidden offset). Undo and redo revert/replay text outside the fold, so
        // the fold stays collapsed — and the restored caret must still be pulled
        // out to the header's end, exactly as the fold gesture would have.
        use crate::Point;
        let mut d = doc("top\nm {\n  a\n}\n");
        let hidden = |d: &Document| {
            let head = d.selections().newest().head();
            FoldMap::new(d.folds(), d.brackets(), d.buffer()).display_position(d.buffer(), head, d.tab_size()).is_none()
        };
        let header_end = |d: &Document| d.buffer().point_to_offset(Point::new(1, 3));
        d.set_selections(SelectionSet::new(d.buffer().point_to_offset(Point::new(2, 2))));
        d.edit(vec![EditOp::insert(0, "// ")]).unwrap();
        let opener = d.buffer().point_to_offset(Point::new(1, 2));
        assert!(d.toggle_fold_opener(opener));
        assert!(!hidden(&d), "the fold gesture ejected the live caret");

        assert!(d.undo());
        assert!(d.folds().is_folded(d.buffer().point_to_offset(Point::new(1, 2))), "fold untouched");
        assert!(!hidden(&d), "undo's restored caret is not left inside the fold");
        assert_eq!(d.selections().newest().head(), header_end(&d), "…it lands at the header's end");

        assert!(d.redo());
        assert!(!hidden(&d), "redo's restored caret is not left inside the fold");
        assert_eq!(d.selections().newest().head(), header_end(&d));
    }

    #[test]
    fn undo_and_redo_restore_the_observed_selections_across_random_verbs() {
        // The selection-restore oracle. A random walk of multi-caret verbs (typing
        // runs, auto-close/overtype/surround, deletes, Enter, line verbs, paste)
        // and selection gestures, interleaved with undo and redo. The model reads
        // only the public API: a verb that deepened `undo_depth` opened a unit
        // whose before/after states are what was observed around it; a verb that
        // moved the revision without deepening merged into the open unit (its
        // after-state moves). Undo must then land on exactly the unit's observed
        // before-state — text AND every selection (ids, direction, goal) — and
        // redo on its after-state. A verb that placed carets outside the commit
        // shows up here as a redo that disagrees with what the verb displayed.
        type State = (String, Vec<Selection>);
        let state = |d: &Document| -> State { (d.text().into_owned(), d.selections().all().to_vec()) };
        let mut rng = 0x5E1E_C7ED_0008_u64;
        let mut next = move |m: u64| {
            rng ^= rng << 13;
            rng ^= rng >> 7;
            rng ^= rng << 17;
            rng % m
        };
        let mut d = doc("fn main() {\n    let a = (1, \"x\");\n}\n");
        d.set_line_comment(Some("//"));
        // Units on the line to `current` (undo pops) and the preferred redo path
        // (redo pops), each as (before, after).
        let mut units: Vec<(State, State)> = Vec::new();
        let mut redos: Vec<(State, State)> = Vec::new();
        let (mut undone, mut redone, mut merged, mut multi) = (0, 0, 0, 0);
        const CHARS: &[char] = &['a', 'b', ' ', '(', ')', '"', '{', '}', '[', ']'];
        for step in 0..4_000 {
            let roll = next(20);
            if roll < 3 {
                let ok = d.undo();
                assert_eq!(ok, !units.is_empty(), "step {step}: undo availability");
                if let Some(unit) = units.pop() {
                    assert_eq!(state(&d), unit.0, "step {step}: undo restores the before-state");
                    redos.push(unit);
                    undone += 1;
                }
                continue;
            }
            // Redo only succeeds after an undo, so it gets the heavier weight.
            if roll < 8 {
                let ok = d.redo();
                assert_eq!(ok, !redos.is_empty(), "step {step}: redo availability");
                if let Some(unit) = redos.pop() {
                    assert_eq!(state(&d), unit.1, "step {step}: redo restores the after-state");
                    units.push(unit);
                    redone += 1;
                }
                continue;
            }
            if roll < 11 {
                // Selection gestures: no unit, but each seals the open run.
                let len = d.buffer().len();
                match next(4) {
                    0 => {
                        let n = 1 + next(4) as usize;
                        let ranges: Vec<(u32, u32)> = (0..n)
                            .map(|_| {
                                let a = next(u64::from(len) + 1) as u32;
                                let b = if next(2) == 0 { a } else { next(u64::from(len) + 1) as u32 };
                                (a, b)
                            })
                            .collect();
                        d.set_selections(SelectionSet::from_ranges(&ranges, next(n as u64) as usize));
                    }
                    1 => {
                        let motions = [Motion::Left, Motion::Right, Motion::Up, Motion::Down, Motion::LineEnd];
                        d.move_carets(motions[next(motions.len() as u64) as usize], next(3) == 0);
                    }
                    2 => d.add_caret(next(u64::from(len) + 1) as u32),
                    _ => d.add_caret_vertical(next(2) == 0),
                }
                continue;
            }
            let (pre, depth, rev) = (state(&d), d.undo_depth(), d.revision());
            match next(16) {
                0..=5 => d.type_char(CHARS[next(CHARS.len() as u64) as usize]),
                6 => d.backspace(),
                7 => d.delete_forward(),
                8 => d.enter(),
                9 => d.tab(),
                10 => d.outdent(),
                11 => d.delete_word_back(),
                12 => d.insert_text("p\r\nq"),
                13 => d.toggle_line_comment(),
                14 => d.insert_line(next(2) == 0),
                _ => match next(3) {
                    0 => d.move_line(next(2) == 0),
                    1 => d.copy_line(next(2) == 0),
                    _ => d.cut(),
                },
            }
            let post = state(&d);
            if d.undo_depth() == depth + 1 {
                multi += usize::from(pre.1.len() > 1);
                units.push((pre, post));
                redos.clear(); // a new unit is the tip: nothing to redo from it
            } else if d.revision() != rev {
                assert_eq!(d.undo_depth(), depth, "step {step}: a merge keeps the depth");
                units.last_mut().expect("a merge needs an open unit").1 = post;
                merged += 1;
            }
        }
        // Guard against a vacuous walk: every route was really exercised.
        // (This seed: 548 undos, 194 redos, 97 merges, 903 multi-caret units.)
        assert!(
            undone > 400 && redone > 140 && merged > 70 && multi > 600,
            "walk too thin: {undone} undos / {redone} redos / {merged} merges / {multi} multi-caret units",
        );
    }

    #[test]
    fn fold_toggle_seals_undo_and_clears_the_expand_ladder() {
        // A fold toggle moves carets (ejection), so it is a gesture boundary:
        // typing must not merge across it, and the expand ladder must clear so a
        // later shrink cannot restore a caret INTO the collapsed fold.
        let mut d = doc("m {\n  word\n}");
        d.set_selections(SelectionSet::new(7)); // inside "word"
        d.type_char('x');
        d.expand_selection(); // pushes the pre-expansion set on the ladder
        assert!(d.toggle_fold_opener(2));
        d.shrink_selection(); // ladder cleared by the toggle → no-op…
        let head = d.selections().newest().head();
        let fm = crate::fold_map::FoldMap::new(d.folds(), d.brackets(), d.buffer());
        assert!(
            fm.display_position(d.buffer(), head, d.tab_size()).is_some(),
            "…so the caret cannot be restored into the collapsed fold"
        );
        // And the toggle sealed the typing group: the later run undoes alone.
        d.type_char('y');
        assert!(d.undo());
        assert!(d.text().contains('x'), "undo reverted only the post-toggle typing");
    }

    #[test]
    fn find_navigation_expands_a_collapsed_inline_fold() {
        // display_position clips a chip-hidden column to the chip center, so an
        // offset inside a collapsed inline fold still reports a position;
        // unfold_to_reveal must expand the fold anyway so a find jump lands on
        // visible text, not inside the chip.
        let mut d = doc("x = [1, 2, 3]\nafter");
        assert!(d.toggle_fold_opener(4)); // the `[`
        d.set_find_query(Some(FindQuery { text: "2".into(), case_sensitive: false, ..Default::default() }), 0);
        d.find_next(0).expect("the match exists");
        assert!(!d.folds().is_folded(4), "the inline fold expanded to show the match");
    }

    #[test]
    fn editing_hidden_text_expands_only_the_enclosing_fold() {
        // expand_folds_touched, windowed to the enclosing folds: an edit into
        // a collapsed block's hidden interior expands THAT block (never edit text
        // the user can't see) and leaves every other fold collapsed — the walk
        // visits only the folds enclosing the edit, not all of them.
        let text = "a {\n  keep\n}\nb {\n  body\n}\nc\n";
        let mut d = doc(text);
        let opens: Vec<u32> = text.match_indices('{').map(|(i, _)| i as u32).collect();
        // `keep` is the first block, `edited` the second. Both openers sit BEFORE
        // the edit, so their offsets don't shift — the checks stay valid.
        let (keep, edited) = (opens[0], opens[1]);
        assert!(d.toggle_fold_opener(keep));
        assert!(d.toggle_fold_opener(edited));
        assert!(d.folds().is_folded(keep) && d.folds().is_folded(edited));
        // Edit inside the SECOND block's hidden interior (its "body" row).
        let inside = text.find("body").unwrap() as u32 + 2;
        d.edit(vec![EditOp::insert(inside, "X")]).unwrap();
        assert!(!d.folds().is_folded(edited), "editing inside the second block expands it");
        assert!(d.folds().is_folded(keep), "the untouched first block stays folded");
    }

    #[test]
    fn next_diagnostic_advances_past_a_shared_start_offset() {
        use crate::{Diagnostic, Severity};
        // Two diagnostics share a start offset: the (start, end) lexicographic
        // walk must reach both and then wrap, never cycle between them.
        let mut d = doc("abcdef");
        let rev = d.revision();
        d.set_diagnostics(
            rev,
            vec![
                Diagnostic::new(1..3, Severity::Error, "a"),
                Diagnostic::new(1..5, Severity::Warning, "b"),
            ],
        );
        assert_eq!(d.next_diagnostic(true), Some(1..3));
        assert_eq!(d.next_diagnostic(true), Some(1..5), "the same-start sibling is reachable");
        assert_eq!(d.next_diagnostic(true), Some(1..3), "and the walk wraps");
    }

    #[test]
    fn reveal_classes_and_no_op_verbs() {
        use crate::{Diagnostic, Severity};
        // Find-family jumps request Center; bracket hops request Fit; verbs
        // that change nothing request nothing — a no-op F8 must not autoscroll
        // the viewport back to the caret.
        let mut d = doc("f( ab )");
        let seq0 = d.reveal_seq();
        d.next_diagnostic(true); // no diagnostics → no request
        assert_eq!(d.reveal_seq(), seq0, "a no-op F8 requests no reveal");
        d.set_selections(SelectionSet::new(3));
        d.jump_to_bracket(); // no adjacent bracket? offset 3 is inside ( ) → moves
        assert!(d.reveal_seq() > seq0, "a real bracket hop requests a reveal");
        assert_eq!(d.reveal_mode(), RevealMode::Fit, "…of the Fit class");
        let rev = d.revision();
        d.set_diagnostics(rev, vec![Diagnostic::new(1..2, Severity::Error, "e")]);
        let seq1 = d.reveal_seq();
        d.next_diagnostic(true);
        assert!(d.reveal_seq() > seq1);
        assert_eq!(d.reveal_mode(), RevealMode::Center, "a diagnostic jump centers");
    }

    #[test]
    fn ctrl_d_force_reveals_while_select_all_holds() {
        // Ctrl+D jumps to the just-added cursor (FitForce); Ctrl+Shift+L reveals
        // with Fit (holds the viewport if a cursor is already visible).
        let mut d = doc("foo bar foo baz foo");
        d.set_selections(SelectionSet::new(0));
        d.add_next_occurrence(); // expand to "foo"
        d.add_next_occurrence(); // add the next "foo" — a new cursor to jump to
        assert_eq!(d.reveal_mode(), RevealMode::FitForce, "Ctrl+D force-reveals the new cursor");
        let mut e = doc("foo bar foo baz foo");
        e.set_selections(SelectionSet::new(0));
        e.select_all_occurrences();
        assert_eq!(e.reveal_mode(), RevealMode::Fit, "Ctrl+Shift+L holds if a cursor is visible");
    }

    #[test]
    fn diagnostic_navigation_wraps_selects_and_reveals() {
        use crate::{Diagnostic, Severity};
        let mut d = doc("aa bb\ncc\ndd");
        let rev = d.revision();
        d.set_diagnostics(
            rev,
            vec![
                Diagnostic::new(3..5, Severity::Warning, "w"),
                Diagnostic::new(9..11, Severity::Error, "e"),
            ],
        );
        assert_eq!(d.next_diagnostic(true), Some(3..5));
        assert_eq!(d.next_diagnostic(true), Some(9..11));
        assert_eq!(d.next_diagnostic(true), Some(3..5), "wraps to the first");
        assert_eq!(d.next_diagnostic(false), Some(9..11), "prev wraps to the last");
        let s = d.selections().newest();
        assert_eq!((s.start(), s.end()), (9, 11), "the diagnostic's span is selected");
        // No diagnostics → None, caret untouched.
        let mut e = doc("x");
        e.set_selections(SelectionSet::new(1));
        assert!(e.next_diagnostic(true).is_none());
        assert_eq!(e.selections().newest().head(), 1);
        // A diagnostic hidden in a collapsed fold is revealed on arrival.
        let mut f = doc("aa\nfn {\nbb\n}\ncc");
        assert!(f.toggle_fold_opener(6));
        let rev = f.revision();
        f.set_diagnostics(rev, vec![Diagnostic::new(8..10, Severity::Error, "hidden")]);
        assert_eq!(f.next_diagnostic(true), Some(8..10));
        assert!(!f.folds().is_folded(6), "the fold expanded to show the diagnostic");
    }

    #[test]
    fn caret_word_occurrences_are_whole_word_only() {
        let mut d = doc("foo foobar foo\nfoo");
        d.set_selections(SelectionSet::new(1)); // inside the first "foo"
        assert_eq!(
            d.caret_word_occurrences(0..u32::MAX),
            vec![0..3, 11..14, 15..18],
            "the foobar prefix is not a whole-word match"
        );
        // The window bounds the scan (the widget passes its viewport)…
        assert_eq!(d.caret_word_occurrences(4..15), vec![11..14], "only in-window matches");
        // …a non-empty selection produces no occurrence wash…
        let mut set = SelectionSet::new(0);
        set.set_single(Selection::from_anchor(SelectionId(0), 0, 3));
        d.set_selections(set);
        assert!(d.caret_word_occurrences(0..u32::MAX).is_empty());
        // …and neither does a caret in open whitespace.
        let mut w = doc("a  b");
        w.set_selections(SelectionSet::new(2));
        assert!(w.caret_word_occurrences(0..u32::MAX).is_empty());
    }

    /// Regression (fails-first): the window was clamped to the length but
    /// sliced as given, so a viewport range starting inside a char panicked
    /// the per-frame wash. It now snaps outward like every host range.
    #[test]
    fn caret_word_occurrences_take_a_mid_char_window() {
        let mut d = doc("é foo é foo"); // é 0..2, foo 3..6, é 7..9, foo 10..13
        d.set_selections(SelectionSet::new(11));
        assert_eq!(d.caret_word_occurrences(1..8), vec![3..6], "both window ends split an 'é'");
    }

    #[test]
    fn find_navigation_expands_a_collapsed_fold_to_reveal_the_match() {
        // A match hidden inside a collapsed block: find_next must unfold it —
        // the caret can never land on an invisible position.
        let mut d = doc("aa\nfn {\nneedle\n}\nbb");
        let opener = 6; // the `{` (pair 6..15, hides rows 2..=3)
        assert!(d.toggle_fold_opener(opener));
        d.set_find_query(Some(FindQuery { text: "needle".into(), case_sensitive: false, ..Default::default() }), 0);
        let m = d.find_next(0).expect("the match exists");
        assert!(!d.folds().is_folded(opener), "the fold expanded to reveal the match");
        let fm = crate::fold_map::FoldMap::new(d.folds(), d.brackets(), d.buffer());
        assert!(
            fm.display_position(d.buffer(), m.end, d.tab_size()).is_some(),
            "the match head renders"
        );
        // A match on VISIBLE ground (the header line) leaves folds alone.
        let mut v = doc("aa\nfn {\nx\n}\nbb");
        assert!(v.toggle_fold_opener(6));
        v.set_find_query(Some(FindQuery { text: "fn".into(), case_sensitive: false, ..Default::default() }), 0);
        v.find_next(0).expect("match on the header");
        assert!(v.folds().is_folded(6), "a visible match keeps the fold collapsed");
    }

    #[test]
    fn jump_to_bracket_crosses_and_returns() {
        // `f( ab )` — ( at 1, ) at 6. Right of `(`: cross to the same side of
        // the partner (after `)`), and a second press returns.
        let mut d = doc("f( ab )");
        d.set_selections(SelectionSet::new(2));
        d.jump_to_bracket();
        assert_eq!(d.selections().newest().head(), 7);
        d.jump_to_bracket();
        assert_eq!(d.selections().newest().head(), 2);
        // No adjacent bracket: jump to the enclosing pair's closer.
        d.set_selections(SelectionSet::new(4)); // inside "ab"
        d.jump_to_bracket();
        assert_eq!(d.selections().newest().head(), 6, "lands before `)`");
        // No bracket in reach: the caret stays put.
        let mut e = doc("plain");
        e.set_selections(SelectionSet::new(3));
        e.jump_to_bracket();
        assert_eq!(e.selections().newest().head(), 3);
    }

    #[test]
    fn expand_selection_climbs_the_bracket_ladder_and_shrinks_back() {
        // `m { a(bb) }` — offsets: m0 ␠1 {2 ␠3 a4 (5 b6 b7 )8 ␠9 }10.
        let mut d = doc("m { a(bb) }");
        d.set_selections(SelectionSet::new(7)); // caret in "bb"
        let sel = |d: &Document| (d.selections().newest().start(), d.selections().newest().end());
        d.expand_selection();
        assert_eq!(sel(&d), (6, 8), "word first");
        d.expand_selection();
        assert_eq!(sel(&d), (5, 9), "word == () contents, so the pair incl. brackets");
        d.expand_selection();
        assert_eq!(sel(&d), (3, 10), "the brace contents");
        d.expand_selection();
        assert_eq!(sel(&d), (2, 11), "the brace pair incl. brackets");
        d.expand_selection();
        assert_eq!(sel(&d), (0, 11), "the whole document");
        d.expand_selection();
        assert_eq!(sel(&d), (0, 11), "fully expanded is a no-op");
        // Shrink walks back down the exact ladder.
        d.shrink_selection();
        assert_eq!(sel(&d), (2, 11));
        d.shrink_selection();
        assert_eq!(sel(&d), (3, 10));
        // Any other gesture clears the ladder — shrink becomes a no-op.
        d.move_carets(Motion::Right, false);
        let caret = sel(&d);
        d.shrink_selection();
        assert_eq!(sel(&d), caret, "the ladder cleared on the caret move");
    }

    #[test]
    fn add_caret_vertical_stacks_and_stops_at_edges() {
        // Stack carets down a column: every caret gains a neighbour, landings
        // on existing carets merge, and typing edits the whole column.
        let mut d = doc("aaa\nbbb\nccc");
        d.set_selections(SelectionSet::new(5)); // row 1, col 1
        d.add_caret_vertical(false); // above → row 0
        d.add_caret_vertical(true); // below both → rows 1 (merges) and 2
        assert_eq!(d.selections().len(), 3);
        d.type_char('X');
        assert_eq!(d.text(), "aXaa\nbXbb\ncXcc");
        // On the top display row, Up adds nothing (no clamp-to-doc-start caret).
        let mut e = doc("aa\nbb");
        e.set_selections(SelectionSet::new(1));
        e.add_caret_vertical(false);
        assert_eq!(e.selections().len(), 1);
    }

    #[test]
    fn add_caret_vertical_skips_a_collapsed_fold() {
        let mut d = doc("aa\nfn {\nbb\ncc\n}\ndd");
        assert!(d.toggle_fold_opener(6)); // hides rows 2..=4
        d.set_selections(SelectionSet::new(16)); // "dd", display row 2
        d.add_caret_vertical(false);
        let rows: Vec<u32> =
            d.selections().all().iter().map(|s| d.buffer().offset_to_point(s.head()).row).collect();
        assert_eq!(rows, vec![1, 5], "the new caret lands on the fold header, not a hidden row");
    }

    #[test]
    fn select_all_occurrences_takes_every_match_from_a_word_seed() {
        // Bare caret in "foo": seed the word, then take ALL occurrences —
        // typing then replaces every one (the multi-cursor rename).
        let mut d = doc("foo bar foo baz foo");
        d.set_selections(SelectionSet::new(1));
        d.select_all_occurrences();
        assert_eq!(d.selections().len(), 3);
        d.type_char('X');
        assert_eq!(d.text(), "X bar X baz X");
        // No word under the caret ⇒ no change.
        let mut e = doc("   ");
        e.set_selections(SelectionSet::new(1));
        e.select_all_occurrences();
        assert_eq!(e.selections().len(), 1);
        assert!(e.selections().newest().is_empty());
    }

    #[test]
    fn select_find_matches_turns_matches_into_selections() {
        let mut d = doc("foo bar foo baz foo");
        d.set_find_query(Some(FindQuery { text: "foo".into(), case_sensitive: false, ..Default::default() }), 0);
        d.find_next(0); // activate the first match (caret there)
        assert!(d.select_find_matches());
        assert_eq!(d.selections().len(), 3);
        assert_eq!(d.selections().newest().start(), 0, "the ACTIVE match is newest");
        // No query ⇒ no live matches ⇒ no-op.
        let mut e = doc("abc");
        assert!(!e.select_find_matches());
        assert_eq!(e.selections().len(), 1);
    }

    #[test]
    fn replace_all_swaps_every_match_in_one_undo_step() {
        // The load-bearing claim: replace-all is ONE transaction, so ONE undo
        // puts the document back byte-for-byte.
        let original = "foo bar foo baz foo";
        let mut d = doc(original);
        d.set_find_query(Some(FindQuery { text: "foo".into(), case_sensitive: false, ..Default::default() }), 0);
        assert_eq!(d.replace_all("QUX", false), 3);
        assert_eq!(d.text(), "QUX bar QUX baz QUX");
        assert!(d.undo());
        assert_eq!(d.text(), original, "replace-all must undo as ONE step");
        assert!(!d.undo(), "…with no second step hiding behind it");
        // The match set rode the commit through the shared mover — undo included.
        assert_eq!(d.find_match_count(), 3);
    }

    #[test]
    fn replace_all_is_not_capped_by_the_live_match_set() {
        // The live set is a capped PREFIX of the document, so a replace-all
        // built from it would silently leave everything past the cap untouched.
        // `replace_all` runs its own uncapped scan; this pins that it must.
        let n = crate::find::FIND_MATCH_CAP + 500;
        let mut d = doc(&"a".repeat(n));
        d.set_find_query(Some(FindQuery { text: "a".into(), case_sensitive: false, ..Default::default() }), 0);
        assert_eq!(d.find_match_count(), crate::find::FIND_MATCH_CAP, "the live set caps");
        assert_eq!(d.replace_all("b", false), n, "replace-all must NOT cap");
        assert_eq!(d.text(), "b".repeat(n), "every match past the cap replaced too");
    }

    #[test]
    fn replace_next_selects_before_it_replaces() {
        let mut d = doc("foo bar foo");
        d.set_find_query(Some(FindQuery { text: "foo".into(), case_sensitive: false, ..Default::default() }), 0);
        // Nothing selected yet: the first press only NAVIGATES — text is never
        // overwritten before it has been shown.
        assert_eq!(d.replace_next("X", false, 0), Some(0..3));
        assert_eq!(d.text(), "foo bar foo", "the first press must not replace");
        // Now the selection IS the active match: replace it, then advance. The
        // returned range is POST-edit — "foo bar foo" − "foo" + "X" ⇒ the
        // surviving match slid 8..11 → 6..9.
        assert_eq!(d.replace_next("X", false, 0), Some(6..9));
        assert_eq!(d.text(), "X bar foo");
        // …and one undo takes the replacement back.
        assert!(d.undo());
        assert_eq!(d.text(), "foo bar foo");
    }

    #[test]
    fn redo_of_a_replace_restores_the_match_it_advanced_to() {
        // Fails-first: the replace committed through `edit` and only THEN moved
        // the selection to the next match, after history had recorded the unit's
        // after-set — so redo restored the selection rebased over the
        // replacement (`0..1`, the "X"), not the next match the user saw.
        let mut d = doc("foo bar foo");
        d.set_find_query(Some(FindQuery { text: "foo".into(), ..Default::default() }), 0);
        assert_eq!(d.replace_next("X", false, 0), Some(0..3), "the first press navigates");
        assert_eq!(d.replace_next("X", false, 0), Some(6..9), "the second replaces and advances");
        assert_eq!(d.text(), "X bar foo");
        let seen = spans(&d);
        assert_eq!(seen, vec![(6, 9)], "the next match is selected");
        assert!(d.undo());
        assert_eq!(spans(&d), vec![(0, 3)], "undo restores the match that was replaced");
        assert!(d.redo());
        assert_eq!(d.text(), "X bar foo");
        assert_eq!(spans(&d), seen, "redo restores the match the replace advanced to");
    }

    #[test]
    fn find_scope_restricts_matches_and_replace_all() {
        let mut d = doc("foo foo | foo foo");
        d.set_find_query(Some(FindQuery { text: "foo".into(), case_sensitive: false, ..Default::default() }), 0);
        assert_eq!(d.find_match_count(), 4);
        // Scope to the left half: the two matches beyond it stop existing.
        d.set_find_scope(Some(0..7), 0);
        assert_eq!(d.find_match_count(), 2, "only the in-scope matches survive");
        // …and replace-all inherits that without knowing the scope exists.
        assert_eq!(d.replace_all("X", false), 2, "replace-all must honor the scope");
        assert_eq!(d.text(), "X X | foo foo", "the out-of-scope matches are untouched");
        // Clearing the scope brings the rest back.
        d.set_find_scope(None, 0);
        assert_eq!(d.find_match_count(), 2, "the two outside are findable again");
    }

    #[test]
    fn the_find_scope_rides_edits_and_drops_when_it_collapses() {
        let mut d = doc("aaa foo bbb");
        d.set_find_query(Some(FindQuery { text: "foo".into(), case_sensitive: false, ..Default::default() }), 0);
        d.set_find_scope(Some(4..7), 0); // exactly "foo"
        assert_eq!(d.find_match_count(), 1);
        // An insert BEFORE the scope slides it, keeping it over the same text.
        d.edit(vec![EditOp::insert(0, "XY")]).unwrap();
        assert_eq!(d.find_scope(), Some(6..9));
        assert_eq!(d.find_match_count(), 1, "the scope still covers the match");
        // Deleting the scope's whole content collapses it ⇒ it drops, rather
        // than pinning zero matches forever.
        d.edit(vec![EditOp::delete(6..9)]).unwrap();
        assert_eq!(d.find_scope(), None, "a collapsed scope must clear");
    }

    /// Regression (fails-first): the find scope stored the host range as-is,
    /// so a mid-char scope was shaded from inside a char and a past-end one was
    /// kept as a live scope over no text. It now clips like every stored range:
    /// outward to whole chars, and a scope that clamps to empty clears.
    #[test]
    fn the_find_scope_clips_a_host_range() {
        let mut d = doc("é foo é"); // é 0..2, foo 3..6, é 7..9
        d.set_find_query(Some(FindQuery { text: "foo".into(), case_sensitive: false, ..Default::default() }), 0);
        d.set_find_scope(Some(1..8), 0);
        assert_eq!(d.find_scope(), Some(0..9));
        assert_eq!(d.find_match_count(), 1);
        d.set_find_scope(Some(1000..2000), 0);
        assert_eq!(d.find_scope(), None, "a scope past the end clamps to empty, which clears");
        assert_eq!(d.find_match_count(), 1);
    }

    #[test]
    fn an_edit_outside_the_scope_creates_no_matches() {
        let mut d = doc("foo | ...");
        d.set_find_query(Some(FindQuery { text: "foo".into(), case_sensitive: false, ..Default::default() }), 0);
        d.set_find_scope(Some(0..3), 0);
        assert_eq!(d.find_match_count(), 1);
        // Type a matching word far outside the scope: the repair window clamps
        // to the scope, so this must NOT become a match.
        d.edit(vec![EditOp::insert(6, "foo")]).unwrap();
        assert_eq!(d.find_match_count(), 1, "out-of-scope text must not match");
    }

    /// The oracle for the scoped repair: after random edits, the incrementally
    /// repaired set must be byte-identical to what a from-scratch scan of the
    /// (patch-ridden) scope produces. "foo" cannot overlap itself, so the
    /// documented self-overlap phase relaxation does not apply — these must
    /// agree exactly.
    #[test]
    fn scoped_repair_equals_a_fresh_scoped_scan_under_random_edits() {
        let mut seed = 0x5EED_u64;
        let mut rng = || {
            seed ^= seed << 13;
            seed ^= seed >> 7;
            seed ^= seed << 17;
            seed
        };
        let base = "foo bar foo baz\nfoo foo bar\nbarfoo foo\n".repeat(3);
        let n = base.len() as u32;
        for trial in 0..300 {
            let mut d = doc(&base);
            let a = (rng() as u32) % n;
            let b = (rng() as u32) % n;
            let (lo, hi) = (a.min(b), a.max(b));
            let lo = d.buffer().clip_offset(lo, Bias::Right);
            let hi = d.buffer().clip_offset(hi, Bias::Left);
            if lo >= hi {
                continue;
            }
            d.set_find_query(Some(FindQuery { text: "foo".into(), case_sensitive: false, ..Default::default() }), 0);
            d.set_find_scope(Some(lo..hi), 0);
            for _ in 0..4 {
                let at = (rng() as u32) % (d.buffer().len() + 1);
                let at = d.buffer().clip_offset(at, Bias::Left);
                let ins = ["foo", "x", "", "\nfoo "][(rng() % 4) as usize];
                d.edit(vec![EditOp::insert(at, ins)]).unwrap();
            }
            let incremental: Vec<_> = d.find_matches_in(0..u32::MAX).map(|(r, _)| r).collect();
            // Force a from-scratch rescan of the SAME (now patch-ridden) scope:
            // dropping the query and re-setting it re-scans, and never touches
            // the scope.
            let scope = d.find_scope();
            let q = d.find_query().cloned().unwrap();
            d.set_find_query(None, 0);
            d.set_find_query(Some(q), 0);
            let fresh: Vec<_> = d.find_matches_in(0..u32::MAX).map(|(r, _)| r).collect();
            assert_eq!(incremental, fresh, "trial {trial}, scope {scope:?}");
            // …and nothing ever escaped the scope.
            if let Some(s) = scope {
                assert!(
                    incremental.iter().all(|m| m.start >= s.start && m.end <= s.end),
                    "trial {trial}: a match escaped the scope {s:?}: {incremental:?}"
                );
            }
        }
    }

    /// The oracle for the LINE-SCOPED repair. After random edits the
    /// incrementally repaired set must be byte-identical to a from-scratch scan
    /// — the same bar the literal path is held to.
    ///
    /// This is the proof that a line window is *sufficient* for a
    /// variable-length pattern, where the literal path's "a match starts at most
    /// k−1 bytes left of a changed byte" argument does not hold at all. `.*` is
    /// the case that makes the point: one edit anywhere rewrites a match
    /// spanning its entire line. The punctuation-edged whole-word needles pin
    /// that the per-match edge check (which reads the neighbour OUTSIDE the
    /// match) stays inside the line window too.
    #[test]
    fn line_scoped_repair_equals_a_fresh_scan_under_random_edits() {
        let mut seed = 0x00C0_FFEE_u64;
        let mut rng = || {
            seed ^= seed << 13;
            seed ^= seed >> 7;
            seed ^= seed << 17;
            seed
        };
        let base =
            "foo bar foo baz\nfoo foo bar\nbarfoo foo\n\nqux foofoo\n(foo) a == b; x=-1 foo.bar\n"
                .repeat(3);
        let ww =
            |text: &str| FindQuery { text: text.into(), whole_word: true, ..Default::default() };
        let queries = [
            ww("foo"),
            // Punctuation-edged whole-word needles: a separator edge is free of
            // its neighbour, so an edit NEXT to one (typing `x` before `(foo`)
            // must not kill it, while an edit next to a word edge must.
            ww("(foo"),
            ww("=="),
            ww("foo."),
            ww("-1"),
            FindQuery {
                text: r"\(foo|==".into(),
                whole_word: true,
                regex: true,
                ..Default::default()
            },
            FindQuery { text: "f.o".into(), regex: true, ..Default::default() },
            FindQuery { text: r"\w+o".into(), regex: true, ..Default::default() },
            // The one a fixed-k window can never handle.
            FindQuery { text: ".*".into(), regex: true, ..Default::default() },
            FindQuery { text: r"\bba\w+".into(), regex: true, ..Default::default() },
            FindQuery {
                text: "foo|bar".into(),
                whole_word: true,
                regex: true,
                ..Default::default()
            },
        ];
        for (qi, q) in queries.iter().enumerate() {
            // Trials whose final set is non-empty: equality of two empty sets
            // proves nothing, so each query must keep real matches to compare.
            let mut nonempty = 0;
            for trial in 0..40 {
                let mut d = doc(&base);
                d.set_find_query(Some(q.clone()), 0);
                for _ in 0..5 {
                    let len = d.buffer().len();
                    // Mix inserts and deletions — a deletion can JOIN two lines,
                    // which is the line-window repair's sharpest case.
                    if rng() % 3 == 0 && len > 4 {
                        let a = d.buffer().clip_offset((rng() as u32) % len, Bias::Left);
                        let b = d
                            .buffer()
                            .clip_offset((a + 1 + (rng() as u32) % 6).min(len), Bias::Right);
                        if a < b {
                            d.edit(vec![EditOp::delete(a..b)]).unwrap();
                        }
                    } else {
                        let at = d.buffer().clip_offset((rng() as u32) % (len + 1), Bias::Left);
                        // `(` `=` `-1` `.` grow and break the punctuation-edged
                        // needles; `x` lands against their edges.
                        let ins = ["foo", "x", "\n", " ", "\nfoo bar", "(", "=", "-1", "."]
                            [(rng() % 9) as usize];
                        d.edit(vec![EditOp::insert(at, ins)]).unwrap();
                    }
                }
                let incremental: Vec<_> = d.find_matches_in(0..u32::MAX).map(|(r, _)| r).collect();
                // Force a from-scratch rescan and compare.
                d.set_find_query(None, 0);
                d.set_find_query(Some(q.clone()), 0);
                let fresh: Vec<_> = d.find_matches_in(0..u32::MAX).map(|(r, _)| r).collect();
                assert_eq!(incremental, fresh, "query {qi} ({:?}), trial {trial}", q.text);
                nonempty += usize::from(!fresh.is_empty());
            }
            assert!(nonempty >= 30, "query {qi} ({:?}) is vacuous: {nonempty}/40", q.text);
        }
    }

    #[test]
    fn regex_replace_all_is_one_undo_step() {
        let original = "a1 b22 c333";
        let mut d = doc(original);
        d.set_find_query(
            Some(FindQuery { text: r"\d+".into(), regex: true, ..Default::default() }),
            0,
        );
        assert_eq!(d.find_match_count(), 3);
        assert_eq!(d.replace_all("#", false), 3);
        assert_eq!(d.text(), "a# b# c#");
        assert!(d.undo());
        assert_eq!(d.text(), original, "a regex replace-all undoes as ONE step");
    }

    #[test]
    fn a_regex_replacement_expands_capture_groups() {
        // Regex mode makes the replacement a TEMPLATE, per VS Code.
        let mut d = doc("fn one()\nfn two()");
        d.set_find_query(
            Some(FindQuery { text: r"fn (\w+)\(\)".into(), regex: true, ..Default::default() }),
            0,
        );
        assert_eq!(d.replace_all("let $1 = 1;", false), 2);
        assert_eq!(d.text(), "let one = 1;\nlet two = 1;");
        assert!(d.undo());
        assert_eq!(d.text(), "fn one()\nfn two()", "still ONE undo step");

        // …and a LITERAL query does not expand: nothing captured anything, so a
        // typed `$1` must land as a literal `$1`.
        let mut e = doc("aaa");
        e.set_find_query(Some(FindQuery { text: "aaa".into(), ..Default::default() }), 0);
        assert_eq!(e.replace_all("$1", false), 1);
        assert_eq!(e.text(), "$1");
    }

    #[test]
    fn replace_next_expands_captures_for_the_active_match_only() {
        let mut d = doc("fn one()\nfn two()");
        d.set_find_query(
            Some(FindQuery { text: r"fn (\w+)\(\)".into(), regex: true, ..Default::default() }),
            0,
        );
        d.replace_next("x", false, 0); // first press: selects only
        d.replace_next("[$1]", false, 0); // second: replaces the active match
        assert_eq!(d.text(), "[one]\nfn two()");
    }

    #[test]
    fn preserve_case_recases_replacements_to_their_match() {
        // A literal rename that keeps each occurrence's casing: FOO→BAR,
        // Foo→Bar, foo→bar, all from one replacement "bar".
        let mut d = doc("FOO Foo foo fOo");
        d.set_find_query(Some(FindQuery { text: "foo".into(), case_sensitive: false, ..Default::default() }), 0);
        assert_eq!(d.replace_all("bar", true), 4);
        // FOO⇒upper, Foo⇒capitalized, foo⇒lower, fOo⇒lower first letter.
        assert_eq!(d.text(), "BAR Bar bar bar");

        // Off, the same replacement lands verbatim.
        let mut e = doc("FOO Foo foo");
        e.set_find_query(Some(FindQuery { text: "foo".into(), case_sensitive: false, ..Default::default() }), 0);
        assert_eq!(e.replace_all("bar", false), 3);
        assert_eq!(e.text(), "bar bar bar");
    }

    #[test]
    fn preserve_case_follows_vs_codes_table() {
        // (match, replacement, expected): the first block is VS Code's own test
        // table for `buildReplaceStringWithCasePreserved`; the second is the
        // camelCase / snake / kebab renames this rule exists for. Each runs
        // end to end through `replace_all` on a one-match document.
        let table: &[(&str, &str, &str)] = &[
            ("abc", "Def", "def"),
            ("Abc", "Def", "Def"),
            ("ABC", "Def", "DEF"),
            ("aBc", "Def", "def"),
            ("AbC", "Def", "Def"),
            ("aBC", "Def", "def"),
            ("aBc", "DeF", "deF"),
            ("Foo-Bar", "newfoo-newbar", "Newfoo-Newbar"),
            ("Foo-Bar-Abc", "newfoo-newbar-newabc", "Newfoo-Newbar-Newabc"),
            ("Foo-Bar-abc", "newfoo-newbar", "Newfoo-newbar"),
            ("foo-Bar", "newfoo-newbar", "newfoo-Newbar"),
            ("foo-BAR", "newfoo-newbar", "newfoo-NEWBAR"),
            ("foO-BAR", "NewFoo-NewBar", "newFoo-NEWBAR"),
            ("Foo_Bar", "newfoo_newbar", "Newfoo_Newbar"),
            ("Foo_Bar_Abc", "newfoo_newbar_newabc", "Newfoo_Newbar_Newabc"),
            ("Foo_Bar_abc", "newfoo_newbar", "Newfoo_newbar"),
            ("Foo_Bar-abc", "newfoo_newbar-abc", "Newfoo_newbar-abc"),
            ("foo_Bar", "newfoo_newbar", "newfoo_Newbar"),
            ("Foo_BAR", "newfoo_newbar", "Newfoo_NEWBAR"),
            // camelCase keeps its lower first letter; the rest is as typed.
            ("fooBar", "BazQux", "bazQux"),
            ("FooBar", "bazQux", "BazQux"),
            ("FOO_BAR", "baz_qux", "BAZ_QUX"),
            ("FOO_BAR", "bazQux", "BAZQUX"),
            ("foo-bar", "Baz-Qux", "baz-qux"),
            ("foo_barBaz", "Qux_quuxCorge", "qux_quuxCorge"),
        ];
        for &(matched, replacement, want) in table {
            let mut d = doc(matched);
            d.set_find_query(Some(FindQuery { text: matched.into(), case_sensitive: true, ..Default::default() }), 0);
            assert_eq!(d.replace_all(replacement, true), 1, "{matched:?}");
            assert_eq!(d.text(), want, "{matched:?} replaced by {replacement:?}");
        }
    }

    #[test]
    fn preserve_case_applies_after_regex_expansion() {
        // The re-casing keys off the whole match, applied to the expanded
        // template — so `$1`-driven text is re-cased too.
        let mut d = doc("GETVALUE getvalue");
        d.set_find_query(
            Some(FindQuery { text: "(get)(value)".into(), regex: true, ..Default::default() }),
            0,
        );
        // Braced refs — `$2_$1` would read `$2_` as a group named "2_" (the
        // greedy unbraced-ref rule), so delimit with `${…}`.
        assert_eq!(d.replace_all("${2}_${1}", true), 2);
        // GETVALUE (all upper) ⇒ VALUE_GET; getvalue (all lower) ⇒ value_get.
        assert_eq!(d.text(), "VALUE_GET value_get");
    }

    #[test]
    fn an_unfinished_regex_matches_nothing_and_reports_why() {
        let mut d = doc("foo (bar)");
        d.set_find_query(
            Some(FindQuery { text: "(".into(), regex: true, ..Default::default() }),
            0,
        );
        assert_eq!(d.find_match_count(), 0, "an unfinished pattern matches nothing");
        assert!(d.find_pattern_error().is_some(), "…and says why");
        // Editing while the pattern is broken must not panic or strand state.
        d.edit(vec![EditOp::insert(0, "x")]).unwrap();
        assert_eq!(d.find_match_count(), 0);
        // Finishing the pattern resumes matching, and clears the error.
        d.set_find_query(
            Some(FindQuery { text: r"\(bar\)".into(), regex: true, ..Default::default() }),
            0,
        );
        assert!(d.find_pattern_error().is_none());
        assert_eq!(d.find_match_count(), 1);
    }

    #[test]
    fn replace_all_without_a_match_commits_nothing() {
        let mut d = doc("foo");
        assert_eq!(d.replace_all("x", false), 0, "no query ⇒ no-op");
        d.set_find_query(Some(FindQuery { text: "zzz".into(), case_sensitive: false, ..Default::default() }), 0);
        assert_eq!(d.replace_all("x", false), 0, "no matches ⇒ no-op");
        assert_eq!(d.text(), "foo");
        assert!(!d.is_dirty(), "a no-op replace must not open an undo step");
        assert!(!d.undo());
    }

    #[test]
    fn replace_reuses_the_matcher_the_query_compiled() {
        // Fails-first: the replacement plan re-compiled the query's pattern on
        // every `replace_next` / `replace_all` — a regex compile per press —
        // beside the matcher `set_find_query` compiles once and every scan and
        // repair already reads. In every matcher flavor: the folding literal
        // (its `(?i)` escape), whole-word, and regex.
        use crate::find::MATCHER_COMPILES;
        let queries = [
            FindQuery { text: "foo".into(), ..Default::default() },
            FindQuery { text: "foo".into(), whole_word: true, ..Default::default() },
            FindQuery { text: "f(o)o".into(), regex: true, ..Default::default() },
        ];
        for q in queries {
            let mut d = doc("foo foo foo");
            d.set_find_query(Some(q.clone()), 0);
            let base = MATCHER_COMPILES.with(std::cell::Cell::get);
            assert_eq!(d.replace_next("x", false, 0), Some(0..3), "{q:?}: the first press navigates");
            assert_eq!(d.replace_next("x", false, 0), Some(2..5), "{q:?}: the second replaces");
            assert_eq!(d.replace_all("y", false), 2, "{q:?}");
            assert_eq!(d.text(), "x y y", "{q:?}");
            assert_eq!(
                MATCHER_COMPILES.with(std::cell::Cell::get) - base,
                0,
                "{q:?}: a replace compiled the pattern again"
            );
        }
    }

    #[test]
    fn caret_moves_seal_the_typing_group() {
        // A caret move, click, or box gesture closes the open typing run —
        // type → move → type undoes as TWO steps, not one.
        let mut d = doc("");
        d.type_char('f');
        d.type_char('o');
        d.move_carets(Motion::Left, false); // arrow-key boundary
        d.type_char('x'); // "fxo"
        assert!(d.undo());
        assert_eq!(d.text(), "fo", "undo reverts only the run typed after the move");

        // A mouse click (set_selections) is the same boundary…
        let mut c = doc("");
        c.type_char('a');
        c.type_char('b');
        c.set_selections(SelectionSet::new(0));
        c.type_char('z'); // "zab"
        assert!(c.undo());
        assert_eq!(c.text(), "ab", "the click sealed the run before it");

        // …and so is a column-box gesture (which seals WITHOUT reset_transient,
        // since it must keep the box anchor).
        let mut b = doc("one\ntwo");
        b.set_selections(SelectionSet::new(0));
        b.type_char('z'); // "zone\ntwo"
        b.column_drag((0, 2), (1, 2));
        b.type_char('q');
        assert!(b.undo());
        assert_eq!(b.text(), "zone\ntwo", "the box gesture sealed the run before it");
    }

    /// A line-duplication verb must drop auto-close provenance through the one
    /// owner (`clear_autoclose`), so its `AutoClosePair` decoration (which has
    /// `EmptyPolicy::Keep`, so the store never self-drops it) is removed with it
    /// rather than orphaned in the store with a lost id.
    #[test]
    fn line_duplication_drops_autoclose_provenance() {
        // Provenance lives in its own auto-close store.
        let ac_count = |d: &Document| d.autoclose_pair_count();
        let mut d = doc("x");
        d.move_carets(Motion::Right, false); // caret after 'x' (offset 1)
        d.type_char('('); // auto-close → "x()", provenance armed over the pair
        assert_eq!(d.text(), "x()");
        assert_eq!(ac_count(&d), 1, "typing '(' arms one AutoClosePair decoration");
        // Duplicate the line above: the caret stays inside the (one-line) pair,
        // so `validate_autoclose` keeps the provenance — and copy_line must clear
        // the decoration rather than leave the rebased one orphaned.
        d.copy_line(false);
        assert_eq!(d.text(), "x()\nx()");
        assert_eq!(
            ac_count(&d),
            0,
            "copy_line must clear the provenance decoration, not orphan it in the store",
        );
    }

    /// Provenance in its OWN store must be untouched by a document-scale
    /// diagnostic set living in the bulk `decorations` store: arm a pair, publish
    /// far diagnostics, type inside the pair — the pair survives, overtype still
    /// works, and the diagnostics ride on independently. The two stores stay
    /// fully decoupled.
    #[test]
    fn type_bracket_then_far_diagnostics_pair_survives() {
        use crate::{Diagnostic, Severity};
        let mut d = doc("hello\nworld\n");
        let end = d.text().len() as u32; // 12 — EOL of the empty final line
        d.set_selections(SelectionSet::new(end));
        d.type_char('('); // "hello\nworld\n()" — provenance armed, caret between ( )
        assert_eq!(d.autoclose_pair_count(), 1);
        // Diagnostics FAR from the pair (line 0), in the SEPARATE bulk store.
        d.set_diagnostics(
            d.revision(),
            vec![
                Diagnostic::new(0..1, Severity::Error, "e0"),
                Diagnostic::new(2..3, Severity::Warning, "w0"),
            ],
        );
        // A plain char inside the pair — the pair must survive (caret stays in it),
        // undisturbed by the diagnostics in the other store.
        d.type_char('x');
        assert!(d.text().ends_with("(x)"));
        assert_eq!(d.autoclose_pair_count(), 1, "far diagnostics don't disturb the pair");
        // The diagnostics still live in the bulk store, rebased past the edit.
        assert_eq!(d.diagnostics_in(0..u32::MAX).count(), 2, "the diagnostics ride on");
        // Overtype still works — provenance is intact and readable from its store.
        d.type_char(')');
        assert!(d.text().ends_with("(x)"), "overtype consumes the tracked close, no doubled )");
        assert_eq!(d.autoclose_pair_count(), 0, "overtype consumed the pair");
    }

    /// Oracle: the own auto-close store must MOVE identically to keeping the pairs
    /// in the unified `decorations` store (per-range independence makes the split
    /// byte-identical). A shadow set of `AutoClosePair` decorations is planted in
    /// the bulk store (interleaved with diagnostics, a realistic mixed store) at
    /// the same ranges; then plain chars are typed *inside* every pair (carets
    /// stay in, so `validate_autoclose` reaps nothing), and after each commit the
    /// own store's ranges must equal the bulk store's `AutoClosePair` ranges —
    /// through BOTH the multi-edit naive mover and the single-edit windowed mover.
    /// A wiring slip (a missed rebase site, a wrong patch, a bias drift) breaks
    /// it.
    #[test]
    fn autoclose_store_moves_identically_to_unified_store() {
        use crate::decorations::{DecorationKind, Stickiness};
        use crate::{Diagnostic, Severity};
        // Run one scenario: arm a pair at each caret, mirror the pairs into the
        // bulk store, then type `steps` plain chars at all carets, asserting the two
        // stores stay range-identical after every commit.
        let scenario = |text: &str, carets: &[u32], steps: usize| {
            let mut d = doc(text);
            d.set_selections(SelectionSet::from_offsets(carets));
            d.type_char('('); // arm one one-line pair per caret
            let pairs = d.autoclose_ranges();
            assert_eq!(pairs.len(), carets.len(), "one pair per caret armed");
            // Shadow the pairs into the bulk store (the "unified" reference) and
            // interleave a diagnostic so the mover sees a realistic mixed store.
            for r in &pairs {
                d.decorations_mut().add_decoration(
                    r.clone(),
                    DecorationKind::AutoClosePair,
                    Stickiness::AlwaysGrows,
                );
            }
            d.set_diagnostics(d.revision(), vec![Diagnostic::new(0..1, Severity::Warning, "d")]);
            let unified = |d: &Document| -> Vec<Range<u32>> {
                d.decorations()
                    .iter()
                    .filter(|r| matches!(r.kind, DecorationKind::AutoClosePair))
                    .map(|r| r.range.clone())
                    .collect()
            };
            assert_eq!(d.autoclose_ranges(), unified(&d), "shadow starts equal");
            for step in 0..steps {
                d.type_char('z'); // grows every pair; carets stay inside
                assert_eq!(
                    d.autoclose_ranges(),
                    unified(&d),
                    "own store diverged from the unified store at step {step}",
                );
            }
        };
        // Multi-caret typing keeps all pairs occupied → the multi-edit naive mover.
        scenario("aa\nbb\ncc\ndd\nee\n", &[2, 5, 8, 11, 14], 8);
        // Single caret → the single-edit windowed mover (one pair, kept occupied).
        scenario("solo line here\n", &[14], 10);
    }

    #[test]
    fn different_classes_do_not_merge() {
        let mut d = doc("ab");
        d.edit_grouped(vec![EditOp::insert(2, "c")], typ(OpClass::Type)).unwrap(); // "abc"
        d.edit_grouped(vec![EditOp::delete(0..1)], typ(OpClass::Delete)).unwrap(); // "bc"
        assert_eq!(d.text(), "bc");
        assert!(d.undo()); // undo the delete only
        assert_eq!(d.text(), "abc");
        assert!(d.undo()); // undo the type
        assert_eq!(d.text(), "ab");
    }

    #[test]
    fn dirty_tracking_survives_undo_and_save() {
        let mut d = doc("x");
        assert!(!d.is_dirty());
        d.edit(vec![EditOp::insert(1, "y")]).unwrap(); // "xy"
        assert!(d.is_dirty());
        d.undo(); // back to "x" == the saved (initial) state
        assert!(!d.is_dirty(), "undo back to the save point reads clean");
        d.redo(); // "xy"
        assert!(d.is_dirty());
        d.mark_saved();
        assert!(!d.is_dirty());
    }

    #[test]
    fn ctrl_d_selects_word_then_adds_occurrences_then_stops() {
        let mut d = doc("foo bar foo baz foo"); // "foo" at 0, 8, 16
        // First press: the caret at 0 expands to the surrounding word.
        d.add_next_occurrence();
        assert_eq!(d.selections().len(), 1);
        let s = d.selections().newest();
        assert_eq!((s.start(), s.end()), (0, 3));
        // Next presses add each following "foo" as a new (newest) selection.
        d.add_next_occurrence();
        assert_eq!(d.selections().len(), 2);
        assert_eq!((d.selections().newest().start(), d.selections().newest().end()), (8, 11));
        d.add_next_occurrence();
        assert_eq!(d.selections().len(), 3);
        assert_eq!(d.selections().newest().start(), 16);
        // All three found; the next press wraps, finds only taken ranges → no-op.
        d.add_next_occurrence();
        assert_eq!(d.selections().len(), 3, "no untaken occurrence remains");
    }

    #[test]
    fn windowed_next_occurrence_equals_whole_text_scan() {
        // The windowed `scan_from` (Ctrl+D's engine, never materializes the
        // rope) must match `find_next_occurrence` (the whole-text `match_indices`
        // oracle) for non-self-overlapping needles, across random texts, seeds,
        // and taken sets — including the wrap path.
        let mut state: u64 = 0x243F_6A88_85A3_08D3;
        let mut next = |n: u32| {
            state = state.wrapping_mul(6364136223846793005).wrapping_add(1442695040888963407);
            ((state >> 33) as u32) % n
        };
        // Alphabet {a,b,c,space}; needles below have no proper prefix == suffix.
        let needles = ["ab", "ba", "abc", "cab"];
        for _ in 0..300 {
            let n = 12 + next(60); // text length
            let text: String = (0..n)
                .map(|_| b"abc "[next(4) as usize] as char)
                .collect();
            let d = doc(&text);
            let needle = needles[next(needles.len() as u32) as usize];
            let nlen = needle.len() as u32;
            // A random subset of the actual occurrences becomes "taken".
            let all: Vec<(u32, u32)> = text
                .match_indices(needle)
                .map(|(i, _)| (i as u32, i as u32 + nlen))
                .collect();
            let taken: Vec<(u32, u32)> = all.iter().copied().filter(|_| next(2) == 0).collect();
            let is_taken = |s: u32| taken.iter().any(|&(st, en)| st == s && en == s + nlen);
            let from = next(n + 1);
            let got = scan_from(d.buffer(), needle, from, d.buffer().len(), &is_taken)
                .or_else(|| scan_from(d.buffer(), needle, 0, from, &is_taken));
            let want = find_next_occurrence(&text, needle, from, &taken);
            assert_eq!(got, want, "text {text:?} needle {needle:?} from {from} taken {taken:?}");
        }
    }

    #[test]
    fn column_select_grows_widens_and_shrinks_back() {
        use crate::movement::ColumnDir::{Down, Left, Right, Up};
        // Three aligned rows; caret at (0, 1).
        let mut d = doc("abcd\nabcd\nabcd");
        d.set_selections(SelectionSet::new(1));
        // Down twice → a caret per row at column 1 (empty box, 3 rows).
        d.column_select(Down);
        d.column_select(Down);
        assert_eq!(d.selections().len(), 3);
        assert!(d.selections().all().iter().all(|s| s.is_empty() && s.start() % 5 == 1));
        // Right twice → each row selects columns 1..3.
        d.column_select(Right);
        d.column_select(Right);
        assert_eq!(d.selections().len(), 3);
        assert!(d.selections().all().iter().all(|s| s.end() - s.start() == 2));
        // Up twice → the box shrinks back to the anchor row only.
        d.column_select(Up);
        d.column_select(Up);
        assert_eq!(d.selections().len(), 1, "shrinks back toward the anchor");
        // Left twice → back to a bare caret at the anchor.
        d.column_select(Left);
        d.column_select(Left);
        assert_eq!(d.selections().len(), 1);
        assert!(d.selections().newest().is_empty());
    }

    #[test]
    fn column_select_clamps_each_row_to_its_length() {
        use crate::movement::ColumnDir::{Down, Right};
        // A long row over a short one; a wide box clamps the short row.
        let mut d = doc("abcdef\nab"); // line 0 len 6, line 1 len 2
        d.set_selections(SelectionSet::new(0)); // caret at (0,0)
        d.column_select(Down); // box rows 0..1, col 0..0
        for _ in 0..4 {
            d.column_select(Right); // active col → 4
        }
        let rows = d.selections().all();
        assert_eq!(rows.len(), 2);
        assert_eq!((rows[0].start(), rows[0].end()), (0, 4)); // "abcd" on line 0
        // Line 1 ("ab", offsets 7..9) clamps to its end: 7..9.
        assert_eq!((rows[1].start(), rows[1].end()), (7, 9));
    }

    #[test]
    fn column_drag_builds_a_box_from_two_corners() {
        let mut d = doc("abcd\nabcd\nabcd");
        d.column_drag((0, 1), (2, 3)); // 3 rows, cols 1..3
        assert_eq!(d.selections().len(), 3);
        assert!(d.selections().all().iter().all(|s| s.end() - s.start() == 2));
        // Virtual columns past a short line clamp per row.
        let mut r = doc("abcdef\nab"); // line0 len 6, line1 len 2
        r.column_drag((0, 0), (1, 5)); // active col 5 > line1 len
        let rows = r.selections().all();
        assert_eq!((rows[0].start(), rows[0].end()), (0, 5)); // line0 → 5
        assert_eq!((rows[1].start(), rows[1].end()), (7, 9)); // line1 clamps to its end
    }

    /// Regression (fails-first): a host corner row past the document was kept,
    /// so the box spanned (and allocated) one selection per *requested* row —
    /// `u32::MAX` overflowed the row count — and kept that phantom anchor for
    /// the keyboard to step from. Corner rows now clamp to the last row; cells
    /// stay virtual, and stepping right from the largest one saturates.
    #[test]
    fn column_drag_clamps_host_corners() {
        let mut d = doc("abcd\nabcd\nabcd");
        d.column_drag((0, 1), (u32::MAX, 3));
        let spans: Vec<(u32, u32)> = d.selections().all().iter().map(|s| (s.start(), s.end())).collect();
        assert_eq!(spans, [(1, 3), (6, 8), (11, 13)], "one row per REAL row, the last one active");
        d.column_select(ColumnDir::Up); // steps from the clamped last row
        assert_eq!(d.selections().len(), 2);
        d.column_drag((0, u32::MAX), (0, u32::MAX));
        d.column_select(ColumnDir::Right); // must not overflow the virtual cell
        assert_eq!(heads(&d), [4]);
    }

    #[test]
    fn column_box_is_display_cells_across_tabs() {
        // Row 0 leads with a tab (4 cells); row 1 is plain. A box over cells
        // 4..6 must select the same VISUAL slice — the two chars after the tab
        // — not reuse the cells as byte columns (which lands at row 0's EOL).
        let mut d = doc("\tabcd\nwxyz"); // row 1 starts at offset 6
        d.column_drag((0, 4), (1, 6));
        let rows = d.selections().all();
        assert_eq!(rows.len(), 2);
        assert_eq!((rows[0].start(), rows[0].end()), (1, 3), "cells 4..6 are bytes 1..3 after the tab");
        assert_eq!((rows[1].start(), rows[1].end()), (10, 10), "row 1 ends at cell 4; both corners clamp");
    }

    #[test]
    fn column_box_resolves_through_a_collapsed_inline_fold() {
        // `f([a, b]) x` with the [..] pair collapsed: display cells right of
        // the chip sit one left of their byte columns. A box edge at cell 9
        // must land on `x` (byte 10), not the byte-9 space.
        let mut d = doc("f([a, b]) x");
        assert!(d.toggle_fold_opener(2)); // the `[`
        d.column_drag((0, 6), (0, 9));
        let s = d.selections().newest();
        assert_eq!((s.start(), s.end()), (7, 10), "cells 6..9 are `]) `, one left of the byte columns");
    }

    #[test]
    fn column_box_spans_visible_rows_only() {
        // A box dragged across a collapsed block fold selects only what is on
        // screen: the rows hidden inside the fold get no selection.
        let mut d = doc("aa\nfn {\nbb\ncc\n}\ndd");
        assert!(d.toggle_fold_opener(6)); // the `{` — hides rows 2..=4
        d.column_drag((0, 0), (5, 1));
        let rows: Vec<u32> =
            d.selections().all().iter().map(|s| d.buffer().offset_to_point(s.start()).row).collect();
        assert_eq!(rows, vec![0, 1, 5], "one selection per VISIBLE row");
    }

    #[test]
    fn column_select_steps_display_rows_over_a_fold() {
        use crate::movement::ColumnDir::Up;
        // Caret below a collapsed fold; growing the box upward hops the hidden
        // rows in ONE step — corners walk display rows, not buffer rows.
        let mut d = doc("aa\nfn {\nbb\ncc\n}\ndd");
        assert!(d.toggle_fold_opener(6));
        d.set_selections(SelectionSet::new(16)); // caret at (5, 0) — on "dd"
        d.column_select(Up);
        let rows: Vec<u32> =
            d.selections().all().iter().map(|s| d.buffer().offset_to_point(s.start()).row).collect();
        assert_eq!(rows, vec![1, 5], "the step lands on the fold header, skipping hidden rows");
    }

    #[test]
    fn column_select_anchors_at_the_display_cell_after_a_tab() {
        use crate::movement::ColumnDir::Down;
        // A caret just after row 0's leading tab renders at cell 4; the box
        // column is that CELL, so on the plain row below it lands at byte 4
        // (visually aligned), not byte 1.
        let mut d = doc("\tab\nwwwwww"); // row 1 starts at offset 4
        d.set_selections(SelectionSet::new(1)); // (0, 1): just after the tab
        d.column_select(Down);
        assert_eq!(d.selections().newest().head(), 8, "cell 4 on row 1 is byte 4 (offset 8)");
    }

    #[test]
    fn any_action_exits_column_mode() {
        use crate::movement::ColumnDir::Down;
        let mut d = doc("abcd\nabcd\nabcd");
        d.set_selections(SelectionSet::new(0));
        d.column_select(Down); // 2-row box
        assert_eq!(d.selections().len(), 2);
        d.move_carets(Motion::Right, false); // a plain move exits the mode…
        // …so the next column_select re-anchors from the current caret, not the
        // stale box (a fresh 2-row box, not a 3-row one).
        d.column_select(Down);
        assert_eq!(d.selections().len(), 2, "re-anchored, not continuing the old box");
    }

    fn range(d: &Document) -> (u32, u32) {
        (d.selections().newest().start(), d.selections().newest().end())
    }

    #[test]
    fn drag_select_word_granularity_keeps_the_origin_word() {
        let mut d = doc("foo bar baz\nqux"); // foo 0..3, bar 4..7, baz 8..11
        // Double-click "bar" (head == origin) selects just the word.
        d.drag_select(Granularity::Word, 5, 5);
        assert_eq!(range(&d), (4, 7));
        // Drag right into "baz": whole words, "bar".."baz".
        d.drag_select(Granularity::Word, 5, 9);
        assert_eq!(range(&d), (4, 11));
        // Drag back-left into "foo": origin word "bar" stays fully selected.
        d.drag_select(Granularity::Word, 5, 1);
        assert_eq!(range(&d), (0, 7));
        // A double-click surrounded by whitespace is a bare caret.
        let mut w = doc("a  b");
        w.drag_select(Granularity::Word, 2, 2);
        assert!(w.selections().newest().is_empty());
    }

    #[test]
    fn drag_select_line_and_char_granularity() {
        let mut d = doc("aa\nbb\ncc"); // line0 0..2/\n2, line1 3..5/\n5, line2 6..8
        d.drag_select(Granularity::Line, 1, 1); // triple-click line 0 → incl \n
        assert_eq!(range(&d), (0, 3));
        d.drag_select(Granularity::Line, 1, 4); // drag into line 1
        assert_eq!(range(&d), (0, 6));
        d.drag_select(Granularity::Line, 7, 7); // last line → to its end
        assert_eq!(range(&d), (6, 8));
        d.drag_select(Granularity::Char, 2, 8); // char = a plain range
        assert_eq!(range(&d), (2, 8));
    }

    /// Regression (fails-first): drag-select took both host offsets unclipped
    /// — a Word drag from inside a char panicked in the word scan, and a Char
    /// drag stored mid-char / past-end endpoints. Each offset now clips like a
    /// caret: past the end → the end, inside a char → its start.
    #[test]
    fn drag_select_clips_host_offsets() {
        let mut d = doc("héllo wörld"); // é 1..3, ö 8..10, len 13
        d.drag_select(Granularity::Word, 2, 2); // inside 'é'
        assert_eq!(range(&d), (0, 6), "the word around the snapped origin");
        d.drag_select(Granularity::Char, 2, 9); // inside 'é' → inside 'ö'
        assert_eq!(range(&d), (1, 8));
        d.drag_select(Granularity::Char, 1000, 2);
        assert_eq!((range(&d), d.selections().newest().head()), ((1, 13), 1));
        d.drag_select(Granularity::Line, 1000, 1000);
        assert_eq!(range(&d), (0, 13));
        d.move_carets(Motion::WordLeft, true); // motions run from valid endpoints
    }

    fn head_row(d: &Document) -> u32 {
        d.buffer().offset_to_point(d.selections().newest().head()).row
    }

    #[test]
    fn move_line_swaps_with_neighbour_and_rides() {
        let mut d = doc("aaa\nbbb\nccc");
        d.set_selections(SelectionSet::new(4)); // "bbb" (row 1)
        d.move_line(true); // down
        assert_eq!(d.text(), "aaa\nccc\nbbb");
        assert_eq!(head_row(&d), 2); // the caret rode down with the line
        d.move_line(false); // up → back
        assert_eq!(d.text(), "aaa\nbbb\nccc");
        assert_eq!(head_row(&d), 1);
    }

    #[test]
    fn move_line_is_a_noop_at_the_edges() {
        let mut d = doc("aaa\nbbb");
        d.set_selections(SelectionSet::new(0));
        d.move_line(false); // up at the top
        assert_eq!(d.text(), "aaa\nbbb");
        d.set_selections(SelectionSet::new(4)); // last content line
        d.move_line(true); // down at the bottom
        assert_eq!(d.text(), "aaa\nbbb");
    }

    #[test]
    fn move_line_down_respects_the_trailing_empty_line() {
        let mut d = doc("aaa\nbbb\n"); // trailing \n → an empty final row
        d.set_selections(SelectionSet::new(4)); // "bbb", the last *content* line
        d.move_line(true); // must not move into/past the empty final line
        assert_eq!(d.text(), "aaa\nbbb\n");
    }

    #[test]
    fn copy_line_duplicates_below_and_above() {
        let mut d = doc("aaa\nbbb");
        d.set_selections(SelectionSet::new(0));
        d.copy_line(true); // down → caret on the lower copy
        assert_eq!(d.text(), "aaa\naaa\nbbb");
        assert_eq!(head_row(&d), 1);
        let mut d2 = doc("aaa\nbbb");
        d2.set_selections(SelectionSet::new(0));
        d2.copy_line(false); // up → caret on the upper copy
        assert_eq!(d2.text(), "aaa\naaa\nbbb");
        assert_eq!(head_row(&d2), 0);
    }

    #[test]
    fn copy_line_duplicates_the_final_line() {
        let mut d = doc("aaa\nbbb"); // no trailing \n
        d.set_selections(SelectionSet::new(4)); // "bbb"
        d.copy_line(true);
        assert_eq!(d.text(), "aaa\nbbb\nbbb");
        assert_eq!(head_row(&d), 2);
    }

    #[test]
    fn move_line_excludes_the_row_a_whole_line_selection_ends_at() {
        // Fails-first: a triple-click selection ends at column 0 of the NEXT
        // row, and move_line counted that row as part of the block — so "b" and
        // "c" moved together past "d".
        let mut d = doc("a\nb\nc\nd\n"); // a 0, b 2, c 4, d 6
        d.drag_select(Granularity::Line, 2, 2); // triple-click "b" → (2, 4)
        assert_eq!(spans(&d), vec![(2, 4)]);
        d.move_line(true);
        assert_eq!(d.text(), "a\nc\nb\nd\n");
        assert_eq!(spans(&d), vec![(4, 6)], "the whole-line selection rides \"b\" down");
        d.move_line(false);
        assert_eq!(d.text(), "a\nb\nc\nd\n");
        assert_eq!(spans(&d), vec![(2, 4)]);
    }

    #[test]
    fn copy_line_excludes_the_row_a_whole_line_selection_ends_at() {
        // Fails-first: the same off-by-one-row block duplicated "b\nc".
        let mut d = doc("a\nb\nc\nd\n");
        d.drag_select(Granularity::Line, 2, 2); // triple-click "b" → (2, 4)
        d.copy_line(true); // below → the selection lands on the lower copy
        assert_eq!(d.text(), "a\nb\nb\nc\nd\n");
        assert_eq!(spans(&d), vec![(4, 6)]);
        let mut u = doc("a\nb\nc\nd\n");
        u.drag_select(Granularity::Line, 2, 2);
        u.copy_line(false); // above → the selection stays on the upper copy
        assert_eq!(u.text(), "a\nb\nb\nc\nd\n");
        assert_eq!(spans(&u), vec![(2, 4)]);
    }

    #[test]
    fn move_line_moves_every_caret_line_and_the_selections_ride() {
        // Fails-first: only the newest caret's line moved, and the set
        // collapsed to that one selection.
        let mut d = doc("l0\nl1\nl2\nl3\nl4\n"); // row r starts at 3r
        // A caret inside "l1" (the newest) and a REVERSED selection over "l3".
        d.set_selections(SelectionSet::from_ranges(&[(4, 4), (11, 9)], 0));
        d.move_line(true);
        assert_eq!(d.text(), "l0\nl2\nl1\nl4\nl3\n");
        assert_eq!(spans(&d), vec![(7, 7), (14, 12)], "both ride down a row, direction kept");
        assert_eq!(d.selections().newest().head(), 7, "the newest selection stays the newest");
        d.move_line(false);
        assert_eq!(d.text(), "l0\nl1\nl2\nl3\nl4\n");
        assert_eq!(spans(&d), vec![(4, 4), (11, 9)]);
    }

    #[test]
    fn move_line_merges_overlapping_and_adjacent_blocks() {
        // Carets on consecutive rows: one block, else both would claim the row
        // between them as their swap neighbour.
        let mut d = doc("l0\nl1\nl2\nl3\nl4\n"); // row r starts at 3r
        d.set_selections(SelectionSet::from_offsets(&[4, 7])); // rows 1 and 2
        d.move_line(true);
        assert_eq!(d.text(), "l0\nl3\nl1\nl2\nl4\n");
        assert_eq!(spans(&d), vec![(7, 7), (10, 10)]);
        // A selection over rows 1–2 and a caret later on row 2: the blocks share
        // row 2 and move as one.
        let mut o = doc("l0\nl1\nl2\nl3\nl4\n");
        o.set_selections(SelectionSet::from_ranges(&[(4, 7), (8, 8)], 1));
        o.move_line(false);
        assert_eq!(o.text(), "l1\nl2\nl0\nl3\nl4\n");
        assert_eq!(spans(&o), vec![(1, 4), (5, 5)]);
    }

    #[test]
    fn move_line_leaves_an_edge_block_and_moves_the_rest() {
        let mut d = doc("l0\nl1\nl2\nl3");
        d.set_selections(SelectionSet::from_offsets(&[1, 7])); // rows 0 and 2
        d.move_line(false); // row 0 is at the top; row 2 still moves up
        assert_eq!(d.text(), "l0\nl2\nl1\nl3");
        assert_eq!(spans(&d), vec![(1, 1), (4, 4)]);
        // Moving onto the final line (no trailing `\n`): a whole-line selection's
        // end, past the block's `\n`, clamps to the buffer end.
        let mut w = doc("a\nb\nc");
        w.drag_select(Granularity::Line, 2, 2); // "b\n" → (2, 4)
        w.move_line(true);
        assert_eq!(w.text(), "a\nc\nb");
        assert_eq!(spans(&w), vec![(4, 5)]);
    }

    #[test]
    fn copy_line_copies_every_caret_line_and_the_selections_land_on_the_copies() {
        // Fails-first: only the newest caret's line was copied, and the set
        // collapsed to that one selection.
        let src = "l0\nl1\nl2\nl3\nl4\n"; // row r starts at 3r
        let both = "l0\nl1\nl1\nl2\nl3\nl3\nl4\n";
        let mut d = doc(src);
        // A caret inside "l1" (the newest) and a REVERSED selection over "l3".
        d.set_selections(SelectionSet::from_ranges(&[(4, 4), (11, 9)], 0));
        d.copy_line(true); // below → onto the lower copies
        assert_eq!(d.text(), both);
        assert_eq!(spans(&d), vec![(7, 7), (17, 15)], "both land on their copies, direction kept");
        assert_eq!(d.selections().newest().head(), 7, "the newest selection stays the newest");
        let mut u = doc(src);
        u.set_selections(SelectionSet::from_ranges(&[(4, 4), (11, 9)], 0));
        u.copy_line(false); // above → onto the upper copies
        assert_eq!(u.text(), both);
        assert_eq!(spans(&u), vec![(4, 4), (14, 12)]);
    }

    #[test]
    fn copy_line_merges_blocks_that_share_a_row() {
        // A selection over rows 1–2 and a caret later on row 2: one block, copied
        // once (not row 2 twice).
        let mut o = doc("l0\nl1\nl2\nl3\nl4\n");
        o.set_selections(SelectionSet::from_ranges(&[(4, 7), (8, 8)], 1));
        o.copy_line(true);
        assert_eq!(o.text(), "l0\nl1\nl2\nl1\nl2\nl3\nl4\n");
        assert_eq!(spans(&o), vec![(10, 13), (14, 14)]);
        // Carets on consecutive rows share no row: each line is copied below
        // itself (VS Code), and each caret lands on its own copy.
        let mut a = doc("l0\nl1\nl2\nl3\nl4\n");
        a.set_selections(SelectionSet::from_offsets(&[4, 7])); // rows 1 and 2
        a.copy_line(true);
        assert_eq!(a.text(), "l0\nl1\nl1\nl2\nl2\nl3\nl4\n");
        assert_eq!(spans(&a), vec![(7, 7), (13, 13)]);
    }

    #[test]
    fn a_multi_block_move_or_copy_undoes_in_one_step() {
        let src = "l0\nl1\nl2\nl3\nl4\n";
        let before = vec![(4, 4), (11, 9)];
        for copy in [false, true] {
            let mut d = doc(src);
            d.set_selections(SelectionSet::from_ranges(&[(4, 4), (11, 9)], 0));
            let depth = d.undo_depth();
            if copy {
                d.copy_line(true);
            } else {
                d.move_line(true);
            }
            assert_eq!(d.undo_depth(), depth + 1, "copy={copy}: both blocks, one unit");
            let (after_text, after) = (d.text().into_owned(), spans(&d));
            assert!(d.undo());
            assert_eq!(d.text(), src, "copy={copy}: one undo restores the text");
            assert_eq!(spans(&d), before, "copy={copy}: …and every selection");
            assert!(d.redo());
            assert_eq!((d.text().into_owned(), spans(&d)), (after_text, after), "copy={copy}");
        }
    }

    #[test]
    fn move_and_copy_line_carry_every_selection_with_its_text() {
        // Seeded property walk: small documents (multibyte and empty lines, with
        // and without a trailing `\n`), random multi-selections, all four
        // directions. Read through the public API only: a move permutes the
        // lines and a copy only adds some; every selection (by id) still selects
        // the same text — less the `\n` a whole-line selection drops when its
        // block becomes the final line — in the same direction; a caret keeps
        // its line and column; one undo restores the text and every selection.
        let mut rng = 0x5E1E_C7ED_0007_u64;
        let mut next = move |m: u64| {
            rng ^= rng << 13;
            rng ^= rng >> 7;
            rng ^= rng << 17;
            rng % m
        };
        const LINES: &[&str] = &["", "a", "bc", "é", "x y", "  {"];
        let sorted_lines = |t: &str| {
            let mut v: Vec<String> = t.split('\n').map(str::to_owned).collect();
            v.sort();
            v
        };
        // The line holding `off`, and `off`'s column on it.
        let line_at = |t: &str, off: u32| {
            let start = t[..off as usize].rfind('\n').map_or(0, |i| i + 1);
            let end = t[start..].find('\n').map_or(t.len(), |i| start + i);
            (t[start..end].to_owned(), off as usize - start)
        };
        let mut checked = 0;
        for step in 0..3_000 {
            let n = 1 + next(6);
            let mut src: String =
                (0..n).map(|_| LINES[next(LINES.len() as u64) as usize]).collect::<Vec<_>>().join("\n");
            if next(2) == 0 {
                src.push('\n');
            }
            let mut d = doc(&src);
            let len = u64::from(d.buffer().len()) + 1;
            let k = 1 + next(3) as usize;
            let raw: Vec<(u32, u32)> = (0..k)
                .map(|_| {
                    let a = next(len) as u32;
                    (a, if next(2) == 0 { a } else { next(len) as u32 })
                })
                .collect();
            let clip = |o: u32| d.buffer().clip_offset(o, Bias::Left);
            let ranges: Vec<(u32, u32)> = raw.iter().map(|&(a, b)| (clip(a), clip(b))).collect();
            d.set_selections(SelectionSet::from_ranges(&ranges, next(k as u64) as usize));
            let before = d.selections().all().to_vec();
            let depth = d.undo_depth();
            let (copy, down) = (next(2) == 0, next(2) == 0);
            if copy {
                d.copy_line(down);
            } else {
                d.move_line(down);
            }
            let text = d.text().into_owned();
            let ctx = format!("step {step}: {src:?} {before:?} copy={copy} down={down} → {text:?}");
            if copy {
                let mut added = sorted_lines(&text);
                for line in sorted_lines(&src) {
                    let i = added.iter().position(|l| *l == line).unwrap_or_else(|| panic!("{ctx}"));
                    added.remove(i);
                }
                assert!(!added.is_empty(), "{ctx}: a copy adds lines");
            } else {
                assert_eq!(sorted_lines(&text), sorted_lines(&src), "{ctx}: a move permutes lines");
            }
            // A carried selection can land touching another (a whole-line
            // selection's end meeting a caret that stayed put) and merge under the
            // set's own rule; only a merge-free step pairs every selection by id.
            let carried = d.selections().len() == before.len();
            for s in before.iter().filter(|_| carried) {
                let t = d.selections().all().iter().find(|t| t.id == s.id).expect("ids are kept");
                checked += 1;
                let was = &src[s.start() as usize..s.end() as usize];
                let now = &text[t.start() as usize..t.end() as usize];
                let dropped_nl = was.strip_suffix('\n') == Some(now) && t.end() as usize == text.len();
                assert!(now == was || dropped_nl, "{ctx}: {s:?} → {t:?} selects {now:?}, not {was:?}");
                if !t.is_empty() {
                    assert_eq!(t.head() < t.tail(), s.head() < s.tail(), "{ctx}: direction kept");
                }
                if s.is_empty() {
                    assert_eq!(line_at(&text, t.head()), line_at(&src, s.head()), "{ctx}: caret rides");
                }
            }
            if d.undo_depth() > depth {
                assert!(d.undo());
                assert_eq!(d.text(), src, "{ctx}: one undo restores the text");
                assert_eq!(d.selections().all(), &before[..], "{ctx}: …and the selections");
            } else {
                assert_eq!(text, src, "{ctx}: no unit, no change");
            }
        }
        assert!(checked > 3_000, "the walk checks enough selections ({checked})");
    }

    #[test]
    fn add_caret_adds_a_second_cursor() {
        let mut d = doc("abcdef");
        assert_eq!(d.selections().len(), 1);
        d.add_caret(3);
        assert_eq!(d.selections().len(), 2);
    }

    fn heads(d: &Document) -> Vec<u32> {
        d.selections().all().iter().map(|s| s.head()).collect()
    }

    /// Regression (fails-first): `set_selections` documented clamping but
    /// installed the set as-is, so a host caret at byte 1 of `"é"` (inside the
    /// 2-byte char) reached the motion layer, whose char read sliced the rope
    /// mid-char and panicked. It now snaps to the char's start.
    #[test]
    fn set_selections_snaps_a_mid_char_caret_so_motion_cannot_panic() {
        let mut d = doc("é");
        d.set_selections(SelectionSet::new(1));
        assert_eq!(heads(&d), [0], "a caret inside a char snaps Left, to its start");
        d.move_carets(Motion::Right, false);
        assert_eq!(heads(&d), [2]);
    }

    /// Regression (fails-first): an out-of-range caret was kept as-is, so it
    /// sat past the document end and motions stepped from there (Left from
    /// 1000 in `"abc"` gave 999). It now clamps to the end.
    #[test]
    fn set_selections_clamps_an_out_of_range_caret() {
        let mut d = doc("abc");
        d.set_selections(SelectionSet::new(1000));
        assert_eq!(heads(&d), [3]);
        d.move_carets(Motion::Left, false);
        assert_eq!(heads(&d), [2]);
    }

    /// A ranged host selection snaps OUTWARD (it never drops part of a char it
    /// covers) and keeps its direction; carets the clamp lands on one offset
    /// merge into one.
    #[test]
    fn set_selections_snaps_ranges_outward_and_merges_clamped_carets() {
        let mut d = doc("aéb"); // a 0, é 1..3, b 3
        d.set_selections(SelectionSet::from_ranges(&[(2, 0)], 0)); // reversed, ends mid-'é'
        let s = *d.selections().newest();
        assert_eq!((s.start(), s.end(), s.head()), (0, 3, 0), "grows over the whole 'é', head kept");
        d.set_selections(SelectionSet::from_offsets(&[1, 50, 99]));
        assert_eq!(heads(&d), [1, 4], "the two past-end carets merge at the end");
    }

    /// Regression (fails-first): Alt+Click's `add_caret` took a host offset
    /// unclipped, so a mid-char caret panicked the next motion.
    #[test]
    fn add_caret_clips_a_host_offset() {
        let mut d = doc("é\né");
        d.add_caret(1); // inside the first 'é' → its start, merging with the caret at 0
        d.add_caret(4); // inside the second 'é' (3..5) → 3
        d.add_caret(1000); // past the end → 5
        assert_eq!(heads(&d), [0, 3, 5]);
        d.move_carets(Motion::Right, false);
        assert_eq!(heads(&d), [2, 5]);
    }

    /// Seeded walk over every host-position entry point — `set_selections`,
    /// `add_caret`, `drag_select`, `column_drag`, `set_diagnostics` — fed raw
    /// offsets that land mid-char, past the end, and at `u32::MAX`, each
    /// followed by a random motion. After every step each selection endpoint
    /// and diagnostic span must sit on a char boundary within the text, judged
    /// independently by `str::is_char_boundary` on the materialized text (not
    /// by the clip under test). Any unclipped entry point panics in the motion
    /// or fails the check.
    #[test]
    fn host_positions_never_leave_the_char_grid() {
        let text = "aé🦀b\n\t日本語 x\n\n🦀🦀 é\nzz";
        let mut d = doc(text);
        let len = d.buffer().len();
        let mut state = 0x5EED_2002_u64; // deterministic LCG
        let mut rand = move |bound: u64| {
            state = state.wrapping_mul(6364136223846793005).wrapping_add(1442695040888963407);
            ((state >> 33) % bound.max(1)) as u32
        };
        // Mostly in or just past the text (so most land inside a multibyte char
        // somewhere), occasionally the extreme.
        let mut raw = move || if rand(16) == 0 { u32::MAX } else { rand(u64::from(len) + 8) };
        let motions = [
            Motion::Left, Motion::Right, Motion::Up, Motion::Down, Motion::WordLeft, Motion::WordRight,
            Motion::LineStart, Motion::LineEnd, Motion::PageUp(2), Motion::PageDown(2),
        ];
        let assert_on_grid = |d: &Document, step: usize, what: &str| {
            for s in d.selections().all() {
                for off in [s.start(), s.end()] {
                    assert!(text.is_char_boundary(off as usize), "step {step} ({what}): selection end {off}");
                }
            }
            for (span, ..) in d.diagnostics_in(0..u32::MAX) {
                for off in [span.start, span.end] {
                    assert!(text.is_char_boundary(off as usize), "step {step} ({what}): diagnostic end {off}");
                }
            }
        };
        let mut mid_char_inputs = 0;
        for step in 0..2000 {
            let (a, b) = (raw(), raw());
            mid_char_inputs += usize::from(!text.is_char_boundary(a as usize) && (a as usize) < text.len());
            let what = match step % 6 {
                0 => {
                    d.set_selections(SelectionSet::from_ranges(&[(a, b), (b, raw())], 0));
                    "set_selections"
                }
                1 => {
                    d.add_caret(a);
                    "add_caret"
                }
                2 => {
                    let g = [Granularity::Char, Granularity::Word, Granularity::Line][step % 3];
                    d.drag_select(g, a, b);
                    "drag_select"
                }
                3 => {
                    // Rows past the document and cells past every line.
                    d.column_drag((a % 9, b), (b % 9, a));
                    "column_drag"
                }
                4 => {
                    let rev = d.revision();
                    let diags = vec![
                        Diagnostic::new(a..b, Severity::Error, "x"),
                        Diagnostic::new(b..b, Severity::Warning, "y"),
                    ];
                    assert_eq!(d.set_diagnostics(rev, diags), DiagnosticsOutcome::Applied { count: 2 });
                    "set_diagnostics"
                }
                _ => {
                    d.set_selections(SelectionSet::from_offsets(&[a, b]));
                    "set_selections (carets)"
                }
            };
            assert_on_grid(&d, step, what);
            d.move_carets(motions[step % motions.len()], step % 4 == 0);
            assert_on_grid(&d, step, "the motion after it");
        }
        // Keep the walk honest: it must actually have fed mid-char offsets.
        assert!(mid_char_inputs >= 200, "only {mid_char_inputs} mid-char inputs");
    }

    #[test]
    fn collapse_returns_to_the_primary_caret() {
        let mut d = doc("foo foo foo");
        d.add_next_occurrence(); // select "foo"
        d.add_next_occurrence(); // add the next
        assert!(d.selections().len() >= 2);
        d.collapse_selections();
        assert_eq!(d.selections().len(), 1);
        assert!(d.selections().newest().is_empty());
    }

    #[test]
    fn find_next_occurrence_scans_forward_then_wraps() {
        // "aXaYa": 'a' at 0, 2, 4. From 1, skipping the (0,1) already-taken one.
        assert_eq!(super::find_next_occurrence("aXaYa", "a", 1, &[(0, 1)]), Some((2, 3)));
        // From past the last match, wrap to the first untaken.
        assert_eq!(super::find_next_occurrence("aXaYa", "a", 5, &[(2, 3), (4, 5)]), Some((0, 1)));
        // Every occurrence taken → None.
        assert_eq!(super::find_next_occurrence("aa", "a", 0, &[(0, 1), (1, 2)]), None);
    }

    #[test]
    fn dirty_after_undo_then_divergent_edit() {
        // Silent-data-loss guard: save, undo, retype something different → the
        // dirty flag must NOT read clean just because the stack depth matches.
        let mut d = doc("abc");
        d.edit(vec![EditOp::delete(2..3)]).unwrap(); // "ab"
        d.mark_saved();
        d.undo(); // "abc"
        assert!(d.is_dirty(), "undone away from the save point → dirty");
        d.edit(vec![EditOp::delete(0..1)]).unwrap(); // "bc" — diverges from "ab"
        assert!(d.is_dirty(), "divergent edit is still dirty, never falsely clean");
    }

    #[test]
    fn highlight_cache_splice_tracks_line_count_across_edits() {
        // Tiny grammar/theme via the same app-injection path scratch uses.
        const G: &str = "%YAML 1.2\n---\nname: T\nscope: source.t\ncontexts:\n  main:\n    - match: '\\w+'\n      scope: keyword.t\n";
        const TH: &str = r#"<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict><key>settings</key><array><dict><key>settings</key><dict><key>foreground</key><string>#FFFFFF</string></dict></dict></array></dict></plist>"#;
        let mut d = doc("ab\ncd");
        d.set_syntax(
            crate::SyntaxDef::from_sublime_syntax(G).unwrap(),
            crate::TokenTheme::from_tm_theme(TH).unwrap(),
        );
        d.tokenize_highlight(d.buffer().line_count());
        assert!(d.highlight_line_spans(1).is_some());
        // Enter inserts a line: the cache must grow (splice old=1 -> new=2).
        d.set_selections(SelectionSet::new(2)); // end of "ab"
        d.enter();
        d.tokenize_highlight(d.buffer().line_count());
        assert_eq!(d.buffer().line_count(), 3);
        assert!(d.highlight_line_spans(2).is_some(), "the new last line is tokenized");
        // Backspace merges it back: the cache must shrink (splice old=2 -> new=1).
        d.backspace();
        d.tokenize_highlight(d.buffer().line_count());
        assert_eq!(d.buffer().line_count(), 2);
        assert!(d.highlight_line_spans(1).is_some());
        assert!(d.highlight_line_spans(2).is_none(), "no spans past the buffer");
    }

    #[test]
    fn multi_op_transaction_highlight_equals_a_fresh_document() {
        // A multi-caret transaction commits ALL its edits at once; rebase_views
        // must derive each edit's line span (old lines from the inverse text,
        // new lines from the post buffer) and coalesce same-line edits, then
        // invalidate exactly those lines. The swept highlight must equal a fresh
        // document on the identical text — a coordinate or coalescing error would
        // surface as a stale (un-re-tokenized) row here.
        const G: &str = "%YAML 1.2\n---\nname: T\nscope: source.t\ncontexts:\n  main:\n    - match: '\\w+'\n      scope: keyword.t\n";
        const TH: &str = r#"<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict><key>settings</key><array><dict><key>settings</key><dict><key>foreground</key><string>#FFFFFF</string></dict></dict></array></dict></plist>"#;
        let make = |text: &str| -> Document {
            let mut d = doc(text);
            d.set_syntax(
                crate::SyntaxDef::from_sublime_syntax(G).unwrap(),
                crate::TokenTheme::from_tm_theme(TH).unwrap(),
            );
            d.tokenize_highlight(u32::MAX);
            d
        };
        // Lines: "aa bb cc"(0-7) \n(8) "dd ee ff"(9-16) \n(17) "gg hh ii"(18-25)
        //        \n(26) "jj kk ll"(27-34) \n(35) "mm nn oo"(36-43).
        let mut d = make("aa bb cc\ndd ee ff\ngg hh ii\njj kk ll\nmm nn oo");
        // One transaction: an edit on line 0, TWO edits on line 1 (must coalesce
        // to one line span), and a newline-bearing insert (a +1 line delta) —
        // all disjoint and ascending.
        d.edit_grouped(
            vec![
                EditOp::new(0..2, "XYZ"),     // line 0
                EditOp::new(9..11, "Q"),      // line 1, col 0
                EditOp::new(15..17, "RR"),    // line 1, col 6 (same line ⇒ coalesce)
                EditOp::insert(27, "NEW\n"),  // start of line 3 ⇒ inserts a line
            ],
            typ(OpClass::Type),
        )
        .unwrap();
        d.tokenize_highlight(u32::MAX);

        let text = d.text();
        let f = make(&text);
        assert_eq!(d.buffer().line_count(), f.buffer().line_count(), "line count");
        for r in 0..d.buffer().line_count() {
            assert_eq!(
                d.highlight_line_spans(r),
                f.highlight_line_spans(r),
                "row {r} live (per-edit invalidation) vs fresh"
            );
        }
    }

    /// A mid-session grammar swap must keep the retention window aimed at the
    /// viewport: the widget's deduped viewport report never re-fires when
    /// nothing visible moved, so the swapped cache must retain the currently
    /// visible rows rather than reset to the top and leave them fallback-styled.
    #[test]
    fn set_syntax_preserves_the_highlight_window_aim() {
        const G: &str = "%YAML 1.2\n---\nname: T\nscope: source.t\ncontexts:\n  main:\n    - match: '\\w+'\n      scope: keyword.t\n";
        const TH: &str = r#"<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict><key>settings</key><array><dict><key>settings</key><dict><key>foreground</key><string>#FFFFFF</string></dict></dict></array></dict></plist>"#;
        let syntax = || crate::SyntaxDef::from_sublime_syntax(G).unwrap();
        let theme = || crate::TokenTheme::from_tm_theme(TH).unwrap();
        let mut d = doc(&"word\n".repeat(3_000));
        d.set_syntax(syntax(), theme());
        // The app scrolled deep: the window is aimed well past the default.
        d.set_highlight_window(2_000..2_040);
        // Grammar swap mid-session (re-highlight when the host swaps the language).
        d.set_syntax(syntax(), theme());
        while d.highlight_frontier().is_some() {
            d.tokenize_highlight(u32::MAX);
        }
        assert!(
            d.highlight_line_spans(2_020).is_some(),
            "the swapped cache must still retain the viewport rows"
        );
    }

    // Off-thread parallel/speculative highlight ingest. A stateless grammar
    // suffices at the Document seam — the stitch correctness lives in
    // highlight.rs's stateful oracle; here we check the seam's contract:
    // revision gating, dirt clearing, and no-checkpoint speculation.
    const HL_G: &str = "%YAML 1.2\n---\nname: T\nscope: source.t\ncontexts:\n  main:\n    - match: '\\bkw\\b'\n      scope: keyword.t\n";
    const HL_TH: &str = r#"<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict><key>settings</key><array><dict><key>settings</key><dict><key>foreground</key><string>#FFFFFF</string></dict></dict></array></dict></plist>"#;

    fn doc_with_syntax(n: usize) -> Document {
        let mut d = doc(&"kw word\n".repeat(n));
        d.set_syntax(
            crate::SyntaxDef::from_sublime_syntax(HL_G).unwrap(),
            crate::TokenTheme::from_tm_theme(HL_TH).unwrap(),
        );
        d
    }

    #[test]
    fn absorb_highlight_drops_a_stale_revision() {
        let mut d = doc_with_syntax(2_000);
        let engine = d.highlight_engine().unwrap();
        let snap = d.snapshot();
        let stale_rev = d.revision();
        let seg = crate::tokenize_segment(&engine, &snap, 0..2_001, crate::SegmentStart::Fresh, None, None);
        // An edit lands after the snapshot was taken…
        d.set_selections(SelectionSet::new(0));
        d.type_char('x');
        assert_ne!(d.revision(), stale_rev);
        // …so the in-flight segment is dropped, absorbing nothing.
        assert!(!d.absorb_highlight(stale_rev, seg, true), "stale segment must be dropped");
        assert_eq!(d.highlight_frontier(), Some(0), "the frontier is untouched by a dropped absorb");
    }

    #[test]
    fn absorb_highlight_verified_clears_the_frontier() {
        let mut d = doc_with_syntax(5_000);
        let engine = d.highlight_engine().unwrap();
        let snap = d.snapshot();
        let rev = d.revision();
        let n = d.buffer().line_count();
        // A single verified segment over the whole document, carrying spans for
        // the whole range so no window gap remains either — then the frontier
        // (dirt ∨ window gap) is fully quiet, proving dirt was cleared.
        let seg =
            crate::tokenize_segment(&engine, &snap, 0..n, crate::SegmentStart::Fresh, Some(0..n), None);
        assert!(d.absorb_highlight(rev, seg, true));
        assert_eq!(d.highlight_frontier(), None, "verified absorb clears every dirty row");
    }

    #[test]
    fn absorb_highlight_speculative_shows_spans_but_keeps_dirt() {
        let mut d = doc_with_syntax(2_000);
        d.set_highlight_window(900..940);
        let engine = d.highlight_engine().unwrap();
        let snap = d.snapshot();
        let rev = d.revision();
        // A viewport-first speculative segment (Fresh guess, spans for the win).
        let seg = crate::tokenize_segment(
            &engine,
            &snap,
            772..940,
            crate::SegmentStart::Fresh,
            Some(900..940),
            None,
        );
        assert!(d.absorb_highlight(rev, seg, false));
        // Spans render immediately…
        assert!(d.highlight_line_spans(920).is_some(), "speculative spans are visible");
        // …but nothing is verified: the frontier still starts at row 0.
        assert_eq!(d.highlight_frontier(), Some(0), "speculation keeps the frontier");
        // Driving the sync frontier still converges to the correct colors.
        while d.highlight_frontier().is_some() {
            d.tokenize_highlight(u32::MAX);
        }
        assert!(d.highlight_line_spans(920).is_some());
    }

    // Engine identity: a segment is only as good as the grammar + theme that
    // tokenized it. `set_theme` / `set_syntax` don't move the buffer revision, so
    // the revision gate alone cannot catch a segment from the outgoing engine.

    /// A `.tmTheme` whose `keyword` scope is `keyword_hex` (default text white).
    fn keyword_theme(keyword_hex: &str) -> crate::TokenTheme {
        crate::TokenTheme::from_tm_theme(&format!(
            r#"<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict><key>settings</key><array>
<dict><key>settings</key><dict><key>foreground</key><string>#FFFFFF</string></dict></dict>
<dict><key>scope</key><string>keyword</string><key>settings</key><dict><key>foreground</key><string>{keyword_hex}</string></dict></dict>
</array></dict></plist>"#
        ))
        .unwrap()
    }
    const HL_RED: crate::Rgba = crate::Rgba { r: 0xff, g: 0, b: 0, a: 0xff };
    const HL_GREEN: crate::Rgba = crate::Rgba { r: 0, g: 0xff, b: 0, a: 0xff };

    /// The colour of row `row`'s span starting at byte `col` (after a full drive).
    fn color_at(d: &Document, row: u32, col: u32) -> crate::Rgba {
        d.highlight_line_spans(row)
            .unwrap_or_else(|| panic!("row {row} has spans"))
            .iter()
            .find(|s| s.range.start == col)
            .unwrap_or_else(|| panic!("row {row} has a span at byte {col}"))
            .style
            .fg
    }

    fn drive_highlight(d: &mut Document) {
        while d.highlight_frontier().is_some() {
            d.tokenize_highlight(u32::MAX);
        }
    }

    /// Fails-first (the ticket's theme repro): a verified segment tokenized with
    /// the red theme, absorbed after `set_theme(green)`, used to be accepted —
    /// row 10's keyword stayed red and the frontier jumped past row 600, so those
    /// rows stayed wrong until edited. It must be rejected, absorbing nothing.
    #[test]
    fn absorb_highlight_rejects_a_segment_from_the_previous_theme() {
        let mut d = doc(&"kw word\n".repeat(2_000));
        d.set_syntax(crate::SyntaxDef::from_sublime_syntax(HL_G).unwrap(), keyword_theme("#FF0000"));
        let engine = d.highlight_engine().unwrap();
        let snap = d.snapshot();
        let rev = d.revision();
        let seg =
            crate::tokenize_segment(&engine, &snap, 0..600, crate::SegmentStart::Fresh, Some(0..600), None);
        d.set_theme(keyword_theme("#00FF00"));
        assert!(!d.absorb_highlight(rev, seg, true), "an old-theme segment must be rejected");
        assert_eq!(d.highlight_frontier(), Some(0), "a rejected absorb must not move the frontier");
        drive_highlight(&mut d);
        assert_eq!(color_at(&d, 10, 0), HL_GREEN, "row 10's keyword repaints in the new theme");
    }

    /// Fails-first (the ticket's grammar repro): the same hole through
    /// `set_syntax`. The old grammar makes `kw` the keyword, the new one `word`;
    /// an old-grammar segment absorbed after the swap would leave `kw` red.
    #[test]
    fn absorb_highlight_rejects_a_segment_from_the_previous_grammar() {
        const WORD_G: &str = "%YAML 1.2\n---\nname: W\nscope: source.w\ncontexts:\n  main:\n    - match: '\\bword\\b'\n      scope: keyword.w\n";
        let mut d = doc(&"kw word\n".repeat(2_000));
        d.set_syntax(crate::SyntaxDef::from_sublime_syntax(HL_G).unwrap(), keyword_theme("#FF0000"));
        let engine = d.highlight_engine().unwrap();
        let snap = d.snapshot();
        let rev = d.revision();
        let seg =
            crate::tokenize_segment(&engine, &snap, 0..600, crate::SegmentStart::Fresh, Some(0..600), None);
        d.set_syntax(crate::SyntaxDef::from_sublime_syntax(WORD_G).unwrap(), keyword_theme("#FF0000"));
        assert!(!d.absorb_highlight(rev, seg, true), "an old-grammar segment must be rejected");
        assert_eq!(d.highlight_frontier(), Some(0), "a rejected absorb must not move the frontier");
        drive_highlight(&mut d);
        assert_eq!(color_at(&d, 10, 3), HL_RED, "`word` is the new grammar's keyword");
        assert_ne!(color_at(&d, 10, 0), HL_RED, "`kw` is plain text under the new grammar");
    }

    /// Provenance covers a segment's INPUTS, not just the engine that ran it: a
    /// coordinator chaining across a swap can hand the current engine an
    /// old-engine boundary to resume from, or an old-engine segment to splice a
    /// converged tail from. Either result carries old-engine state or spans, so
    /// it must be refused like the old engine's own output.
    #[test]
    fn absorb_highlight_rejects_a_segment_built_on_the_previous_engines_output() {
        let mut d = doc(&"kw word\n".repeat(2_000));
        d.set_syntax(crate::SyntaxDef::from_sublime_syntax(HL_G).unwrap(), keyword_theme("#FF0000"));
        let old = d.highlight_engine().unwrap();
        let snap = d.snapshot();
        let rev = d.revision();
        let old_prefix = crate::tokenize_segment(&old, &snap, 0..300, crate::SegmentStart::Fresh, None, None);
        let old_guess =
            crate::tokenize_segment(&old, &snap, 300..800, crate::SegmentStart::Fresh, Some(300..800), None);
        d.set_theme(keyword_theme("#00FF00"));
        let new = d.highlight_engine().unwrap();

        // Resumed from the old engine's end boundary.
        let after_old = crate::SegmentStart::After(old_prefix.end_boundary().clone());
        let chained = crate::tokenize_segment(&new, &snap, 300..800, after_old, Some(300..800), None);
        assert!(!d.absorb_highlight(rev, chained, true), "resumed from an old-engine boundary");

        // A converging re-run against the old engine's segment: the stateless
        // grammar converges at the first stride checkpoint, so without the
        // provenance rule the old (red) tail would be spliced in under the new
        // engine's stamp.
        let new_prefix = crate::tokenize_segment(&new, &snap, 0..300, crate::SegmentStart::Fresh, None, None);
        let after_new = crate::SegmentStart::After(new_prefix.end_boundary().clone());
        let rerun = crate::tokenize_segment(&new, &snap, 300..800, after_new, None, Some(&old_guess));
        assert!(!d.absorb_highlight(rev, rerun, true), "spliced from an old-engine segment");

        assert_eq!(d.highlight_frontier(), Some(0), "nothing was absorbed");
        // The new engine's own chain is still accepted.
        assert!(d.absorb_highlight(rev, new_prefix, true), "the current engine's own segment");
    }

    #[test]
    fn diagnostics_install_then_ride_a_forward_edit() {
        use crate::{Diagnostic, DiagnosticsOutcome, Severity};
        let mut d = doc("let x = 1;");
        let rev = d.revision();
        let out = d.set_diagnostics(rev, vec![Diagnostic::new(4..5, Severity::Error, "unused")]);
        assert!(matches!(out, DiagnosticsOutcome::Applied { count: 1 }));
        let got: Vec<_> = d.diagnostics_in(0..100).collect();
        assert_eq!((got.len(), got[0].0.clone(), got[0].1), (1, 4..5, Severity::Error));
        // Insert 4 chars at the top → the squiggle (NeverGrows) rides to 8..9.
        d.edit(vec![EditOp::insert(0, "abcd")]).unwrap();
        assert_eq!(d.diagnostics_in(0..100).next().unwrap().0, 8..9, "rode via apply_patch");
    }

    #[test]
    fn stale_diagnostic_set_is_dropped_and_the_prior_kept() {
        use crate::{Diagnostic, DiagnosticsOutcome, Severity};
        let mut d = doc("abcdef");
        let rev = d.revision();
        d.set_diagnostics(rev, vec![Diagnostic::new(0..1, Severity::Warning, "w")]);
        d.edit(vec![EditOp::insert(0, "z")]).unwrap(); // revision advances
        let out = d.set_diagnostics(rev, vec![Diagnostic::new(3..4, Severity::Error, "e")]);
        assert!(matches!(out, DiagnosticsOutcome::Stale { .. }), "old-revision set dropped");
        let got: Vec<_> = d.diagnostics_in(0..100).collect();
        assert_eq!((got.len(), got[0].0.clone(), got[0].1), (1, 1..2, Severity::Warning));
    }

    #[test]
    fn diagnostic_spans_clip_to_the_buffer_length() {
        use crate::{Diagnostic, Severity};
        let mut d = doc("abc"); // len 3
        let rev = d.revision();
        d.set_diagnostics(rev, vec![Diagnostic::new(2..99, Severity::Error, "past eof")]);
        assert_eq!(d.diagnostics_in(0..100).next().unwrap().0, 2..3, "clipped to buffer len");
    }

    /// Regression (fails-first): spans were clipped to the length but not to
    /// char boundaries, so `1..3` over `"é"` was stored as-is — a squiggle
    /// starting inside a char, which diagnostic navigation then installed as
    /// a selection. Spans now snap outward to whole chars; an empty span snaps
    /// to the start of the char it split and stays empty.
    #[test]
    fn diagnostic_spans_snap_to_char_boundaries() {
        use crate::{Diagnostic, Severity};
        let mut d = doc("é\néé"); // é 0..2, \n 2, é 3..5, é 5..7
        let rev = d.revision();
        let diag = |span| Diagnostic::new(span, Severity::Error, "x");
        d.set_diagnostics(rev, vec![diag(1..3), diag(4..4), diag(6..900)]);
        let spans: Vec<Range<u32>> = d.diagnostics_in(0..u32::MAX).map(|(r, ..)| r).collect();
        assert_eq!(spans, [0..3, 3..3, 5..7]);
        // Navigation selects each span: every one must be motion-safe.
        for want in [0..3, 3..3, 5..7] {
            assert_eq!(d.next_diagnostic(true), Some(want.clone()));
            assert_eq!(range(&d), (want.start, want.end));
            d.move_carets(Motion::Right, true);
        }
    }

    #[test]
    fn host_decorations_snap_to_char_boundaries() {
        // Fails-first: `decorations_mut` hands the host the document's
        // own store, which installed every range verbatim — `1..3` over "éé"
        // was stored mid-char at both ends, and a past-end span stayed past the
        // end. Every store door that stores a caller's range now clips it
        // through the one range rule, against the document's current text.
        use crate::{Diagnostic, DiagnosticsOutcome};
        let mut d = doc("éé"); // é 0..2, é 2..4
        let stop = |index| DecorationKind::SnippetStop { index };
        let range_of = |d: &Document, id| d.decorations().decoration_range(id);
        let a = d.decorations_mut().add_decoration(1..3, stop(0), Stickiness::NeverGrows);
        let b = d.decorations_mut().add_decoration(3..900, stop(1), Stickiness::NeverGrows);
        let c = d.decorations_mut().add_decoration(1..1, stop(2), Stickiness::AlwaysGrows);
        assert_eq!(range_of(&d, a), Some(0..4), "a mid-char span snaps outward to whole chars");
        assert_eq!(range_of(&d, b), Some(2..4), "a past-end end clamps to the end");
        assert_eq!(range_of(&d, c), Some(0..0), "an empty span stays empty, at its char's start");
        // The batch doors, and the store's own diagnostics door, clip alike.
        let batch = d.decorations_mut().add_sorted_batch([1..3, 5..9], stop(3), Stickiness::NeverGrows);
        let spliced = d.decorations_mut().splice_sorted_batch(&[3..3, 9..9], stop(4), Stickiness::NeverGrows);
        let ranges: Vec<_> = batch.iter().chain(&spliced).map(|&id| range_of(&d, id)).collect();
        assert_eq!(ranges, [Some(0..4), Some(4..4), Some(2..2), Some(4..4)]);
        let rev = d.revision().0;
        let diags = vec![Diagnostic::new(1..3, Severity::Error, "x")];
        assert_eq!(d.decorations_mut().set_diagnostics(rev, rev, diags), DiagnosticsOutcome::Applied { count: 1 });
        let spans: Vec<Range<u32>> = d.diagnostics_in(0..u32::MAX).map(|(r, ..)| r).collect();
        assert_eq!((spans.len(), spans.first().cloned()), (1, Some(0..4)));
        // Against the CURRENT text: after an edit shifts the chars, a span
        // clips to where they are now.
        d.edit(vec![EditOp::insert(0, "a")]).unwrap(); // é 1..3, é 3..5
        let e = d.decorations_mut().add_decoration(2..4, stop(5), Stickiness::NeverGrows);
        assert_eq!(range_of(&d, e), Some(1..5));
        // A standalone store knows no text: it still installs verbatim.
        let mut lone = DecorationStore::new();
        let f = lone.add_decoration(1..3, stop(6), Stickiness::NeverGrows);
        assert_eq!(lone.decoration_range(f), Some(1..3));
    }

    #[test]
    fn a_host_fold_opener_is_clipped_to_the_buffer() {
        // Fails-first: `toggle_fold_opener` keyed the fold by its host
        // offset as given, so a fold at 1000 outlived a 4-byte document, and
        // one at byte 1 of "é" split a char.
        let mut d = doc("a{b}");
        assert!(d.toggle_fold_opener(1000));
        let len = d.buffer().len();
        assert!(d.folds().iter().all(|o| o <= len), "a fold past the end: {:?}", d.folds().iter().collect::<Vec<_>>());
        assert!(d.toggle_fold_opener(1000), "the same host offset toggles the clipped fold back");
        assert!(d.folds().is_empty());
        let mut e = doc("é{\n}");
        assert!(e.toggle_fold_opener(1));
        let text = e.text().into_owned();
        assert!(e.folds().iter().all(|o| text.is_char_boundary(o as usize)), "a fold inside a char");
    }

    #[test]
    fn rend04_diagnostic_render_row_shifts_when_lines_inserted_above() {
        // A diagnostic deep in the document rides the code as whole lines are
        // inserted above it — its RENDER row (offset → point) shifts by the
        // inserted line count, still glued to the same text.
        use crate::{Diagnostic, Point, Severity};
        let mut d = doc("L0\nL1\nL2\nL3\nL4\nL5\nL6\nL7\nL8\nL9");
        let row5 = d.buffer().point_to_offset(Point { row: 5, col: 0 });
        d.set_diagnostics(d.revision(), vec![Diagnostic::new(row5..row5 + 2, Severity::Error, "e")]);
        let start = d.diagnostics_in(0..u32::MAX).next().unwrap().0.start;
        assert_eq!(d.buffer().offset_to_point(start).row, 5);
        // Insert three lines at the very top.
        d.edit(vec![EditOp::insert(0, "a\nb\nc\n")]).unwrap();
        let span = d.diagnostics_in(0..u32::MAX).next().unwrap().0;
        assert_eq!(d.buffer().offset_to_point(span.start).row, 8, "5 + 3 inserted lines");
        assert_eq!(&d.text()[span.start as usize..span.end as usize], "L5", "still glued to its code");
    }

    /// The windowed fold queries (the fold-gutter mouse hot paths) must agree
    /// with the whole-document ones on every row / window — else a hover/click
    /// near a fold would mis-decide. A windowed query that drops a headed pair or
    /// mis-clamps the byte range diverges here. Uses nested + inline + adjacent
    /// blocks so the partition-point windowing is exercised at boundaries.
    #[test]
    fn windowed_fold_queries_match_the_whole_document() {
        let mut d = doc(
            "top\n\
             a {\n  b [1, 2]\n  c {\n    d\n  }\n}\n\
             mid\n\
             e (x,\n  y)\n\
             f {\n  g\n}\n\
             end",
        );
        let n = d.buffer().line_count();
        // block_opener_on_row(r) windowed == the whole-document oracle.
        for row in 0..n {
            let want = d
                .foldable_pairs()
                .into_iter()
                .filter(|&(_, _, h, l)| h == row && l > h)
                .max_by_key(|&(_, _, h, l)| l - h)
                .map(|(o, ..)| o);
            assert_eq!(d.block_opener_on_row(row), want, "block_opener_on_row row {row}");
        }
        // collapsible_pairs_in_rows(0..n) == collapsible_pairs() (whole doc).
        assert_eq!(d.collapsible_pairs_in_rows(0..n), d.collapsible_pairs());
        // A sub-window returns exactly the whole-doc pairs headed inside it.
        for (a, b) in [(0u32, 3u32), (2, 6), (3, 4), (7, n)] {
            let want: Vec<_> =
                d.collapsible_pairs().into_iter().filter(|&(_, _, h, _)| a <= h && h < b).collect();
            assert_eq!(d.collapsible_pairs_in_rows(a..b), want, "collapsible_pairs_in_rows {a}..{b}");
        }
        // foldable_ranges_in_rows(r..r+1) headers agree with foldable_ranges().
        for row in 0..n {
            let windowed: Vec<_> =
                d.foldable_ranges_in_rows(row..row + 1).into_iter().filter(|(h, _)| h.0 == row).collect();
            let whole: Vec<_> =
                d.foldable_ranges().into_iter().filter(|(h, _)| h.0 == row).collect();
            assert_eq!(windowed, whole, "foldable_ranges row {row}");
        }
        // And it still holds after a fold collapses (folded pairs drop out).
        let opener = d.block_opener_on_row(1).unwrap();
        assert!(d.toggle_fold_opener(opener));
        assert_eq!(d.collapsible_pairs_in_rows(0..n), d.collapsible_pairs());
    }

    #[test]
    fn fold_survives_undo_redo() {
        // A fold rides the commit patch exactly like a decoration: an edit
        // above shifts it, undo restores its original rows, redo re-shifts — with
        // no fold-specific undo handling. The block is bracketed so it stays a
        // valid foldable range across the reconcile that runs on every edit.
        use crate::{fold_map::FoldMap, BufferRow};
        let mut d = doc("L0\nL1\nL2\nL3\nL4\nblk {\n  x\n  y\n}\nL9");
        assert_eq!(d.foldable_ranges().iter().map(|(h, l)| (h.0, l.0)).collect::<Vec<_>>(), vec![(5, 8)]);
        assert!(d.fold(BufferRow(5), BufferRow(8)));
        let header = |d: &Document| FoldMap::new(d.folds(), d.brackets(), d.buffer()).fold_at_header(BufferRow(5));
        let header8 = |d: &Document| FoldMap::new(d.folds(), d.brackets(), d.buffer()).fold_at_header(BufferRow(8));
        assert_eq!(header(&d), Some(BufferRow(8)));
        // Insert three lines at the top → fold shifts to header 8, last 11.
        d.edit(vec![EditOp::insert(0, "a\nb\nc\n")]).unwrap();
        assert_eq!(header8(&d), Some(BufferRow(11)));
        // Undo → fold back at 5..8. Redo → shifted again.
        assert!(d.undo());
        assert_eq!(header(&d), Some(BufferRow(8)));
        assert!(d.redo());
        assert_eq!(header8(&d), Some(BufferRow(11)));
    }

    #[test]
    fn pasting_after_the_collapsed_line_keeps_the_outer_fold() {
        use crate::{fold_map::FoldMap, BufferRow, SelectionSet};
        // Outer block (0,3) around a nested inner block (1,2).
        let mut d = doc("{\n\t{\n\t}\n}\n");
        assert_eq!(d.foldable_ranges().iter().map(|(h, l)| (h.0, l.0)).collect::<Vec<_>>(), vec![(0, 3), (1, 2)]);
        assert!(d.fold(BufferRow(0), BufferRow(3))); // fold the outer bracket
        // Copy the whole collapsed block `{…}` (offsets [0,9)) and paste it at the
        // end of the collapsed line (offset 9, just after the `}` on row 3).
        let block = d.buffer().text()[0..9].to_string();
        d.set_selections(SelectionSet::new(9));
        d.insert_text(&block);
        // The outer block's `{`…`}` is still on rows 0..3, so the fold must STAY on
        // (0,3) — not drop, and not grow onto a bogus range.
        assert_eq!(d.folds().len(), 1, "the outer fold survives the paste");
        assert_eq!(FoldMap::new(d.folds(), d.brackets(), d.buffer()).fold_at_header(BufferRow(0)), Some(BufferRow(3)));
    }

    #[test]
    fn editing_after_the_brace_keeps_a_folded_block() {
        use crate::{fold_map::FoldMap, BufferRow, SelectionSet};
        let mut d = doc("{\n}");
        assert!(d.fold(BufferRow(0), BufferRow(1)));
        // Type arbitrary text after the `}` — the `{`…`}` block is intact.
        d.set_selections(SelectionSet::new(d.buffer().len()));
        d.insert_text("abc");
        assert_eq!(d.buffer().text(), "{\n}abc");
        assert_eq!(d.folds().len(), 1, "fold survives typing after the brace");
        // …and delete it back.
        let end = d.buffer().len();
        d.edit(vec![EditOp::delete(end - 3..end)]).unwrap();
        assert_eq!(d.buffer().text(), "{\n}");
        assert_eq!(d.folds().len(), 1, "fold survives deleting after the brace");
        assert_eq!(FoldMap::new(d.folds(), d.brackets(), d.buffer()).fold_at_header(BufferRow(0)), Some(BufferRow(1)));
    }

    #[test]
    fn pressing_return_after_a_folded_eof_block_keeps_it_folded() {
        use crate::{fold_map::FoldMap, BufferRow, SelectionSet};
        // A fold created at EOF: `}` is the last line, so its interior has no
        // trailing `\n`.
        let mut d = doc("{\n}");
        assert!(d.fold(BufferRow(0), BufferRow(1)));
        // Caret at the very end (after `}`); press Enter (insert `\n`). The block
        // is untouched — a blank line is added after it — so the fold must STAY.
        d.set_selections(SelectionSet::new(d.buffer().len()));
        d.insert_text("\n");
        assert_eq!(d.buffer().text(), "{\n}\n");
        assert_eq!(d.folds().len(), 1, "the intact block stays folded");
        assert_eq!(FoldMap::new(d.folds(), d.brackets(), d.buffer()).fold_at_header(BufferRow(0)), Some(BufferRow(1)));
    }

    #[test]
    fn cutting_trailing_content_keeps_an_intact_fold() {
        use crate::{fold_map::FoldMap, BufferRow};
        // rows: 0 "{" 1 "}" 2 "X"
        let mut d = doc("{\n}\nX");
        assert!(d.fold(BufferRow(0), BufferRow(1))); // fold the set
        // Select from after X (offset 5) to the end of the `}` (offset 3) and cut:
        // deletes the `}` line's trailing `\n` + `X`. The `{`…`}` block is intact,
        // so the fold must STAY.
        let a = d.buffer().point_to_offset(crate::Point::new(1, 1)); // 3
        let b = d.buffer().point_to_offset(crate::Point::new(2, 1)); // 5
        d.edit(vec![EditOp::delete(a..b)]).unwrap();
        assert_eq!(d.buffer().text(), "{\n}", "only the trailing content was removed");
        assert_eq!(d.folds().len(), 1, "the intact block stays folded");
        assert_eq!(FoldMap::new(d.folds(), d.brackets(), d.buffer()).fold_at_header(BufferRow(0)), Some(BufferRow(1)));
    }

    #[test]
    fn cutting_across_a_folds_boundary_drops_it_not_drifts_it() {
        use crate::{fold_map::FoldMap, BufferRow};
        // Three sibling blocks. rows: 0 "{" 1 "}" 2 "{" 3 "}" 4 "{" 5 "}" 6 ""
        let mut d = doc("{\n}\n{\n}\n{\n}\n");
        assert!(d.fold(BufferRow(2), BufferRow(3))); // fold the MIDDLE set
        // Select from the end of the first `}` (offset 3) to the end of the middle
        // `}` (offset 7) and cut it — a delete that crosses the fold's interior
        // start. The whole middle block is removed.
        let a = d.buffer().point_to_offset(crate::Point::new(1, 1)); // 3
        let b = d.buffer().point_to_offset(crate::Point::new(3, 1)); // 7
        d.edit(vec![EditOp::delete(a..b)]).unwrap();
        // The fold must DROP — not drift onto the first set (which is itself a
        // valid foldable range, so reconcile can't catch the drift).
        assert!(d.folds().is_empty(), "fold dropped, not drifted onto the first block");
        assert_eq!(FoldMap::new(d.folds(), d.brackets(), d.buffer()).fold_at_header(BufferRow(0)), None, "first set not folded");
    }

    #[test]
    fn typing_at_many_carets_over_folds_stays_linear() {
        use crate::bracket::ENCLOSING_WALKS;
        use crate::row_layout::DISPLAY_POSITION_PROBES;
        use crate::{Motion, SelectionSet};
        // Select every `fn pid` occurrence, fold each block, then type.
        // `expand_folds_touched` is windowed, so per commit it does ONE enclosing
        // walk (for the first edit point) and O(edit points) display-position
        // probes, independent of caret count — never O(carets) leftward enclosing
        // walks plus an O(carets²) per-candidate edit scan. Gates both: an
        // un-windowed implementation trips these by a factor of N.
        let mut src = String::new();
        for i in 0..400 {
            src.push_str(&format!(
                "// block {i}\nfn pid_{i}(pid: u8) -> u8 {{\n    switch pid {{\n        0x0D => {{ return 88; }}\n    }}\n}}\n\n"
            ));
        }
        let mut d = doc(&src);
        let first = d.buffer().text().find("fn pid").unwrap() as u32;
        d.set_selections(SelectionSet::from_ranges(&[(first, first + 6)], 0));
        d.select_all_occurrences();
        let carets = d.selections().all().len();
        assert!(carets >= 400, "select-all found every block ({carets} carets)");
        d.move_carets(Motion::LineEnd, false);
        d.fold_at_carets(false);
        d.move_carets(Motion::LineEnd, false);

        // Measure ONLY the commit for the typed character.
        ENCLOSING_WALKS.with(|c| c.set(0));
        DISPLAY_POSITION_PROBES.with(|c| c.set(0));
        d.insert_text("a");
        let walks = ENCLOSING_WALKS.with(std::cell::Cell::get);
        let probes = DISPLAY_POSITION_PROBES.with(std::cell::Cell::get);
        assert!(walks <= 2, "one enclosing walk per commit, not O(carets): {walks} for {carets} carets");
        assert!(
            probes <= 4 * carets as u64,
            "display-position probes are O(edit points), not O(carets²): {probes} for {carets} carets"
        );
    }

    #[test]
    fn folded_keystroke_never_resolves_bracket_depth() {
        use crate::bracket_tree::BRACKET_VIEW_CALLS;
        use crate::SelectionSet;
        // Fold every function block, then type. The edit-path fold queries —
        // expand-on-hidden-edit, reconcile, the FoldMap rebuild — must resolve
        // each fold's partner via the depth-free `foldable_partner`, NEVER
        // `bracket_view`, whose per-opener prefix-stack Vec (allocated at every
        // tree level) would turn a fold-heavy keystroke into an O(folds · depth)
        // allocation storm. `bracket_view` is a DRAW-path (colorization)
        // primitive only; a single fold-edit commit must leave the
        // depth-resolution canary at zero regardless of how many folds are open.
        // Resolving partners through `at().partner` → `bracket_view` would read
        // ~2·folds; the depth-free path pins it to zero.
        let mut src = String::new();
        for i in 0..300 {
            src.push_str(&format!("fn f_{i}() {{\n    body\n}}\n"));
        }
        let mut d = doc(&src);
        // The block `{` of each function (the `()` params are single-line, not folds).
        let openers: Vec<u32> = d
            .brackets()
            .all()
            .iter()
            .filter(|b| b.open && d.buffer().char_at(b.offset) == Some('{'))
            .map(|b| b.offset)
            .collect();
        assert_eq!(openers.len(), 300, "one foldable block opener each");
        for &o in &openers {
            assert!(d.toggle_fold_opener(o));
        }
        // A caret just after each (visible) header `{` — the "hit END, type" position.
        let carets: Vec<(u32, u32)> = openers.iter().map(|&o| (o + 1, o + 1)).collect();
        d.set_selections(SelectionSet::from_ranges(&carets, 0));
        let _ = d.fold_map(); // warm the map so the measured commit is steady-state

        BRACKET_VIEW_CALLS.with(|c| c.set(0));
        d.insert_text("a");
        let _ = d.fold_map(); // the per-keystroke refresh rides the same lookups
        let depth_resolves = BRACKET_VIEW_CALLS.with(std::cell::Cell::get);
        assert_eq!(
            depth_resolves, 0,
            "a fold-heavy keystroke resolved bracket depth {depth_resolves} times over 300 folds \
             — the edit path must use foldable_partner, not at()/bracket_view"
        );
    }

    #[test]
    fn single_line_pair_folds_inline() {
        use crate::{fold_map::FoldMap, SelectionSet};
        // one line: `[` at 4, `]` at 12.
        let mut d = doc("x = [1, 2, 3]");
        d.set_selections(SelectionSet::new(6)); // caret inside the array
        let opener = d.fold_opener_at_caret(false).expect("an enclosing foldable pair");
        assert_eq!(opener, 4);
        assert!(d.toggle_fold_opener(opener));
        let m = FoldMap::new(d.folds(), d.brackets(), d.buffer());
        assert_eq!(m.display_row_count(), 1, "an inline fold hides no rows");
        assert_eq!(m.inline_folds().len(), 1);
        assert_eq!((m.inline_folds()[0].row, m.inline_folds()[0].open, m.inline_folds()[0].close), (0, 4, 12));
        // Unfold via the same opener.
        assert!(d.toggle_fold_opener(4));
        assert!(FoldMap::new(d.folds(), d.brackets(), d.buffer()).inline_folds().is_empty());
    }

    #[test]
    fn fold_at_carets_acts_on_every_caret() {
        use crate::{fold_map::FoldMap, SelectionSet};
        // Two inline blocks: {x} at 1..3 and {y} at 6..8.
        let mut d = doc("a{x}\nb{y}");
        d.set_selections(SelectionSet::from_offsets(&[2, 7])); // a caret inside each
        assert!(d.fold_at_carets(false), "Ctrl+Shift+[ folds at every caret");
        let m = FoldMap::new(d.folds(), d.brackets(), d.buffer());
        assert_eq!(m.inline_folds().len(), 2, "both blocks collapsed, not just the primary");
        // …and unfold at every caret.
        assert!(d.fold_at_carets(true), "Ctrl+Shift+] unfolds at every caret");
        assert!(
            FoldMap::new(d.folds(), d.brackets(), d.buffer()).inline_folds().is_empty(),
            "both blocks expanded",
        );
    }

    #[test]
    fn fold_map_cache_matches_a_fresh_build_across_changes() {
        // The memoized fold_map() must DEEP-EQUAL a from-scratch build. It is
        // shifted in place on a no-line-change edit, so the drift risk is an
        // inline fold's offsets diverging from a fresh resolve — this exercises
        // both a block and an inline fold across folds, plain typing (in-place
        // shift, cumulative), and a newline (line change → rebuild fallback).
        fn consistent(d: &Document) -> bool {
            *d.fold_map() == crate::fold_map::FoldMap::new(d.folds(), d.brackets(), d.buffer())
        }
        let mut d = doc("a {\nx\n}\nb = [1, 2, 3]\nc\n");
        assert!(consistent(&d), "empty folds");
        // Fold a block AND an inline pair (the inline offsets are the shift risk).
        let block = d.text().find('{').unwrap() as u32;
        let inline = d.text().find('[').unwrap() as u32;
        d.toggle_fold_opener(block);
        d.toggle_fold_opener(inline);
        assert!(consistent(&d), "after folds — rebuilt on the generation");
        // A plain char at offset 0 (visible, before both folds) shifts the inline
        // fold's offsets; the cache is shifted in place, not rebuilt.
        d.edit(vec![EditOp::insert(0, "Z")]).unwrap();
        assert!(consistent(&d), "after a no-line-change edit — shifted in place");
        d.edit(vec![EditOp::insert(0, "Y")]).unwrap();
        assert!(consistent(&d), "after a second in-place shift (cumulative)");
        // A newline changes the line count → the cache falls back to a rebuild.
        d.edit(vec![EditOp::insert(0, "\n")]).unwrap();
        assert!(consistent(&d), "after a line change — rebuilt");
        d.edit(vec![EditOp::insert(0, "W")]).unwrap();
        assert!(consistent(&d), "after an edit following a rebuild");
    }

    #[test]
    fn deleting_into_a_folded_interior_rebuilds_not_drifts() {
        // A deletion whose OLD range reached a folded block's hidden interior
        // (the newline ending the header line) is NOT caught by `expand` (which
        // probes only the collapsed new endpoint, landing on a visible row), so
        // the incremental mover must detect the span change and rebuild rather
        // than rigidly shift — a rigid shift would diverge from a fresh build, and
        // underflow `vgap` for a fold headed on row 0.
        let consistent = |d: &Document| {
            *d.fold_map() == crate::fold_map::FoldMap::new(d.folds(), d.brackets(), d.buffer())
        };
        for prefix in ["xx\n", ""] {
            // With "xx\n" the fold heads on row 1; with "" it heads on row 0 (vgap 0,
            // the underflow variant).
            let mut d = doc(&format!("{prefix}fn foo() {{\n  body\n}}\nafter\n"));
            let open = d.text().find('{').unwrap() as u32;
            d.toggle_fold_opener(open);
            let _ = d.fold_map();
            assert!(consistent(&d), "{prefix:?}: folded");
            let nl = open + d.text()[open as usize..].find('\n').unwrap() as u32;
            d.edit(vec![EditOp::delete(nl..nl + 1)]).unwrap(); // delete the header newline
            assert!(consistent(&d), "{prefix:?}: after deleting the header-terminating newline");
        }
    }

    #[test]
    fn fold_map_cache_matches_fresh_build_under_random_edits() {
        // The drift oracle as a random walk: the incrementally-shifted fold cache
        // must DEEP-EQUAL a from-scratch build after EVERY edit — line inserts and
        // deletes at arbitrary offsets (the new O(log) block-region reanchor + the
        // inline row/offset shift), multi-line inserts, and edits that land in a
        // fold interior (expand → generation rebuild). All paths must stay consistent.
        let consistent = |d: &Document| {
            *d.fold_map() == crate::fold_map::FoldMap::new(d.folds(), d.brackets(), d.buffer())
        };
        let mut state = 0xF01D_5EEDu32;
        let mut next = || {
            state ^= state << 13;
            state ^= state >> 17;
            state ^= state << 5;
            state
        };
        let mut d = doc(&"fn f() {\n  x = [1, 2]\n  y\n}\n".repeat(6));
        for open in d.collapsible_pairs().iter().map(|&(o, ..)| o).collect::<Vec<_>>() {
            d.toggle_fold_opener(open);
        }
        assert!(consistent(&d), "after collapse-all");
        for step in 0..1500 {
            let len = d.buffer().len();
            if len == 0 {
                break;
            }
            let at = next() % (len + 1);
            let _ = match next() % 6 {
                0 => d.edit(vec![EditOp::insert(at, "\n")]),       // single-line insert
                1 => d.edit(vec![EditOp::insert(at, "z")]),        // plain char, no line change
                2 => d.edit(vec![EditOp::insert(at, "ab\ncd")]),   // multi-line insert
                3 => d.edit(vec![EditOp::insert(at, "  ")]),       // whitespace, no line change
                _ if at < len => {
                    let end = (at + 1 + next() % 5).min(len); // delete (may cross a newline)
                    d.edit(vec![EditOp::delete(at..end)])
                }
                _ => d.edit(vec![EditOp::insert(at, "q")]),
            };
            assert!(consistent(&d), "step {step}: cache drifted from a fresh build (at {at})");
        }
    }

    #[test]
    fn keystroke_and_arrow_do_not_rebuild_the_fold_map_at_scale() {
        // The per-keystroke fold GATE (the analog of the widget draw-budget gate):
        // with a document-scale set collapsed, a plain typed character and an
        // arrow key must NOT rebuild the whole FoldMap (O(folds)) — the cache is
        // shifted in place / read, never rebuilt. A per-keystroke `FoldMap::new`
        // (a common source of typing lag) would trip this.
        use crate::fold_map::FOLD_BUILDS;
        let mut text = String::new();
        for i in 0..300 {
            text.push_str(&format!("fn f{i}() {{\n    body\n}}\n"));
        }
        let mut d = doc(&text);
        let opens: Vec<u32> = d.collapsible_pairs().into_iter().map(|(o, ..)| o).collect();
        assert!(opens.len() >= 300, "every block is foldable");
        d.set_selections(SelectionSet::from_offsets(&opens));
        d.fold_at_carets(false); // collapse everything
        d.set_selections(SelectionSet::new(0)); // caret at the visible top
        let _ = d.fold_map(); // warm the cache

        // A plain keystroke at a visible position, then a render-style map read.
        let base = FOLD_BUILDS.with(std::cell::Cell::get);
        d.type_char('x');
        let _ = d.fold_map();
        assert_eq!(
            FOLD_BUILDS.with(std::cell::Cell::get) - base,
            0,
            "a keystroke over {} folds must not rebuild the FoldMap",
            opens.len()
        );

        // An arrow key (movement reads the memoized map, not a throwaway build).
        let base = FOLD_BUILDS.with(std::cell::Cell::get);
        d.move_carets(Motion::Down, false);
        let _ = d.fold_map();
        assert_eq!(
            FOLD_BUILDS.with(std::cell::Cell::get) - base,
            0,
            "an arrow key over {} folds must not rebuild the FoldMap",
            opens.len()
        );

        // Adding a NEWLINE at the start changes the line count — the
        // "insert lines at the top with everything folded" case. The incremental
        // region-tree reanchor shifts every fold's rows in O(log) at one seam, so
        // it must NOT rebuild. A line-change fallback that rebuilt the whole
        // O(folds) FoldMap every keystroke would trip this.
        d.set_selections(SelectionSet::new(0));
        let base = FOLD_BUILDS.with(std::cell::Cell::get);
        d.edit(vec![EditOp::insert(0, "\n")]).unwrap();
        let _ = d.fold_map();
        assert_eq!(
            FOLD_BUILDS.with(std::cell::Cell::get) - base,
            0,
            "a newline at the top over {} folds must not rebuild the FoldMap",
            opens.len()
        );
    }

    #[test]
    fn undo_and_redo_build_the_fold_map_once() {
        // Undo/redo can't shift the memo through their patches (the whole-set
        // reconcile they run bumps the fold generation), so ONE rebuild each is
        // the floor. The restore's caret ejection must BE that rebuild — the
        // memo, which the next render then reads — not a throwaway
        // `FoldMap::new` the render follows with a second O(folds) build.
        use crate::fold_map::FOLD_BUILDS;
        let mut text = String::new();
        for i in 0..50 {
            text.push_str(&format!("fn f{i}() {{\n    body\n}}\n"));
        }
        let mut d = doc(&text);
        let opens: Vec<u32> = d.collapsible_pairs().into_iter().map(|(o, ..)| o).collect();
        d.set_selections(SelectionSet::from_offsets(&opens));
        d.fold_at_carets(false); // collapse everything
        // A caret at the start of every header row — visible, and outside the
        // fold it heads, so the typed unit leaves every fold collapsed.
        d.move_carets(Motion::LineStart, false);
        d.type_char('x');
        assert_eq!(d.folds().len(), opens.len(), "typing before the headers folds nothing open");
        let _ = d.fold_map(); // warm the memo
        let builds = |d: &mut Document, step: fn(&mut Document) -> bool| {
            let base = FOLD_BUILDS.with(std::cell::Cell::get);
            assert!(step(d));
            let _ = d.fold_map(); // the render's read
            FOLD_BUILDS.with(std::cell::Cell::get) - base
        };
        assert_eq!(builds(&mut d, Document::undo), 1, "undo + render build the fold map once");
        assert_eq!(builds(&mut d, Document::redo), 1, "redo + render build the fold map once");
    }

    #[test]
    fn keystroke_with_document_scale_decorations_does_not_resort_the_store() {
        // The per-keystroke DECORATION gate: typing with a document-scale
        // decoration set present must NOT re-sort the whole store — apply_patch
        // shifts in place (a monotonic patch keeps order) and the autoclose scans
        // hit only the (here empty) own auto-close store. An O(D log D) full-store
        // sort every commit would trip this.
        use crate::decorations::DECORATION_SORTS;
        use crate::{Diagnostic, Severity};
        let mut d = doc(&"let x = 1;\n".repeat(2000)); // 22k bytes
        let rev = d.revision();
        let diags: Vec<Diagnostic> = (0..2000u32)
            .map(|i| Diagnostic::new(i * 10..i * 10 + 3, Severity::Warning, "w"))
            .collect();
        d.set_diagnostics(rev, diags); // publishes (sorts once, here — not per keystroke)
        d.set_selections(SelectionSet::new(0));

        let base = DECORATION_SORTS.with(std::cell::Cell::get);
        d.type_char('z');
        assert_eq!(
            DECORATION_SORTS.with(std::cell::Cell::get) - base,
            0,
            "a keystroke with 2000 diagnostics must not re-sort the decoration store"
        );
    }

    #[test]
    fn reconcile_scans_the_fold_set_only_when_a_fold_actually_breaks() {
        // reconcile drops folds whose pair an edit broke. Two tightenings are gated
        // here. (1) A non-bracket edit — a letter, or an Enter (a line change with
        // no bracket char) — leaves every pairing intact, so it must not touch the
        // fold set at all. (2) Even a BRACKET edit that breaks no existing fold must
        // not scan (retain) the whole fold set: the windowed reconcile checks only
        // the folds its re-matched region covers and mutates nothing when none
        // broke. Only an edit that actually breaks a fold pays the O(folds) removal.
        use crate::fold_map::RECONCILE_SCANS;
        let mut d = doc("fn f() {\n  body\n}\ntail\n");
        let open = d.text().find('{').unwrap() as u32;
        assert!(d.toggle_fold_opener(open));
        d.set_selections(SelectionSet::new(0));

        // "a"/"\n": no bracket char → reconcile never runs. "{": a bracket edit
        // that re-pairs but breaks no fold (the block's own pair stays matched) →
        // the windowed reconcile inspects the fold and drops nothing, so still no
        // whole-set scan.
        for text in ["a", "\n", "{"] {
            let base = RECONCILE_SCANS.with(std::cell::Cell::get);
            d.edit(vec![EditOp::insert(0, text)]).unwrap();
            assert_eq!(
                RECONCILE_SCANS.with(std::cell::Cell::get) - base,
                0,
                "inserting {text:?} breaks no fold, so it must not scan the fold set"
            );
        }

        // Deleting the block's `}` breaks its pair → the fold must drop → one scan.
        let close = d.text().rfind('}').unwrap() as u32;
        let base = RECONCILE_SCANS.with(std::cell::Cell::get);
        d.edit(vec![EditOp::delete(close..close + 1)]).unwrap();
        assert!(
            RECONCILE_SCANS.with(std::cell::Cell::get) - base >= 1,
            "deleting a brace that breaks a fold must reconcile the fold set"
        );
        assert!(d.folds().is_empty(), "the broken fold was dropped");
    }

    #[test]
    fn windowed_reconcile_matches_the_whole_set_reconcile_under_random_edits() {
        use crate::SelectionSet;
        // The edit-path windowed reconcile must drop EXACTLY the folds the whole-set
        // reconcile would. Oracle: after each random bracket-heavy edit, an extra
        // whole-set reconcile must be a no-op (find nothing more to drop). A window
        // that misses a broken fold — e.g. an enclosing fold whose partner an edit
        // deletes far from its opener, so the post-edit brackets no longer flag it
        // as enclosing — diverges here immediately. A naive window that omits the
        // seed-stack (enclosing) left edge would fail this.
        let mut src = String::new();
        for i in 0..40 {
            src.push_str(&format!("block{i} {{\n  a\n  b\n}}\n"));
        }
        let mut d = doc(&src);
        for open in d.collapsible_pairs().iter().map(|&(o, ..)| o).collect::<Vec<_>>() {
            d.toggle_fold_opener(open);
        }
        // Deterministic LCG — no rand crate, no Date::now (both banned in tests).
        let mut state: u32 = 0x1234_5678;
        let mut rng = || {
            state = state.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
            state
        };
        for _ in 0..300 {
            let len = d.buffer().len();
            if len == 0 {
                break;
            }
            let pos = rng() % len;
            match rng() % 5 {
                0 => {
                    d.set_selections(SelectionSet::new(pos));
                    d.insert_text("{");
                }
                1 => {
                    d.set_selections(SelectionSet::new(pos));
                    d.insert_text("}");
                }
                2 if len > 1 => {
                    // Delete one byte, char-snapped (the doc is ASCII, so pos is a
                    // boundary), biased toward braces to break pairs often.
                    let s = pos.min(len - 1);
                    d.edit(vec![EditOp::delete(s..s + 1)]).unwrap();
                }
                _ => {
                    d.set_selections(SelectionSet::new(pos));
                    d.insert_text("x");
                }
            }
            let before: Vec<u32> = d.folds().iter().collect();
            d.force_whole_reconcile();
            let after: Vec<u32> = d.folds().iter().collect();
            assert_eq!(before, after, "windowed reconcile missed a fold the whole-set pass caught");
            // Every surviving fold is a genuine foldable pair — no orphan left behind.
            for o in after {
                let foldable = d
                    .brackets()
                    .at(o)
                    .filter(|b| b.open)
                    .and_then(|b| b.partner)
                    .is_some_and(|c| crate::row_layout::pair_has_interior(o, c));
                assert!(foldable, "a surviving fold at {o} is not a foldable pair");
            }
        }
    }

    #[test]
    fn fold_at_carets_ejects_carets_hidden_by_a_block() {
        use crate::SelectionSet;
        let mut d = doc("a {\nhidden\n}\nb"); // block: { at 2, } at 11 (rows 0..=2)
        let inside = d.buffer().point_to_offset(Point::new(1, 3)); // inside "hidden"
        d.set_selections(SelectionSet::new(inside));
        assert!(d.fold_at_carets(false), "the block folds");
        // The caret sat on a now-hidden interior row — the batched ejection must
        // pull it to the visible header row, never leave it on invisible text.
        let row = d.buffer().offset_to_point(d.selections().newest().head()).row;
        assert_eq!(row, 0, "caret ejected to the header row");
    }

    #[test]
    fn fold_at_carets_ejects_a_caret_on_the_closing_rows_indent() {
        // Fails-first: the batched ejection read only rows STRICTLY inside a
        // block as hidden, so a caret in the closing row's leading whitespace —
        // which renders nowhere (`display_position` is `None` there) — stayed
        // put after Ctrl+Shift+[, where the single-fold toggle ejected it.
        use crate::SelectionSet;
        let mut d = doc("m {\n  a\n  }\nz"); // rows: "m {", "  a", "  }", "z"
        d.set_selections(SelectionSet::new(d.buffer().point_to_offset(Point::new(2, 1))));
        assert!(d.fold_at_carets(false), "the block folds");
        let head = d.selections().newest().head();
        assert_eq!(head, d.buffer().point_to_offset(Point::new(0, 3)), "ejected to the header's end");
        assert!(d.fold_map().display_position(d.buffer(), head, d.tab_size()).is_some());
    }

    #[test]
    fn caret_ejection_hides_exactly_what_display_position_cannot_place() {
        // The one "hidden" owner, checked against THE owner of where an offset
        // renders: over every offset of documents with every pair collapsed,
        // `entry_edge_if_hidden` ejects exactly the offsets `display_position`
        // cannot place (a block's gap, its closing row's indent) plus an inline
        // gap's interior, which `display_position` clips to the chip instead.
        for text in [
            "m {\n  a\n  }\nz",
            "m {\n\ta\n\t}\nz",
            "m {\n  [1, 2]\n  }",
            "m { [1, 2]\n  a\n  }",
            "x [1, 2] y",
            "a {\n  b {\n    c\n  }\n  d\n}\n",
        ] {
            let mut d = doc(text);
            let openers: Vec<u32> = d.collapsible_pairs().into_iter().map(|(o, ..)| o).collect();
            d.set_selections(SelectionSet::from_offsets(&openers));
            d.fold_at_carets(false);
            let map = d.fold_map();
            for off in 0..=d.buffer().len() {
                let unplaceable = map.display_position(d.buffer(), off, d.tab_size()).is_none();
                let in_inline_gap = map.inline_fold_before(off).is_some_and(|f| f.hides_caret_at(off));
                assert_eq!(
                    map.entry_edge_if_hidden(d.buffer(), off).is_some(),
                    unplaceable || in_inline_gap,
                    "{text:?} @ {off}"
                );
            }
        }
    }

    #[test]
    fn horizontal_movement_hops_an_inline_fold() {
        use crate::{Motion, SelectionSet};
        let mut d = doc("x = [1, 2, 3]"); // `[` at 4, `]` at 12
        d.set_selections(SelectionSet::new(6)); // inside the array
        let op = d.fold_opener_at_caret(false).unwrap();
        assert!(d.toggle_fold_opener(op));
        assert_eq!(d.selections().newest().head(), 5, "caret snapped just after `[`");
        d.move_carets(Motion::Right, false);
        assert_eq!(d.selections().newest().head(), 12, "Right hops the collapsed interior to `]`");
        d.move_carets(Motion::Left, false);
        assert_eq!(d.selections().newest().head(), 5, "Left hops back to just after `[`");
    }

    #[test]
    fn collapsible_at_prefers_the_innermost() {
        // A block `{ … }` containing an inline `[ … ]` — nested collapsibles.
        let d = doc("fn m() {\n    let x = [1, 2, 3];\n}");
        let mut pairs = d.collapsible_pairs();
        pairs.sort();
        assert_eq!(pairs, vec![(7, 32, 0, 2), (21, 29, 1, 1)]);
        // Inside the array → the tighter inline pair wins over its enclosing block.
        assert_eq!(d.collapsible_at(24), Some(21));
        // Inside the block but left of the array → the block.
        assert_eq!(d.collapsible_at(12), Some(7));
        // On the `fn` header, before the `{` → nothing collapsible.
        assert_eq!(d.collapsible_at(0), None);
    }

    #[test]
    fn collapsible_excludes_the_already_folded() {
        let mut d = doc("fn m() {\n    let x = [1, 2, 3];\n}");
        // Fold the block; it drops out of the candidate set (nothing left to
        // collapse), but the inline array inside stays reachable.
        assert!(d.toggle_fold_opener(7));
        let openers: Vec<u32> = d.collapsible_pairs().iter().map(|&(o, ..)| o).collect();
        assert_eq!(openers, vec![21]);
        assert_eq!(d.collapsible_at(12), None, "the folded block is no longer a target");
        assert_eq!(d.collapsible_at(24), Some(21), "the array inside it still is");
    }

    #[test]
    fn nested_inline_folds_reduce_to_the_outer() {
        use crate::fold_map::FoldMap;
        // `(` at 10, `[` at 14, `]` at 22, `)` at 23 — the params contain the array.
        let mut d = doc("outer_call(a, [1, 2, 3])");
        assert!(d.toggle_fold_opener(14)); // collapse the array first
        assert!(d.toggle_fold_opener(10)); // then the outer_call params around it
        let inline = |d: &Document| {
            FoldMap::new(d.folds(), d.brackets(), d.buffer()).inline_folds().iter().map(|f| f.open).collect::<Vec<_>>()
        };
        // Only the outer `( … )` chip renders; the array is hidden inside it.
        assert_eq!(inline(&d), vec![10]);
        // Expanding the params reveals the array, still collapsed (state preserved).
        assert!(d.toggle_fold_opener(10));
        assert_eq!(inline(&d), vec![14]);
    }

    #[test]
    fn horizontal_movement_hops_the_collapsed_gap() {
        use crate::{BufferRow, Motion, Point, SelectionSet};
        // rows: 0 "m {", 1 "  a", 2 "  b", 3 "}", 4 "after"
        let mut d = doc("m {\n  a\n  b\n}\nafter");
        assert!(d.fold(BufferRow(0), BufferRow(3))); // collapse; the tail is row 3 `}`
        let caret = |d: &Document| d.buffer().offset_to_point(d.selections().newest().head());
        // Caret at the end of the header line "m {" (row 0, col 3).
        d.set_selections(SelectionSet::new(d.buffer().point_to_offset(Point::new(0, 3))));
        d.move_carets(Motion::Right, false);
        assert_eq!(caret(&d), Point::new(3, 0), "Right hops the hidden interior to the closing bracket");
        d.move_carets(Motion::Left, false);
        assert_eq!(caret(&d), Point::new(0, 3), "Left hops back to the header end");
    }

    #[test]
    fn vertical_move_skips_folds() {
        use crate::{BufferRow, Motion, Point, SelectionSet};
        let mut d = doc("L0\n{\nL2\nL3\n}\nL5");
        assert!(d.fold(BufferRow(1), BufferRow(4))); // { on row 1 … } on row 4 — hide rows 2,3,4
        let row = |d: &Document| d.buffer().offset_to_point(d.selections().newest().head()).row;
        // Caret on the header row L1; Down lands on L5 (the fold interior is skipped).
        d.set_selections(SelectionSet::new(d.buffer().point_to_offset(Point::new(1, 0))));
        d.move_carets(Motion::Down, false);
        assert_eq!(row(&d), 5);
        // Up from L5 lands back on the header L1, never inside the fold.
        d.move_carets(Motion::Up, false);
        assert_eq!(row(&d), 1);
    }

    #[test]
    fn typing_into_an_inline_folds_gap_expands_it() {
        use crate::SelectionSet;
        // `x = [1, 2, 3]` — fold the pair; the caret is pulled to just after
        // `[` (offset 5). Typing there would insert a CHIP-HIDDEN character,
        // so the edit expands the fold to reveal itself.
        let mut d = doc("x = [1, 2, 3]");
        d.set_selections(SelectionSet::new(6));
        assert!(d.toggle_fold_opener(4));
        assert_eq!(d.selections().newest().head(), 5, "caret ejected to the left edge");
        d.type_char('9');
        assert!(!d.folds().is_folded(4), "editing hidden text expands the fold");
        assert_eq!(d.text(), "x = [91, 2, 3]");
    }

    #[test]
    fn typing_at_a_collapsed_headers_end_keeps_it_folded() {
        use crate::{Point, SelectionSet};
        // Rows: 0 "m {", 1 "  a", 2 "}" — fold, caret ejected to the header's
        // end (a VISIBLE position, just before the `…`): typing there edits
        // the header line in plain sight, so the fold stays collapsed.
        let mut d = doc("m {\n  a\n}");
        d.set_selections(SelectionSet::new(d.buffer().point_to_offset(Point::new(1, 0))));
        let opener = 2;
        assert!(d.toggle_fold_opener(opener));
        d.type_char('x'); // header line becomes "m {x"... still one visible edit
        assert!(d.folds().is_folded(opener), "a visible-part edit leaves the fold alone");
        assert!(d.text().starts_with("m {x\n"));
    }

    #[test]
    fn undo_into_a_folded_region_expands_it() {
        use crate::{Point, SelectionSet};
        // Type inside the (unfolded) block, then fold, then undo: the revert
        // touches now-hidden text, so the fold expands to show it — the same
        // reveal rule as forward edits, through the same seam.
        let mut d = doc("m {\n  a\n}");
        d.set_selections(SelectionSet::new(d.buffer().point_to_offset(Point::new(1, 3))));
        d.type_char('b'); // "  ab" on row 1
        let opener = 2;
        assert!(d.toggle_fold_opener(opener));
        assert!(d.folds().is_folded(opener));
        assert!(d.undo());
        assert!(!d.folds().is_folded(opener), "undoing hidden text reveals it");
        assert!(d.text().contains("\n  a\n"), "the typed char was reverted");
    }

    #[test]
    fn folding_a_block_ejects_a_hidden_caret_to_the_header_end() {
        use crate::{Point, SelectionSet};
        // Rows: 0 "m {", 1 "  a", 2 "  }" — the `{` at offset 2.
        let mut d = doc("m {\n  a\n  }");
        let opener = 2;
        // A caret on an interior row is ejected to the header line's end…
        d.set_selections(SelectionSet::new(d.buffer().point_to_offset(Point::new(1, 2))));
        assert!(d.toggle_fold_opener(opener));
        assert_eq!(
            d.selections().newest().head(),
            d.buffer().point_to_offset(Point::new(0, 3)),
            "the hidden caret ejects to just before the placeholder"
        );
        assert!(d.toggle_fold_opener(opener)); // unfold
        // …a caret in the tail row's leading whitespace (also hidden) ejects…
        d.set_selections(SelectionSet::new(d.buffer().point_to_offset(Point::new(2, 1))));
        assert!(d.toggle_fold_opener(opener));
        assert_eq!(d.selections().newest().head(), d.buffer().point_to_offset(Point::new(0, 3)));
        assert!(d.toggle_fold_opener(opener)); // unfold
        // …but a caret ON the visible tail (the `}`) stays exactly put.
        let on_tail = d.buffer().point_to_offset(Point::new(2, 2));
        d.set_selections(SelectionSet::new(on_tail));
        assert!(d.toggle_fold_opener(opener));
        assert_eq!(d.selections().newest().head(), on_tail, "the visible tail is not ejected");
    }

    #[test]
    fn fold_chord_works_when_the_caret_touches_a_bracket() {
        use crate::SelectionSet;
        // `x = [1, 2, 3]` — `[` at 4, `]` at 12.
        let mut d = doc("x = [1, 2, 3]");
        // Caret just BEFORE the `[` (offset 4): touching the opener folds.
        d.set_selections(SelectionSet::new(4));
        assert_eq!(d.fold_opener_at_caret(false), Some(4), "touching the opener from the left");
        // Caret just AFTER the `]` (offset 13): touching the closer folds.
        d.set_selections(SelectionSet::new(13));
        assert_eq!(d.fold_opener_at_caret(false), Some(4), "touching the closer from the right");
        // …and once collapsed, the same touching positions unfold it.
        assert!(d.toggle_fold_opener(4));
        assert_eq!(d.fold_opener_at_caret(true), Some(4), "touching unfolds too");
        // Away from the pair entirely: nothing to fold.
        assert!(d.toggle_fold_opener(4));
        d.set_selections(SelectionSet::new(1));
        assert_eq!(d.fold_opener_at_caret(false), None);
    }

    #[test]
    fn fold_chord_at_a_shared_boundary_picks_the_touched_inner_pair() {
        use crate::SelectionSet;
        // `{a [b] c}` — outer `{` 0 / `}` 8, inner `[` 3 / `]` 5. A caret just
        // after the inner `]` (offset 6) is inside the block AND touching the
        // inline pair — the tighter, touched pair wins.
        let d = {
            let mut d = doc("{a [b] c}");
            d.set_selections(SelectionSet::new(6));
            d
        };
        assert_eq!(d.fold_opener_at_caret(false), Some(3), "the touched inline pair beats the enclosing block");
    }

    #[test]
    fn vertical_goal_is_a_display_cell_across_tab_stops() {
        use crate::{Motion, Point, SelectionSet};
        // Row 0: a tab then "ab" — the caret after the tab sits at CELL 4.
        // Row 1: plain "xxxxxxxxxx". The vertical goal is the visual column, so
        // it lands at cell 4 = col 4, not the byte column (col 1) far to the left.
        let mut d = doc("\tab\nxxxxxxxxxx");
        d.set_selections(SelectionSet::new(d.buffer().point_to_offset(Point::new(0, 1))));
        d.move_carets(Motion::Down, false);
        assert_eq!(
            d.buffer().offset_to_point(d.selections().newest().head()),
            Point::new(1, 4),
            "the goal is the visual column, not the byte column"
        );
        // And back up: cell 4 re-resolves to just after the tab (col 1).
        d.move_carets(Motion::Up, false);
        assert_eq!(d.buffer().offset_to_point(d.selections().newest().head()), Point::new(0, 1));
    }

    #[test]
    fn vertical_move_through_a_collapsed_tail_stays_visual() {
        use crate::{BufferRow, Motion, Point, SelectionSet};
        // Rows: 0 "m {", 1 "a", 2 "} t", 3 "abcdefgh"; fold rows 0..=2. The
        // collapsed line reads `m { … } t` — the tail renders at cells 7…10.
        let mut d = doc("m {\na\n} t\nabcdefgh");
        assert!(d.fold(BufferRow(0), BufferRow(2)));
        // Caret at the tail's end (row 2, col 3) — display cell 10.
        d.set_selections(SelectionSet::new(d.buffer().point_to_offset(Point::new(2, 3))));
        d.move_carets(Motion::Down, false);
        assert_eq!(
            d.buffer().offset_to_point(d.selections().newest().head()),
            Point::new(3, 8),
            "Down from the far-right tail lands at the row's visual end, not byte col 3"
        );
        // Up from cell 8 lands back ON the visible tail (row 2), not the header text.
        d.move_carets(Motion::Up, false);
        assert_eq!(
            d.buffer().offset_to_point(d.selections().newest().head()).row,
            2,
            "a goal over the placeholder tail resolves onto the tail"
        );
    }

    #[test]
    fn vertical_landing_snaps_out_of_a_collapsed_inline_gap() {
        use crate::{Motion, Point, SelectionSet};
        // Row 0 plain; row 1 has `[123456]` collapsed — its chip spans cells
        // 2..5. A goal cell on the chip snaps to the landable left edge,
        // never a hidden interior slot.
        let mut d = doc("aaaaaaaaaa\nx[123456]y");
        let opener = d.buffer().text().find('[').unwrap() as u32;
        assert!(d.toggle_fold_opener(opener));
        d.set_selections(SelectionSet::new(d.buffer().point_to_offset(Point::new(0, 3))));
        d.move_carets(Motion::Down, false);
        assert_eq!(
            d.selections().newest().head(),
            opener + 1,
            "a landing on the chip snaps to just after the opening bracket"
        );
    }

    #[test]
    fn home_and_end_operate_on_the_collapsed_display_line() {
        use crate::{BufferRow, Motion, Point, SelectionSet};
        // Rows: 0 "L0", 1 "  m {", 2 "a", 3 "  }" — the collapsed display line
        // reads `  m { … }`, with the tail `}` a real position on row 3.
        let mut d = doc("L0\n  m {\na\n  }");
        assert!(d.fold(BufferRow(1), BufferRow(3)));
        let head = |d: &Document| d.selections().newest().head();
        // End on the collapsed HEADER goes past the visible tail — the last
        // row's end — not to the header text's own end mid-placeholder.
        d.set_selections(SelectionSet::new(d.buffer().point_to_offset(Point::new(1, 2))));
        d.move_carets(Motion::LineEnd, false);
        assert_eq!(head(&d), d.buffer().point_to_offset(Point::new(3, 3)), "End lands after the tail brace");
        // Home from the TAIL goes to the display line's start: the header's
        // first non-whitespace…
        d.move_carets(Motion::LineStart, false);
        assert_eq!(head(&d), d.buffer().point_to_offset(Point::new(1, 2)), "Home jumps to the header's smart start");
        // …and a second Home (now on the header) toggles to column 0.
        d.move_carets(Motion::LineStart, false);
        assert_eq!(head(&d), d.buffer().point_to_offset(Point::new(1, 0)));
        // Unfolded, End is the plain line end again.
        assert!(d.unfold(BufferRow(1)));
        d.set_selections(SelectionSet::new(d.buffer().point_to_offset(Point::new(1, 2))));
        d.move_carets(Motion::LineEnd, false);
        assert_eq!(head(&d), d.buffer().point_to_offset(Point::new(1, 5)), "plain End at the header's own end");
    }

    #[test]
    fn foldable_ranges_from_multiline_brackets() {
        // Rows: 0 `mod m {`, 1 `fn f() {`, 2 `if x {`, 3 `a`, 4 `}`, 5 `}`,
        // 6 `g()` (single-line), 7 `}`.
        let d = doc("mod m {\n    fn f() {\n        if x {\n            a\n        }\n    }\n    g()\n}");
        let pairs: Vec<(u32, u32)> = d.foldable_ranges().iter().map(|(h, l)| (h.0, l.0)).collect();
        // Every multi-line pair; the single-line `q()` is not foldable.
        assert_eq!(pairs, vec![(0, 7), (1, 5), (2, 4)]);
    }

    #[test]
    fn fold_dropped_when_its_bracket_pair_is_broken() {
        use crate::{fold_map::FoldMap, BufferRow};
        // 0 "m {", 1 "  a", 2 "  b", 3 "}", 4 "after"
        let mut d = doc("m {\n  a\n  b\n}\nafter");
        assert_eq!(d.foldable_ranges().iter().map(|(h, l)| (h.0, l.0)).collect::<Vec<_>>(), vec![(0, 3)]);
        assert!(d.fold(BufferRow(0), BufferRow(3)));
        assert_eq!(FoldMap::new(d.folds(), d.brackets(), d.buffer()).display_row_count(), 2); // header + "after"

        // Delete only the `}` line (row 3). Its interior rows 1,2 are untouched, so
        // the fold rides the patch and would survive — orphaning rows 1,2 behind a
        // header that no longer draws a chevron. reconcile_folds must drop it.
        let s = d.buffer().point_to_offset(crate::Point::new(3, 0));
        let e = d.buffer().point_to_offset(crate::Point::new(4, 0));
        d.edit(vec![EditOp::delete(s..e)]).unwrap();
        assert!(d.foldable_ranges().is_empty(), "no closing brace ⇒ nothing foldable");
        assert!(d.folds().is_empty(), "invalidated fold dropped, not left orphaning hidden rows");
        assert_eq!(
            FoldMap::new(d.folds(), d.brackets(), d.buffer()).display_row_count(),
            d.buffer().line_count(),
            "every row is visible again"
        );
    }

    #[test]
    fn valid_fold_survives_edit_above() {
        use crate::{fold_map::FoldMap, BufferRow, SelectionSet};
        let mut d = doc("m {\n  a\n  b\n}\nafter");
        assert!(d.fold(BufferRow(0), BufferRow(3)));
        // Insert a line above the block: the fold stays valid (it still matches a
        // foldable range, now shifted down one row) — reconcile must NOT drop it.
        d.set_selections(SelectionSet::new(0));
        d.insert_text("top\n");
        assert_eq!(d.foldable_ranges().iter().map(|(h, l)| (h.0, l.0)).collect::<Vec<_>>(), vec![(1, 4)]);
        assert_eq!(d.folds().len(), 1, "the still-valid fold is kept");
        let m = FoldMap::new(d.folds(), d.brackets(), d.buffer());
        assert_eq!(m.fold_at_header(BufferRow(1)), Some(BufferRow(4)));
        assert!(m.is_folded(BufferRow(2)) && m.is_folded(BufferRow(3)) && m.is_folded(BufferRow(4)));
    }

    #[test]
    fn breaking_one_block_keeps_a_sibling_fold() {
        use crate::{fold_map::FoldMap, BufferRow};
        // Two sibling blocks: A rows 0-2, B rows 3-5, then "after".
        // 0 "a {", 1 "  x", 2 "}", 3 "b {", 4 "  y", 5 "}", 6 "after"
        let mut d = doc("a {\n  x\n}\nb {\n  y\n}\nafter");
        assert_eq!(d.foldable_ranges().iter().map(|(h, l)| (h.0, l.0)).collect::<Vec<_>>(), vec![(0, 2), (3, 5)]);
        assert!(d.fold(BufferRow(0), BufferRow(2)));
        assert!(d.fold(BufferRow(3), BufferRow(5)));
        assert_eq!(d.folds().len(), 2);
        // Delete block B's `}` (row 5). B is no longer foldable; A is untouched —
        // only B's fold should drop.
        let s = d.buffer().point_to_offset(crate::Point::new(5, 0));
        let e = d.buffer().point_to_offset(crate::Point::new(6, 0));
        d.edit(vec![EditOp::delete(s..e)]).unwrap();
        assert_eq!(d.folds().len(), 1, "only the broken block's fold drops");
        let m = FoldMap::new(d.folds(), d.brackets(), d.buffer());
        assert_eq!(m.fold_at_header(BufferRow(0)), Some(BufferRow(2)), "sibling A still collapsed");
        assert_eq!(m.fold_at_header(BufferRow(3)), None, "B is no longer folded");
    }

    #[test]
    fn fold_drops_when_its_interior_is_deleted() {
        use crate::{fold_map::FoldMap, BufferRow};
        let mut d = doc("L0\n{\nL2\nL3\n}\nL5");
        assert!(d.fold(BufferRow(1), BufferRow(4))); // hide rows 2,3,4 (incl. the `}`)
        // Delete rows 2..=4 (their whole byte span, incl. the closing `}`).
        let start = d.buffer().point_to_offset(crate::Point::new(2, 0));
        let end = d.buffer().point_to_offset(crate::Point::new(5, 0));
        d.edit(vec![EditOp::delete(start..end)]).unwrap();
        assert!(d.folds().is_empty(), "fold dropped when its interior text is deleted");
        assert_eq!(FoldMap::new(d.folds(), d.brackets(), d.buffer()).display_row_count(), d.buffer().line_count());
    }

    #[test]
    fn intel05_diagnostic_keeps_byte_offsets_on_a_multibyte_line() {
        // The core stores and returns diagnostics as BYTE spans, never
        // pre-converted to cells — so the render does the byte→cell mapping
        // exactly once (display_map::expand). "aé=x": é is 2 bytes / 1 cell, so
        // "x" is byte 4 but cell 3.
        use crate::{Diagnostic, Severity};
        let mut d = doc("aé=x");
        d.set_diagnostics(d.revision(), vec![Diagnostic::new(4..5, Severity::Error, "e")]);
        let span = d.diagnostics_in(0..100).next().unwrap().0;
        assert_eq!(span, 4..5, "diagnostics_in returns raw byte offsets, not cells");
        // The single byte→cell mapping places "x" at cell 3: the multibyte é
        // shifted the column by one, not two.
        assert_eq!(crate::display_map::expand(&d.buffer().line(0), span.start, 4), 3);
    }

    #[test]
    fn undo_resyncs_brackets_and_highlight_to_the_reverted_text() {
        const G: &str = "%YAML 1.2\n---\nname: T\nscope: source.t\ncontexts:\n  main:\n    - match: '\\w+'\n      scope: keyword.t\n";
        const TH: &str = r#"<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict><key>settings</key><array><dict><key>settings</key><dict><key>foreground</key><string>#FFFFFF</string></dict></dict></array></dict></plist>"#;
        let mut d = doc("()");
        d.set_syntax(
            crate::SyntaxDef::from_sublime_syntax(G).unwrap(),
            crate::TokenTheme::from_tm_theme(TH).unwrap(),
        );
        d.tokenize_highlight(d.buffer().line_count());
        d.set_selections(SelectionSet::new(1)); // between ( and )
        d.edit(vec![EditOp::insert(1, "[]\n")]).unwrap(); // "([]\n)" — 2 lines, 4 brackets
        d.tokenize_highlight(d.buffer().line_count());
        assert_eq!((d.buffer().line_count(), d.brackets().all().len()), (2, 4));
        assert!(d.undo(), "there was something to undo");
        assert_eq!(d.buffer().text(), "()");
        // The resync ran: brackets re-matched, highlight cache back to one line.
        assert_eq!((d.buffer().line_count(), d.brackets().all().len()), (1, 2));
        d.tokenize_highlight(d.buffer().line_count());
        assert!(d.highlight_line_spans(0).is_some());
        assert!(d.highlight_line_spans(1).is_none(), "no phantom line after undo");
    }

    #[test]
    fn select_all_spans_the_whole_buffer_with_head_at_end() {
        let mut d = doc("abc\ndef"); // 7 bytes
        d.select_all();
        assert_eq!(d.selections().len(), 1);
        let s = d.selections().newest();
        assert_eq!((s.start(), s.end(), s.head()), (0, 7, 7));
    }

    fn query(text: &str) -> crate::FindQuery {
        crate::FindQuery { text: text.into(), case_sensitive: true, ..Default::default() }
    }

    #[test]
    fn find_matches_ride_an_edit_above_them() {
        // The handle-tracked match set remaps across an edit above it.
        let mut d = doc("xx target"); // "target" at 3..9
        d.set_find_query(Some(query("target")), 0);
        assert_eq!(d.find_matches_in(0..100).collect::<Vec<_>>(), vec![(3..9, false)]);
        d.set_selections(SelectionSet::new(0));
        d.edit(vec![EditOp::insert(0, "ab")]).unwrap(); // 2 chars above the match
        // Rode via apply_patch to 5..11 (the repair window near the edit then
        // re-verifies it in place).
        assert_eq!(d.find_matches_in(0..100).collect::<Vec<_>>(), vec![(5..11, false)]);
    }

    #[test]
    fn find_next_prev_start_from_the_caret_and_wrap() {
        // Nearest-from-caret ordering and wrap-around.
        let mut d = doc("foo bar foo baz foo"); // "foo" at 0..3, 8..11, 16..19
        d.set_find_query(Some(query("foo")), 0);
        assert_eq!((d.find_match_count(), d.active_find_match()), (3, None));
        d.set_selections(SelectionSet::new(5)); // between match 0 and 1
        assert_eq!(d.find_next(0), Some(8..11)); // first start ≥ 5
        assert_eq!(d.active_find_match(), Some(1));
        assert_eq!(d.find_next(0), Some(16..19)); // repeated press cycles
        assert_eq!(d.find_next(0), Some(0..3), "wraps to first");
        assert_eq!(d.find_prev(0), Some(16..19), "prev from first wraps to last");
        d.set_selections(SelectionSet::new(0));
        assert_eq!(d.find_prev(0), Some(16..19), "prev before all wraps to last");
    }

    #[test]
    fn active_match_survives_a_rescan_at_the_same_start() {
        // The active match survives an edit that adds matches elsewhere: the
        // commit-path repair makes the new match visible IMMEDIATELY and the
        // untouched active survives by decoration-id stability —
        // `maybe_rescan_find` is a no-op on an uncapped set.
        let mut d = doc("foo foo foo");
        d.set_find_query(Some(query("foo")), 0);
        d.set_selections(SelectionSet::new(4)); // the middle match's start
        d.find_next(0);
        assert_eq!(d.active_find_match(), Some(1));
        d.set_selections(SelectionSet::new(11));
        d.edit(vec![EditOp::insert(11, " foo")]).unwrap(); // a 4th match, below
        assert_eq!(
            (d.find_match_count(), d.active_find_match()),
            (4, Some(1)),
            "current at the commit, active untouched"
        );
        assert!(!d.maybe_rescan_find(1000), "nothing stale to rescan (uncapped)");
        assert_eq!((d.find_match_count(), d.active_find_match()), (4, Some(1)));
    }

    #[test]
    fn find_matches_ride_undo_and_redo_through_the_shared_mover() {
        // Find highlights ride the reverse patch on undo/redo exactly like any
        // forward edit — through the shared decoration mover, with no
        // find-specific undo code — so they stay at their correct positions.
        let mut d = doc("foo bar");
        d.set_find_query(Some(query("foo")), 0);
        assert_eq!(d.find_matches_in(0..100).next().unwrap().0, 0..3);
        d.set_selections(SelectionSet::new(0));
        d.edit(vec![EditOp::insert(0, "xy")]).unwrap(); // "xyfoo bar" → match rides to 2..5
        assert_eq!(d.find_matches_in(0..100).next().unwrap().0, 2..5);
        d.undo(); // back to "foo bar" → match must ride back to 0..3
        assert_eq!(d.buffer().text(), "foo bar");
        assert_eq!(d.find_matches_in(0..100).next().unwrap().0, 0..3, "rode the undo");
        d.redo(); // → 2..5 again
        assert_eq!(d.find_matches_in(0..100).next().unwrap().0, 2..5, "rode the redo");
    }

    #[test]
    fn find_count_reflects_live_matches_after_a_collapse_delete() {
        // A collapse-delete drops a FindMatch decoration in `apply_patch`; the
        // count must follow the live store set. There is no shadow handle list to
        // over-report — the store IS the set.
        let mut d = doc("foo foo"); // matches 0..3 and 4..7
        d.set_find_query(Some(query("foo")), 0);
        assert_eq!(d.find_match_count(), 2);
        d.edit(vec![EditOp::delete(0..4)]).unwrap(); // "foo": collapses match 0
        assert_eq!(d.buffer().text(), "foo");
        assert_eq!(d.find_match_count(), 1, "collapsed match not counted");
        assert_eq!(d.find_matches_in(0..100).count(), 1, "count agrees with render");
    }

    #[test]
    fn find_navigation_requests_a_reveal() {
        let mut d = doc("foo bar foo");
        d.set_find_query(Some(query("foo")), 0);
        let before = d.reveal_seq();
        assert!(d.find_next(0).is_some());
        assert!(d.reveal_seq() > before, "navigation bumps the reveal request");
    }

    #[test]
    fn clearing_the_query_drops_every_match() {
        let mut d = doc("foo foo");
        d.set_find_query(Some(query("foo")), 0);
        assert_eq!(d.find_match_count(), 2);
        d.set_find_query(None, 0);
        assert_eq!((d.find_match_count(), d.find_query().is_none()), (0, true));
        assert_eq!(d.find_matches_in(0..100).count(), 0);
    }

    #[test]
    fn edits_repair_the_match_set_immediately() {
        // The eager per-commit repair makes the match set current AT the commit,
        // so `maybe_rescan_find` narrows to the capped-refill path — a no-op on
        // an uncapped set, before or after any debounce window.
        let mut d = doc("foo");
        d.set_find_query(Some(query("foo")), 0);
        d.edit(vec![EditOp::insert(0, "foo ")]).unwrap(); // "foo foo"
        assert_eq!(d.find_match_count(), 2, "current immediately — no debounce");
        assert!(!d.maybe_rescan_find(50), "nothing to rescan");
        assert!(!d.maybe_rescan_find(1_000), "uncapped: never rescans");
        assert_eq!(d.find_match_count(), 2);
    }

    // --- Find-match repair battery. ---

    /// The live `FindMatch` decoration ids, in document order.
    fn match_ids(d: &Document) -> Vec<crate::decorations::DecorationId> {
        d.decorations
            .decorations_in(0..u32::MAX)
            .filter(|r| matches!(r.kind, DecorationKind::FindMatch))
            .map(|r| r.id)
            .collect()
    }

    /// The live match ranges, in document order.
    fn match_ranges(d: &Document) -> Vec<Range<u32>> {
        d.find_matches_in(0..u32::MAX).map(|(r, _)| r).collect()
    }

    /// A seeded xorshift for the randomized repair oracles.
    fn xorshift(mut state: u64) -> impl FnMut() -> u64 {
        move || {
            state ^= state << 13;
            state ^= state >> 7;
            state ^= state << 17;
            state
        }
    }

    #[test]
    fn repair_preserves_far_match_ids() {
        // An edit FAR from every match must not re-mint the match decorations —
        // the repair touches only matches near the edit, so untouched ones keep
        // their ids rather than being wholesale-replaced.
        let mut d = doc("foo bar foo bar baz padding padding foo");
        d.set_find_query(Some(query("foo")), 0);
        let before = match_ids(&d);
        assert_eq!(before.len(), 3);
        // Inside the first "padding" — farther than a needle length from all.
        d.edit(vec![EditOp::insert(22, "zz")]).unwrap();
        assert!(!d.maybe_rescan_find(1_000), "always current: nothing to rescan");
        assert_eq!(match_ids(&d), before, "untouched matches keep their ids");
        assert_eq!(match_ranges(&d), vec![0..3, 8..11, 38..41]);
    }

    #[test]
    fn repair_insert_creates_match_in_window() {
        let mut d = doc("fo bar");
        d.set_find_query(Some(query("foo")), 0);
        assert_eq!(d.find_match_count(), 0);
        d.edit(vec![EditOp::insert(2, "o")]).unwrap(); // "foo bar"
        assert_eq!(match_ranges(&d), vec![0..3], "current at the commit");
    }

    #[test]
    fn repair_delete_joins_halves_creates_match() {
        // Deleting the interloper joins "fo" + "o" into a fresh match.
        let mut d = doc("foXo bar");
        d.set_find_query(Some(query("foo")), 0);
        assert_eq!(d.find_match_count(), 0);
        d.edit(vec![EditOp::delete(2..3)]).unwrap(); // "foo bar"
        assert_eq!(match_ranges(&d), vec![0..3]);
    }

    #[test]
    fn repair_destroys_straddling_match() {
        // A deletion straddling the match's tail leaves "fo" — no match.
        let mut d = doc("afoob");
        d.set_find_query(Some(query("foo")), 0);
        assert_eq!(match_ranges(&d), vec![1..4]);
        d.edit(vec![EditOp::delete(3..5)]).unwrap(); // "afo"
        assert_eq!(d.find_match_count(), 0);
    }

    #[test]
    fn repair_interior_insert_invalidates_match() {
        // NeverGrows grows on a strictly-interior insert: the grown range no
        // longer equals the needle, so the repair must remove it.
        let mut d = doc("foo");
        d.set_find_query(Some(query("foo")), 0);
        assert_eq!(d.find_match_count(), 1);
        d.edit(vec![EditOp::insert(1, "x")]).unwrap(); // "fxoo"
        assert_eq!(d.find_match_count(), 0);
    }

    #[test]
    fn repair_multi_edit_transaction() {
        // ONE apply() with two scattered edits — one patch, two repair windows.
        let mut d = doc("fo bar fo baz");
        d.set_find_query(Some(query("foo")), 0);
        d.edit(vec![EditOp::insert(2, "o"), EditOp::insert(9, "o")]).unwrap();
        assert_eq!(d.buffer().text(), "foo bar foo baz");
        assert_eq!(match_ranges(&d), vec![0..3, 8..11]);
    }

    #[test]
    fn repair_equals_full_scan_property() {
        // The repair oracle: for a NON-self-overlapping needle, after EVERY
        // commit the live match set is byte-identical to a fresh `scan` of the
        // live text. Driven through Document::edit so the rebase_views wiring is
        // what's under test.
        let fq = query("ab");
        let mut next = xorshift(0x243F_6A88_85A3_08D3);
        let alphabet = ['a', 'b', ' '];
        let mut d = doc(&"ab ba a b ab ".repeat(8));
        d.set_find_query(Some(fq.clone()), 0);
        for step in 0..300 {
            let len = d.buffer().len();
            match next() % 3 {
                0 => {
                    let at = (next() % u64::from(len + 1)) as u32;
                    let n = 1 + next() % 3;
                    let s: String = (0..n).map(|_| alphabet[(next() % 3) as usize]).collect();
                    d.edit(vec![EditOp::insert(at, s)]).unwrap();
                }
                1 if len > 0 => {
                    let a = (next() % u64::from(len)) as u32;
                    let b = (a + 1 + (next() % 4) as u32).min(len);
                    d.edit(vec![EditOp::delete(a..b)]).unwrap();
                }
                _ => {
                    // Two scattered inserts as ONE transaction.
                    let a = (next() % u64::from(len + 1)) as u32;
                    let b = (next() % u64::from(len + 1)) as u32;
                    let (a, b) = (a.min(b), a.max(b));
                    if a == b {
                        d.edit(vec![EditOp::insert(a, "ab")]).unwrap();
                    } else {
                        d.edit(vec![EditOp::insert(a, "ba"), EditOp::insert(b, "ab")]).unwrap();
                    }
                }
            }
            let (oracle, _) = crate::find::scan(&d.buffer().text(), &fq);
            assert_eq!(match_ranges(&d), oracle, "step {step} diverged from the oracle");
        }
    }

    #[test]
    fn folding_repair_equals_full_scan_property() {
        // The repair oracle under Unicode simple case folding, where a match's
        // BYTE length is not the needle's: `k` folds with `K` KELVIN SIGN (3
        // bytes), `s` with `ſ` LONG S (2), `ß` with `ẞ` (3), `σ` with `Σ`/`ς`.
        // After every commit — forward edits, multi-edit transactions, undo,
        // redo — the live set must equal a fresh `scan` of the live text. Each
        // needle's first char occurs nowhere else in it, so it cannot overlap
        // itself even under folding and equality is exact.
        //
        // `kkkkks` is the case with teeth: 7 bytes typed but up to 17 folded
        // (`KKKKKſ`, KELVIN SIGNs). The repair reaches about twice the margin
        // left of an edit (the window, then the removed extents widened again),
        // so a margin sized from the TYPED length — the pre-folding `k` — only
        // fails once a folded match outgrows the typed one by more than 2×,
        // which only KELVIN's 3 bytes do: a join that completes a match far
        // left of the edit point (deleting the gap in `KKKKK ſ`) then goes
        // unfound. (Verified: that mutation fails here, with the bounds
        // `debug_assert` in the scan disabled.)
        let ks = ['k', 'K', '\u{212A}', '\u{212A}', '\u{212A}', 's', 'S', '\u{17F}', ' '];
        let sharp = ['ß', '\u{1E9E}', 'σ', 'Σ', 'ς', 'ς', ' '];
        let cases: [(u64, &str, &[char], &str); 4] = [
            (0x5DEE_CE66_D1CE_4E5B, "ks", &ks, "ks \u{212A}ſ KS k s "),
            (
                0x2545_F491_4F6C_DD1D,
                "kkkkks",
                &ks,
                "\u{212A}\u{212A}\u{212A}\u{212A}\u{212A}ſ kkkkks \u{212A}\u{212A}\u{212A}\u{212A}\u{212A} ſ KK\u{212A}KkS ",
            ),
            (0x9E37_79B9_7F4A_7C15, "\u{212A}ſſſ", &ks, "kSSS \u{212A}ſſſ Ksss "),
            (0x0DDB_A11C_AFE5_EED5, "ßσσσ", &sharp, "\u{1E9E}ΣΣΣ ßσσς \u{1E9E}ςςς ẞσσ "),
        ];
        for (seed, needle, alphabet, seed_text) in cases {
            let fq = crate::FindQuery { text: needle.into(), case_sensitive: false, ..Default::default() };
            let mut next = xorshift(seed);
            let rand_str = |next: &mut dyn FnMut() -> u64| -> String {
                (0..1 + next() % 3).map(|_| alphabet[(next() % alphabet.len() as u64) as usize]).collect()
            };
            let mut d = doc(&seed_text.repeat(6));
            d.set_find_query(Some(fq.clone()), 0);
            // Random byte offsets snapped to char boundaries (edits must land on them).
            let at = |d: &Document, raw: u64| {
                d.buffer().clip_offset((raw % u64::from(d.buffer().len() + 1)) as u32, Bias::Left)
            };
            let mut nonempty = 0;
            for step in 0..400 {
                match next() % 6 {
                    0 | 1 => {
                        let p = at(&d, next());
                        let s = rand_str(&mut next);
                        d.edit(vec![EditOp::insert(p, s)]).unwrap();
                    }
                    2 if !d.buffer().is_empty() => {
                        let a = at(&d, next());
                        let b = d.buffer().clip_offset(a + 1 + (next() % 8) as u32, Bias::Right);
                        if a < b {
                            d.edit(vec![EditOp::delete(a..b)]).unwrap();
                        }
                    }
                    3 => {
                        // Two scattered inserts as ONE transaction.
                        let (a, b) = (at(&d, next()), at(&d, next()));
                        let (a, b) = (a.min(b), a.max(b));
                        let (s, t) = (rand_str(&mut next), rand_str(&mut next));
                        let ops = if a == b {
                            vec![EditOp::insert(a, s + &t)]
                        } else {
                            vec![EditOp::insert(a, s), EditOp::insert(b, t)]
                        };
                        d.edit(ops).unwrap();
                    }
                    4 => {
                        d.undo();
                    }
                    _ => {
                        d.redo();
                    }
                }
                let (oracle, _) = crate::find::scan(&d.buffer().text(), &fq);
                nonempty += usize::from(!oracle.is_empty());
                assert_eq!(match_ranges(&d), oracle, "{needle:?} step {step} diverged from the oracle");
            }
            assert!(nonempty > 200, "{needle:?}: the oracle must not pass vacuously ({nonempty})");
        }
    }

    #[test]
    fn repair_self_overlapping_needle_is_maximal_and_valid() {
        // Documented relaxation: a self-overlapping needle ("aa") repairs to a
        // MAXIMAL valid non-overlapping set — every match equals the needle, no
        // two overlap, and no further non-overlapping placement exists — though
        // the phase near an edit may differ from a from-scratch greedy scan until
        // the next full scan.
        let mut next = xorshift(0x9E37_79B9_7F4A_7C15);
        let alphabet = ['a', ' '];
        let mut d = doc(&"aaa a aaaa aa ".repeat(6));
        d.set_find_query(Some(query("aa")), 0);
        for step in 0..300 {
            let len = d.buffer().len();
            if next().is_multiple_of(2) || len == 0 {
                let at = (next() % u64::from(len + 1)) as u32;
                let n = 1 + next() % 3;
                let s: String = (0..n).map(|_| alphabet[(next() % 2) as usize]).collect();
                d.edit(vec![EditOp::insert(at, s)]).unwrap();
            } else {
                let a = (next() % u64::from(len)) as u32;
                let b = (a + 1 + (next() % 3) as u32).min(len);
                d.edit(vec![EditOp::delete(a..b)]).unwrap();
            }
            let live = match_ranges(&d);
            let text = d.buffer().text();
            let bytes = text.as_bytes();
            for (i, r) in live.iter().enumerate() {
                assert_eq!(
                    &bytes[r.start as usize..r.end as usize],
                    b"aa",
                    "step {step}: stale match {r:?}"
                );
                if i > 0 {
                    assert!(live[i - 1].end <= r.start, "step {step}: overlapping matches");
                }
            }
            for p in 0..bytes.len().saturating_sub(1) {
                if &bytes[p..p + 2] == b"aa" {
                    let p = p as u32;
                    assert!(
                        live.iter().any(|r| r.start < p + 2 && p < r.end),
                        "step {step}: placement at {p} misses every match (not maximal)"
                    );
                }
            }
        }
    }

    #[test]
    fn active_survives_untouched() {
        // Active-match stability by id: an edit near OTHER matches leaves the
        // active one's decoration (and so its N-of-M slot) alone.
        let mut d = doc("foo bar foo");
        d.set_find_query(Some(query("foo")), 0);
        d.find_next(0); // activates 0..3
        let id = d.find.active_id().expect("a match is active");
        d.edit(vec![EditOp::insert(7, "x")]).unwrap(); // within k−1 of the 2nd match
        assert_eq!(d.find.active_id(), Some(id), "untouched active keeps its id");
        assert_eq!((d.find_match_count(), d.active_find_match()), (2, Some(0)));
    }

    #[test]
    fn active_transfers_same_start() {
        // A repair window removes and re-creates the active match at the same
        // start — the active transfers to the new id.
        let mut d = doc("foo bar");
        d.set_find_query(Some(query("foo")), 0);
        d.find_next(0); // activates 0..3
        let old = d.find.active_id().expect("a match is active");
        d.edit(vec![EditOp::insert(4, "x")]).unwrap(); // "foo xbar": in-window, text intact
        let new = d.find.active_id().expect("active transferred");
        assert_ne!(new, old, "the decoration was re-minted by the repair");
        assert_eq!(d.active_find_match(), Some(0), "still the first match");
        assert_eq!(match_ranges(&d), vec![0..3]);
    }

    #[test]
    fn active_cleared_when_destroyed() {
        let mut d = doc("foo bar foo");
        d.set_find_query(Some(query("foo")), 0);
        d.find_next(0); // activates 0..3
        d.edit(vec![EditOp::delete(0..2)]).unwrap(); // "o bar foo": destroys it
        assert_eq!(d.find.active_id(), None, "destroyed active clears");
        assert_eq!((d.find_match_count(), d.active_find_match()), (1, None));
    }

    #[test]
    fn count_and_order_consistent_after_repair() {
        let mut d = doc("foo foo foo");
        d.set_find_query(Some(query("foo")), 0);
        d.set_selections(SelectionSet::new(4));
        d.find_next(0); // activates the match at 4..7
        d.edit(vec![EditOp::insert(0, "foo ")]).unwrap(); // a NEW first match
        let all: Vec<(Range<u32>, bool)> = d.find_matches_in(0..u32::MAX).collect();
        let ranges: Vec<Range<u32>> = all.iter().map(|(r, _)| r.clone()).collect();
        assert_eq!(ranges, vec![0..3, 4..7, 8..11, 12..15]);
        assert_eq!(d.find_match_count(), all.len());
        // The active rode from 4..7 to 8..11; N-of-M agrees with the iteration.
        assert_eq!(d.active_find_match(), Some(2));
        assert_eq!(all.iter().position(|(_, active)| *active), Some(2));
    }

    #[test]
    fn active_start_tracks_the_decoration_under_random_edits() {
        // Anti-drift pin: with a match active, after EVERY commit the tracked
        // `active_start` must equal the active decoration's live start (or both
        // be None). It is the single rebased position kept in lockstep with
        // `active` across the ~5 mutation sites; if the per-commit rebase is
        // dropped (or the transfer forgets to re-set it), an edit *before* the
        // active match slides its decoration but leaves `active_start` stale, and
        // this trips. (An edit exactly *at* the match start always routes through
        // the window remove→transfer, which resets `active_start` — so this pins
        // the delta-rebase, and `count_and_order_consistent_after_repair` pins the
        // ordinal that rebase feeds.)
        let base = "foo foo bar foo baz foo qux foo end";
        let mut rng = 0xDEAD_BEEF_0000_1111u64;
        let mut next = move || {
            rng ^= rng << 13;
            rng ^= rng >> 7;
            rng ^= rng << 17;
            rng
        };
        for trial in 0..400u32 {
            let mut d = doc(base);
            d.set_find_query(Some(query("foo")), 0);
            // Activate a MID-document match (offset > 0), so "edit before it"
            // trials exist to exercise the delta-rebase.
            d.set_selections(SelectionSet::new(10));
            d.find_next(0);
            for _step in 0..14 {
                if d.find.active_id().is_none() {
                    // Re-activate so the invariant keeps getting exercised.
                    d.set_selections(SelectionSet::new(1));
                    d.find_next(0);
                }
                let len = d.buffer().len();
                // Sometimes aim the edit at the active match's start (the
                // Bias::Right boundary), else a random position.
                let at = match d.find.active_start() {
                    Some(s) if next() % 3 == 0 => s,
                    _ => (next() % u64::from(len + 1)) as u32,
                };
                match next() % 3 {
                    0 => {
                        let _ = d.edit(vec![EditOp::insert(at, "z")]);
                    }
                    1 => {
                        let end = (at + 1 + (next() % 3) as u32).min(len);
                        if end > at {
                            let _ = d.edit(vec![EditOp::delete(at..end)]);
                        }
                    }
                    _ => {
                        // Multi-caret insert at two disjoint carets.
                        let a = (next() % u64::from(len + 1)) as u32;
                        let b = (next() % u64::from(len + 1)) as u32;
                        let (lo, hi) = (a.min(b), a.max(b));
                        if lo != hi {
                            d.set_selections(SelectionSet::from_ranges(&[(lo, lo), (hi, hi)], 0));
                            d.insert_text("q");
                        }
                    }
                }
                let want = d
                    .find
                    .active_id()
                    .and_then(|id| d.decorations.decoration_range(id))
                    .map(|r| r.start);
                assert_eq!(
                    d.find.active_start(),
                    want,
                    "trial {trial}: active_start drifted from its decoration's live start",
                );
            }
        }
    }

    #[test]
    fn capped_scan_keeps_a_document_prefix() {
        // > FIND_MATCH_CAP occurrences: the fresh scan keeps the first 10k
        // (a document prefix) and reports capped.
        let text = "x ".repeat(crate::FIND_MATCH_CAP + 50);
        let mut d = doc(&text);
        d.set_find_query(Some(query("x")), 0);
        assert!(d.find.capped());
        let live = match_ranges(&d);
        assert_eq!(live.len(), crate::FIND_MATCH_CAP);
        assert_eq!(live.last().cloned(), Some(19_998..19_999), "prefix, not a sample");
    }

    #[test]
    fn typing_while_capped_does_not_rescan_the_match_set() {
        // While a >cap find is active, the per-keystroke cap bookkeeping must be
        // O(1): a `decorations_in(0..u32::MAX).filter(is_find).collect()` would
        // charge ~FIND_MATCH_CAP work units on EVERY keystroke while capped.
        // Reading the count from the root summary (`find_count`, O(1)) and
        // trimming via ordinal `nth_find` (O(log)) means a steady capped
        // keystroke touches no whole-store scan.
        let text = "x ".repeat(crate::FIND_MATCH_CAP + 50);
        let mut d = doc(&text);
        d.set_find_query(Some(query("x")), 0);
        assert!(d.find.capped());
        assert_eq!(d.find_match_count(), crate::FIND_MATCH_CAP);
        d.set_selections(crate::SelectionSet::new(0));
        crate::perf::reset();
        d.type_char('z'); // adds no `x` ⇒ the set stays exactly at the cap (no trim)
        let work = crate::perf::meter();
        assert_eq!(d.find_match_count(), crate::FIND_MATCH_CAP, "still capped");
        assert!(
            work < 2_000,
            "capped keystroke charged {work} work units (≈FIND_MATCH_CAP ⇒ the O(M) cap scan survived)"
        );
    }

    #[test]
    fn capped_trims_tail_and_coverage() {
        // Exactly at the cap (uncapped) — one edit adds matches mid-document,
        // the repair pushes past the cap, and the TAIL is trimmed so the set
        // stays a prefix of the document.
        let text = "x ".repeat(crate::FIND_MATCH_CAP);
        let mut d = doc(&text);
        d.set_find_query(Some(query("x")), 0);
        assert!(!d.find.capped());
        d.edit(vec![EditOp::insert(1_000, "xxx")]).unwrap();
        assert!(d.find.capped(), "over the cap after the repair");
        let live = match_ranges(&d);
        assert_eq!(live.len(), crate::FIND_MATCH_CAP, "trimmed back to the cap");
        assert!(live.windows(2).all(|w| w[0].end <= w[1].start), "still non-overlapping");
        // The new matches near the edit are IN; the trim came off the tail.
        assert_eq!(live.iter().filter(|r| (1_000..1_004).contains(&r.start)).count(), 4);
        assert_eq!(live.last().map(|r| r.start), Some(19_995), "tail trimmed");
    }

    #[test]
    fn capped_refill_is_debounced() {
        let text = "x ".repeat(crate::FIND_MATCH_CAP + 50);
        let mut d = doc(&text);
        d.set_find_query(Some(query("x")), 0); // capped; scan stamp at 0 ms
        // Kill 5 matches inside the covered prefix → room below the cap.
        d.edit(vec![EditOp::delete(0..10)]).unwrap();
        assert_eq!(d.find_match_count(), crate::FIND_MATCH_CAP - 5);
        assert!(!d.maybe_rescan_find(50), "inside the debounce window");
        assert_eq!(d.find_match_count(), crate::FIND_MATCH_CAP - 5);
        assert!(d.maybe_rescan_find(100), "past the window → refill");
        assert_eq!(d.find_match_count(), crate::FIND_MATCH_CAP, "coverage re-grew");
        assert!(!d.maybe_rescan_find(300), "idle after the refill: no re-scan");
    }

    #[test]
    fn undo_redo_match_set_equals_fresh_scan() {
        // Undo/redo flow through the same rebase_views mover, so the repaired
        // set must equal the oracle after every reverted/replayed step too.
        let fq = query("ab");
        let mut d = doc("ab ab ba ab");
        d.set_find_query(Some(fq.clone()), 0);
        let check = |d: &Document, at: &str| {
            let (oracle, _) = crate::find::scan(&d.buffer().text(), &fq);
            assert_eq!(match_ranges(d), oracle, "diverged after {at}");
        };
        d.edit(vec![EditOp::insert(2, "ab")]).unwrap();
        check(&d, "edit 1");
        d.edit(vec![EditOp::delete(0..3)]).unwrap();
        check(&d, "edit 2");
        d.edit(vec![EditOp::insert(5, "b a")]).unwrap();
        check(&d, "edit 3");
        assert!(d.undo());
        check(&d, "undo 1");
        assert!(d.undo());
        check(&d, "undo 2");
        assert!(d.undo());
        check(&d, "undo 3");
        assert!(d.redo());
        check(&d, "redo 1");
        assert!(d.redo());
        check(&d, "redo 2");
    }

    #[test]
    fn case_fold_repair() {
        // The windowed repair honors the query's fold toggle.
        let fq = crate::FindQuery { text: "foo".into(), case_sensitive: false, ..Default::default() };
        let mut d = doc("FO bar");
        d.set_find_query(Some(fq), 0);
        assert_eq!(d.find_match_count(), 0);
        d.edit(vec![EditOp::insert(2, "O")]).unwrap(); // "FOO bar"
        assert_eq!(match_ranges(&d), vec![0..3]);
        d.edit(vec![EditOp::insert(0, "f")]).unwrap(); // "fFOO bar"
        assert_eq!(match_ranges(&d), vec![1..4], "re-anchored, still folded");
    }
}