kimun_notes/components/search_list/

mod.rs

//! `SearchList`: the one module behind every query-input-over-an-async-loaded
//! list surface in the TUI. See CONTEXT.md.

#[cfg(test)]
mod adapters;
mod host;
mod load;
mod resolving;
mod seams;

pub use resolving::{ResolvingRowSource, Unresolvable};
pub use seams::{
    Emit, Filter, Loaded, OrderFn, RowSource, SearchRow, StaticRowSource, SuggestionItem,
    SuggestionSource, VaultSuggestions, YankTarget,
};

use crate::components::autocomplete::{
    AutocompleteController, AutocompleteMode, HandleKeyOutcome, TriggerOptions,
};
use crate::components::single_line_input::{InputOutcome, SingleLineInput};
use crate::keys::key_combo::KeyCombo;
use crate::settings::icons::Icons;
use crate::settings::themes::Theme;
use load::LoadEngine;
use ratatui::crossterm::event::KeyEvent;
use ratatui::{
    Frame,
    layout::Rect,
    style::Style,
    widgets::{List, ListItem, ListState},
};
use seams::Loaded as LoadedInner;
use std::sync::Arc;

/// Fuzzy-ranks the rows named by `base` (indices into `rows`, in the order
/// ties should keep) against `query`; absent = no match.
fn fuzzy_indices<R: SearchRow>(rows: &[R], base: &[usize], query: &str) -> Vec<usize> {
    use nucleo::pattern::{CaseMatching, Normalization, Pattern};
    use nucleo::{Matcher, Utf32Str};
    let mut matcher = Matcher::new(nucleo::Config::DEFAULT);
    let pat = Pattern::parse(query, CaseMatching::Ignore, Normalization::Smart);
    let mut scored: Vec<(usize, u32)> = base
        .iter()
        .filter_map(|&i| {
            let hay = rows[i].match_text()?;
            let mut buf = Vec::new();
            let h = Utf32Str::new(hay, &mut buf);
            pat.score(h, &mut matcher).map(|s| (i, s))
        })
        .collect();
    // Stable: equal scores keep `base` order, so an `order_by` still decides
    // among ties.
    scored.sort_by_key(|&(_, s)| std::cmp::Reverse(s));
    scored.into_iter().map(|(i, _)| i).collect()
}

/// Which half of a [`SearchList`] owns the keyboard. See CONTEXT.md
/// (**List focus**). In [`Focus::Input`] typing filters the list; in
/// [`Focus::List`] plain letters are verbs (`j`/`k` navigate, surface-registered
/// letters act on the selected row) and never type into the query.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Focus {
    Input,
    List,
}

/// Verdict returned by [`SearchList::handle_key`].
#[derive(Debug, PartialEq, Eq)]
pub enum KeyReaction {
    Consumed,
    Submit,
    Cancel,
    Intercepted(crate::keys::key_combo::KeyCombo),
    /// A surface-registered list-focus verb fired on the selected row. The
    /// engine attaches NO meaning to the char — the caller maps it to an
    /// action (see [`SearchListBuilder::list_verb`]).
    ListVerb(char),
    /// The yank chord fired: the selected row's [`YankTarget`], or `None` when
    /// nothing is selected or the row has nothing worth copying.
    ///
    /// SearchList decides *that* the chord is a yank and *what* it would copy;
    /// it does not touch the clipboard, because it holds no `AppTx` and emits
    /// nothing on its own. Callers hand this straight to
    /// [`crate::components::yank_row`].
    Yank(Option<YankTarget>),
    Unhandled,
}

pub struct SearchList<R: SearchRow> {
    source: Arc<dyn RowSource<R>>,
    rows: Vec<R>,
    /// Indices into `rows` in display order (after filtering/ranking).
    display: Vec<usize>,
    /// A synthetic, query-fresh, filter-exempt row pinned at visible position 0
    /// (the `Create: <q>` affordance / saved-searches virtual entry). Held
    /// separately from `rows` so it works regardless of delivery (one-shot
    /// `Replace` or streamed `Push`) and refreshes on every query change. See
    /// [`RowSource::leading_row`].
    leading: Option<R>,
    /// Index into the VISIBLE sequence `[leading?] ++ display` of the selected
    /// item.
    selected: Option<usize>,
    /// Whether `selected` is the user's own choice rather than the seed
    /// `recompute_and_seed` puts on the first row. A chosen selection tracks
    /// its row across a re-sort; a seeded one keeps the top slot, so a streamed
    /// listing highlights the top of the `order_by` order at every frame
    /// instead of whichever row the source happened to emit first.
    selection_pinned: bool,
    /// Viewport offset: visible position of the first row on screen. Owned
    /// here (not by a per-frame `ListState`) so mouse-wheel scrolling can move
    /// the viewport directly; `render` writes it back after ratatui clamps it
    /// to keep the selection visible.
    offset: usize,
    filter: Filter<R>,
    /// Optional total order applied before the local filter; see
    /// [`SearchListBuilder::order_by`].
    order: Option<OrderFn<R>>,
    query: String,
    loader: LoadEngine<R>,
    input: SingleLineInput,
    autocomplete: Option<AutocompleteController>,
    /// Key combos the caller wants to intercept before the engine acts.
    intercept: Vec<KeyCombo>,
    /// The chords that yank the selected row's [`YankTarget`]. Defaults to
    /// [`crate::keys::default_yank_combo`]; surfaces that hold the user's
    /// [`KeyBindings`](crate::keys::KeyBindings) pass the resolved combos, so a
    /// rebinding reaches the list. Empty = the user unbound it.
    yank_combos: Vec<KeyCombo>,
    icons: Icons,
    list_rect: Rect,
    /// The host panel's full bounds, for wheel hit-testing: scroll events
    /// anywhere within it scroll the list — header, query box, preview —
    /// while clicks still hit-test against `list_rect` only. Empty (the
    /// default) falls back to `list_rect`, so hosts that never record it
    /// keep scroll-over-the-list-only behavior.
    panel_rect: Rect,
    /// A host-owned scrollable sub-region within the panel (e.g. an expanded
    /// note preview). Wheel events inside it are routed back to the host as
    /// [`SearchMouse::ContentScrollUp`]/[`ContentScrollDown`] instead of
    /// scrolling the list — the sub-region wins over `panel_rect`. Empty (the
    /// default) means no sub-region; hosts re-record it every render so it is
    /// never stale.
    ///
    /// [`ContentScrollDown`]: SearchMouse::ContentScrollDown
    content_rect: Rect,
    /// Where the query input was drawn by the last [`Self::render_query`].
    /// A click there gives the input the keyboard.
    input_rect: Rect,
    /// Load generation whose rows are currently held. When a newer generation
    /// (a requery / reload) delivers its first event, `poll` clears the stale
    /// rows before applying it — required for streamed (`Push`) sources, which
    /// would otherwise append onto a superseded load's rows.
    applied_generation: u64,
    /// Set when a SavedSearch suggestion was just accepted: the search's name,
    /// for the host to pin as the saved-search breadcrumb. Read once via
    /// [`take_accepted_saved_search`](Self::take_accepted_saved_search).
    accepted_saved_search: Option<String>,
    /// Visible position of the last left-click, so "click the selected row
    /// again activates" only fires on a true click-click — never on a click
    /// landing on an auto- or keyboard-made selection.
    last_click_pos: Option<usize>,
    /// When the last left-click landed — a second one on the same row within
    /// [`DOUBLE_CLICK`](crate::components::DOUBLE_CLICK) is a double-click.
    last_click_at: Option<std::time::Instant>,
    /// The last left press came back [`SearchMouse::Activated`] — so a fast
    /// press after it completes a double-click whose first half already
    /// acted (see `DoubleClicked::repeat`).
    last_click_activated: bool,
    /// Render the query input with syntax highlighting (the FIND drawer
    /// and the telescope modal; plain inputs like the sidebar filter skip it).
    highlight_query: bool,
    /// Which half owns the keyboard. See [`Focus`] and CONTEXT.md.
    focus: Focus,
    /// Whether the list-focus state machine is active for this surface. `true`
    /// iff the surface opens on the list OR registers at least one verb;
    /// otherwise `Esc` cancels immediately, byte-identical to a plain input
    /// list, so surfaces that never opt in keep their exact keystroke behavior.
    focus_enabled: bool,
    /// Surface-registered list-focus verb chars. When one is pressed in
    /// [`Focus::List`], `handle_key` returns [`KeyReaction::ListVerb`]; the
    /// engine attaches no meaning to them.
    list_verbs: Vec<char>,
}

/// Mouse interaction result from [`SearchList::handle_mouse`].
#[derive(Debug, PartialEq, Eq)]
pub enum SearchMouse {
    Selected(usize),
    Activated(usize),
    /// A fast double-click on a row (both presses within
    /// [`DOUBLE_CLICK`](crate::components::DOUBLE_CLICK)). Hosts whose
    /// [`Activated`](Self::Activated) already means "open" treat both the
    /// same; hosts where it toggles a preview open the row instead.
    ///
    /// `repeat`: the pair's first press already came back `Activated` (it
    /// re-clicked a row an earlier, slower click had selected). A host where
    /// both mean the same thing must not act twice; it ignores the repeat.
    DoubleClicked {
        pos: usize,
        repeat: bool,
    },
    /// Right-click on a row: selected, and the host should open its context
    /// menu for it.
    Context(usize),
    Scrolled,
    /// The wheel landed inside the host's content sub-region (see
    /// [`SearchList::set_content_rect`]); the host owns that view's scroll,
    /// so the engine routed the event instead of moving the list.
    ContentScrollUp,
    ContentScrollDown,
    /// A left click on the query input: it now owns the keyboard (list
    /// focus, where the surface has one, went back to the input).
    InputFocused,
    /// The event landed on the open autocomplete popup. `edited`: a click
    /// accepted a suggestion into the query — the host reacts exactly as to
    /// a key [`KeyReaction::Consumed`] (breadcrumb, preview re-anchor).
    Autocomplete {
        edited: bool,
    },
    None,
}

pub struct SearchListBuilder<R: SearchRow> {
    source: Arc<dyn RowSource<R>>,
    redraw: Arc<dyn Fn() + Send + Sync>,
    initial_query: String,
    filter: Filter<R>,
    order: Option<OrderFn<R>>,
    autocomplete: Option<(Arc<dyn SuggestionSource>, AutocompleteMode)>,
    intercept: Vec<KeyCombo>,
    yank_combos: Vec<KeyCombo>,
    icons: Icons,
    debounce: Option<std::time::Duration>,
    highlight_query: bool,
    opening_focus: Focus,
    list_verbs: Vec<char>,
}

impl<R: SearchRow> SearchList<R> {
    pub fn builder(
        source: impl RowSource<R>,
        redraw: Arc<dyn Fn() + Send + Sync>,
    ) -> SearchListBuilder<R> {
        SearchListBuilder {
            source: Arc::new(source),
            redraw,
            initial_query: String::new(),
            filter: Filter::SourceOrder,
            order: None,
            autocomplete: None,
            intercept: Vec::new(),
            yank_combos: vec![crate::keys::default_yank_combo()],
            icons: Icons::new(false),
            debounce: None,
            highlight_query: false,
            opening_focus: Focus::Input,
            list_verbs: Vec::new(),
        }
    }

    /// The async path: kick off the initial load; rows land on a later `poll`.
    fn new(b: SearchListBuilder<R>) -> Self {
        let mut list = Self::assemble(b);
        list.loader.start(list.source.clone(), list.query.clone());
        list
    }

    /// The synchronous path: apply an in-memory row set and seed the initial
    /// selection here and now — no async load, no channel, no redraw
    /// round-trip. The [`LoadEngine`] stays idle (`is_loading()` is false
    /// immediately), and the source's `load` is never invoked, so a caller can
    /// read `selected_row()`/`rows()` on the very next line. For static sources
    /// (`reload_on_query() == false`), where the query is a local filter over
    /// the built rows. See [`StaticRowSource`].
    ///
    /// [`StaticRowSource`]: crate::components::search_list::StaticRowSource
    fn with_rows(b: SearchListBuilder<R>, rows: Vec<R>) -> Self {
        let mut list = Self::assemble(b);
        list.rows = rows;
        list.recompute_and_seed();
        list
    }

    /// Build the struct with an idle loader (no load started). The two entry
    /// points ([`new`](Self::new)/[`with_rows`](Self::with_rows)) diverge on
    /// what they do next: spawn an async load, or seed rows synchronously.
    fn assemble(b: SearchListBuilder<R>) -> Self {
        let loader = LoadEngine::new(b.redraw.clone());
        let input = SingleLineInput::with_value(&b.initial_query);
        let debounce = b.debounce;
        let autocomplete = b.autocomplete.map(|(suggestions, mode)| {
            let mut ac =
                AutocompleteController::new(suggestions, mode).with_trigger_opts(TriggerOptions {
                    disambiguate_header: false,
                    apply_exclusion_zone: false,
                    // The controller derives `allow_saved_search` from its mode
                    // at detect time, so this seed value is not load-bearing.
                    ..TriggerOptions::default()
                });
            if let Some(d) = debounce {
                ac = ac.with_debounce(d);
            }
            ac.set_redraw_callback(b.redraw.clone());
            ac
        });
        Self {
            source: b.source,
            rows: Vec::new(),
            display: Vec::new(),
            leading: None,
            selected: None,
            selection_pinned: false,
            offset: 0,
            filter: b.filter,
            order: b.order,
            query: b.initial_query,
            loader,
            input,
            highlight_query: b.highlight_query,
            last_click_pos: None,
            last_click_at: None,
            last_click_activated: false,
            autocomplete,
            intercept: b.intercept,
            yank_combos: b.yank_combos,
            icons: b.icons,
            list_rect: Rect::default(),
            panel_rect: Rect::default(),
            content_rect: Rect::default(),
            input_rect: Rect::default(),
            applied_generation: 0,
            accepted_saved_search: None,
            focus: b.opening_focus,
            // List focus is active when the surface opens on the list or
            // registers verbs; otherwise the surface keeps plain Esc→Cancel.
            focus_enabled: b.opening_focus == Focus::List || !b.list_verbs.is_empty(),
            list_verbs: b.list_verbs,
        }
    }

