chore: Update docs for - feat: Show the actual matches for typo resistant fuzzy search

closes https://github.com/dmtrKovalenko/fff.nvim/issues/269
closes https://github.com/dmtrKovalenko/fff.nvim/issues/256

.github/workflows/external-tests.yml

@@ -44,7 +44,7 @@ jobs:
 
       - name: Build Rust binary (Windows)
         if: matrix.target
-        run: cargo build --release --target ${{ matrix.target }} -p fff-nvim
+        run: cargo build --release --target ${{ matrix.target }} -p fff-nvim --features zlob
 
       - name: Copy binary to target/release (Windows)
         if: matrix.target
@@ -71,7 +71,7 @@ jobs:
 
       - name: Build Rust binary
         if: ${{ !matrix.target }}
-        run: cargo build --release -p fff-nvim
+        run: cargo build --release -p fff-nvim --features zlob
 
       - name: Install Neovim
         uses: rhysd/action-setup-vim@v1

.github/workflows/release.yaml

@@ -81,7 +81,7 @@ jobs:
       - name: Build for Linux
         if: contains(matrix.os, 'ubuntu') && !contains(matrix.target, 'android')
         run: |
-          cargo zigbuild --release --target ${{ matrix.zigbuild_target || matrix.target }} -p fff-nvim
+          cargo zigbuild --release --target ${{ matrix.zigbuild_target || matrix.target }} -p fff-nvim --features zlob
           mv "${{ matrix.artifact_name }}" "${{ matrix.target }}.${{ matrix.ext }}"
 
       - name: Build for Android (Termux)
@@ -95,13 +95,13 @@ jobs:
           export AR_aarch64_linux_android="$NDK_BIN/llvm-ar"
           export CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER="$NDK_BIN/aarch64-linux-android24-clang"
 
-          cargo build --release --target ${{ matrix.target }} -p fff-nvim
+          cargo build --release --target ${{ matrix.target }} -p fff-nvim --features zlob
           mv "${{ matrix.artifact_name }}" "${{ matrix.target }}.${{ matrix.ext }}"
 
       - name: Build for macOS
         if: contains(matrix.os, 'macos')
         run: |
-          MACOSX_DEPLOYMENT_TARGET="13" cargo build --release --target ${{ matrix.target }} -p fff-nvim
+          MACOSX_DEPLOYMENT_TARGET="13" cargo build --release --target ${{ matrix.target }} -p fff-nvim --features zlob
           mv "${{ matrix.artifact_name }}" "${{ matrix.target }}.${{ matrix.ext }}"
 
       - name: Ad-hoc sign macOS binary
@@ -112,7 +112,7 @@ jobs:
         if: contains(matrix.os, 'windows')
         shell: bash
         run: |
-          cargo build --release --target ${{ matrix.target }} -p fff-nvim
+          cargo build --release --target ${{ matrix.target }} -p fff-nvim --features zlob
           mv "${{ matrix.artifact_name }}" "${{ matrix.target }}.${{ matrix.ext }}"
 
       - name: Upload artifacts
@@ -212,7 +212,7 @@ jobs:
       - name: Build for Linux
         if: contains(matrix.os, 'ubuntu') && !contains(matrix.target, 'android')
         run: |
-          cargo zigbuild --release --target ${{ matrix.zigbuild_target || matrix.target }} -p fff-c
+          cargo zigbuild --release --target ${{ matrix.zigbuild_target || matrix.target }} -p fff-c --features zlob
           mv "${{ matrix.artifact_name }}" "c-lib-${{ matrix.target }}.${{ matrix.ext }}"
 
       - name: Build for Android (Termux)
@@ -225,13 +225,13 @@ jobs:
           export AR_aarch64_linux_android="$NDK_BIN/llvm-ar"
           export CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER="$NDK_BIN/aarch64-linux-android24-clang"
 
-          cargo build --release --target ${{ matrix.target }} -p fff-c
+          cargo build --release --target ${{ matrix.target }} -p fff-c --features zlob
           mv "${{ matrix.artifact_name }}" "c-lib-${{ matrix.target }}.${{ matrix.ext }}"
 
       - name: Build for macOS
         if: contains(matrix.os, 'macos')
         run: |
-          MACOSX_DEPLOYMENT_TARGET="13" cargo build --release --target ${{ matrix.target }} -p fff-c
+          MACOSX_DEPLOYMENT_TARGET="13" cargo build --release --target ${{ matrix.target }} -p fff-c --features zlob
           mv "${{ matrix.artifact_name }}" "c-lib-${{ matrix.target }}.${{ matrix.ext }}"
 
       - name: Ad-hoc sign macOS binary
@@ -242,7 +242,7 @@ jobs:
         if: contains(matrix.os, 'windows')
         shell: bash
         run: |
