lattice_picker/

context.rs

//! Host-built snapshot the picker primitive hands to source
//! generators on every `:picker <source>` open.
//!
//! `PickerContext` is the *runtime-varying* "where am I"
//! state every picker source needs: the active buffer, the
//! workspace root, the recent-files MRU, marks, registers,
//! and the position-history ring. It does NOT carry feature-
//! specific facades (LSP supervisor handle, snippet registry,
//! grammar registry) -- those are captured by source
//! generators at construction time. See
//! `docs/dev/architecture/picker.md` for why.
//!
//! The struct is borrow-heavy by design: sync sources read
//! straight through the borrows, async sources clone what
//! they need into their future's captures before the
//! synchronous `init` call returns. Three fields are owned
//! vecs (`buffers`, `marks`, `registers`) -- the App rebuilds
//! these fresh on each picker-open because their backing
//! state lives in non-borrow-friendly types (HashMaps with
//! transient liveness). Allocation cost is trivial at our
//! sizes (<100 buffers, <26 marks, <40 registers).

use std::path::{Path, PathBuf};
use std::sync::Arc;

use lattice_core::Buffer;
use lattice_protocol::Position;

/// Snapshot the host passes to `PickerSourceGenerator::init`
/// (and `accept`) on each picker invocation.
///
/// Sources access the borrowed fields directly during the
/// synchronous prelude; the moment `init` returns, the
/// borrow is released and any captured async work owns its
/// own clones.
pub struct PickerContext<'a> {
    pub active_buffer: ActiveBufferSnapshot<'a>,
    /// The active buffer's **project root** (PR.4), resolved by the
    /// host through `ProjectResolverHandle::for_path`.
    ///
    /// NOT the process working directory, and not the active
    /// document's parent — both were tried and both were wrong in
    /// opposite directions. The parent "behaved unintuitively for
    /// projects spread across many subdirectories"; the cwd is right
    /// only if you launched the editor inside the tree you are
    /// editing. A source wanting "where does this file's project
    /// live" reads this and needs nothing else.
    ///
    /// Degrades to the process cwd (then `.`) only when no
    /// `ProjectResolverHandle` is registered — a test harness, not a
    /// real boot. Owned because that fallback is fallible and the
    /// PathBuf needs somewhere stable to live.
    pub workspace_root: PathBuf,
    pub recent_files: &'a [PathBuf],
    /// Position-history ring, translated from the App's richer
    /// `PositionEntry` (which carries `BufferKind`) to this
    /// crate's picker-friendly view. Owned vec because the
    /// translation step produces fresh entries -- consistent
    /// with `buffers` / `marks` / `registers` below.
    pub position_history: Vec<PositionEntry>,
    pub buffers: Vec<BufferEntry>,
    pub marks: Vec<(char, Position)>,
    /// Registers as `(name, contents)` pairs, with the **full**
    /// contents.
    ///
    /// It used to carry a 40-char preview with newlines replaced by
    /// `\u{21B5}`, which was harmless while the only consumer routed
    /// `PasteRegister { name }` and the host re-read the register itself.
    /// `yank-ring` returns the text directly, so a preview here meant
    /// picking a long register inserted a truncation — and one with `↵`
    /// where its newlines had been, so corrupt rather than merely short.
    ///
    /// Consumers truncate for display; only display should be lossy.
    pub registers: Vec<(String, String)>,
    /// YR.4: the yank ring, newest first, as
    /// `(content, linewise)` pairs.
    ///
    /// The full content, not a preview — the picker's accept has to
    /// return the real text, and truncating here would mean pasting a
    /// truncation. `registers` above carries previews because its accept
    /// is `PasteRegister { name }`, which re-reads the register host-side
    /// rather than carrying its text.
    ///
    /// `linewise` rides along because a linewise and a charwise entry
    /// paste differently, and a picker that hides that makes paste
    /// unpredictable exactly when the user is choosing between two
    /// similar-looking rows.
    pub yank_ring: Vec<(String, bool)>,
    /// MARG.3 (2026-07-15): active minor+major mode names for the
    /// current buffer. The command completion margin uses this to
    /// filter out keybindings whose source minor/major mode is not
    /// currently active (see [`KeybindingSource::Mode`]).
    pub active_modes: Vec<Arc<str>>,
    /// MB.3: the App's command-line history ring (`command_history`),
    /// oldest-first as stored host-side. The `history` picker source
    /// (`q:` / `:history`) walks this reversed (newest first) and
    /// `<CR>` loads the chosen entry into the `:` line without
    /// executing. Owned vec, rebuilt per picker-open like the other
    /// snapshot fields.
    pub command_history: Vec<String>,
    /// MB.5: the App's search-line history ring (`search_history`),
    /// oldest-first as stored host-side. The `search-history` picker
    /// source (`q/` / `q?` / `:history search`) walks this reversed
    /// (newest first) and `<CR>` loads the chosen entry into the `/`
    /// search line without executing.
    pub search_history: Vec<String>,
    /// PBH.5: the ACTIVE pane's buffer trail, oldest-first, as
    /// `(label, is_current)` per entry. The `pane-buffer-history`
    /// source (`:history pane-buffers`) walks this reversed so the most
    /// recent stop is on top, and marks the entry the walk cursor is
    /// currently on.
    ///
    /// Per-pane by construction: the host snapshots only the active
    /// pane's trail, so the picker cannot accidentally show a global
    /// or cross-pane view.
    pub pane_buffer_history: Vec<PaneHistoryRow>,
}