    /// Which half currently owns the keyboard. See [`Focus`].
    pub fn focus(&self) -> Focus {
        self.focus
    }

    pub fn poll(&mut self) {
        let drained = self.loader.drain();
        if !drained.is_empty() {
            // A newer load delivered its first event(s): drop the prior load's
            // rows so a streamed source starts from a clean slate (one-shot
            // `Replace` overwrites anyway, but `Push` would otherwise append).
            let current_gen = self.loader.generation();
            if current_gen != self.applied_generation {
                self.rows.clear();
                self.selected = None;
                self.selection_pinned = false;
                self.offset = 0;
                self.applied_generation = current_gen;
            }
            // Pushes only append, so row indices stay valid across the drain
            // and the selection can follow its row wherever `order` puts it.
            // A `Replace` swaps the whole set; indices mean nothing after it.
            let keep = if drained
                .iter()
                .any(|ev| matches!(ev, LoadedInner::Replace(_)))
            {
                None
            } else {
                self.selection_to_carry()
            };
            for ev in drained {
                match ev {
                    LoadedInner::Replace(rows) => {
                        self.rows = rows;
                    }
                    LoadedInner::Push(row) => {
                        self.rows.push(row);
                    }
                    LoadedInner::Done => {}
                }
            }
            self.recompute_and_seed();
            self.reselect(keep);
        }
        if let Some(ac) = &mut self.autocomplete {
            ac.poll_results();
        }
    }

    /// Recompute the display order, then seed the selection to the first row
    /// when nothing is selected yet (e.g. after the first load or a filter that
    /// repopulated the list). The single place display + initial selection are
    /// brought in sync.
    fn recompute_and_seed(&mut self) {
        self.recompute_display();
        if self.selected.is_none() && self.visible_len() > 0 {
            self.selected = Some(0);
        }
    }

    /// Build a host snapshot from the current input state.
    /// Only reads `self.input` so the result can be stored in a local
    /// before taking `&mut self.autocomplete`, resolving the borrow conflict.
    fn autocomplete_snapshot(&self) -> host::SearchBoxHostSnapshot {
        let value = self.input.value().to_string();
        let cursor_byte = self.input.cursor_byte();
        let col = value[..cursor_byte.min(value.len())].chars().count();
        host::SearchBoxHostSnapshot {
            lines: vec![value],
            cursor: (0, col),
            caret_pos: self.input.last_caret_pos(),
        }
    }

    fn clamp_selection(&mut self) {
        let len = self.visible_len();
        self.selected = if len == 0 {
            None
        } else {
            Some(self.selected.unwrap_or(0).min(len - 1))
        };
    }

    /// `1` when a leading row is pinned at visible position 0, else `0`.
    fn leading_offset(&self) -> usize {
        self.leading.is_some() as usize
    }

    /// Length of the visible sequence `[leading?] ++ display`.
    pub fn visible_len(&self) -> usize {
        self.leading_offset() + self.display.len()
    }

    /// Number of real matches — the visible rows minus the synthetic leading
    /// affordance ("Create: …"), for result-count displays.
    pub fn match_count(&self) -> usize {
        self.display.len()
    }

    /// Row at visible position `pos` in `[leading?] ++ display`.
    fn visible_row(&self, pos: usize) -> Option<&R> {
        if self.leading.is_some() && pos == 0 {
            self.leading.as_ref()
        } else {
            self.rows
                .get(*self.display.get(pos - self.leading_offset())?)
        }
    }

    /// The source-delivered rows only (NOT the leading row). Prefer
    /// [`visible_len`](Self::visible_len)/[`visible_rows`](Self::visible_rows)
    /// for visible counts.
    pub fn rows(&self) -> &[R] {
        &self.rows
    }

    pub fn selected_row(&self) -> Option<&R> {
        self.selected.and_then(|p| self.visible_row(p))
    }

    pub fn visible_rows(&self) -> Vec<&R> {
        (0..self.visible_len())
            .filter_map(|p| self.visible_row(p))
            .collect()
    }

    pub fn query(&self) -> &str {
        &self.query
    }

    /// Take the name of a just-accepted saved search, if any. The host calls
    /// this after a `Consumed` key to learn whether to pin (or refresh) the
    /// saved-search breadcrumb. Returns `None` once read.
    pub fn take_accepted_saved_search(&mut self) -> Option<String> {
        self.accepted_saved_search.take()
    }

    /// The visible text in the query input widget. Test-only: lets callers
    /// assert the input bar reflects a programmatic query change.
    #[cfg(test)]
    pub(crate) fn input_value(&self) -> &str {
        self.input.value()
    }
    pub fn is_loading(&self) -> bool {
        self.loader.loading
    }

    /// Set the query programmatically: updates the visible input widget (cursor
    /// to end) AND the query string, then starts a load (for `reload_on_query`
    /// sources) or recomputes the display. This is the setter every external
    /// caller wants — a saved search applied, a sort directive rewritten — so
    /// the input bar always reflects the query. The interactive keystroke path
    /// uses `sync_query_from_input` instead,
    /// because the input widget already holds the typed text (and its cursor
    /// must not jump back to the end on every keystroke).
    pub fn set_query(&mut self, q: impl Into<String>) {
        let q = q.into();
        self.input.set_value(q.clone());
        self.query = q;
        self.requery();
    }

    /// Pull the query string FROM the input widget without touching the widget
    /// (so the cursor stays put), then reload/recompute. The keystroke and
    /// autocomplete-accept paths use this after they have already mutated the
    /// input in place.
    fn sync_query_from_input(&mut self) {
        self.query = self.input.value().to_string();
        self.requery();
    }

    /// Start a fresh load for `reload_on_query` sources, else recompute the
    /// local display. The generation guard in `LoadEngine` drops stale results.
    fn requery(&mut self) {
        if self.source.reload_on_query() {
            self.loader.start(self.source.clone(), self.query.clone());
        }
        // Recompute now so the query-fresh leading row (and local filter, for
        // non-reload sources) reflect the new query in this frame. Reload
        // sources refresh again when their load drains in poll().
        self.recompute_and_seed();
    }

    /// Re-run the source load for the current query (e.g. after a mutation).
    pub fn reload(&mut self) {
        self.loader.start(self.source.clone(), self.query.clone());
    }

    /// Replace (or clear) the row order and re-sort the rows already loaded.
    /// A recompute, not a reload: the source is not consulted. A selection the
    /// user chose stays on the row it was on; a seeded one keeps the top slot
    /// of the NEW order — and stays a seed, so a still-streaming listing goes
    /// on re-seeding it (the `selection_pinned` split, as in `poll`).
    pub fn set_order(&mut self, cmp: Option<OrderFn<R>>) {
        let keep = self.selection_to_carry();
        self.order = cmp;
        self.recompute_display();
        self.reselect(keep);
    }

    /// The row a recompute has to put the selection back on: the row the user
    /// chose, or `None` for a seed — a seed belongs to the top of the order,
    /// wherever the recompute puts it. The one rule behind `poll`, `set_order`
    /// and `update_rows`.
    fn selection_to_carry(&self) -> Option<usize> {
        self.selection_pinned
            .then(|| self.selected_row_index())
            .flatten()
    }

    /// Index into `rows` of the selected row, if the selection is on a real
    /// (non-leading) row.
    fn selected_row_index(&self) -> Option<usize> {
        let pos = self.selected?.checked_sub(self.leading_offset())?;
        self.display.get(pos).copied()
    }

    /// Move the selection back onto the row at `rows[row]` after the display
    /// was recomputed, if that row is still visible; otherwise leave it where
    /// the recompute clamped it.
    fn reselect(&mut self, row: Option<usize>) {
        if let Some(row) = row
            && let Some(pos) = self.display.iter().position(|&i| i == row)
        {
            self.selected = Some(pos + self.leading_offset());
        }
    }

    /// Mutate rows in place. `mutate` is called for each row and returns `true`
    /// for each row it changed; if any did, the display is recomputed — which
    /// re-filters AND re-sorts, so an edit to a field the `order_by` reads
    /// moves its row. Returns whether anything changed.
    ///
    /// The selection is carried the same way every other recompute carries it:
    /// a chosen row stays chosen wherever it lands, a seed keeps the top slot.
    ///
    /// This is the one seam that touches rows outside the [`RowSource`]; every
    /// other change rebuilds from the source. Structural changes (add/remove)
    /// must still reload; a reorder is [`set_order`](Self::set_order).
    /// `SearchList` stays ignorant of the row type; callers layer the
    /// path-matched operations on top.
    pub fn update_rows(&mut self, mut mutate: impl FnMut(&mut R) -> bool) -> bool {
        let mut changed = false;
        for row in &mut self.rows {
            if mutate(row) {
                changed = true;
            }
        }
        if changed {
            let keep = self.selection_to_carry();
            self.recompute_display();
            self.reselect(keep);
        }
        changed
    }

    /// Select the visible row at `pos` (clamped to the visible range); clears
    /// the selection when the list is empty. The index-based counterpart to
    /// [`select_next`](Self::select_next)/[`select_prev`](Self::select_prev),
    /// for surfaces that point the cursor at a specific row (the Sources view's
    /// citation jump).
    pub fn select(&mut self, pos: usize) {
        let n = self.visible_len();
        self.selected = if n == 0 { None } else { Some(pos.min(n - 1)) };
        // Unconditional: aiming at a row IS the choice, even when it happens
        // to be the row the seed already sat on. Only the blind nudges below
        // have to prove they moved.
        self.selection_pinned = self.selected.is_some();
    }

    pub fn select_next(&mut self) {
        let n = self.visible_len();
        if n == 0 {
            return;
        }
        self.move_selection(Some(self.selected.map_or(0, |i| (i + 1).min(n - 1))));
    }

    pub fn select_prev(&mut self) {
        if self.visible_len() == 0 {
            return;
        }
        self.move_selection(Some(self.selected.map_or(0, |i| i.saturating_sub(1))));
    }

    /// Move the selection, marking it the user's own choice only when it
    /// actually lands somewhere new. A nudge against either end of the list
    /// changes nothing, so it must not turn a seed into a choice — one stray
    /// `Up` on the first row of a streaming listing would otherwise freeze the
    /// highlight at position 0 and let rows arriving above it walk underneath.
    fn move_selection(&mut self, next: Option<usize>) {
        if next != self.selected {
            self.selected = next;
            self.selection_pinned = next.is_some();
        }
    }

    /// Largest useful viewport offset: the first visible position from which
    /// the rows through the end still fill the recorded list rect. Scrolling
    /// past it would leave blank space below the last row, so
    /// [`scroll_down`](Self::scroll_down) clamps to it.
    fn max_scroll_offset(&self) -> usize {
        let viewport = self.list_rect.height as usize;
        let n = self.visible_len();
        if viewport == 0 || n == 0 {
            return 0;
        }
        let mut budget = viewport;
        let mut first = n;
        while first > 0 {
            let h = self
                .visible_row(first - 1)
                .map(|r| r.visual_height() as usize)
                .unwrap_or(1);
            if h > budget {
                break;
            }
            budget -= h;
            first -= 1;
        }
        first.min(n - 1)
    }

    /// Scroll the viewport one row down, carrying the selection along so the
    /// selected row keeps its on-screen position. No-op once the last row is
    /// in view — the shared mouse-wheel behavior for every list surface.
    pub fn scroll_down(&mut self) {
        let n = self.visible_len();
        if n == 0 || self.offset >= self.max_scroll_offset() {
            return;
        }
        self.offset += 1;
        self.move_selection(self.selected.map(|i| (i + 1).min(n - 1)));
    }

    /// Scroll the viewport one row up, carrying the selection along so the
    /// selected row keeps its on-screen position. No-op at the top.
    pub fn scroll_up(&mut self) {
        if self.offset == 0 {
            return;
        }
        self.offset -= 1;
        self.move_selection(self.selected.map(|i| i.saturating_sub(1)));
    }

    /// The current viewport offset. Test-only: lets scroll tests assert the
    /// viewport moved while the selection kept its screen position.
    #[cfg(test)]
    pub(crate) fn scroll_offset(&self) -> usize {
        self.offset
    }

    /// Whether `key` is one of this list's yank chords. For surfaces that do
    /// NOT route every key into the engine (`ListPanelSpec::HAS_FILTER = false`,
    /// e.g. the LINKS drawer, where plain letters are the host's sub-view keys):
    /// they forward only what they recognise, and without this the yank chord
    /// would be the one thing their rows declare but can never deliver.
    pub fn is_yank_chord(&self, key: &KeyEvent) -> bool {
        crate::keys::key_event_to_combo(key).is_some_and(|c| self.yank_combos.contains(&c))
    }