-          cargo build --release --target ${{ matrix.target }} -p fff-c
+          cargo build --release --target ${{ matrix.target }} -p fff-c --features zlob
           mv "${{ matrix.artifact_name }}" "c-lib-${{ matrix.target }}.${{ matrix.ext }}"
 
       - name: Prepare npm package

.github/workflows/rust.yml

@@ -37,7 +37,9 @@ jobs:
           components: rustfmt, clippy
 
       - name: Run tests
-        run: cargo test --verbose --workspace --exclude fff-nvim
+        run: |
+          cargo test --verbose -p fff-core -p fff-query-parser -p fff-c --features zlob
+          cargo test --verbose -p grep-searcher
 
   fmt:
     name: cargo fmt
@@ -71,4 +73,6 @@ jobs:
           components: clippy
           
       - name: Run clippy
-        run: cargo clippy -- -D warnings
+        run: |
+          cargo clippy -p fff-core -p fff-query-parser -p fff-nvim -p fff-c --features zlob -- -D warnings
+          cargo clippy -p grep-searcher -- -D warnings

Cargo.lock

@@ -482,6 +482,7 @@ dependencies = [
  "fff-query-parser",
  "git2",
  "glidesort",
+ "globset",
  "grep-matcher",
  "grep-searcher",
  "heed",
@@ -541,7 +542,6 @@ dependencies = [
  "tracing",
  "tracing-appender",
  "tracing-subscriber",
- "zlob",
 ]
 
 [[package]]

Cargo.toml

@@ -22,6 +22,7 @@ git2 = { version = "0.20.2", default-features = false, features = [
   "vendored-libgit2",
 ] }
 glidesort = "0.1"
+globset = "0.4"
 grep-matcher = "0.1.8"
 grep-searcher = { path = "crates/fff-searcher" }
 heed = "0.22.0"

Makefile

@@ -3,7 +3,7 @@ PLENARY_DIR ?= ../plenary.nvim
 .PHONY: build test test-rust test-lua test-bun test-setup prepare-bun
 
 build:
-	cargo build --release
+	cargo build --release --features zlob
 
 test-setup:
 	@if [ ! -d "$(PLENARY_DIR)" ]; then \
@@ -12,7 +12,7 @@ test-setup:
 	fi
 
 test-rust:
-	cargo test --workspace
+	cargo test --workspace --features zlob
 
 test-lua: test-setup build
 	nvim --headless -u tests/minimal_init.lua \

README.md

@@ -282,8 +282,7 @@ require('fff').setup({
 #### Available Methods
 
 ```lua
-require('fff').find_files()                         -- Find files in current directory
-require('fff').find_in_git_root()                   -- Find files in the current git repository
+require('fff').find_files()                         -- Find files in current repositro
 require('fff').scan_files()                         -- Trigger rescan of files in the current directory
 require('fff').refresh_git_status()                 -- Refresh git status for the active file lock
 require('fff').find_files_in_dir(path)              -- Find files in a specific directory

crates/fff-c/Cargo.toml

@@ -8,6 +8,10 @@ license = "MIT"
 [lib]
 crate-type = ["cdylib"]
 
+[features]
+default = []
+zlob = ["fff-core/zlob"]
+
 [dependencies]
 mimalloc.workspace = true
 tracing.workspace = true

crates/fff-core/Cargo.toml

@@ -13,6 +13,9 @@ crate-type = ["rlib", "staticlib", "cdylib"]
 default = []
 # Enable C FFI exports
 ffi = []
+# Use zlob (Zig-compiled C globbing library) for glob matching.
+# Requires Zig to be installed. When disabled, falls back to globset (pure Rust).
+zlob = ["dep:zlob", "fff-query-parser/zlob"]
 
 [dependencies]
 # Workspace dependencies
@@ -23,7 +26,7 @@ thiserror = { workspace = true }
 tracing = { workspace = true }
 
 # Local crates
-fff-query-parser = { path = "../fff-query-parser" }
+fff-query-parser = { path = "../fff-query-parser", default-features = false }
 
 # External dependencies
 bindet = { workspace = true }
@@ -32,6 +35,7 @@ chrono = { workspace = true }
 dirs = { workspace = true }
 git2 = { workspace = true }
 glidesort = { workspace = true }
+globset = { workspace = true }
 grep-matcher = { workspace = true }
 grep-searcher = { workspace = true }
 memchr = "2"
@@ -49,7 +53,7 @@ serde = { version = "1.0", features = ["derive"] }
 smartstring = { version = "1.0.1", features = ["serde"] }
 tracing-appender = "0.2"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
-zlob = { workspace = true }
+zlob = { workspace = true, optional = true }
 # Platform-specific: dunce for Windows to avoid \\?\ extended path prefix
 [target.'cfg(windows)'.dependencies]
 dunce = { workspace = true }

crates/fff-core/build.rs

@@ -1,16 +1,46 @@
 fn main() {
+    // When the `zlob` feature is enabled (Zig-compiled C library):
     // On Windows MSVC, explicitly link the C runtime libraries.
-    // This is needed because Zig-compiled static libraries (zlob) don't emit
-    // /DEFAULTLIB directives for the MSVC CRT. Without this, symbols like
-    // strcmp, memcpy, memchr etc. from vendored C libraries (libgit2, lmdb)
-    // are unresolved when linking the cdylib.
-    //
-    // We link both msvcrt (classic CRT) and ucrt (Universal CRT where memchr,
-    // strcmp etc. live on newer MSVC/ARM64 targets).
-    let target = std::env::var("TARGET").unwrap_or_default();
-    if target.contains("windows") && target.contains("msvc") {
-        println!("cargo:rustc-link-lib=msvcrt");
-        println!("cargo:rustc-link-lib=ucrt");
-        println!("cargo:rustc-link-lib=vcruntime");
+    // Zig-compiled static libraries don't emit /DEFAULTLIB directives for the
+    // MSVC CRT, so symbols like strcmp, memcpy etc. would be unresolved.
+    if std::env::var("CARGO_FEATURE_ZLOB").is_ok() {
+        let target = std::env::var("TARGET").unwrap_or_default();
+        if target.contains("windows") && target.contains("msvc") {
+            println!("cargo:rustc-link-lib=msvcrt");
+            println!("cargo:rustc-link-lib=ucrt");
+            println!("cargo:rustc-link-lib=vcruntime");
+        }
+    } else if std::env::var("CI").is_ok() {
+        // CI must always build with zlob for production-quality binaries.
+        if !zig_available() {
+            panic!(
+                "CI detected but Zig is not installed. \
+                 Please install Zig and build with `--features zlob`."
+            );
+        }
+        panic!(
+            "CI detected but `zlob` feature is not enabled. \
+             Build with `--features zlob`."
+        );
+    } else {
+        // Hint: if Zig is available but the zlob feature wasn't enabled,
+        // let the developer know they can get faster glob matching.
+        if zig_available() {
+            println!(
+                "cargo:warning=Zig detected but `zlob` feature is not enabled. \
+                 Build with `--features zlob` for faster glob matching."
+            );
+        }
     }
 }
+
+/// Probe the system for a working Zig installation.
+fn zig_available() -> bool {
+    std::process::Command::new("zig")
+        .arg("version")
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::null())
+        .status()
+        .map(|s| s.success())
+        .unwrap_or(false)
+}

crates/fff-core/src/constraints.rs

@@ -9,7 +9,6 @@
 use ahash::AHashSet;
 use fff_query_parser::{Constraint, GitStatusFilter};
 use smallvec::SmallVec;
-use zlob::{ZlobFlags, zlob_match_paths};
 
 use crate::git::is_modified_status;
 
@@ -235,32 +234,8 @@ fn collect_glob_indices<'a>(
 ) {
     match constraint {
         Constraint::Glob(pattern) => {
-            if let Ok(Some(matches)) = zlob_match_paths(pattern, paths, ZlobFlags::RECOMMENDED) {
-                let matched_set: AHashSet<usize> =
-                    matches.iter().map(|s| s.as_ptr() as usize).collect();
-
-                let indices: AHashSet<usize> = if paths.len() >= PAR_THRESHOLD {
-                    use rayon::prelude::*;
-                    paths
-                        .par_iter()
-                        .enumerate()
-                        .filter(|(_, p)| matched_set.contains(&(p.as_ptr() as usize)))
-                        .map(|(i, _)| i)
-                        .collect::<Vec<_>>()
-                        .into_iter()
-                        .collect()
-                } else {
-                    paths
-                        .iter()
-                        .enumerate()
-                        .filter(|(_, p)| matched_set.contains(&(p.as_ptr() as usize)))
-                        .map(|(i, _)| i)
-                        .collect()
-                };
-                results.push((is_negated, indices));
-            } else {
-                results.push((is_negated, AHashSet::new()));
-            }
+            let indices = match_glob_pattern(pattern, paths);
+            results.push((is_negated, indices));
         }
         Constraint::Not(inner) => {
             collect_glob_indices(inner, paths, results, !is_negated);
@@ -269,6 +244,66 @@ fn collect_glob_indices<'a>(
     }
 }
 
+/// Match a glob pattern against a list of paths, returning the set of matching indices.
+///
+/// When the `zlob` feature is enabled, delegates to `zlob::zlob_match_paths` (Zig-compiled
+/// C library, fastest). Otherwise falls back to `globset::Glob` (pure Rust).
+#[cfg(feature = "zlob")]
+fn match_glob_pattern(pattern: &str, paths: &[&str]) -> AHashSet<usize> {
+    let Ok(Some(matches)) = zlob::zlob_match_paths(pattern, paths, zlob::ZlobFlags::RECOMMENDED)
+    else {
+        return AHashSet::new();
+    };
+
+    let matched_set: AHashSet<usize> = matches.iter().map(|s| s.as_ptr() as usize).collect();
+
+    if paths.len() >= PAR_THRESHOLD {
+        use rayon::prelude::*;
+        paths
+            .par_iter()
+            .enumerate()
+            .filter(|(_, p)| matched_set.contains(&(p.as_ptr() as usize)))
+            .map(|(i, _)| i)
+            .collect::<Vec<_>>()
+            .into_iter()
+            .collect()
+    } else {
+        paths
+            .iter()
+            .enumerate()
+            .filter(|(_, p)| matched_set.contains(&(p.as_ptr() as usize)))
+            .map(|(i, _)| i)
+            .collect()
+    }
+}
+
+#[cfg(not(feature = "zlob"))]
+fn match_glob_pattern(pattern: &str, paths: &[&str]) -> AHashSet<usize> {
+    let Ok(glob) = globset::Glob::new(pattern) else {
+        return AHashSet::new();
+    };
+    let matcher = glob.compile_matcher();
+
+    if paths.len() >= PAR_THRESHOLD {
+        use rayon::prelude::*;
+        paths
+            .par_iter()
+            .enumerate()
+            .filter(|(_, p)| matcher.is_match(p))
+            .map(|(i, _)| i)
+            .collect::<Vec<_>>()
+            .into_iter()
+            .collect()
+    } else {
+        paths
+            .iter()
+            .enumerate()
+            .filter(|(_, p)| matcher.is_match(p))
+            .map(|(i, _)| i)
+            .collect()
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

crates/fff-core/src/file_picker.rs

@@ -186,6 +186,7 @@ pub struct FilePicker {
     scanned_files_count: Arc<AtomicUsize>,
     background_watcher: Option<BackgroundWatcher>,
     warmup_mmap_cache: bool,
+    cancelled: Arc<AtomicBool>,
 }
 
 impl std::fmt::Debug for FilePicker {
@@ -250,6 +251,7 @@ impl FilePicker {
         // rather than a stale `false` (the thread hasn't started yet).
         let scan_signal = Arc::new(AtomicBool::new(true));
         let synced_files_count = Arc::new(AtomicUsize::new(0));
+        let cancelled = Arc::new(AtomicBool::new(false));
 
         let picker = FilePicker {
             base_path: path.clone(),
@@ -258,6 +260,7 @@ impl FilePicker {
             scanned_files_count: Arc::clone(&synced_files_count),
             background_watcher: None,
             warmup_mmap_cache,
+            cancelled: Arc::clone(&cancelled),
         };
 
         // Place the picker into the shared handle before spawning the
@@ -274,6 +277,7 @@ impl FilePicker {
             warmup_mmap_cache,
             shared_picker,
             shared_frecency,
+            cancelled,
         );
 
         Ok(())
@@ -578,6 +582,11 @@ impl FilePicker {
             .retain_files(|file| !file.path.starts_with(dir_path))
     }
 
+    /// We use this to prevent any substantial background threads from acquiring the locks
+    pub fn cancel(&self) {
+        self.cancelled.store(true, Ordering::Release);
+    }
+
     pub fn stop_background_monitor(&mut self) {
         if let Some(watcher) = self.background_watcher.take() {
             watcher.stop();
@@ -644,6 +653,7 @@ fn spawn_scan_and_watcher(
     warmup_mmap_cache: bool,
     shared_picker: SharedPicker,
     shared_frecency: SharedFrecency,
+    cancelled: Arc<AtomicBool>,
 ) {
     std::thread::spawn(move || {
         // scan_signal is already `true` (set by the caller before spawning)
@@ -653,6 +663,12 @@ fn spawn_scan_and_watcher(
         let mut git_workdir = None;
         match scan_filesystem(&base_path, &synced_files_count, &shared_frecency) {
             Ok(sync) => {
+                if cancelled.load(Ordering::Acquire) {
+                    info!("Scan completed but picker was replaced, discarding results");
+                    scan_signal.store(false, Ordering::Relaxed);
+                    return;
+                }
+
                 info!(
                     "Initial filesystem scan completed: found {} files",
                     sync.files.len()
@@ -672,13 +688,8 @@ fn spawn_scan_and_watcher(
                 }
 
                 // OPTIMIZATION: Warmup mmap cache in background to avoid blocking first grep.
-                // The aggressive parallel warmup was causing cache thrashing and delaying
-                // initial searches. Now it runs async and doesn't block.
-                //
-                // We warmup under a read lock on the picker's actual files so that
-                // the OnceLock<Mmap> instances are populated in-place — no clone needed.
-                // Read locks allow concurrent readers so this doesn't block searches.
                 if warmup_mmap_cache
+                    && !cancelled.load(Ordering::Acquire)
                     && let Ok(guard) = shared_picker.read()
                     && let Some(ref picker) = *guard
                 {
@@ -691,6 +702,12 @@ fn spawn_scan_and_watcher(
         }
         scan_signal.store(false, Ordering::Relaxed);
 
+        // Don't create a watcher if this picker instance was already replaced
+        if cancelled.load(Ordering::Acquire) {
+            info!("Picker was replaced, skipping background watcher creation");
+            return;
+        }
+
         match BackgroundWatcher::new(
             base_path,
             git_workdir,
@@ -700,6 +717,15 @@ fn spawn_scan_and_watcher(
             Ok(watcher) => {
                 info!("Background file watcher initialized successfully");
 
+                // Final cancellation check: if the picker was replaced between
+                // watcher creation and this write, drop the watcher instead of
+                // storing it in the wrong picker.
+                if cancelled.load(Ordering::Acquire) {
+                    info!("Picker was replaced, dropping orphaned watcher");
+                    drop(watcher);
+                    return;
+                }
+
                 let write_result = shared_picker.write().ok().map(|mut guard| {
                     if let Some(ref mut picker) = *guard {
                         picker.background_watcher = Some(watcher);

crates/fff-core/src/grep.rs

@@ -707,24 +707,39 @@ fn fuzzy_grep_search<'a>(
     //   3-5 chars → 1 typo
     //   6+  chars → 2 typos
     let max_typos = (grep_text.len() / 3).min(2);
-    let frizbee_config = neo_frizbee::Config {
+    let scoring = neo_frizbee::Scoring {
+        // Use default gap penalties. Higher values (e.g. 20) cause
+        // smith-waterman to prefer *dropping needle chars* over paying
+        // gap costs, which inflates the typo count and breaks
+        // transposition matching ("shcema" → "schema" becomes 3 typos
+        // instead of 1). Scattered matches are filtered by max_typos
+        // and the match span check below instead.
+        exact_match_bonus: 100,
+        // gap_open_penalty: 4,
+        // gap_extend_penalty: 2,
+        prefix_bonus: 0,
+        capitalization_bonus: if case_insensitive { 0 } else { 4 },
+        ..neo_frizbee::Scoring::default()
+    };
+
+    // Two configs: match_list uses a lenient max_typos (needle_len) to keep
+    // the SIMD prefilter active (cheap char-presence check) while avoiding
+    // aggressive SIMD typo rejection that can disagree with the reference
+    // implementation on some architectures (e.g. aarch64 portable SIMD).
+    // match_indices uses the actual max_typos for correct typo filtering
+    // via the reference (scalar) Smith-Waterman traceback.
+    let match_list_config = neo_frizbee::Config {
         prefilter: true, // SIMD prefilter rejects obvious non-matches cheaply
-        max_typos: Some(max_typos as u16),
+        max_typos: Some(grep_text.len() as u16),
         sort: false, // We handle ordering ourselves
-        scoring: neo_frizbee::Scoring {
-            // Use default gap penalties. Higher values (e.g. 20) cause
-            // smith-waterman to prefer *dropping needle chars* over paying
-            // gap costs, which inflates the typo count and breaks
-            // transposition matching ("shcema" → "schema" becomes 3 typos
-            // instead of 1). Scattered matches are filtered by max_typos
-            // and the match span check below instead.
-            exact_match_bonus: 100,
-            // gap_open_penalty: 4,
-            // gap_extend_penalty: 2,
-            prefix_bonus: 0,
-            capitalization_bonus: if case_insensitive { 0 } else { 4 },
-            ..neo_frizbee::Scoring::default()
-        },
+        scoring,
+    };
+
+    let match_indices_config = neo_frizbee::Config {
+        prefilter: false,
+        max_typos: Some(max_typos as u16),
+        sort: false,
+        scoring,
     };
 
     // Minimum score threshold: 50% of a perfect contiguous match.
@@ -797,7 +812,7 @@ fn fuzzy_grep_search<'a>(
                 return Vec::new();
             }
 
-            let matches = neo_frizbee::match_list(grep_text, &file_lines, &frizbee_config);
+            let matches = neo_frizbee::match_list(grep_text, &file_lines, &match_list_config);
             let mut file_matches: Vec<GrepMatch> = Vec::new();
 
             for m in &matches {
@@ -822,7 +837,7 @@ fn fuzzy_grep_search<'a>(
                 };
 
                 let Some(match_indices) =
-                    neo_frizbee::match_indices(grep_text, display_line, &frizbee_config)
+                    neo_frizbee::match_indices(grep_text, display_line, &match_indices_config)
                 else {
                     continue; // something is off treat as nomatch
                 };

crates/fff-nvim/Cargo.toml

@@ -7,6 +7,10 @@ edition = "2024"
 path = "src/lib.rs"
 crate-type = ["cdylib", "rlib"]
 
+[features]
+default = []
+zlob = ["fff-core/zlob"]
+
 [[bin]]
 name = "test_watcher"
 path = "src/bin/test_watcher.rs"
@@ -63,7 +67,6 @@ serde = { version = "1.0", features = ["derive"] }
 smartstring = { version = "1.0.1", features = ["serde"] }
 tracing-appender = "0.2"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
-zlob = { workspace = true }
 
 [dev-dependencies]
 criterion = { version = "0.5", features = ["html_reports"] }

crates/fff-nvim/src/lib.rs

@@ -100,17 +100,24 @@ pub fn init_file_picker(_: &Lua, base_path: String) -> LuaResult<bool> {
 }
 
 fn reinit_file_picker_internal(path: &Path) -> Result<(), Error> {
-    // Stop existing picker
+    // Cancel and stop the old picker under a single write lock to avoid
+    // a window where FILE_PICKER is None (which causes FilePickerMissing
+    // errors if the UI is searching concurrently).
     {
         let mut guard = FILE_PICKER
             .write()
             .with_lock_error(Error::AcquireItemLock)?;
-        if let Some(mut picker) = guard.take() {
+        if let Some(ref mut picker) = *guard {
+            // Signal cancellation BEFORE stopping — this tells any orphaned
+            // scan threads from this picker to discard their results.
+            picker.cancel();
             picker.stop_background_monitor();
         }
+        // Don't take() here — leave the old picker in place so searches
+        // still work until new_with_shared_state replaces it atomically.
     }
 
-    // Create new picker backed by the same shared state
+    // Create new picker — this atomically replaces the old one via write lock
     FilePicker::new_with_shared_state(
         path.to_string_lossy().to_string(),
         false,
@@ -134,6 +141,12 @@ pub fn restart_index_in_path(_: &Lua, new_path: String) -> LuaResult<()> {
         LuaError::RuntimeError(format!("Failed to canonicalize path '{}': {}", new_path, e))
     })?;
 
+    if let Ok(Some(picker)) = FILE_PICKER.read().as_deref()
+        && picker.base_path() == canonical_path
+    {
+        return Ok(()); // same dir
+    }
+
     // Spawn a background thread to avoid blocking Lua/UI thread
     std::thread::spawn(move || {
         if let Err(e) = reinit_file_picker_internal(&canonical_path) {
@@ -564,21 +577,28 @@ pub fn get_historical_grep_query(_: &Lua, offset: usize) -> LuaResult<Option<Str
 }
 
 pub fn wait_for_initial_scan(_: &Lua, timeout_ms: Option<u64>) -> LuaResult<bool> {
-    let file_picker = FILE_PICKER
-        .read()
-        .with_lock_error(Error::AcquireItemLock)
-        .into_lua_result()?;
-    let picker = file_picker
-        .as_ref()
-        .ok_or(Error::FilePickerMissing)
-        .into_lua_result()?;
+    // Extract the scan signal Arc WITHOUT holding the read lock, so the
+    // scan thread can acquire the write lock to store its results.
+    // Holding a read lock while polling would deadlock: the scan thread
+    // needs a write lock to finish, but can't acquire it while we hold the read lock.
+    let scan_signal = {
+        let file_picker = FILE_PICKER
+            .read()
+            .with_lock_error(Error::AcquireItemLock)
+            .into_lua_result()?;
+        let picker = file_picker
+            .as_ref()
+            .ok_or(Error::FilePickerMissing)
+            .into_lua_result()?;
+        picker.scan_signal()
+    }; // read lock released here
 
     let timeout_ms = timeout_ms.unwrap_or(500);
     let timeout_duration = Duration::from_millis(timeout_ms);
     let start_time = std::time::Instant::now();
     let mut sleep_duration = Duration::from_millis(1);
 
-    while picker.is_scan_active() {
+    while scan_signal.load(std::sync::atomic::Ordering::Relaxed) {
         if start_time.elapsed() >= timeout_duration {
             ::tracing::warn!("wait_for_initial_scan timed out after {}ms", timeout_ms);
             return Ok(false);

crates/fff-query-parser/Cargo.toml

@@ -6,9 +6,13 @@ edition = "2024"
 [lib]
 path = "src/lib.rs"
 
+[features]
+default = []
+zlob = ["dep:zlob"]
+
 [dependencies]
 smallvec = { workspace = true }
-zlob = { version = "1.2.8" }
+zlob = { workspace = true, optional = true }
 
 [dev-dependencies]
 criterion = { version = "0.5", features = ["html_reports"] }

crates/fff-query-parser/src/config.rs

@@ -1,5 +1,5 @@
 use crate::constraints::Constraint;
-use zlob::{ZlobFlags, has_wildcards};
+use crate::glob_detect::has_wildcards;
 
 /// Parser configuration trait - allows different picker types to customize parsing
 pub trait ParserConfig {
@@ -40,7 +40,7 @@ pub trait ParserConfig {
     /// Override this in configs where some wildcard characters are common
     /// in search text (e.g. grep mode where `?` and `[` appear in code).
     fn is_glob_pattern(&self, token: &str) -> bool {
-        has_wildcards(token, ZlobFlags::RECOMMENDED)
+        has_wildcards(token)
     }
 
     /// Custom constraint parsers for picker-specific needs
@@ -87,7 +87,7 @@ impl ParserConfig for GrepConfig {
     /// - Contains `{…}` → brace expansion (e.g. `{src,lib}`)
     fn is_glob_pattern(&self, token: &str) -> bool {
         // Must contain at least one glob wildcard character
-        if !has_wildcards(token, ZlobFlags::RECOMMENDED) {
+        if !has_wildcards(token) {
             return false;
         }
 

crates/fff-query-parser/src/glob_detect.rs

@@ -0,0 +1,18 @@
+//! Glob wildcard detection — delegates to zlob when available, pure-Rust fallback otherwise.
+//!
+//! All call sites use a single function: `has_wildcards(text) -> bool`.
+//! When the `zlob` feature is enabled this calls `zlob::has_wildcards` with
+//! `ZlobFlags::RECOMMENDED`; without it we check for the same set of wildcard
+//! characters (`*`, `?`, `[`, `{`) in pure Rust.
+
+#[cfg(feature = "zlob")]
+#[inline]
+pub fn has_wildcards(s: &str) -> bool {
+    zlob::has_wildcards(s, zlob::ZlobFlags::RECOMMENDED)
+}
+
+#[cfg(not(feature = "zlob"))]
+#[inline]
+pub fn has_wildcards(s: &str) -> bool {
+    s.bytes().any(|b| matches!(b, b'*' | b'?' | b'[' | b'{'))
+}

crates/fff-query-parser/src/lib.rs

@@ -41,6 +41,7 @@
 
 mod config;
 mod constraints;
+pub mod glob_detect;
 pub mod location;
 mod parser;
 

crates/fff-query-parser/src/parser.rs

@@ -1,8 +1,8 @@
 use crate::ConstraintVec;
 use crate::config::ParserConfig;
 use crate::constraints::{Constraint, GitStatusFilter, TextPartsBuffer};
+use crate::glob_detect::has_wildcards;
 use crate::location::{Location, parse_location};
-use zlob::{ZlobFlags, has_wildcards};
 
 #[derive(Debug, Clone, PartialEq)]
 #[allow(clippy::large_enum_variant)]
@@ -184,7 +184,7 @@ fn parse_token<'a, C: ParserConfig>(token: &'a str, config: &C) -> Option<Constr
                 // Only return Extension if the rest doesn't have wildcards
                 // e.g., *.rs is Extension, but *.test.* should be Glob
                 let ext_part = &token[2..];
-                if !has_wildcards(ext_part, ZlobFlags::RECOMMENDED) {
+                if !has_wildcards(ext_part) {
                     return Some(constraint);
                 }
             }
@@ -283,7 +283,7 @@ fn parse_token_without_negation<'a, C: ParserConfig>(
             // Try extension first (*.rs) - simple patterns without additional wildcards
             if let Some(constraint) = parse_extension(token) {
                 let ext_part = &token[2..];
-                if !has_wildcards(ext_part, ZlobFlags::RECOMMENDED) {
+                if !has_wildcards(ext_part) {
                     return Some(constraint);
                 }
             }

doc/fff.nvim.txt

@@ -1,4 +1,4 @@
-*fff.nvim.txt*        For Neovim >= 0.10.0       Last change: 2026 February 28
+*fff.nvim.txt*         For Neovim >= 0.10.0         Last change: 2026 March 06
 
 ==============================================================================
 Table of Contents                                 *fff.nvim-table-of-contents*
@@ -149,7 +149,7 @@ all available options:
           prompt_position = 'bottom', -- or 'top'
           preview_position = 'right', -- or 'left', 'right', 'top', 'bottom'
           preview_size = 0.5,
-          flex = { -- set to nil to disable flex layout
+          flex = { -- set to false to disable flex layout
             size = 130, -- column threshold: if screen width >= size, use preview_position; otherwise use wrap
             wrap = 'top', -- position to use when screen is narrower than size
           },
@@ -168,6 +168,7 @@ all available options:
           binary_file_threshold = 1024, -- amount of bytes to scan for binary content (set 0 to disable)
           imagemagick_info_format_str = '%m: %wx%h, %[colorspace], %q-bit',
           line_numbers = false,
+          cursorlineopt = 'both', -- the cursorlineopt used for lines in grep file previews, see :h cursorlineopt
           wrap_lines = false,
           filetypes = {
             svg = { wrap_lines = true },
@@ -291,8 +292,7 @@ KEY FEATURES ~
 AVAILABLE METHODS
 
 >lua
-    require('fff').find_files()                         -- Find files in current directory
-    require('fff').find_in_git_root()                   -- Find files in the current git repository
+    require('fff').find_files()                         -- Find files in current repositro
     require('fff').scan_files()                         -- Trigger rescan of files in the current directory
     require('fff').refresh_git_status()                 -- Refresh git status for the active file lock
     require('fff').find_files_in_dir(path)              -- Find files in a specific directory

lua/fff/core.lua

@@ -65,12 +65,6 @@ local function setup_global_autocmds(config)
     end,
     desc = 'Automatically sync FFF directory changes',
   })
-
-  vim.api.nvim_create_autocmd('VimLeavePre', {
-    group = group,
-    callback = function() pcall(fuzzy.cleanup_file_picker) end,
-    desc = 'Cleanup FFF background threads on Neovim exit',
-  })
 end
 
 --- @return boolean

lua/fff/file_renderer.lua

@@ -180,7 +180,7 @@ function M.apply_highlights(item, ctx, item_idx, buf, ns_id, line_idx, line_cont
     local border_hl
 
     if is_cursor then
-      local base_hl = git_utils.get_border_highlight(item.git_status)
+      local base_hl = git_utils.get_border_highlight_selected(item.git_status)
       if base_hl and base_hl ~= '' then
         local border_fg = vim.fn.synIDattr(vim.fn.synIDtrans(vim.fn.hlID(base_hl)), 'fg')
         local cursor_bg = vim.fn.synIDattr(vim.fn.synIDtrans(vim.fn.hlID(ctx.config.hl.cursor)), 'bg')

lua/fff/list_renderer.lua

@@ -189,17 +189,17 @@ local function apply_all_highlights(lines, item_to_lines, ctx, list_buf, ns_id)
   for i = ctx.display_start, ctx.display_end do
     local item = ctx.items[i]
     local item_lines = item_to_lines[i]
-    if not item_lines then goto continue end
 
-    -- The content line is always the last line in the mapping
-    local line_idx = item_lines.last
-    local line_content = lines[line_idx]
+    if item_lines then
+      -- The content line is always the last line in the mapping
+      local line_idx = item_lines.last
+      local line_content = lines[line_idx]
 
-    if not line_content then goto continue end
-
-    ---@diagnostic disable-next-line: param-type-mismatch
-    renderer.apply_highlights(item, ctx, i, list_buf, ns_id, line_idx, line_content)
-    ::continue::
+      if line_content then
+        ---@diagnostic disable-next-line: param-type-mismatch
+        renderer.apply_highlights(item, ctx, i, list_buf, ns_id, line_idx, line_content)
+      end
+    end
   end
 end
 

lua/fff/main.lua

@@ -42,6 +42,8 @@ function M.live_grep(opts)
   picker_ui.open(picker_opts)
 end
 
+--- Changes the directory indexed by the file picker to the git root and opens the file picker
+--- @deprecated Use `find_files` instead
 function M.find_in_git_root()
   local fuzzy = require('fff.core').ensure_initialized()
   local ok, git_root = pcall(fuzzy.get_git_root)

lua/fff/picker_ui.lua

@@ -1346,7 +1346,10 @@ local function format_file_display(item, max_width)
   return filename, display_path
 end
 
---- Adjust scroll for bottom prompt to eliminate gaps
+--- Adjust scroll for bottom prompt to eliminate gaps.
+--- When the cursor has moved above the bottom viewport (e.g. user scrolled up
+--- through many results), follow the cursor instead of forcing the view to the
+--- bottom — otherwise the selected item disappears off the top of the window.
 local function scroll_to_bottom()
   if not M.state.list_win or not vim.api.nvim_win_is_valid(M.state.list_win) then return end
 
@@ -1355,8 +1358,21 @@ local function scroll_to_bottom()
 
   vim.api.nvim_win_call(M.state.list_win, function()
     local view = vim.fn.winsaveview()
-    -- Force topline to show content at bottom
-    view.topline = math.max(1, buf_lines - win_height + 1)
+    local bottom_topline = math.max(1, buf_lines - win_height + 1)
+    local cursor_line = vim.api.nvim_win_get_cursor(M.state.list_win)[1]
+
+    if cursor_line >= bottom_topline then
+      -- Cursor is visible when anchored to bottom — keep content near prompt
+      view.topline = bottom_topline
+    elseif cursor_line < view.topline then
+      -- Cursor scrolled above the current viewport — shift topline up just
+      -- enough to keep the cursor visible (1 line margin above)
+      view.topline = math.max(1, cursor_line - 1)
+    elseif cursor_line >= view.topline + win_height then
+      -- Cursor below viewport (shouldn't happen often) — snap to bottom
+      view.topline = bottom_topline
+    end
+    -- Otherwise cursor is already within the current viewport — don't move it
     vim.fn.winrestview(view)
   end)
 end