/// PBH.5: one row of the active pane's buffer trail, flattened for the
/// picker.
///
/// Carries the trail **index** rather than a buffer id: the same buffer
/// can appear at several points in a trail, and accepting the third
/// stop must land on the third stop, not the first occurrence.
pub struct PaneHistoryRow {
    /// Position in the trail, oldest-first. The accept payload.
    pub index: u32,
    /// Display label — the buffer's name or path.
    pub label: String,
    /// Line the trail recorded for this stop (1-based for display).
    pub line: u32,
    /// Whether the walk cursor currently sits on this entry.
    pub is_current: bool,
}

/// Snapshot of the active document buffer at the moment the
/// picker opened. Carries enough state for line / mark /
/// outline / grep / LSP-position sources to do their work
/// without a second App round-trip.
pub struct ActiveBufferSnapshot<'a> {
    pub buffer_id: u32,
    pub path: Option<&'a Path>,
    /// Language id (`"rust"`, `"markdown"`, ...). Snippet and
    /// outline sources filter on this; absent for unknown /
    /// untyped buffers.
    pub language: Option<&'a str>,
    pub cursor: Position,
    /// Visual-mode selection extent at picker-open, if any.
    /// `:picker grep` defaults its pattern to the selected
    /// text when present.
    pub selection: Option<(Position, Position)>,
    /// Read-only borrow of the rope. Line / outline / grep
    /// sources walk this directly; long-running async work
    /// must extract what it needs before `init` returns.
    pub buffer: &'a Buffer,
    /// Tree-sitter symbol locations (name, line, byte-col)
    /// for the active buffer when syntax is available.
    /// Pre-collected by the host via
    /// `Syntax::collect_symbol_locations`; empty when there's
    /// no parser registered for the buffer's language. Drives
    /// `:picker outline`.
    pub syntax_symbols: Vec<(String, u32, u32)>,
    /// PH.2: per-line syntax-highlight spans for the active
    /// buffer, one inner `Vec` per buffer line, each span's
    /// `range` a *line-relative* byte range. Pre-collected by
    /// the host via `SyntaxSnapshot::highlight_lines` (a
    /// read-only tree query run off the render thread, mirroring
    /// the `syntax_symbols` precedent) and already mapped to
    /// `DisplaySpan` host-side so this crate needs no
    /// `lattice-cells` dependency. Empty when no grammar is
    /// registered / the snapshot is stale → plain previews.
    /// `LinesSource` clones the matching line's spans into a
    /// candidate's `display_spans`; `OutlineSource` clips them
    /// to the symbol-name column. See
    /// `docs/dev/architecture/picker-preview-highlight.md` §6.
    pub syntax_highlights: Vec<Vec<lattice_completion::DisplaySpan>>,
}

/// One buffer in the registry, projected for picker rows.
/// `kind_label` is a display string -- the picker primitive
/// stays oblivious to the actual `BufferKind` enum so the
/// "no kind-specific logic" rule (CLAUDE.md memory) holds at
/// this seam too.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BufferEntry {
    pub id: u32,
    pub kind_label: String,
    pub path: Option<PathBuf>,
    pub title: String,
    pub dirty: bool,
}

/// Picker-friendly view of one entry in the App's
/// position-history ring (§5.1.1 unified jump list + mark
/// ring). The App's richer `PositionEntry` carries
/// `BufferKind` + framework-internal fields; the picker only
/// needs `(buffer_id, line, col, source)` to render a row
/// and emit a jump outcome.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PositionEntry {
    pub buffer_id: u32,
    pub line: u32,
    pub col: u32,
    pub source: PositionSource,
}

/// Why this entry was pushed onto the position history.
/// Mirror of `lattice_ui_tui::app::PositionSource` but kept
/// here so `lattice-picker` doesn't depend on the host
/// crate. The App translates between the two at
/// PickerContext-build time.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PositionSource {
    /// Big motions: `gg`, `G`, search, `*`, `#`, `%`, mark jump.
    AutoJump,
    /// Explicit user "remember here" push (reserved for
    /// `g<C-o>` style emacs-`set-mark` equivalents).
    ExplicitMark,
    /// LSP / fuzzy-finder / plugin-pushed jumps.
    PluginPush,
    /// Named mark (`mX`). Walks via `g;` / `g,`.
    NamedMark(char),
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn buffer_entry_clone_and_eq() {
        let a = BufferEntry {
            id: 7,
            kind_label: "doc".into(),
            path: Some("/tmp/foo.rs".into()),
            title: "foo.rs".into(),
            dirty: false,
        };
        let b = a.clone();
        assert_eq!(a, b);
    }

    #[test]
    fn position_entry_carries_source_variant() {
        let e = PositionEntry {
            buffer_id: 3,
            line: 12,
            col: 4,
            source: PositionSource::NamedMark('a'),
        };
        assert_eq!(
            e.source,
            PositionSource::NamedMark('a'),
            "NamedMark name survives copy"
        );
        assert_ne!(e.source, PositionSource::AutoJump);
    }
}