    /// Write an accepted suggestion into the query — one path for a key
    /// accept and a click accept.
    fn apply_accept(&mut self, action: crate::components::autocomplete::AcceptAction) {
        self.input.replace_range_bytes(
            action.range.clone(),
            &action.new_text,
            action.new_cursor_byte,
        );
        // Stash any accepted SavedSearch name for the host's breadcrumb
        // (`None` for every other kind). The host reads it on this same
        // event, so a plain assign never clobbers an unread value.
        self.accepted_saved_search = action.saved_search_name;
        self.sync_query_from_input();
    }

    pub fn handle_key(&mut self, key: &KeyEvent) -> KeyReaction {
        use ratatui::crossterm::event::{KeyCode, KeyModifiers};

        // Caller-registered intercepts get first crack — before autocomplete or
        // any built-in binding.
        if let Some(combo) = crate::keys::key_event_to_combo(key)
            && self.intercept.contains(&combo)
        {
            return KeyReaction::Intercepted(combo);
        }

        // Autocomplete popup gets first crack when open. Build snapshot before
        // taking &mut self.autocomplete to avoid borrow-checker conflict
        // (snapshot only reads self.input).
        if self.autocomplete.as_ref().is_some_and(|ac| ac.is_open()) {
            let snap = self.autocomplete_snapshot();
            if let Some(ac) = &mut self.autocomplete {
                match ac.handle_key(*key, &snap) {
                    HandleKeyOutcome::Accepted(action) => {
                        self.apply_accept(action);
                        return KeyReaction::Consumed;
                    }
                    HandleKeyOutcome::Dismissed | HandleKeyOutcome::Consumed => {
                        return KeyReaction::Consumed;
                    }
                    HandleKeyOutcome::NotHandled => {}
                }
            }
        }

        // Arrows navigate and Enter submits in BOTH foci (arrows as today).
        match key.code {
            KeyCode::Up => {
                self.select_prev();
                return KeyReaction::Consumed;
            }
            KeyCode::Down => {
                self.select_next();
                return KeyReaction::Consumed;
            }
            KeyCode::Enter => return KeyReaction::Submit,
            _ => {}
        }
        // Esc: with the list-focus machine active, the first Esc moves Input →
        // List focus (Consumed); from List focus (and for surfaces that never
        // opted in) Esc is Cancel, so their keystroke behavior is unchanged.
        if key.code == KeyCode::Esc {
            if self.focus_enabled && self.focus == Focus::Input {
                self.focus = Focus::List;
                self.close_autocomplete();
                return KeyReaction::Consumed;
            }
            return KeyReaction::Cancel;
        }
        // The yank chord, claimed above the Ctrl/Alt drop below (which would
        // otherwise swallow it). Every surface built on SearchList gets this
        // without wiring a key — the note browser lacked one for exactly that
        // reason. What gets copied is the ROW's business; performing
        // the copy is the CALLER's, since SearchList holds no `AppTx`.
        if let Some(combo) = crate::keys::key_event_to_combo(key)
            && self.yank_combos.contains(&combo)
        {
            return KeyReaction::Yank(self.selected_row().and_then(|r| r.yank_target()));
        }
        // Drop Ctrl/Alt-modified chars so combos don't leak as text (both foci;
        // registered intercepts already claimed theirs above).
        if let KeyCode::Char(_) = key.code {
            let non_shift = key.modifiers - KeyModifiers::SHIFT;
            if !non_shift.is_empty() {
                return KeyReaction::Unhandled;
            }
        }
        // List focus: plain letters are verbs, never query text.
        if self.focus == Focus::List {
            if let KeyCode::Char(c) = key.code {
                return match c {
                    // `i` / `/` return to the input (cursor there, typing filters).
                    'i' | '/' => {
                        self.focus = Focus::Input;
                        KeyReaction::Consumed
                    }
                    'j' => {
                        self.select_next();
                        KeyReaction::Consumed
                    }
                    'k' => {
                        self.select_prev();
                        KeyReaction::Consumed
                    }
                    _ if self.list_verbs.contains(&c) => KeyReaction::ListVerb(c),
                    // Unregistered letters do NOTHING — never type into the query.
                    _ => KeyReaction::Consumed,
                };
            }
            // Other keys (Tab, function keys, …) are the surface's to handle.
            return KeyReaction::Unhandled;
        }
        let outcome = self.input.handle_key(key);
        // Sync/refresh/close the autocomplete popup based on the input outcome.
        // Build snapshot before taking &mut self.autocomplete (same borrow trick).
        let snap = self.autocomplete_snapshot();
        match outcome {
            InputOutcome::Changed => {
                if let Some(ac) = &mut self.autocomplete {
                    ac.sync(&snap);
                }
            }
            InputOutcome::Consumed => {
                if let Some(ac) = &mut self.autocomplete {
                    ac.refresh_if_open(&snap);
                }
            }
            InputOutcome::Cancel | InputOutcome::Submit => {
                if let Some(ac) = &mut self.autocomplete {
                    ac.close();
                }
            }
            InputOutcome::NotConsumed => {}
        }
        match outcome {
            InputOutcome::Changed => {
                self.sync_query_from_input();
                KeyReaction::Consumed
            }
            InputOutcome::Consumed => KeyReaction::Consumed,
            InputOutcome::Submit => KeyReaction::Submit,
            InputOutcome::Cancel => KeyReaction::Cancel,
            InputOutcome::NotConsumed => KeyReaction::Unhandled,
        }
    }

    pub fn render_query(&mut self, f: &mut Frame, area: Rect, theme: &Theme, focused: bool) {
        // The query input signals focus only when the panel is focused AND the
        // input half owns the keyboard; in list focus it renders unfocused
        // (dimmed, cursor hidden). For surfaces that never opt into list focus
        // `self.focus` is always `Input`, so this is byte-identical to today.
        self.input_rect = area;
        let focused = focused && self.focus == Focus::Input;
        let base = Style::default()
            .fg(theme.fg.to_ratatui())
            .bg(theme.bg_panel.to_ratatui());
        if self.highlight_query {
            let line =
                crate::components::query_highlight::highlight_line(self.input.value(), theme, base);
            self.input.render_line(f, area, line, base, 0, focused);
        } else {
            self.input.render(f, area, base, 0, focused);
        }
    }

    pub fn render(&mut self, f: &mut Frame, area: Rect, theme: &Theme, focused: bool) {
        self.poll();
        let sel = self.selected;
        let items: Vec<ListItem> = (0..self.visible_len())
            .filter_map(|pos| {
                self.visible_row(pos)
                    .map(|r| r.to_list_item(theme, &self.icons, sel == Some(pos)))
            })
            .collect();
        let mut state = ListState::default().with_offset(self.offset);
        state.select(self.selected);
        let list =
            List::new(items).highlight_style(Style::default().bg(theme.selection_bg.to_ratatui()));
        f.render_stateful_widget(list, area, &mut state);
        // Read the offset back: ratatui clamps it and keeps the selection in
        // view (keyboard moves included), so the stored offset always matches
        // what is actually on screen.
        self.offset = state.offset();
        self.list_rect = area;
        let _ = focused;
    }

    /// Override the rect used for mouse hit-testing. The recorded rect must be
    /// the area where list ITEMS actually render — row 0 is the first item, NOT
    /// a block border. Hosts that draw the list inside a bordered block pass the
    /// block's INNER rect; borderless hosts pass the list area directly. The
    /// recorded rect and the rendered-items rect MUST be identical, so
    /// [`handle_mouse`] maps a click at `row` to visual offset `row - rect.y`.
    ///
    /// [`handle_mouse`]: Self::handle_mouse
    pub fn set_list_rect(&mut self, rect: Rect) {
        self.list_rect = rect;
    }

    /// Record the host panel's full bounds so the wheel scrolls the list from
    /// anywhere within the panel — header, query box, preview — not just over
    /// the list items. Hosts call this each render with the same rect they
    /// were drawn into. Never set = wheel hit-tests `list_rect` only.
    pub fn set_panel_rect(&mut self, rect: Rect) {
        self.panel_rect = rect;
    }

    /// Record a host-owned scrollable sub-region (e.g. an expanded preview):
    /// wheel events inside it are routed back to the host as
    /// [`SearchMouse::ContentScrollUp`]/[`ContentScrollDown`] instead of
    /// scrolling the list. Hosts re-record it every render (empty when the
    /// sub-region is not drawn) so the hit-test never sees a stale rect.
    ///
    /// [`ContentScrollDown`]: SearchMouse::ContentScrollDown
    pub fn set_content_rect(&mut self, rect: Rect) {
        self.content_rect = rect;
    }

    /// Test-only: the recorded content sub-region (empty when none is on
    /// screen), so host tests can hit-test against where the preview was
    /// drawn.
    #[cfg(test)]
    pub(crate) fn content_rect(&self) -> Rect {
        self.content_rect
    }

    pub fn render_autocomplete(&mut self, f: &mut Frame, clamp: Rect, theme: &Theme) {
        if let Some(ac) = &mut self.autocomplete {
            ac.poll_results();
            let caret = self.input.last_caret_pos();
            if let (Some(state), Some(anchor)) = (ac.state_mut(), caret) {
                state.anchor = anchor;
            }
            if let Some(state) = ac.state_mut() {
                crate::components::autocomplete::render(f, state, clamp, theme);
            }
        }
    }

    /// Close an open autocomplete popup. [`handle_mouse`] does this for every
    /// event it sees ("any mouse interaction dismisses the popup"); hosts that
    /// consume a mouse event WITHOUT routing it through the engine call this
    /// to keep that rule intact.
    ///
    /// [`handle_mouse`]: Self::handle_mouse
    pub fn close_autocomplete(&mut self) {
        if let Some(ac) = &mut self.autocomplete {
            ac.close();
        }
    }

    /// Test-only: true when the autocomplete popup is open, so host tests
    /// can assert the any-mouse-interaction-dismisses rule.
    #[cfg(test)]
    pub(crate) fn autocomplete_is_open(&self) -> bool {
        self.autocomplete.as_ref().is_some_and(|ac| ac.is_open())
    }

    /// Whether (col,row) is on the query input drawn by the last
    /// [`Self::render_query`].
    pub fn input_contains(&self, col: u16, row: u16) -> bool {
        self.input_rect
            .contains(ratatui::layout::Position::new(col, row))
    }

    /// Whether (col,row) is on a row of the open autocomplete popup, as last
    /// drawn — a host that filters mouse events must let these through.
    pub fn popup_contains(&self, col: u16, row: u16) -> bool {
        self.autocomplete
            .as_ref()
            .and_then(|ac| ac.state())
            .is_some_and(|st| {
                st.rows_rect
                    .contains(ratatui::layout::Position::new(col, row))
            })
    }

    pub fn handle_mouse(&mut self, m: &ratatui::crossterm::event::MouseEvent) -> SearchMouse {
        self.handle_mouse_at(m, std::time::Instant::now())
    }

    /// [`Self::handle_mouse`] with the clock passed in, so a test describes a
    /// gap instead of sleeping through one.
    pub(crate) fn handle_mouse_at(
        &mut self,
        m: &ratatui::crossterm::event::MouseEvent,
        now: std::time::Instant,
    ) -> SearchMouse {
        use ratatui::crossterm::event::{MouseButton, MouseEventKind};
        use ratatui::layout::Position;
        // An open popup gets first crack: a click on a suggestion accepts
        // it, the wheel over it moves the highlight.
        if self.autocomplete.as_ref().is_some_and(|ac| ac.is_open()) {
            let snap = self.autocomplete_snapshot();
            if let Some(ac) = &mut self.autocomplete {
                match ac.handle_mouse(m, &snap) {
                    HandleKeyOutcome::Accepted(action) => {
                        self.apply_accept(action);
                        return SearchMouse::Autocomplete { edited: true };
                    }
                    HandleKeyOutcome::Consumed | HandleKeyOutcome::Dismissed => {
                        return SearchMouse::Autocomplete { edited: false };
                    }
                    HandleKeyOutcome::NotHandled => {}
                }
            }
        }
        // A press or a scroll anywhere else dismisses an open popup (a click
        // on the preview/border closes a stale popup). Pointer motion does
        // not: the terminal reports every move, and closing on those would
        // drop the popup before the pointer could reach it.
        if matches!(
            m.kind,
            MouseEventKind::Down(_) | MouseEventKind::ScrollUp | MouseEventKind::ScrollDown
        ) {
            self.close_autocomplete();
        }
        let pos = Position {
            x: m.column,
            y: m.row,
        };
        // The wheel is hit-tested against the host's panel bounds (when
        // recorded), so scrolling works from anywhere within the panel;
        // clicks below keep hit-testing the list rect only.
        if matches!(
            m.kind,
            MouseEventKind::ScrollUp | MouseEventKind::ScrollDown
        ) {
            // The host's content sub-region wins over the panel bounds: a
            // wheel inside it is the host's to handle (it scrolls its own
            // view), so route it back instead of moving the list.
            if !self.content_rect.is_empty() && self.content_rect.contains(pos) {
                return if m.kind == MouseEventKind::ScrollUp {
                    SearchMouse::ContentScrollUp
                } else {
                    SearchMouse::ContentScrollDown
                };
            }
            let bounds = if self.panel_rect.is_empty() {
                self.list_rect
            } else {
                self.panel_rect
            };
            if !bounds.contains(pos) {
                return SearchMouse::None;
            }
            if m.kind == MouseEventKind::ScrollUp {
                self.scroll_up();
            } else {
                self.scroll_down();
            }
            return SearchMouse::Scrolled;
        }
        if matches!(m.kind, MouseEventKind::Down(MouseButton::Left))
            && self.input_rect.contains(pos)
        {
            // The mouse's `i` / `/`: the input takes the keyboard back.
            self.focus = Focus::Input;
            return SearchMouse::InputFocused;
        }
        let r = self.list_rect;
        if !r.contains(pos) {
            return SearchMouse::None;
        }
        match m.kind {
            MouseEventKind::Down(MouseButton::Left | MouseButton::Right) if m.row >= r.y => {
                let right_click = matches!(m.kind, MouseEventKind::Down(MouseButton::Right));
                let target_visual = m.row - r.y; // 0-based visual offset; row 0 = first item
                let mut acc: u16 = 0;
                let mut hit: Option<usize> = None;
                // Walk the VISIBLE sequence (leading row at position 0, then the
                // display rows) starting at the viewport offset — screen row 0
                // is the item at `offset`, not visible position 0 — so visual
                // offsets map to the positions actually on screen.
                for pos in self.offset..self.visible_len() {
                    let h = self
                        .visible_row(pos)
                        .map(|r| r.visual_height())
                        .unwrap_or(1);
                    if target_visual < acc + h {
                        hit = Some(pos);
                        break;
                    }
                    acc += h;
                }
                if let Some(pos) = hit {
                    let prev = self.selected;
                    let prev_click = self.last_click_pos.replace(pos);
                    let prev_at = if right_click {
                        self.last_click_at.take()
                    } else {
                        self.last_click_at.replace(now)
                    };
                    self.selected = Some(pos);
                    self.selection_pinned = true;
                    let fast = prev_at
                        .is_some_and(|at| now.duration_since(at) < crate::components::DOUBLE_CLICK);
                    let was_activate = std::mem::take(&mut self.last_click_activated);
                    return if right_click {
                        SearchMouse::Context(pos)
                    } else if prev == Some(pos) && prev_click == Some(pos) && fast {
                        // A burst: a third press must not chain into a
                        // second double-click.
                        self.last_click_at = None;
                        SearchMouse::DoubleClicked {
                            pos,
                            repeat: was_activate,
                        }
                    } else if prev == Some(pos) && prev_click == Some(pos) {
                        // Activate only on click-click: the row was already
                        // selected BY A CLICK, not by auto-select or keys.
                        self.last_click_activated = true;
                        SearchMouse::Activated(pos)
                    } else {
                        SearchMouse::Selected(pos)
                    };
                }
                SearchMouse::None
            }
            _ => SearchMouse::None,
        }
    }

    fn recompute_display(&mut self) {
        let q = self.query.trim();
        // The leading row is query-fresh: rebuilt on every poll AND on every
        // local-filter `set_query`, so it never goes stale.
        self.leading = self.source.leading_row(q);
        // Source order, or `order_by` order when one is set.
        let mut base: Vec<usize> = (0..self.rows.len()).collect();
        if let Some(cmp) = &self.order {
            let rows = &self.rows;
            base.sort_by(|&a, &b| cmp(&rows[a], &rows[b]));
        }
        let mut idx: Vec<usize> = match &self.filter {
            Filter::SourceOrder => base,
            Filter::Fuzzy if q.is_empty() => base,
            Filter::Fuzzy => fuzzy_indices(&self.rows, &base, q),
            Filter::Rank(_) if q.is_empty() => base,
            Filter::Rank(f) => {
                let f = f.clone();
                f(&self.rows, &base, q)
            }
        };
        // Filter-exempt rows (match_text() == None: Up / Create / virtual pinned)
        // are always present; prepend any that the filter dropped.
        for i in 0..self.rows.len() {
            if self.rows[i].match_text().is_none() && !idx.contains(&i) {
                idx.insert(0, i);
            }
        }
        self.display = idx;
        self.clamp_selection();
    }

    #[cfg(test)]
    pub(crate) async fn poll_until_idle(&mut self) {
        // In-memory sources settle on the first poll (no sleep paid). Vault-backed
        // sources run their read on a worker/blocking thread, which can starve
        // under the full parallel suite — so once still loading, sleep a little
        // between polls and use a generous ceiling. Early-breaks the instant the
        // load lands, keeping the common (in-memory) path fast.
        for _ in 0..600 {
            tokio::task::yield_now().await;
            self.poll();
            if !self.is_loading() {
                break;
            }
            tokio::time::sleep(std::time::Duration::from_millis(2)).await;
        }
        self.poll();
    }
}

impl<R: SearchRow> SearchListBuilder<R> {
    pub fn initial_query(mut self, q: impl Into<String>) -> Self {
        self.initial_query = q.into();
        self
    }
    pub fn filter(mut self, f: Filter<R>) -> Self {
        self.filter = f;
        self
    }
    /// Keep the rows in this order regardless of arrival order. Composes with
    /// any [`Filter`]: with an empty query the order is the display order;
    /// under `Fuzzy` it decides ties between equally-scored matches. Change it
    /// later with [`SearchList::set_order`].
    pub fn order_by(mut self, cmp: OrderFn<R>) -> Self {
        self.order = Some(cmp);
        self
    }
    pub fn autocomplete(
        mut self,
        suggestions: Arc<dyn SuggestionSource>,
        mode: AutocompleteMode,
    ) -> Self {
        self.autocomplete = Some((suggestions, mode));
        self
    }
    /// Bind the yank chord to whatever the user has bound
    /// [`ActionShortcuts::YankRow`](crate::keys::action_shortcuts::ActionShortcuts::YankRow) to.
    /// Surfaces that hold `KeyBindings` should always call this — the builder
    /// default is only for those that do not (and for tests).
    pub fn yank_combos_from(self, bindings: &crate::keys::KeyBindings) -> Self {
        self.yank_combos(
            bindings.combos_for(&crate::keys::action_shortcuts::ActionShortcuts::YankRow),
        )
    }

    /// Override the yank chords directly (see [`Self::yank_combos_from`]).
    /// An empty list disables the chord for this surface.
    pub fn yank_combos(mut self, combos: Vec<KeyCombo>) -> Self {
        self.yank_combos = combos;
        self
    }

    pub fn intercept(mut self, v: Vec<KeyCombo>) -> Self {
        self.intercept = v;
        self
    }
    /// Render the query input with syntax highlighting.
    pub fn highlight_query(mut self) -> Self {
        self.highlight_query = true;
        self
    }
    pub fn icons(mut self, icons: Icons) -> Self {
        self.icons = icons;
        self
    }
    /// The focus the surface opens on (default [`Focus::Input`]). Opening on
    /// [`Focus::List`] also activates the list-focus state machine (so `Esc`
    /// cancels from the list rather than flipping into it).
    pub fn opening_focus(mut self, focus: Focus) -> Self {
        self.opening_focus = focus;
        self
    }
    /// Register a plain letter as a list-focus verb. In [`Focus::List`],
    /// pressing it returns [`KeyReaction::ListVerb`] with the char; the engine
    /// attaches no meaning — the caller decides the action. Registering any
    /// verb activates the list-focus state machine. `j`/`k`/`i`/`/` are
    /// reserved (navigation and focus switching) and win over a same-letter
    /// verb.
    pub fn list_verb(mut self, c: char) -> Self {
        self.list_verbs.push(c);
        self
    }
    /// Override the autocomplete controller's debounce. Tests use
    /// `Duration::ZERO` to get suggestions without waiting on the debounce timer.
    pub fn debounce(mut self, d: std::time::Duration) -> Self {
        self.debounce = Some(d);
        self
    }
    pub fn build(self) -> SearchList<R> {
        SearchList::new(self)
    }

    /// Build synchronously over a known, in-memory row set: the rows are
    /// applied and the initial selection seeded before this returns — no async
    /// load, no channel, no redraw round-trip. For static sources
    /// (`reload_on_query() == false`); the source's `load` is never called, so
    /// most static consumers pair this with [`StaticRowSource`]. The redraw
    /// callback passed to [`builder`](SearchList::builder) is never fired on
    /// this path.
    ///
    /// [`StaticRowSource`]: crate::components::search_list::StaticRowSource
    pub fn build_with_rows(self, rows: Vec<R>) -> SearchList<R> {
        SearchList::with_rows(self, rows)
    }
}

#[cfg(test)]
mod tests {
    use super::adapters::{
        ReloadWithLeadSource, ScriptedStreamLeadSource, ScriptedStreamSource, StreamRow, TestRow,
        VecSource, VecSourceWithLead,
    };
    use super::*;
    use ratatui::crossterm::event::{KeyCode, KeyEvent, KeyModifiers};

    fn noop_redraw() -> std::sync::Arc<dyn Fn() + Send + Sync> {
        std::sync::Arc::new(|| {})
    }

    fn key(c: KeyCode) -> KeyEvent {
        KeyEvent::new(c, KeyModifiers::NONE)
    }

    // ── The yank chord ────────────────────────────────────────────
    //
    // The bug these pin: yanking the selected row was hand-rolled per surface,
    // so the note browser — the most-reached list — silently had none. Claiming
    // the chord here means every SearchList surface gets it.

    fn yank_list(rows: &[&str]) -> SearchList<TestRow> {
        SearchList::builder(
            VecSource {
                rows: vec![],
                reload: false,
            },
            noop_redraw(),
        )
        .build_with_rows(rows.iter().map(|n| TestRow::new(n)).collect())
    }

    fn ctrl(c: char) -> KeyEvent {
        KeyEvent::new(KeyCode::Char(c), KeyModifiers::CONTROL)
    }

    #[test]
    fn yank_chord_reports_the_selected_rows_target() {
        let mut list = yank_list(&["alpha", "beta"]);
        match list.handle_key(&ctrl('y')) {
            KeyReaction::Yank(Some(t)) => {
                assert_eq!(t.text, "alpha");
                assert_eq!(t.noun, "path");
            }
            r => panic!("got {r:?}"),
        }
    }

    #[test]
    fn yank_chord_reports_none_for_a_row_with_nothing_to_copy() {
        // Distinguishable from "the clipboard failed" only because the row
        // says so — the caller flashes "nothing to copy".
        let mut list = yank_list(&["quiet"]);
        list.select_next();
        assert!(matches!(
            list.handle_key(&ctrl('y')),
            KeyReaction::Yank(None)
        ));
    }

    #[test]
    fn yank_chord_reports_none_when_nothing_is_selected() {
        let mut list = yank_list(&[]);
        assert!(matches!(
            list.handle_key(&ctrl('y')),
            KeyReaction::Yank(None)
        ));
    }

    #[test]
    fn yank_chord_is_claimed_before_ctrl_chars_are_dropped() {
        // The regression guard: the Ctrl/Alt drop below the chord check
        // returns `Unhandled`, which is what swallowed a per-panel yank that
        // was registered too late in the ladder.
        let mut list = yank_list(&["alpha"]);
        list.select_next();
        assert!(
            !matches!(list.handle_key(&ctrl('y')), KeyReaction::Unhandled),
            "the yank chord must not fall through to the Ctrl-char drop"
        );
    }

    #[test]
    fn a_rebound_yank_combo_replaces_the_default() {
        let mut list = SearchList::builder(
            VecSource {
                rows: vec![],
                reload: false,
            },
            noop_redraw(),
        )
        .yank_combos(vec![crate::keys::key_event_to_combo(&ctrl('k')).unwrap()])
        .build_with_rows(vec![TestRow::new("alpha")]);
        list.select_next();
        assert!(matches!(
            list.handle_key(&ctrl('k')),
            KeyReaction::Yank(Some(_))
        ));
        assert!(
            !matches!(list.handle_key(&ctrl('y')), KeyReaction::Yank(_)),
            "the default chord must stop yanking once overridden"
        );
    }

    fn mouse_down_at(col: u16, row: u16) -> ratatui::crossterm::event::MouseEvent {
        use ratatui::crossterm::event::{MouseButton, MouseEvent, MouseEventKind};
        MouseEvent {
            kind: MouseEventKind::Down(MouseButton::Left),
            column: col,
            row,
            modifiers: KeyModifiers::NONE,
        }
    }

    #[derive(Clone, Debug, PartialEq)]
    struct TallRow {
        name: String,
        height: u16,
    }
    impl SearchRow for TallRow {
        fn to_list_item(
            &self,
            _t: &crate::settings::themes::Theme,
            _i: &crate::settings::icons::Icons,
            _s: bool,
        ) -> ratatui::widgets::ListItem<'static> {
            ratatui::widgets::ListItem::new(self.name.clone())
        }
        fn visual_height(&self) -> u16 {
            self.height
        }
        fn match_text(&self) -> Option<&str> {
            Some(&self.name)
        }
    }
    struct TallSource(Vec<TallRow>);
    #[async_trait::async_trait]
    impl RowSource<TallRow> for TallSource {
        async fn load(&self, _q: &str, emit: Emit<TallRow>) {
            emit.replace(self.0.clone());
        }
    }

    /// The wheel is routed to the host (ContentScroll*) inside the recorded
    /// content sub-region — which wins over the panel bounds — and scrolls
    /// the list everywhere else within the panel.
    #[tokio::test]
    async fn wheel_in_content_rect_routes_to_host() {
        use ratatui::crossterm::event::{MouseEvent, MouseEventKind};
        let rows: Vec<TallRow> = (0..10)
            .map(|i| TallRow {
                name: format!("r{}", i),
                height: 1,
            })
            .collect();
        let mut list = SearchList::builder(TallSource(rows), noop_redraw()).build();
        list.poll_until_idle().await;
        let rect = |y: u16, h: u16| ratatui::layout::Rect {
            x: 0,
            y,
            width: 20,
            height: h,
        };
        // Panel covers rows 0..10; list draws in 0..4; content region 5..10.
        list.set_panel_rect(rect(0, 10));
        list.set_list_rect(rect(0, 4));
        list.set_content_rect(rect(5, 5));
        let wheel = |kind: MouseEventKind, row: u16| MouseEvent {
            kind,
            column: 2,
            row,
            modifiers: KeyModifiers::NONE,
        };

        // Inside the content region: routed to the host, list untouched.
        let m = wheel(MouseEventKind::ScrollDown, 6);
        assert_eq!(list.handle_mouse(&m), SearchMouse::ContentScrollDown);
        assert_eq!(list.offset, 0, "list viewport must not move");
        let m = wheel(MouseEventKind::ScrollUp, 6);
        assert_eq!(list.handle_mouse(&m), SearchMouse::ContentScrollUp);

        // Over the list (panel bounds, outside content): the list scrolls.
        let m = wheel(MouseEventKind::ScrollDown, 2);
        assert_eq!(list.handle_mouse(&m), SearchMouse::Scrolled);

        // Cleared sub-region: the wheel falls back to the panel-wide scroll.
        list.set_content_rect(ratatui::layout::Rect::default());
        let m = wheel(MouseEventKind::ScrollDown, 6);
        assert_eq!(list.handle_mouse(&m), SearchMouse::Scrolled);
    }

    #[tokio::test]
    async fn mouse_maps_visual_row_to_display_index_by_height() {
        // Row 0 occupies 3 visual rows, row 1 occupies 1. The recorded list rect
        // is the rendered-items area: row 0 == the FIRST item (no border row).
        let src = TallSource(vec![
            TallRow {
                name: "a".into(),
                height: 3,
            },
            TallRow {
                name: "b".into(),
                height: 1,
            },
        ]);
        let mut list = SearchList::builder(src, noop_redraw()).build();
        list.poll_until_idle().await;
        // Force the recorded list rect (render not run in test): items start at y=0.
        list.set_list_rect(ratatui::layout::Rect {
            x: 0,
            y: 0,
            width: 20,
            height: 10,
        });
        // "a" occupies rows 0..=2; row 3 is the FIRST row of "b".
        let m = mouse_down_at(2, 3);
        assert!(matches!(list.handle_mouse(&m), SearchMouse::Selected(1)));
        assert_eq!(list.selected_row().unwrap().name, "b");
        // A click at row 1 = within "a" (rows 0..=2) -> display index 0.
        let m = mouse_down_at(2, 1);
        list.handle_mouse(&m);
        assert_eq!(list.selected_row().unwrap().name, "a");
    }

    // Mouse-wheel scrolling moves the VIEWPORT, carrying the selection along
    // so the selected row keeps its on-screen position (selected - offset is
    // invariant) — unlike keyboard navigation, which moves the selection.
    #[tokio::test]
    async fn scroll_moves_viewport_and_keeps_selection_screen_position() {
        let src = VecSource {
            rows: (0..10).map(|i| TestRow::new(&format!("row{i}"))).collect(),
            reload: true,
        };
        let mut list = SearchList::builder(src, noop_redraw()).build();
        list.poll_until_idle().await;
        // Viewport shows 4 of the 10 rows.
        list.set_list_rect(ratatui::layout::Rect {
            x: 0,
            y: 0,
            width: 20,
            height: 4,
        });
        // Move the selection to screen row 2 first.
        list.select_next();
        list.select_next();
        assert_eq!(list.selected_row().unwrap().name, "row2");

        let scroll = |kind| ratatui::crossterm::event::MouseEvent {
            kind,
            column: 1,
            row: 1,
            modifiers: KeyModifiers::NONE,
        };
        use ratatui::crossterm::event::MouseEventKind;

        // Scroll down: viewport and selection move together.
        assert_eq!(
            list.handle_mouse(&scroll(MouseEventKind::ScrollDown)),
            SearchMouse::Scrolled
        );
        assert_eq!(list.scroll_offset(), 1);
        assert_eq!(list.selected_row().unwrap().name, "row3");

        // Scroll back up: both return.
        list.handle_mouse(&scroll(MouseEventKind::ScrollUp));
        assert_eq!(list.scroll_offset(), 0);
        assert_eq!(list.selected_row().unwrap().name, "row2");

        // At the top, scrolling up is a no-op (selection does NOT move).
        list.handle_mouse(&scroll(MouseEventKind::ScrollUp));
        assert_eq!(list.scroll_offset(), 0);
        assert_eq!(list.selected_row().unwrap().name, "row2");

        // Scrolling down clamps once the last row is in view: 10 rows in a
        // 4-row viewport → max offset 6.
        for _ in 0..20 {
            list.handle_mouse(&scroll(MouseEventKind::ScrollDown));
        }
        assert_eq!(list.scroll_offset(), 6);
        assert_eq!(list.selected_row().unwrap().name, "row8");
        // The selection kept its screen row through the clamped scroll.
        // (row2 at offset 0 → screen row 2; row8 at offset 6 → screen row 2.)
    }

    // The wheel hit-tests the recorded PANEL rect: scrolling over the host's
    // header/query box (outside the list rect) still scrolls the list. Without
    // a panel rect it falls back to the list rect only.
    #[tokio::test]
    async fn scroll_hits_panel_rect_clicks_hit_list_rect() {
        let src = VecSource {
            rows: (0..10).map(|i| TestRow::new(&format!("row{i}"))).collect(),
            reload: true,
        };
        let mut list = SearchList::builder(src, noop_redraw()).build();
        list.poll_until_idle().await;
        // List items render at y 5..9; the panel spans y 0..20.
        list.set_list_rect(ratatui::layout::Rect {
            x: 0,
            y: 5,
            width: 20,
            height: 4,
        });
        let scroll_at = |row| ratatui::crossterm::event::MouseEvent {
            kind: ratatui::crossterm::event::MouseEventKind::ScrollDown,
            column: 1,
            row,
            modifiers: KeyModifiers::NONE,
        };
        // No panel rect: a scroll over the header (y=1) misses.
        assert_eq!(list.handle_mouse(&scroll_at(1)), SearchMouse::None);
        assert_eq!(list.scroll_offset(), 0);
        list.set_panel_rect(ratatui::layout::Rect {
            x: 0,
            y: 0,
            width: 20,
            height: 20,
        });
        // With the panel rect, the same scroll-over-header scrolls the list.
        assert_eq!(list.handle_mouse(&scroll_at(1)), SearchMouse::Scrolled);
        assert_eq!(list.scroll_offset(), 1);
        // Clicks still hit-test the LIST rect only: a click on the header
        // (inside the panel, outside the list) selects nothing.
        let before = list.selected_row().unwrap().name.clone();
        assert_eq!(list.handle_mouse(&mouse_down_at(1, 1)), SearchMouse::None);
        assert_eq!(list.selected_row().unwrap().name, before);
    }

    // Regression: the click hit-test must account for the viewport offset —
    // after wheel scrolling, screen row 0 is the item at `offset`, not
    // visible position 0.
    #[tokio::test]
    async fn click_after_scroll_selects_the_clicked_row() {
        let src = VecSource {
            rows: (0..10).map(|i| TestRow::new(&format!("row{i}"))).collect(),
            reload: true,
        };
        let mut list = SearchList::builder(src, noop_redraw()).build();
        list.poll_until_idle().await;
        list.set_list_rect(ratatui::layout::Rect {
            x: 0,
            y: 0,
            width: 20,
            height: 4,
        });
        let scroll_down = ratatui::crossterm::event::MouseEvent {
            kind: ratatui::crossterm::event::MouseEventKind::ScrollDown,
            column: 1,
            row: 1,
            modifiers: KeyModifiers::NONE,
        };
        for _ in 0..3 {
            list.handle_mouse(&scroll_down);
        }
        assert_eq!(list.scroll_offset(), 3);
        // Screen row 2 shows visible position offset + 2 = 5.
        assert!(matches!(
            list.handle_mouse(&mouse_down_at(2, 2)),
            SearchMouse::Selected(5)
        ));
        assert_eq!(list.selected_row().unwrap().name, "row5");
        // Screen row 0 shows the item at the offset itself.
        list.handle_mouse(&mouse_down_at(2, 0));
        assert_eq!(list.selected_row().unwrap().name, "row3");
    }

    /// Two presses on a row inside the double-click window are a
    /// double-click; a slower second press is the old click-click
    /// activation. A third fast press does not chain into another double.
    #[tokio::test]
    async fn double_click_needs_a_fast_second_press() {
        let src = VecSource {
            rows: (0..3).map(|i| TestRow::new(&format!("row{i}"))).collect(),
            reload: true,
        };
        let mut list = SearchList::builder(src, noop_redraw()).build();
        list.poll_until_idle().await;
        list.set_list_rect(ratatui::layout::Rect::new(0, 0, 20, 3));
        let t0 = std::time::Instant::now();
        let ms = |n: u64| t0 + std::time::Duration::from_millis(n);
        let press = mouse_down_at(2, 1);

        assert_eq!(
            list.handle_mouse_at(&press, ms(0)),
            SearchMouse::Selected(1)
        );
        assert_eq!(
            list.handle_mouse_at(&press, ms(150)),
            SearchMouse::DoubleClicked {
                pos: 1,
                repeat: false
            }
        );
        assert_eq!(
            list.handle_mouse_at(&press, ms(250)),
            SearchMouse::Activated(1),
            "a third press is not a second double-click"
        );
        let slow = ms(250) + crate::components::DOUBLE_CLICK;
        assert_eq!(
            list.handle_mouse_at(&press, slow),
            SearchMouse::Activated(1),
            "a slow click-click still activates"
        );
    }

    /// A double-click on a row an earlier click already selected: the first
    /// press activates (slow click-click), the second completes the double
    /// — flagged `repeat`, so hosts where both mean "open" act once.
    #[tokio::test]
    async fn a_double_click_after_an_activation_is_a_repeat() {
        let src = VecSource {
            rows: (0..3).map(|i| TestRow::new(&format!("row{i}"))).collect(),
            reload: true,
        };
        let mut list = SearchList::builder(src, noop_redraw()).build();
        list.poll_until_idle().await;
        list.set_list_rect(ratatui::layout::Rect::new(0, 0, 20, 3));
        let t0 = std::time::Instant::now();
        let ms = |n: u64| t0 + std::time::Duration::from_millis(n);
        let press = mouse_down_at(2, 1);

        assert_eq!(
            list.handle_mouse_at(&press, ms(0)),
            SearchMouse::Selected(1)
        );
        assert_eq!(
            list.handle_mouse_at(&press, ms(1000)),
            SearchMouse::Activated(1)
        );
        assert_eq!(
            list.handle_mouse_at(&press, ms(1150)),
            SearchMouse::DoubleClicked {
                pos: 1,
                repeat: true
            }
        );
    }

    // The synchronous build seam: `build_with_rows` applies the rows and seeds
    // the selection in the same call — no poll, no spawn, `is_loading()` false
    // immediately. This is the static-source path (StaticRowSource); the row
    // set is readable on the very next line.
    #[tokio::test]
    async fn build_with_rows_applies_synchronously_without_a_poll() {
        let list = SearchList::builder(StaticRowSource, noop_redraw())
            .filter(Filter::Fuzzy)
            .build_with_rows(vec![TestRow::new("alpha"), TestRow::new("beta")]);
        // No poll, no settle: the rows and the seeded selection are live now.
        assert!(!list.is_loading(), "static build is not loading");
        assert_eq!(list.rows().len(), 2);
        assert_eq!(list.selected_row().map(|r| r.name.as_str()), Some("alpha"));
    }

    #[tokio::test]
    async fn initial_load_populates_rows() {
        let src = VecSource {
            rows: vec![TestRow::new("alpha"), TestRow::new("beta")],
            reload: true,
        };
        let mut list = SearchList::builder(src, noop_redraw()).build();
        list.poll_until_idle().await;
        assert_eq!(list.rows().len(), 2);
        assert_eq!(list.selected_row().map(|r| r.name.as_str()), Some("alpha"));
    }

    #[tokio::test]
    async fn requery_supersedes_and_reloads() {
        let src = VecSource {
            rows: vec![
                TestRow::new("alpha"),
                TestRow::new("alps"),
                TestRow::new("beta"),
            ],
            reload: true,
        };
        let mut list = SearchList::builder(src, noop_redraw()).build();
        list.poll_until_idle().await;
        assert_eq!(list.rows().len(), 3);
        list.set_query("alp");
        list.poll_until_idle().await;
        assert_eq!(list.rows().len(), 2); // alpha, alps
        assert!(list.rows().iter().all(|r| r.name.contains("alp")));
    }

    #[tokio::test]
    async fn arrows_navigate_and_enter_submits() {
        let src = VecSource {
            rows: vec![TestRow::new("a"), TestRow::new("b")],
            reload: true,
        };
        let mut list = SearchList::builder(src, noop_redraw()).build();
        list.poll_until_idle().await;
        assert_eq!(list.handle_key(&key(KeyCode::Down)), KeyReaction::Consumed);
        assert_eq!(list.selected_row().unwrap().name, "b");
        assert_eq!(list.handle_key(&key(KeyCode::Enter)), KeyReaction::Submit);
        assert_eq!(list.handle_key(&key(KeyCode::Esc)), KeyReaction::Cancel);
    }

    #[tokio::test]
    async fn typing_a_char_changes_query() {
        let src = VecSource {
            rows: vec![TestRow::new("alpha"), TestRow::new("beta")],
            reload: true,
        };
        let mut list = SearchList::builder(src, noop_redraw()).build();
        list.poll_until_idle().await;
        assert_eq!(
            list.handle_key(&key(KeyCode::Char('a'))),
            KeyReaction::Consumed
        );
        list.poll_until_idle().await;
        assert_eq!(list.query(), "a");
    }

    #[tokio::test]
    async fn rank_filter_orders_by_closure() {
        let src = VecSource {
            rows: vec![
                TestRow::new("todo"),
                TestRow::new("today"),
                TestRow::new("misc"),
            ],
            reload: false,
        };
        let rank = std::sync::Arc::new(|rows: &[TestRow], base: &[usize], q: &str| -> Vec<usize> {
            let mut idx: Vec<usize> = base
                .iter()
                .copied()
                .filter(|&i| rows[i].name.contains(q))
                .collect();
            idx.sort_by_key(|&i| if rows[i].name == q { 0 } else { 1 });
            idx
        });
        let mut list = SearchList::builder(src, noop_redraw())
            .filter(Filter::Rank(rank))
            .build();
        list.poll_until_idle().await;
        list.set_query("today");
        list.poll();
        assert_eq!(list.selected_row().unwrap().name, "today");
    }

    #[tokio::test]
    async fn fuzzy_filter_narrows_local_set() {
        let src = VecSource {
            rows: vec![TestRow::new("alpha"), TestRow::new("beta")],
            reload: false,
        };
        let mut list = SearchList::builder(src, noop_redraw())
            .filter(Filter::Fuzzy)
            .build();
        list.poll_until_idle().await;
        list.set_query("alp");
        list.poll();
        assert_eq!(list.visible_rows().len(), 1);
        assert_eq!(list.selected_row().unwrap().name, "alpha");
    }

    #[tokio::test]
    async fn streamed_rows_arrive_then_done_and_filter_locally() {
        let src = ScriptedStreamSource {
            batches: vec![vec![TestRow::new("alpha")], vec![TestRow::new("beta")]],
        };
        let mut list = SearchList::builder(src, noop_redraw())
            .filter(Filter::Fuzzy)
            .build();
        list.poll_until_idle().await;
        assert_eq!(list.rows().len(), 2);
        assert!(!list.is_loading());
        list.set_query("alp");
        list.poll();
        assert_eq!(list.visible_rows().len(), 1);
    }

    #[tokio::test]
    async fn source_order_unfiltered_passthrough() {
        let src = VecSource {
            rows: vec![TestRow::new("a"), TestRow::new("b")],
            reload: true,
        };
        let mut list = SearchList::builder(src, noop_redraw()).build(); // default Filter::SourceOrder
        list.poll_until_idle().await;
        assert_eq!(list.visible_rows().len(), 2);
        assert_eq!(list.selected_row().unwrap().name, "a");
    }

    #[tokio::test]
    async fn intercepted_combo_returns_intercepted_without_acting() {
        let src = VecSource {
            rows: vec![TestRow::new("a")],
            reload: true,
        };
        let combo = crate::keys::key_event_to_combo(&key(KeyCode::Enter)).unwrap();
        let mut list = SearchList::builder(src, noop_redraw())
            .intercept(vec![combo])
            .build();
        list.poll_until_idle().await;
        // Enter is intercepted: engine returns Intercepted, does NOT submit/act.
        assert_eq!(
            list.handle_key(&key(KeyCode::Enter)),
            KeyReaction::Intercepted(combo)
        );
    }

    #[tokio::test]
    async fn autocomplete_accept_rewrites_query_without_vault() {
        struct Mem;
        #[async_trait::async_trait]
        impl crate::components::search_list::SuggestionSource for Mem {
            async fn notes_by_prefix(
                &self,
                _p: &str,
                _n: usize,
            ) -> Vec<crate::components::search_list::SuggestionItem> {
                vec![]
            }
            async fn tags_by_prefix(
                &self,
                p: &str,
                _n: usize,
            ) -> Vec<crate::components::search_list::SuggestionItem> {
                if "projects".starts_with(p) {
                    vec![crate::components::search_list::SuggestionItem::plain(
                        "projects",
                    )]
                } else {
                    vec![]
                }
            }
        }
        let src = VecSource {
            rows: vec![],
            reload: true,
        };
        let mut list = SearchList::builder(src, noop_redraw())
            .autocomplete(
                std::sync::Arc::new(Mem),
                crate::components::autocomplete::AutocompleteMode::SearchQuery,
            )
            .debounce(std::time::Duration::ZERO)
            .build();
        for c in ['#', 'p', 'r', 'o'] {
            let _ = list.handle_key(&key(KeyCode::Char(c)));
        }
        for _ in 0..50 {
            tokio::task::yield_now().await;
            list.poll();
        }
        let _ = list.handle_key(&key(KeyCode::Tab));
        assert_eq!(list.query(), "#projects");
    }

    /// Pointer motion must not close the popup — the terminal reports every
    /// move, so the popup would vanish before the pointer reached it.
    #[tokio::test]
    async fn moving_the_pointer_keeps_the_popup_open() {
        struct Mem;
        #[async_trait::async_trait]
        impl crate::components::search_list::SuggestionSource for Mem {
            async fn notes_by_prefix(&self, _p: &str, _n: usize) -> Vec<SuggestionItem> {
                vec![]
            }
            async fn tags_by_prefix(&self, _p: &str, _n: usize) -> Vec<SuggestionItem> {
                vec![SuggestionItem::plain("projects")]
            }
        }
        let src = VecSource {
            rows: vec![],
            reload: true,
        };
        let mut list = SearchList::builder(src, noop_redraw())
            .autocomplete(
                std::sync::Arc::new(Mem),
                crate::components::autocomplete::AutocompleteMode::SearchQuery,
            )
            .debounce(std::time::Duration::ZERO)
            .build();
        for c in ['#', 'p'] {
            let _ = list.handle_key(&key(KeyCode::Char(c)));
        }
        for _ in 0..50 {
            tokio::task::yield_now().await;
            list.poll();
        }
        assert!(list.autocomplete_is_open());
        let moved = ratatui::crossterm::event::MouseEvent {
            kind: ratatui::crossterm::event::MouseEventKind::Moved,
            column: 30,
            row: 30,
            modifiers: KeyModifiers::NONE,
        };
        list.handle_mouse(&moved);
        assert!(list.autocomplete_is_open(), "motion keeps it");
        list.handle_mouse(&mouse_down_at(30, 30));
        assert!(!list.autocomplete_is_open(), "a press elsewhere closes it");
    }

    /// A click on a suggestion accepts it — the same rewrite Tab makes —
    /// and reports the edit so hosts run their query-edit path.
    #[tokio::test]
    async fn clicking_a_suggestion_accepts_it() {
        use ratatui::{Terminal, backend::TestBackend};
        struct Mem;
        #[async_trait::async_trait]
        impl crate::components::search_list::SuggestionSource for Mem {
            async fn notes_by_prefix(&self, _p: &str, _n: usize) -> Vec<SuggestionItem> {
                vec![]
            }
            async fn tags_by_prefix(&self, p: &str, _n: usize) -> Vec<SuggestionItem> {
                if "projects".starts_with(p) {
                    vec![SuggestionItem::plain("projects")]
                } else {
                    vec![]
                }
            }
        }
        let src = VecSource {
            rows: vec![],
            reload: true,
        };
        let mut list = SearchList::builder(src, noop_redraw())
            .autocomplete(
                std::sync::Arc::new(Mem),
                crate::components::autocomplete::AutocompleteMode::SearchQuery,
            )
            .debounce(std::time::Duration::ZERO)
            .build();
        for c in ['#', 'p', 'r', 'o'] {
            let _ = list.handle_key(&key(KeyCode::Char(c)));
        }
        for _ in 0..50 {
            tokio::task::yield_now().await;
            list.poll();
        }
        let theme = Theme::gruvbox_dark();
        let mut t = Terminal::new(TestBackend::new(40, 12)).unwrap();
        t.draw(|f| {
            let input = ratatui::layout::Rect::new(0, 0, 40, 1);
            list.render_query(f, input, &theme, true);
            list.render_autocomplete(f, f.area(), &theme);
        })
        .unwrap();
        let rows = list
            .autocomplete
            .as_ref()
            .and_then(|ac| ac.state())
            .map(|st| st.rows_rect)
            .expect("popup open");
        assert!(
            list.popup_contains(rows.x + 1, rows.y),
            "hosts that filter clicks can see the popup"
        );
        let click = match crate::test_support::mouse_down_at(rows.x + 1, rows.y) {
            crate::components::events::InputEvent::Mouse(m) => m,
            _ => unreachable!(),
        };
        assert_eq!(
            list.handle_mouse(&click),
            SearchMouse::Autocomplete { edited: true }
        );
        assert_eq!(list.query(), "#projects");
    }

    // Accepting a SavedSearch suggestion expands the whole field to the
    // stored query AND exposes the accepted name (for the breadcrumb) via
    // `take_accepted_saved_search`.
    #[tokio::test]
    async fn accepting_saved_search_expands_query_and_exposes_name() {
        struct Mem;
        #[async_trait::async_trait]
        impl crate::components::search_list::SuggestionSource for Mem {
            async fn notes_by_prefix(&self, _p: &str, _n: usize) -> Vec<SuggestionItem> {
                vec![]
            }
            async fn tags_by_prefix(&self, _p: &str, _n: usize) -> Vec<SuggestionItem> {
                vec![]
            }
            async fn saved_searches_by_prefix(&self, p: &str, _n: usize) -> Vec<SuggestionItem> {
                if "todo-week".starts_with(p) {
                    vec![SuggestionItem {
                        display: "todo-week".into(),
                        secondary: Some("#todo ^modified".into()),
                    }]
                } else {
                    vec![]
                }
            }
        }
        let src = VecSource {
            rows: vec![],
            reload: true,
        };
        let mut list = SearchList::builder(src, noop_redraw())
            .autocomplete(
                std::sync::Arc::new(Mem),
                crate::components::autocomplete::AutocompleteMode::SearchQuery,
            )
            .debounce(std::time::Duration::ZERO)
            .build();
        for c in ['?', 't', 'o'] {
            let _ = list.handle_key(&key(KeyCode::Char(c)));
        }
        for _ in 0..50 {
            tokio::task::yield_now().await;
            list.poll();
        }
        let _ = list.handle_key(&key(KeyCode::Tab));
        // Whole field expanded to the stored query.
        assert_eq!(list.query(), "#todo ^modified");
        // The accepted name is exposed once, then cleared.
        assert_eq!(
            list.take_accepted_saved_search().as_deref(),
            Some("todo-week")
        );
        assert_eq!(list.take_accepted_saved_search(), None);
    }

    // Regression: Enter (not just Tab) must accept an open autocomplete popup,
    // and the engine must report Consumed — NOT Submit — so a host does not
    // mistake the accept for a list submit. (A QueryPanel Enter pre-check used
    // to swallow this, breaking accept-on-Enter in the right sidebar.)
    #[tokio::test]
    async fn enter_accepts_open_popup_and_reports_consumed() {
        struct Mem;
        #[async_trait::async_trait]
        impl crate::components::search_list::SuggestionSource for Mem {
            async fn notes_by_prefix(
                &self,
                _p: &str,
                _n: usize,
            ) -> Vec<crate::components::search_list::SuggestionItem> {
                vec![]
            }
            async fn tags_by_prefix(
                &self,
                p: &str,
                _n: usize,
            ) -> Vec<crate::components::search_list::SuggestionItem> {
                if "projects".starts_with(p) {
                    vec![crate::components::search_list::SuggestionItem::plain(
                        "projects",
                    )]
                } else {
                    vec![]
                }
            }
        }
        let src = VecSource {
            rows: vec![],
            reload: true,
        };
        let mut list = SearchList::builder(src, noop_redraw())
            .autocomplete(
                std::sync::Arc::new(Mem),
                crate::components::autocomplete::AutocompleteMode::SearchQuery,
            )
            .debounce(std::time::Duration::ZERO)
            .build();
        for c in ['#', 'p', 'r', 'o'] {
            let _ = list.handle_key(&key(KeyCode::Char(c)));
        }
        for _ in 0..50 {
            tokio::task::yield_now().await;
            list.poll();
        }
        // Popup is open: Enter accepts the suggestion and reports Consumed.
        assert_eq!(list.handle_key(&key(KeyCode::Enter)), KeyReaction::Consumed);
        assert_eq!(list.query(), "#projects");
        // Popup now closed: a second Enter falls through to Submit.
        assert_eq!(list.handle_key(&key(KeyCode::Enter)), KeyReaction::Submit);
    }

    // Regression (P0): a STREAMED source (sidebar shape) supplies a query-fresh
    // leading row. It must appear at visible position 0 even though rows arrive
    // via Push (never Replace), be present when the query matches no streamed
    // row, and refresh when the query changes (reload_on_query() == false).
    #[tokio::test]
    async fn streamed_source_leading_row_is_pinned_and_query_fresh() {
        let src = ScriptedStreamLeadSource {
            items: vec!["alpha".into(), "beta".into()],
        };
        let mut list = SearchList::builder(src, noop_redraw())
            .filter(Filter::Fuzzy)
            .initial_query("zz")
            .build();
        list.poll_until_idle().await;
        // Leading present even though "zz" matches no streamed Item.
        let vis = list.visible_rows();
        assert_eq!(vis[0], &StreamRow::Create("zz".into()));
        assert_eq!(list.visible_len(), 1); // just the leading; no Item matches
        // Query-fresh: changing the query rebuilds the leading and re-filters.
        list.set_query("alp");
        list.poll();
        let vis = list.visible_rows();
        assert_eq!(vis[0], &StreamRow::Create("alp".into()));
        assert_eq!(vis[1], &StreamRow::Item("alpha".into()));
        assert_eq!(list.visible_len(), 2);
        // Empty query: leading disappears, both Items show.
        list.set_query("");
        list.poll();
        assert!(
            list.visible_rows()
                .iter()
                .all(|r| matches!(r, StreamRow::Item(_)))
        );
        assert_eq!(list.visible_len(), 2);
    }

    // Regression guard for the saved-searches virtual entry: a one-shot
    // (Replace) source with a leading row still pins it at position 0.
    #[tokio::test]
    async fn oneshot_source_leading_row_still_works() {
        let src = VecSourceWithLead {
            rows: vec![TestRow::new("alpha"), TestRow::new("beta")],
        };
        let mut list = SearchList::builder(src, noop_redraw())
            .filter(Filter::Fuzzy)
            .initial_query("alp")
            .build();
        list.poll_until_idle().await;
        let vis = list.visible_rows();
        assert_eq!(vis[0].name, "create:alp");
        assert_eq!(vis[1].name, "alpha");
        assert_eq!(list.visible_len(), 2);
    }

    // Selection walks the VISIBLE sequence: position 0 is the leading row, and
    // select_next steps from the leading to the first real row.
    #[tokio::test]
    async fn selection_includes_leading_at_position_zero() {
        let src = VecSourceWithLead {
            rows: vec![TestRow::new("alpha"), TestRow::new("alps")],
        };
        let mut list = SearchList::builder(src, noop_redraw())
            .filter(Filter::Fuzzy)
            .initial_query("alp")
            .build();
        list.poll_until_idle().await;
        // Auto-selected position 0 -> the leading.
        assert_eq!(list.selected_row().unwrap().name, "create:alp");
        list.handle_key(&key(KeyCode::Down));
        assert_eq!(list.selected_row().unwrap().name, "alpha");
    }

    // A source with NO leading row has no off-by-one: visible_len == display.
    #[tokio::test]
    async fn no_leading_row_visible_len_matches_display() {
        let src = VecSource {
            rows: vec![TestRow::new("a"), TestRow::new("b")],
            reload: true,
        };
        let mut list = SearchList::builder(src, noop_redraw()).build();
        list.poll_until_idle().await;
        assert_eq!(list.visible_len(), 2);
        assert_eq!(list.visible_rows().len(), 2);
        assert_eq!(list.selected_row().unwrap().name, "a");
    }

    // update_rows re-runs the active fuzzy filter after the mutation so rows
    // that no longer match the query drop out of the visible view.
    #[tokio::test]
    async fn update_rows_refilters_visible_view() {
        let source = VecSource {
            rows: vec![
                TestRow::new("alpha"),
                TestRow::new("beta"),
                TestRow::new("gamma"),
            ],
            reload: false,
        };
        let mut list = SearchList::builder(source, noop_redraw())
            .filter(Filter::Fuzzy)
            .build();
        list.poll_until_idle().await;

        // With query "alp", only "alpha" should be visible.
        list.set_query("alp");
        list.poll();
        assert_eq!(
            list.visible_rows()
                .iter()
                .map(|r| r.name.as_str())
                .collect::<Vec<_>>(),
            vec!["alpha"],
            "before update: only 'alpha' matches 'alp'"
        );

        // Rename "alpha" to something that no longer contains "alp".
        let changed = list.update_rows(|r| {
            if r.name == "alpha" {
                r.name = "renamed".to_string();
                true
            } else {
                false
            }
        });
        assert!(changed);

        // The visible view must now be empty: "renamed" does not match "alp".
        assert_eq!(
            list.visible_rows().len(),
            0,
            "after renaming 'alpha' -> 'renamed', nothing should match 'alp'"
        );
    }

    #[tokio::test]
    async fn update_rows_mutates_in_place_and_recomputes() {
        let source = VecSource {
            rows: vec![TestRow::new("alpha"), TestRow::new("beta")],
            reload: false,
        };
        let mut list = SearchList::builder(source, noop_redraw()).build();
        list.poll_until_idle().await;

        // Mutate the row named "alpha".
        let changed = list.update_rows(|r| {
            if r.name == "alpha" {
                r.name = "renamed".to_string();
                true
            } else {
                false
            }
        });
        assert!(changed, "a row was changed");
        assert!(
            list.rows().iter().any(|r| r.name == "renamed"),
            "the mutation is visible in rows()"
        );

        // A no-op mutation reports no change and does not panic.
        let changed_again = list.update_rows(|_| false);
        assert!(!changed_again, "no row changed");
    }

    // Regression guard (Fix A): for reload_on_query == true sources that also
    // expose a leading row, set_query must rebuild the leading row synchronously
    // in the same frame — before any poll/drain. The old code skipped
    // recompute_and_seed() for reload sources, so the leading row lagged until
    // the async load landed. This test must FAIL without the fix (the leading
    // row still shows the old query immediately after set_query).
    #[tokio::test]
    async fn reload_source_leading_row_updates_synchronously_on_set_query() {
        let src = ReloadWithLeadSource {
            rows: vec![
                TestRow::new("alpha"),
                TestRow::new("beta"),
                TestRow::new("gamma"),
            ],
        };
        let mut list = SearchList::builder(src, noop_redraw()).build();
        list.poll_until_idle().await;
        // Sanity: no leading row for empty query.
        assert!(list.leading.is_none(), "no leading row for empty query");

        // Change query — do NOT poll/drain after this.
        list.set_query("alp");

        // The leading row must reflect the NEW query immediately (synchronously).
        let vis = list.visible_rows();
        assert!(
            !vis.is_empty(),
            "visible_rows must not be empty right after set_query"
        );
        assert_eq!(
            vis[0].name, "create:alp",
            "leading row must show new query synchronously, before any poll/drain"
        );

        // The async load will also arrive, but the leading row must already be
        // correct without waiting for it.
        list.poll_until_idle().await;
        let vis = list.visible_rows();
        assert_eq!(
            vis[0].name, "create:alp",
            "leading row correct after drain too"
        );
        // Only "alpha" matches "alp" from the server-side filter.
        assert_eq!(vis.len(), 2, "leading + alpha");
        assert_eq!(vis[1].name, "alpha");
    }

    // Regression guard: local-filter sources (reload_on_query == false) must
    // reseed the selection back to row 0 when a filter change repopulates the
    // list after having emptied it.
    //
    // The gate in `poll()` (only recompute when drain is non-empty) must NOT
    // suppress the reseed for local filters, because they go through
    // `requery()` → `recompute_and_seed()` directly — no loader drain.
    #[tokio::test]
    async fn local_filter_reseed_after_empty_then_repopulate() {
        let src = VecSource {
            rows: vec![
                TestRow::new("alpha"),
                TestRow::new("beta"),
                TestRow::new("gamma"),
            ],
            reload: false,
        };
        let mut list = SearchList::builder(src, noop_redraw())
            .filter(Filter::Fuzzy)
            .build();
        list.poll_until_idle().await;

        // Sanity: initial load selected the first row.
        assert!(
            list.selected_row().is_some(),
            "should have a selection after initial load"
        );

        // Apply a filter that matches nothing → visible list is empty → selection cleared.
        list.set_query("zzznomatch");
        assert_eq!(list.visible_len(), 0, "no rows should match 'zzznomatch'");
        assert!(
            list.selected_row().is_none(),
            "selection must be None when list is empty"
        );

        // Widen the filter so rows come back (no drain will happen — local filter).
        list.set_query("alp");
        assert!(
            list.visible_len() > 0,
            "at least 'alpha' should match 'alp'"
        );
        // The selection MUST be reseeded to Some(0) — the subtlety the gating
        // would regress if recompute_and_seed() weren't called from requery().
        assert!(
            list.selected_row().is_some(),
            "selection must be reseeded to first visible row after repopulation"
        );
        assert_eq!(
            list.selected_row().unwrap().name,
            "alpha",
            "first visible row must be selected after reseeding"
        );
    }

    // ── List focus ──────────────────────────────────────────────────────

    async fn focus_list(verbs: &[char]) -> SearchList<TestRow> {
        let src = VecSource {
            rows: vec![TestRow::new("alpha"), TestRow::new("beta")],
            reload: false,
        };
        let mut b = SearchList::builder(src, noop_redraw()).filter(Filter::Fuzzy);
        for &c in verbs {
            b = b.list_verb(c);
        }
        let mut list = b.build();
        list.poll_until_idle().await;
        list
    }

    // Registering a verb activates the machine: the first Esc flips Input→List
    // (Consumed, not Cancel); a second Esc (now in List focus) Cancels.
    #[tokio::test]
    async fn esc_enters_list_focus_then_cancels() {
        let mut list = focus_list(&['l']).await;
        assert_eq!(list.focus(), Focus::Input);
        assert_eq!(list.handle_key(&key(KeyCode::Esc)), KeyReaction::Consumed);
        assert_eq!(list.focus(), Focus::List);
        assert_eq!(list.handle_key(&key(KeyCode::Esc)), KeyReaction::Cancel);
        assert_eq!(list.focus(), Focus::List, "Cancel does not change focus");
    }

    // Surfaces that never opt in keep byte-identical Esc→Cancel and stay Input.
    #[tokio::test]
    async fn esc_cancels_immediately_when_focus_disabled() {
        let mut list = focus_list(&[]).await;
        assert_eq!(list.handle_key(&key(KeyCode::Esc)), KeyReaction::Cancel);
        assert_eq!(list.focus(), Focus::Input);
    }

    // `i` and `/` return from List focus to Input focus.
    #[tokio::test]
    async fn i_and_slash_return_to_input_focus() {
        for ret in ['i', '/'] {
            let mut list = focus_list(&['l']).await;
            list.handle_key(&key(KeyCode::Esc)); // → List
            assert_eq!(list.focus(), Focus::List);
            assert_eq!(
                list.handle_key(&key(KeyCode::Char(ret))),
                KeyReaction::Consumed
            );
            assert_eq!(list.focus(), Focus::Input);
            assert_eq!(list.query(), "", "switching focus must not type a char");
        }
    }

    // In List focus `j`/`k` navigate (arrows keep working too).
    #[tokio::test]
    async fn list_focus_j_k_navigate() {
        let mut list = focus_list(&['l']).await;
        list.handle_key(&key(KeyCode::Esc)); // → List
        assert_eq!(list.selected_row().unwrap().name, "alpha");
        assert_eq!(
            list.handle_key(&key(KeyCode::Char('j'))),
            KeyReaction::Consumed
        );
        assert_eq!(list.selected_row().unwrap().name, "beta");
        assert_eq!(
            list.handle_key(&key(KeyCode::Char('k'))),
            KeyReaction::Consumed
        );
        assert_eq!(list.selected_row().unwrap().name, "alpha");
    }

    // A registered verb fires as ListVerb; an unregistered letter does NOTHING
    // (Consumed, query untouched) — it never types into the query.
    #[tokio::test]
    async fn registered_verb_fires_unregistered_letter_does_nothing() {
        let mut list = focus_list(&['l', 'o']).await;
        list.handle_key(&key(KeyCode::Esc)); // → List
        assert_eq!(
            list.handle_key(&key(KeyCode::Char('l'))),
            KeyReaction::ListVerb('l')
        );
        assert_eq!(
            list.handle_key(&key(KeyCode::Char('o'))),
            KeyReaction::ListVerb('o')
        );
        // 'z' is not registered: swallowed, query stays empty.
        assert_eq!(
            list.handle_key(&key(KeyCode::Char('z'))),
            KeyReaction::Consumed
        );
        assert_eq!(list.query(), "");
    }

    // In Input focus, verb letters type into the query exactly as before —
    // the verb is inert until the user Esc-es into the list.
    #[tokio::test]
    async fn verbs_are_inert_in_input_focus() {
        let mut list = focus_list(&['l', 'o']).await;
        assert_eq!(list.focus(), Focus::Input);
        assert_eq!(
            list.handle_key(&key(KeyCode::Char('l'))),
            KeyReaction::Consumed
        );
        list.poll_until_idle().await;
        assert_eq!(list.query(), "l", "verb letters still type in Input focus");
    }

    /// Clicking the query input is the mouse's `i`: list focus goes back to
    /// the input, so typing filters again.
    #[tokio::test]
    async fn clicking_the_input_gives_it_the_keyboard() {
        use ratatui::{Terminal, backend::TestBackend};
        let src = VecSource {
            rows: vec![TestRow::new("alpha"), TestRow::new("beta")],
            reload: false,
        };
        let mut list = SearchList::builder(src, noop_redraw())
            .filter(Filter::Fuzzy)
            .opening_focus(Focus::List)
            .build();
        list.poll_until_idle().await;
        let theme = Theme::gruvbox_dark();
        let mut t = Terminal::new(TestBackend::new(30, 1)).unwrap();
        t.draw(|f| list.render_query(f, f.area(), &theme, true))
            .unwrap();
        let m = match crate::test_support::mouse_down_at(3, 0) {
            crate::components::events::InputEvent::Mouse(m) => m,
            _ => unreachable!(),
        };
        assert_eq!(list.handle_mouse(&m), SearchMouse::InputFocused);
        assert_eq!(list.focus(), Focus::Input);
        list.handle_key(&key(KeyCode::Char('a')));
        list.poll_until_idle().await;
        assert_eq!(list.query(), "a");
    }

    // Opening on the list starts in List focus; a plain letter with no verb
    // registered does nothing (never types).
    #[tokio::test]
    async fn opening_focus_list_starts_in_list() {
        let src = VecSource {
            rows: vec![TestRow::new("alpha"), TestRow::new("beta")],
            reload: false,
        };
        let mut list = SearchList::builder(src, noop_redraw())
            .filter(Filter::Fuzzy)
            .opening_focus(Focus::List)
            .build();
        list.poll_until_idle().await;
        assert_eq!(list.focus(), Focus::List);
        assert_eq!(
            list.handle_key(&key(KeyCode::Char('a'))),
            KeyReaction::Consumed
        );
        assert_eq!(list.query(), "");
        // `i` drops to the input where typing filters again.
        list.handle_key(&key(KeyCode::Char('i')));
        assert_eq!(list.focus(), Focus::Input);
        list.handle_key(&key(KeyCode::Char('a')));
        list.poll_until_idle().await;
        assert_eq!(list.query(), "a");
    }

    // Registered intercepts fire in BOTH foci.
    #[tokio::test]
    async fn intercept_fires_in_both_foci() {
        let src = VecSource {
            rows: vec![TestRow::new("a")],
            reload: false,
        };
        let combo = crate::keys::key_event_to_combo(&key(KeyCode::Enter)).unwrap();
        let mut list = SearchList::builder(src, noop_redraw())
            .intercept(vec![combo])
            .list_verb('l')
            .build();
        list.poll_until_idle().await;
        // Input focus: intercepted.
        assert_eq!(
            list.handle_key(&key(KeyCode::Enter)),
            KeyReaction::Intercepted(combo)
        );
        // Flip to List focus, intercept still fires.
        list.handle_key(&key(KeyCode::Esc));
        assert_eq!(list.focus(), Focus::List);
        assert_eq!(
            list.handle_key(&key(KeyCode::Enter)),
            KeyReaction::Intercepted(combo)
        );
    }
}

#[cfg(test)]
mod order_tests {
    use super::adapters::{HeldEmitSource, ScriptedStreamSource, TestRow};
    use super::seams::RankFn;
    use super::*;
    use std::sync::{Arc, Mutex};

    fn noop_redraw() -> Arc<dyn Fn() + Send + Sync> {
        Arc::new(|| {})
    }

    fn by_name_asc() -> OrderFn<TestRow> {
        Arc::new(|a: &TestRow, b: &TestRow| a.name.cmp(&b.name))
    }

    fn by_name_desc() -> OrderFn<TestRow> {
        Arc::new(|a: &TestRow, b: &TestRow| b.name.cmp(&a.name))
    }

    fn names(list: &SearchList<TestRow>) -> Vec<String> {
        list.visible_rows().iter().map(|r| r.name.clone()).collect()
    }

    /// Rows pushed out of order land in `order_by` order, so a streamed
    /// listing is sorted at every frame, not only once the stream ends.
    #[tokio::test]
    async fn order_by_sorts_pushed_rows_as_they_arrive() {
        let source = ScriptedStreamSource {
            batches: vec![
                vec![TestRow::new("charlie")],
                vec![TestRow::new("alpha")],
                vec![TestRow::new("bravo")],
            ],
        };
        let mut list = SearchList::builder(source, noop_redraw())
            .filter(Filter::Fuzzy)
            .order_by(by_name_asc())
            .build();
        list.poll_until_idle().await;
        assert_eq!(names(&list), ["alpha", "bravo", "charlie"]);
    }

    /// Changing the order re-sorts the rows already in memory; no reload, no
    /// second trip to the source.
    #[tokio::test]
    async fn set_order_reorders_in_place_without_reload() {
        let source = ScriptedStreamSource {
            batches: vec![vec![
                TestRow::new("bravo"),
                TestRow::new("alpha"),
                TestRow::new("charlie"),
            ]],
        };
        let mut list = SearchList::builder(source, noop_redraw())
            .order_by(by_name_asc())
            .build();
        list.poll_until_idle().await;
        assert_eq!(names(&list), ["alpha", "bravo", "charlie"]);

        list.set_order(Some(by_name_desc()));

        assert!(!list.is_loading(), "reordering must not start a load");
        assert_eq!(names(&list), ["charlie", "bravo", "alpha"]);
    }

    /// Changing the sort must respect the same seeded/chosen split as a
    /// streaming poll: an untouched selection keeps the TOP slot of the new
    /// order, and stays a seed, so later-arriving rows still take it.
    ///
    /// Regression: `set_order` carried the selection by row index
    /// unconditionally, so a sort change pushed an untouched seed off the top
    /// row AND froze it at that numeric position — the highlight then walked
    /// across a different row on every subsequent poll.
    #[tokio::test]
    async fn changing_the_order_keeps_a_seeded_selection_on_the_top_row() {
        let slot = Arc::new(Mutex::new(None));
        let source = HeldEmitSource { slot: slot.clone() };
        let mut list = SearchList::builder(source, noop_redraw())
            .order_by(by_name_asc())
            .build();
        let emit = loop {
            if let Some(e) = slot.lock().unwrap().clone() {
                break e;
            }
            tokio::task::yield_now().await;
        };

        emit.push(TestRow::new("bravo"));
        emit.push(TestRow::new("charlie"));
        list.poll();
        assert_eq!(list.selected_row().map(|r| r.name.as_str()), Some("bravo"));

        list.set_order(Some(by_name_desc()));
        assert_eq!(names(&list), ["charlie", "bravo"]);
        assert_eq!(
            list.selected_row().map(|r| r.name.as_str()),
            Some("charlie"),
            "an untouched selection keeps the top slot of the new order"
        );

        // Still a seed, not a choice: the next row to sort above it takes it.
        emit.push(TestRow::new("delta"));
        list.poll();
        assert_eq!(names(&list), ["delta", "charlie", "bravo"]);
        assert_eq!(
            list.selected_row().map(|r| r.name.as_str()),
            Some("delta"),
            "a sort change must not silently turn a seed into a choice"
        );
        emit.done();
    }

    /// The chosen half of that split: a row the user picked stays picked
    /// across a sort change.
    #[tokio::test]
    async fn changing_the_order_keeps_a_chosen_selection_on_its_row() {
        let source = ScriptedStreamSource {
            batches: vec![vec![
                TestRow::new("bravo"),
                TestRow::new("alpha"),
                TestRow::new("charlie"),
            ]],
        };
        let mut list = SearchList::builder(source, noop_redraw())
            .order_by(by_name_asc())
            .build();
        list.poll_until_idle().await;
        list.select_next(); // "bravo", by the user's own keys
        assert_eq!(list.selected_row().map(|r| r.name.as_str()), Some("bravo"));

        list.set_order(Some(by_name_desc()));
        assert_eq!(names(&list), ["charlie", "bravo", "alpha"]);
        assert_eq!(
            list.selected_row().map(|r| r.name.as_str()),
            Some("bravo"),
            "a chosen selection tracks its row through a re-sort"
        );
    }

    /// A nudge that hits the end of the list moves nothing, so it must not
    /// turn a seed into a choice — otherwise one stray `Up` on the first row
    /// of a streaming listing freezes the highlight and lets it drift.
    #[tokio::test]
    async fn a_nudge_that_moves_nothing_leaves_the_seed_a_seed() {
        let slot = Arc::new(Mutex::new(None));
        let source = HeldEmitSource { slot: slot.clone() };
        let mut list = SearchList::builder(source, noop_redraw())
            .order_by(by_name_asc())
            .build();
        let emit = loop {
            if let Some(e) = slot.lock().unwrap().clone() {
                break e;
            }
            tokio::task::yield_now().await;
        };

        emit.push(TestRow::new("charlie"));
        list.poll();
        list.select_prev(); // already on the only (top) row: nothing moves
        list.select_next(); // already on the only (last) row: nothing moves
        assert_eq!(
            list.selected_row().map(|r| r.name.as_str()),
            Some("charlie")
        );

        emit.push(TestRow::new("alpha"));
        list.poll();
        assert_eq!(names(&list), ["alpha", "charlie"]);
        assert_eq!(
            list.selected_row().map(|r| r.name.as_str()),
            Some("alpha"),
            "a keypress that changed nothing must leave the selection seeded"
        );
        emit.done();
    }

    /// A row the user selected while rows were still streaming stays selected
    /// when a later row sorts in above it.
    #[tokio::test]
    async fn selection_follows_its_row_while_rows_stream_in() {
        let slot = Arc::new(Mutex::new(None));
        let source = HeldEmitSource { slot: slot.clone() };
        let mut list = SearchList::builder(source, noop_redraw())
            .order_by(by_name_asc())
            .build();
        let emit = loop {
            if let Some(e) = slot.lock().unwrap().clone() {
                break e;
            }
            tokio::task::yield_now().await;
        };

        emit.push(TestRow::new("bravo"));
        emit.push(TestRow::new("charlie"));
        list.poll();
        list.select_next();
        assert_eq!(
            list.selected_row().map(|r| r.name.as_str()),
            Some("charlie")
        );

        emit.push(TestRow::new("alpha"));
        list.poll();

        assert_eq!(names(&list), ["alpha", "bravo", "charlie"]);
        assert_eq!(
            list.selected_row().map(|r| r.name.as_str()),
            Some("charlie"),
            "selection tracks the row, not its old position"
        );
        emit.done();
    }

    /// `order_by` composes with a [`Filter::Rank`] surface: the ranker is
    /// handed the candidate indices in `order_by` order, so rows it scores
    /// equally keep the list's order.
    ///
    /// Regression: the `Rank` arm ranked `self.rows` directly and threw `base`
    /// away, so pairing a rank filter with an order was a silent no-op.
    #[tokio::test]
    async fn order_by_composes_with_a_rank_filter() {
        // Keeps every row containing the query, in the order it was handed.
        let rank: RankFn<TestRow> = Arc::new(|rows: &[TestRow], base: &[usize], q: &str| {
            base.iter()
                .copied()
                .filter(|&i| rows[i].name.contains(q))
                .collect()
        });
        let source = ScriptedStreamSource {
            batches: vec![vec![
                TestRow::new("charlie"),
                TestRow::new("alpha"),
                TestRow::new("bravo"),
            ]],
        };
        let mut list = SearchList::builder(source, noop_redraw())
            .filter(Filter::Rank(rank))
            .order_by(by_name_asc())
            .build();
        list.poll_until_idle().await;
        list.set_query("a"); // every row matches, so only the order decides
        assert_eq!(names(&list), ["alpha", "bravo", "charlie"]);
    }

    /// The other half of that contract: a selection the user has NEVER moved
    /// is not a choice, it is a seed. It must stay on the top of the
    /// `order_by` order as rows stream in.
    ///
    /// Regression: `poll` carried the seeded selection by row index like a
    /// user-chosen one, so on a slow (streamed) directory the initial
    /// highlight stuck to whichever entry the walker happened to emit first
    /// and drifted down the list as better-sorting rows arrived above it.
    #[tokio::test]
    async fn a_seeded_selection_stays_on_the_top_row_as_rows_stream_in() {
        let slot = Arc::new(Mutex::new(None));
        let source = HeldEmitSource { slot: slot.clone() };
        let mut list = SearchList::builder(source, noop_redraw())
            .order_by(by_name_asc())
            .build();
        let emit = loop {
            if let Some(e) = slot.lock().unwrap().clone() {
                break e;
            }
            tokio::task::yield_now().await;
        };

        // First row to arrive seeds the selection.
        emit.push(TestRow::new("charlie"));
        list.poll();
        assert_eq!(
            list.selected_row().map(|r| r.name.as_str()),
            Some("charlie")
        );

        // A row that sorts above it must take the highlight with the top slot.
        emit.push(TestRow::new("alpha"));
        list.poll();
        assert_eq!(names(&list), ["alpha", "charlie"]);
        assert_eq!(
            list.selected_row().map(|r| r.name.as_str()),
            Some("alpha"),
            "an untouched selection seeds to the top of the order, not to the first-arrived row"
        );
        emit.done();
    }

    /// Moving the selection and landing back on the top row still counts as a
    /// choice: from then on it tracks that row, exactly as any other
    /// user-chosen selection does.
    #[tokio::test]
    async fn a_selection_moved_back_to_the_top_row_is_still_pinned_to_it() {
        let slot = Arc::new(Mutex::new(None));
        let source = HeldEmitSource { slot: slot.clone() };
        let mut list = SearchList::builder(source, noop_redraw())
            .order_by(by_name_asc())
            .build();
        let emit = loop {
            if let Some(e) = slot.lock().unwrap().clone() {
                break e;
            }
            tokio::task::yield_now().await;
        };

        emit.push(TestRow::new("bravo"));
        emit.push(TestRow::new("charlie"));
        list.poll();
        list.select_next();
        list.select_prev(); // back on "bravo", but by the user's own keys
        assert_eq!(list.selected_row().map(|r| r.name.as_str()), Some("bravo"));

        emit.push(TestRow::new("alpha"));
        list.poll();
        assert_eq!(names(&list), ["alpha", "bravo", "charlie"]);
        assert_eq!(
            list.selected_row().map(|r| r.name.as_str()),
            Some("bravo"),
            "a selection the user placed tracks its row even when it sits at the top"
        );
        emit.done();
    }
}