fix: Only use static linking libraries on windows (#232 )

closes https://github.com/dmtrKovalenko/fff.nvim/issues/228
feat: Live grep (#231 )
2026-02-16 12:12:51 -08:00 · 2026-02-15 21:42:42 -08:00 · 2026-02-12 00:39:07 -08:00 · 2026-02-11 23:58:11 -08:00
95 changed files with 14236 additions and 1233 deletions
@@ -1,10 +1,4 @@
-[target.x86_64-apple-darwin]
-rustflags = [
-  "-C", "link-arg=-undefined",
-  "-C", "link-arg=dynamic_lookup",
-]
-
-[target.aarch64-apple-darwin]
+[target.'cfg(target_os = "macos")']
 rustflags = [
  "-C", "link-arg=-undefined",
  "-C", "link-arg=dynamic_lookup",
@@ -0,0 +1,87 @@
+name: Lua E2E Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+  MACOSX_DEPLOYMENT_TARGET: "13"
+
+jobs:
+  lua-tests:
+    name: Lua E2E (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+          - os: macos-latest
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Zig
+        uses: mlugg/setup-zig@v2
+        with:
+          version: 0.15.2
+
+      - name: Install Rust
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          cache: true
+          cache-on-failure: true
+          cache-key: "v1-lua-e2e"
+          rustflags: ""
+          target: ${{ matrix.target || '' }}
+
+      - name: Build Rust binary (Windows)
+        if: matrix.target
+        run: cargo build --release --target ${{ matrix.target }} -p fff-nvim
+
+      - name: Copy binary to target/release (Windows)
+        if: matrix.target
+        shell: bash
+        run: |
+          cp target/${{ matrix.target }}/release/fff_nvim.dll target/release/fff_nvim.dll
+
+      - name: Verify Windows DLL has no unexpected dependencies
+        if: matrix.target
+        shell: pwsh
+        run: |
+          # Find dumpbin via vswhere (always available on GitHub Actions Windows runners)
+          $vsPath = & "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" -latest -property installationPath
+          $dumpbin = Get-ChildItem "$vsPath" -Recurse -Filter "dumpbin.exe" | Select-Object -First 1
+          if (-not $dumpbin) { Write-Error "dumpbin.exe not found"; exit 1 }
+
+          $deps = & $dumpbin.FullName /DEPENDENTS target\release\fff_nvim.dll | Out-String
+          Write-Host $deps
+          # zlob must be statically linked - fail if zlob.dll appears as a dependency
+          if ($deps -match 'zlob\.dll') {
+            Write-Error "fff_nvim.dll has unexpected dynamic dependency on zlob.dll - zlob should be statically linked"
+            exit 1
+          }
+
+      - name: Build Rust binary
+        if: ${{ !matrix.target }}
+        run: cargo build --release -p fff-nvim
+
+      - name: Install Neovim
+        uses: rhysd/action-setup-vim@v1
+        with:
+          neovim: true
+          version: v0.10.4
+
+      - name: Clone plenary.nvim
+        shell: bash
+        run: git clone --depth 1 https://github.com/nvim-lua/plenary.nvim ../plenary.nvim
+
+      - name: Run Lua tests
+        shell: bash
+        run: |
+          nvim --headless -u tests/minimal_init.lua \
+            -c "PlenaryBustedFile tests/fff_core_spec.lua" 2>&1
@@ -6,8 +6,99 @@ on:
  pull_request:

 jobs:
-  build:
-    name: Build ${{ matrix.target }}
+  build-nvim:
+    name: Build Neovim ${{ matrix.target }}
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+    strategy:
+      matrix:
+        include:
+          ## Linux builds (using cargo-zigbuild)
+          # Glibc 2.17 (RHEL 7, CentOS 7 compatible)
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+            zigbuild_target: x86_64-unknown-linux-gnu.2.17
+            artifact_name: target/x86_64-unknown-linux-gnu/release/libfff_nvim.so
+            ext: so
+          - os: ubuntu-latest
+            target: aarch64-unknown-linux-gnu
+            zigbuild_target: aarch64-unknown-linux-gnu.2.17
+            artifact_name: target/aarch64-unknown-linux-gnu/release/libfff_nvim.so
+            ext: so
+          # Musl (statically linked)
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-musl
+            artifact_name: target/x86_64-unknown-linux-musl/release/libfff_nvim.so
+            ext: so
+          - os: ubuntu-latest
+            target: aarch64-unknown-linux-musl
+            artifact_name: target/aarch64-unknown-linux-musl/release/libfff_nvim.so
+            ext: so
+
+          ## macOS builds
+          - os: macos-latest
+            target: x86_64-apple-darwin
+            artifact_name: target/x86_64-apple-darwin/release/libfff_nvim.dylib
+            ext: dylib
+          - os: macos-latest
+            target: aarch64-apple-darwin
+            artifact_name: target/aarch64-apple-darwin/release/libfff_nvim.dylib
+            ext: dylib
+
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+            artifact_name: target/x86_64-pc-windows-msvc/release/fff_nvim.dll
+            ext: dll
+          - os: windows-latest
+            target: aarch64-pc-windows-msvc
+            artifact_name: target/aarch64-pc-windows-msvc/release/fff_nvim.dll
+            ext: dll
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install Rust
+        run: rustup target add ${{ matrix.target }}
+
+      - name: Install Zig
+        uses: mlugg/setup-zig@v2
+        with:
+          version: 0.15.2
+
+      - name: Install cargo-zigbuild
+        if: contains(matrix.os, 'ubuntu')
+        run: cargo install cargo-zigbuild
+
+      - name: Build for Linux
+        if: contains(matrix.os, 'ubuntu')
+        run: |
+          cargo zigbuild --release --target ${{ matrix.zigbuild_target || matrix.target }} -p fff-nvim
+          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
+          mv "${{ matrix.artifact_name }}" "${{ matrix.target }}.${{ matrix.ext }}"
+
+      - name: Build for Windows
+        if: contains(matrix.os, 'windows')
+        shell: bash
+        run: |
+          cargo build --release --target ${{ matrix.target }} -p fff-nvim
+          mv "${{ matrix.artifact_name }}" "${{ matrix.target }}.${{ matrix.ext }}"
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: nvim-${{ matrix.target }}
+          path: ${{ matrix.target }}.*
+
+  build-c:
+    name: Build C FFI ${{ matrix.target }}
    runs-on: ${{ matrix.os }}
    permissions:
      contents: read
@@ -15,86 +106,91 @@ jobs:
      matrix:
        include:
          ## Linux builds
-          # Glibc 2.21
          - os: ubuntu-latest
            target: x86_64-unknown-linux-gnu
-            artifact_name: target/x86_64-unknown-linux-gnu/release/libfff_nvim.so
+            zigbuild_target: x86_64-unknown-linux-gnu.2.17
+            artifact_name: target/x86_64-unknown-linux-gnu/release/libfff_c.so
+            ext: so
          - os: ubuntu-latest
            target: aarch64-unknown-linux-gnu
-            artifact_name: target/aarch64-unknown-linux-gnu/release/libfff_nvim.so
-          # Musl 1.2.3
+            zigbuild_target: aarch64-unknown-linux-gnu.2.17
+            artifact_name: target/aarch64-unknown-linux-gnu/release/libfff_c.so
+            ext: so
          - os: ubuntu-latest
            target: x86_64-unknown-linux-musl
-            artifact_name: target/x86_64-unknown-linux-musl/release/libfff_nvim.so
+            artifact_name: target/x86_64-unknown-linux-musl/release/libfff_c.so
+            ext: so
          - os: ubuntu-latest
            target: aarch64-unknown-linux-musl
-            artifact_name: target/aarch64-unknown-linux-musl/release/libfff_nvim.so
-          # # Android (Termux)
-          # - os: ubuntu-latest
-          #   target: aarch64-linux-android
-          #   artifact_name: target/aarch64-linux-android/release/libfff_nvim.so
+            artifact_name: target/aarch64-unknown-linux-musl/release/libfff_c.so
+            ext: so

          ## macOS builds
          - os: macos-latest
            target: x86_64-apple-darwin
-            artifact_name: target/x86_64-apple-darwin/release/libfff_nvim.dylib
+            artifact_name: target/x86_64-apple-darwin/release/libfff_c.dylib
+            ext: dylib
          - os: macos-latest
            target: aarch64-apple-darwin
-            artifact_name: target/aarch64-apple-darwin/release/libfff_nvim.dylib
+            artifact_name: target/aarch64-apple-darwin/release/libfff_c.dylib
+            ext: dylib

          ## Windows builds
          - os: windows-latest
            target: x86_64-pc-windows-msvc
-            artifact_name: target/x86_64-pc-windows-msvc/release/fff_nvim.dll
+            artifact_name: target/x86_64-pc-windows-msvc/release/fff_c.dll
+            ext: dll
          - os: windows-latest
            target: aarch64-pc-windows-msvc
-            artifact_name: target/aarch64-pc-windows-msvc/release/fff_nvim.dll
+            artifact_name: target/aarch64-pc-windows-msvc/release/fff_c.dll
+            ext: dll

    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

-      # - name: Set Rust toolchain
-      #   if: contains(matrix.target, 'linux')
-      #   # https://github.com/rust-cross/cargo-zigbuild/issues/327
-      #   run: echo -e '[toolchain]\nchannel = "nightly-2025-02-19"' > rust-toolchain.toml
-
      - name: Install Rust
-        run: |
-          rustup target add ${{ matrix.target }}
+        run: rustup target add ${{ matrix.target }}
+
+      - name: Install Zig
+        uses: mlugg/setup-zig@v2
+        with:
+          version: 0.15.2
+
+      - name: Install cargo-zigbuild
+        if: contains(matrix.os, 'ubuntu')
+        run: cargo install cargo-zigbuild

      - name: Build for Linux
        if: contains(matrix.os, 'ubuntu')
        run: |
-          cargo install cross --git https://github.com/cross-rs/cross
-          cross build --release --target ${{ matrix.target }}
-          mv "${{ matrix.artifact_name }}" "${{ matrix.target }}.so"
+          cargo zigbuild --release --target ${{ matrix.zigbuild_target || matrix.target }} -p fff-c
+          mv "${{ matrix.artifact_name }}" "c-lib-${{ matrix.target }}.${{ matrix.ext }}"

      - name: Build for macOS
        if: contains(matrix.os, 'macos')
        run: |
-          # Ventura (https://en.wikipedia.org/wiki/MacOS_version_history#Releases)
-          MACOSX_DEPLOYMENT_TARGET="13" cargo build --release --target ${{ matrix.target }}
-          mv "${{ matrix.artifact_name }}" "${{ matrix.target }}.dylib"
+          MACOSX_DEPLOYMENT_TARGET="13" cargo build --release --target ${{ matrix.target }} -p fff-c
+          mv "${{ matrix.artifact_name }}" "c-lib-${{ matrix.target }}.${{ matrix.ext }}"

      - name: Build for Windows
        if: contains(matrix.os, 'windows')
+        shell: bash
        run: |
-          cargo build --release --target ${{ matrix.target }}
-          mv "${{ matrix.artifact_name }}" "${{ matrix.target }}.dll"
+          cargo build --release --target ${{ matrix.target }} -p fff-c
+          mv "${{ matrix.artifact_name }}" "c-lib-${{ matrix.target }}.${{ matrix.ext }}"

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
-          name: ${{ matrix.target }}
-          path: ${{ matrix.target }}*
+          name: c-lib-${{ matrix.target }}
+          path: c-lib-${{ matrix.target }}.*

  release:
    name: Release
-    needs: build
+    needs: [build-nvim, build-c]
    runs-on: ubuntu-latest
-    if: github.event_name == 'push'
    permissions:
      contents: write
    steps:
@@ -105,12 +201,44 @@ jobs:
        with:
          path: ./binaries

+      - name: Flatten and rename Neovim artifacts
+        working-directory: ./binaries
+        run: |
+          # Move nvim artifacts to root level with original naming
+          for dir in nvim-*/; do
+            target="${dir#nvim-}"
+            target="${target%/}"
+            for file in "$dir"*; do
+              if [ -f "$file" ]; then
+                filename=$(basename "$file")
+                mv "$file" "./$filename"
+              fi
+            done
+            rmdir "$dir" 2>/dev/null || true
+          done
+
+      - name: Flatten C library artifacts
+        working-directory: ./binaries
+        run: |
+          # Move c-lib artifacts to root level
+          for dir in c-lib-*/; do
+            for file in "$dir"*; do
+              if [ -f "$file" ]; then
+                filename=$(basename "$file")
+                mv "$file" "./$filename"
+              fi
+            done
+            rmdir "$dir" 2>/dev/null || true
+          done
+
      - name: Generate checksums
        working-directory: ./binaries
        run: |
-          ls -a 
-          for file in ./**/*; do
-            sha256sum "$file" > "${file}.sha256"
+          ls -la
+          for file in *; do
+            if [ -f "$file" ] && [[ ! "$file" == *.sha256 ]]; then
+              sha256sum "$file" > "${file}.sha256"
+            fi
          done

      - name: Prepare tag
@@ -126,16 +254,22 @@ jobs:
          name: "${{ steps.vars.outputs.tag }}"
          tag_name: "${{ steps.vars.outputs.tag }}"
          token: ${{ github.token }}
-          files: ./binaries/**/*
+          files: ./binaries/*
          draft: false
          prerelease: true
          generate_release_notes: false
          body: |
            Nightly release from commit: ${{ github.sha }}

+            ## Neovim Plugin
+            - `{target}.so` / `.dylib` / `.dll` - Lua module for Neovim
+
+            ## C FFI Library (for Bun/Node/Python)
+            - `c-lib-{target}.so` / `.dylib` / `.dll` - C FFI library
+
  comment-on-pr:
    name: Comment on PR
-    needs: build
+    needs: [build-nvim, build-c]
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    permissions:
@@ -161,15 +295,19 @@ jobs:
          edit-mode: replace
          body: |
            <!-- fff-nvim-build-comment -->
-            ## 🔨 Build Artifacts for your PR
-
-            You can test the prebuilt binaries if you use lazy.nvim right now.
+            ## Build Artifacts for your PR

+            ### Neovim Plugin
+            Test with lazy.nvim:
            ```lua
            {
              "dmtrKovalenko/fff.nvim",
              tag = "${{ steps.vars.outputs.short_sha }}",
            }
            ```
+
+            ### Bun/TypeScript Package
+            The `fff` npm package will download binaries from this release automatically.
+
            ---
            *Built from ${{ github.sha }}*
@@ -8,6 +8,9 @@ on:

 env:
  CARGO_TERM_COLOR: always
+  # Ensure consistent macOS deployment target across all compiled objects
+  # (Rust, cc-compiled C code, and Zig-compiled zlob) to avoid linker warnings
+  MACOSX_DEPLOYMENT_TARGET: "13"

 jobs:
  test:
@@ -15,22 +18,26 @@ jobs:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
-        os: [ubuntu-latest, windows-latest]
+        os: [ubuntu-latest, macos-latest]
    steps:
-      - name: Install Lua
-        if: matrix.os == 'macos-latest'
-        run: brew install lua
      - uses: actions/checkout@v4
-      - uses: actions-rust-lang/setup-rust-toolchain@v1
+      
+      # Zig is required to compile zlob
+      - name: Install Zig
+        uses: mlugg/setup-zig@v2
+        with:
+          version: 0.15.2
+
+      - name: Install Rust
+        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          cache: true
          cache-on-failure: true
          cache-key: "v1-rust"
          components: rustfmt, clippy
-          target: wasm32-unknown-unknown

      - name: Run tests
-        run: cargo test --verbose
+        run: cargo test --verbose --workspace --exclude fff-nvim

  fmt:
    name: cargo fmt
@@ -50,10 +57,18 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
+      
+      # Zig is required to compile zlob
+      - name: Install Zig
+        uses: mlugg/setup-zig@v2
+        with:
+          version: 0.15.2
+
      - name: Install Rust
        uses: dtolnay/rust-toolchain@master
        with:
          toolchain: stable
          components: clippy
+          
      - name: Run clippy
        run: cargo clippy -- -D warnings
@@ -78,6 +78,32 @@ dependencies = [
 "serde",
 ]

+[[package]]
+name = "bindet"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5afee99ef5f7527f3944f2bf4f5d443749fa47d43eb1d4f83a36e839be7900a3"
+
+[[package]]
+name = "bindgen"
+version = "0.70.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f49d8fed880d473ea71efb9bf597651e77201bdd4893efe54c9e5d65ae04ce6f"
+dependencies = [
+ "bitflags 2.9.1",
+ "cexpr",
+ "clang-sys",
+ "itertools",
+ "log",
+ "prettyplease",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "rustc-hash 1.1.0",
+ "shlex",
+ "syn",
+]
+
 [[package]]
 name = "bitflags"
 version = "1.3.2"
@@ -145,6 +171,15 @@ dependencies = [
 "shlex",
 ]

+[[package]]
+name = "cexpr"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
+dependencies = [
+ "nom",
+]
+
 [[package]]
 name = "cfg-if"
 version = "1.0.1"
@@ -169,7 +204,7 @@ dependencies = [
 "num-traits",
 "serde",
 "wasm-bindgen",
- "windows-link",
+ "windows-link 0.1.3",
 ]

 [[package]]
@@ -199,6 +234,17 @@ dependencies = [
 "half",
 ]

+[[package]]
+name = "clang-sys"
+version = "1.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b023947811758c97c59bf9d1c188fd619ad4718dcaa767947df1cadb14f39f4"
+dependencies = [
+ "glob",
+ "libc",
+ "libloading",
+]
+
 [[package]]
 name = "clap"
 version = "4.5.53"
@@ -381,6 +427,12 @@ dependencies = [
 "phf",
 ]

+[[package]]
+name = "dunce"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92773504d58c093f6de2459af4af33faa518c13451eb8f2b5698ed3d36e7c813"
+
 [[package]]
 name = "either"
 version = "1.15.0"
@@ -404,7 +456,62 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"

 [[package]]
-name = "fff_nvim"
+name = "fff-c"
+version = "0.1.0"
+dependencies = [
+ "fff-core",
+ "fff-query-parser",
+ "git2",
+ "mimalloc",
+ "once_cell",
+ "serde",
+ "serde_json",
+ "tracing",
+]
+
+[[package]]
+name = "fff-core"
+version = "0.1.0"
+dependencies = [
+ "ahash",
+ "bindet",
+ "blake3",
+ "chrono",
+ "criterion",
+ "dirs",
+ "dunce",
+ "fff-query-parser",
+ "git2",
+ "glidesort",
+ "grep-matcher",
+ "grep-searcher",
+ "heed",
+ "ignore",
+ "memchr",
+ "memmap2",
+ "neo_frizbee",
+ "notify",
+ "notify-debouncer-full 0.7.0",
+ "once_cell",
+ "openssl",
+ "parking_lot",
+ "pathdiff",
+ "rand",
+ "rayon",
+ "regex",
+ "serde",
+ "smallvec",
+ "smartstring",
+ "tempfile",
+ "thiserror 2.0.12",
+ "tracing",
+ "tracing-appender",
+ "tracing-subscriber",
+ "zlob",
+]
+
+[[package]]
+name = "fff-nvim"
 version = "0.1.0"
 dependencies = [
 "ahash",
@@ -413,6 +520,8 @@ dependencies = [
 "criterion",
 "ctrlc",
 "dirs",
+ "fff-core",
+ "fff-query-parser",
 "git2",
 "glidesort",
 "heed",
@@ -421,18 +530,30 @@ dependencies = [
 "mlua",
 "neo_frizbee",
 "notify",
- "notify-debouncer-full",
+ "notify-debouncer-full 0.6.0",
 "once_cell",
+ "openssl",
 "pathdiff",
 "rand",
 "rayon",
 "serde",
+ "smallvec",
 "smartstring",
 "tempfile",
 "thiserror 2.0.12",
 "tracing",
 "tracing-appender",
 "tracing-subscriber",
+ "zlob",
+]
+
+[[package]]
+name = "fff-query-parser"
+version = "0.1.0"
+dependencies = [
+ "criterion",
+ "smallvec",
+ "zlob",
 ]

 [[package]]
@@ -444,6 +565,21 @@ dependencies = [
 "windows-sys 0.60.2",
 ]

+[[package]]
+name = "foreign-types"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f6f339eb8adc052cd2ca78910fda869aefa38d22d5cb648e6485e4d3fc06f3b1"
+dependencies = [
+ "foreign-types-shared",
+]
+
+[[package]]
+name = "foreign-types-shared"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "00b0228411908ca8685dba7fc2cdd70ec9990a6e753e89b6ac91a84c40fbaf4b"
+
 [[package]]
 name = "form_urlencoded"
 version = "1.2.1"
@@ -495,8 +631,6 @@ dependencies = [
 "libc",
 "libgit2-sys",
 "log",
- "openssl-probe",
- "openssl-sys",
 "url",
 ]

@@ -506,6 +640,12 @@ version = "0.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f2e102e6eb644d3e0b186fc161e4460417880a0a0b87d235f2e5b8fb30f2e9e0"

+[[package]]
+name = "glob"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
+
 [[package]]
 name = "globset"
 version = "0.4.16"
@@ -519,6 +659,24 @@ dependencies = [
 "regex-syntax 0.8.5",
 ]

+[[package]]
+name = "grep-matcher"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36d7b71093325ab22d780b40d7df3066ae4aebb518ba719d38c697a8228a8023"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "grep-searcher"
+version = "0.1.16"
+dependencies = [
+ "bstr",
+ "grep-matcher",
+ "memchr",
+]
+
 [[package]]
 name = "half"
 version = "2.7.1"
@@ -827,12 +985,20 @@ checksum = "1c42fe03df2bd3c53a3a9c7317ad91d80c81cd1fb0caec8d7cc4cd2bfa10c222"
 dependencies = [
 "cc",
 "libc",
- "libssh2-sys",
 "libz-sys",
- "openssl-sys",
 "pkg-config",
 ]

+[[package]]
+name = "libloading"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
+dependencies = [
+ "cfg-if",
+ "windows-link 0.2.1",
+]
+
 [[package]]
 name = "libmimalloc-sys"
 version = "0.1.43"
@@ -853,20 +1019,6 @@ dependencies = [
 "libc",
 ]

-[[package]]
-name = "libssh2-sys"
-version = "0.3.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "220e4f05ad4a218192533b300327f5150e809b54c4ec83b5a1d91833601811b9"
-dependencies = [
- "cc",
- "libc",
- "libz-sys",
- "openssl-sys",
- "pkg-config",
- "vcpkg",
-]
-
 [[package]]
 name = "libz-sys"
 version = "1.1.22"
@@ -933,6 +1085,15 @@ version = "2.7.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32a282da65faaf38286cf3be983213fcf1d2e2a58700e808f83f4ea9a4804bc0"

+[[package]]
+name = "memmap2"
+version = "0.9.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "744133e4a0e0a658e1374cf3bf8e415c4052a15a111acd372764c55b4177d490"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "mimalloc"
 version = "0.1.47"
@@ -942,6 +1103,12 @@ dependencies = [
 "libmimalloc-sys",
 ]

+[[package]]
+name = "minimal-lexical"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
+
 [[package]]
 name = "mio"
 version = "1.0.4"
@@ -966,7 +1133,7 @@ dependencies = [
 "mlua_derive",
 "num-traits",
 "parking_lot",
- "rustc-hash",
+ "rustc-hash 2.1.1",
 "rustversion",
 ]

@@ -1016,9 +1183,9 @@ dependencies = [

 [[package]]
 name = "neo_frizbee"
-version = "0.7.1"
+version = "0.8.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2b4421f748f561dd0bb677e46f2e6c1ed2c52ba7130349229a73445af5010d17"
+checksum = "7e3f70b45907246d13fbe88cee200ebba81c9b77476028133a527c88bd875bc7"
 dependencies = [
 "multiversion",
 "rayon",
@@ -1036,6 +1203,16 @@ dependencies = [
 "libc",
 ]

+[[package]]
+name = "nom"
+version = "7.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
+dependencies = [
+ "memchr",
+ "minimal-lexical",
+]
+
 [[package]]
 name = "notify"
 version = "8.2.0"
@@ -1067,6 +1244,19 @@ dependencies = [
 "walkdir",
 ]

+[[package]]
+name = "notify-debouncer-full"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c02b49179cfebc9932238d04d6079912d26de0379328872846118a0fa0dbb302"
+dependencies = [
+ "file-id",
+ "log",
+ "notify",
+ "notify-types",
+ "walkdir",
+]
+
 [[package]]
 name = "notify-types"
 version = "2.0.0"
@@ -1111,10 +1301,30 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e"

 [[package]]
-name = "openssl-probe"
-version = "0.1.6"
+name = "openssl"
+version = "0.10.73"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d05e27ee213611ffe7d6348b942e8f942b37114c00cc03cec254295a4a17852e"
+checksum = "8505734d46c8ab1e19a1dce3aef597ad87dcb4c37e7188231769bd6bd51cebf8"
+dependencies = [
+ "bitflags 2.9.1",
+ "cfg-if",
+ "foreign-types",
+ "libc",
+ "once_cell",
+ "openssl-macros",
+ "openssl-sys",
+]
+
+[[package]]
+name = "openssl-macros"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a948666b637a0f465e8564c73e89d4dde00d72d4d473cc972f390fc3dcee7d9c"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]

 [[package]]
 name = "openssl-src"
@@ -1301,6 +1511,16 @@ dependencies = [
 "zerocopy",
 ]

+[[package]]
+name = "prettyplease"
+version = "0.2.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff24dfcda44452b9816fff4cd4227e1bb73ff5a2f1bc1105aa92fb8565ce44d2"
+dependencies = [
+ "proc-macro2",
+ "syn",
+]
+
 [[package]]
 name = "proc-macro2"
 version = "1.0.95"
@@ -1439,6 +1659,12 @@ version = "0.8.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2b15c43186be67a4fd63bee50d0303afffcef381492ebe2c5d87f324e1b8815c"

+[[package]]
+name = "rustc-hash"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08d43f7aa6b08d49f382cde6a7982047c3426db949b1424bc4b7ec9ae12c6ce2"
+
 [[package]]
 name = "rustc-hash"
 version = "2.1.1"
@@ -1964,7 +2190,7 @@ checksum = "c0fdd3ddb90610c7638aa2b3a3ab2904fb9e5cdbecc643ddb3647212781c4ae3"
 dependencies = [
 "windows-implement",
 "windows-interface",
- "windows-link",
+ "windows-link 0.1.3",
 "windows-result",
 "windows-strings",
 ]
@@ -1997,13 +2223,19 @@ version = "0.1.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e6ad25900d524eaabdbbb96d20b4311e1e7ae1699af4fb28c17ae66c80d798a"

+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
 [[package]]
 name = "windows-result"
 version = "0.3.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "56f42bd332cc6c8eac5af113fc0c1fd6a8fd2aa08a0119358686e5160d0586c6"
 dependencies = [
- "windows-link",
+ "windows-link 0.1.3",
 ]

 [[package]]
@@ -2012,7 +2244,7 @@ version = "0.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "56e6c93f3a0c3b36176cb1327a4958a0353d5d166c2a35cb268ace15e91d3b57"
 dependencies = [
- "windows-link",
+ "windows-link 0.1.3",
 ]

 [[package]]
@@ -2079,7 +2311,7 @@ version = "0.53.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d5fe6031c4041849d7c496a8ded650796e7b6ecc19df1a431c1a363342e5dc91"
 dependencies = [
- "windows-link",
+ "windows-link 0.1.3",
 "windows_aarch64_gnullvm 0.53.0",
 "windows_aarch64_msvc 0.53.0",
 "windows_i686_gnu 0.53.0",
@@ -2340,3 +2572,13 @@ dependencies = [
 "quote",
 "syn",
 ]
+
+[[package]]
+name = "zlob"
+version = "1.2.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "674f4e74544c0a00887c0dff7862fe13742de8c5dbcf6db9eac0643362554d44"
+dependencies = [
+ "bindgen",
+ "bitflags 2.9.1",
+]
@@ -1,65 +1,53 @@
-[package]
-name = "fff_nvim"
-version = "0.1.0"
-edition = "2024"
+[workspace]
+members = [
+  "crates/fff-c",
+  "crates/fff-core",
+  "crates/fff-nvim",
+  "crates/fff-query-parser",
+  "crates/fff-searcher",
+]
+resolver = "2"

-[lib]
-path = "lua/fff/rust/lib.rs"
-crate-type = ["cdylib", "rlib"]
-
-[[bin]]
-name = "test_watcher"
-path = "src/bin/test_watcher.rs"
-
-[[bin]]
-name = "jemalloc_profile"
-path = "src/bin/jemalloc_profile.rs"
-[[bin]]
-name = "search_profiler"
-path = "src/bin/search_profiler.rs"
-
-[[bin]]
-name = "bench_search_only"
-path = "src/bin/bench_search_only.rs"
-
-[[bench]]
-name = "query_tracker_bench"
-harness = false
-
-[dependencies]
+[workspace.dependencies]
+# Shared dependencies
 ahash = "0.8"
+bindet = "0.3"
 blake3 = "1.8.2"
 chrono = { version = "0.4", features = ["serde"] }
 ctrlc = "3.4.2"
 dirs = "5.0"
-git2 = { version = "0.20.2", features = [
-  "vendored-openssl",
+dunce = "1.0"
+# git2 - base config without TLS (each crate adds platform-specific TLS)
+git2 = { version = "0.20.2", default-features = false, features = [
  "vendored-libgit2",
 ] }
 glidesort = "0.1"
+grep-matcher = "0.1.8"
+grep-searcher = { path = "crates/fff-searcher" }
 heed = "0.22.0"
 ignore = "0.4.22"
+memmap2 = "0.9"
 mimalloc = "0.1.47"
+zlob = "1.2.9"

 mlua = { version = "0.11.1", features = ["module", "luajit"] }
-neo_frizbee = { version = "0.7.1" }
+neo_frizbee = "0.8.1"
 notify = "8.1.0"
-notify-debouncer-full = "0.6"
+notify-debouncer-full = "0.7"
 once_cell = "1.20.2"
+parking_lot = "0.12"
 pathdiff = "0.2.1"
 rayon = "1.8.0"
-serde = { version = "1.0", features = ["derive"] }
-smartstring = { version = "1.0.1", features = ["serde"] }
+regex = "1.11"
+smallvec = { version = "1.13", features = ["const_generics", "union"] }
 thiserror = "2.0.10"
 tracing = "0.1"
-tracing-appender = "0.2"
-tracing-subscriber = { version = "0.3", features = ["env-filter"] }

-[dev-dependencies]
-criterion = { version = "0.5", features = ["html_reports"] }
-rand = { version = "0.8", features = ["small_rng"] }
-tempfile = "3.8"
+[profile.release]
+opt-level = 3
+lto = "fat"
+codegen-units = 1
+strip = true

-[[bench]]
-name = "indexing_and_search"
-harness = false
+[profile.bench]
+inherits = "release"
@@ -1,7 +0,0 @@
-# Picked glibc 2.21 to support Ubuntu 14.04+
-
-[target.x86_64-unknown-linux-gnu]
-zig = "2.17"
-
-[target.aarch64-unknown-linux-gnu]
-zig = "2.17"
@@ -0,0 +1,28 @@
+PLENARY_DIR ?= ../plenary.nvim
+
+.PHONY: build test test-rust test-lua test-setup
+
+build:
+	cargo build --release
+
+test-setup:
+	@if [ ! -d "$(PLENARY_DIR)" ]; then \
+		echo "Cloning plenary.nvim..."; \
+		git clone --depth 1 https://github.com/nvim-lua/plenary.nvim $(PLENARY_DIR); \
+	fi
+
+test-rust:
+	cargo test --verbose --workspace --exclude fff-nvim
+
+test-lua: test-setup build
+	nvim --headless -u tests/minimal_init.lua \
+		-c "PlenaryBustedFile tests/fff_core_spec.lua" 2>&1
+
+test: test-rust test-lua
+
+format-rust:
+	cargo fmt --all
+format-lua:
+	stylua .
+
+format: format-rust format-lua
@@ -69,6 +69,20 @@ FFF.nvim requires:
      "ff", -- try it if you didn't it is a banger keybinding for a picker
      function() require('fff').find_files() end,
      desc = 'FFFind files',
+    },
+    {
+      "fg",
+      function() require('fff').live_grep() end,
+      desc = 'LiFFFe grep',
+    },
+    {
+      "fz",
+      function() require('fff').live_grep({
+	grep = {
+	  modes = { 'fuzzy', 'plain' }
+	}
+      }) end,
+      desc = 'Live fffuzy grep',
    }
  }
 }
@@ -161,6 +175,8 @@ require('fff').setup({
      -- multi-select keymaps for quickfix
      toggle_select = '<Tab>',
      send_to_quickfix = '<C-q>',
+      -- grep mode: cycle between plain text, regex, and fuzzy search
+      toggle_grep_regex = '<S-Tab>',
    },
    hl = {
      border = 'FloatBorder',
@@ -199,6 +215,13 @@ require('fff').setup({
      git_sign_renamed_selected = 'FFFGitSignRenamedSelected',
      git_sign_untracked_selected = 'FFFGitSignUntrackedSelected',
      git_sign_ignored_selected = 'FFFGitSignIgnoredSelected',
+      -- Grep highlights
+      grep_match = 'IncSearch',               -- Highlight for matched text in grep results
+      grep_line_number = 'LineNr',            -- Highlight for :line:col location
+      grep_regex_active = 'DiagnosticInfo',   -- Highlight for keybind + label when regex is on
+      grep_regex_inactive = 'Comment',        -- Highlight for keybind + label when regex is off
+      -- Cross-mode suggestion highlights
+      suggestion_header = 'WarningMsg',       -- Highlight for the "No results found. Suggested..." banner
    },
    -- Store file open frecency
    frecency = {
@@ -225,6 +248,14 @@ require('fff').setup({
      enabled = true,
      log_file = vim.fn.stdpath('log') .. '/fff.log',
      log_level = 'info',
+    },
+    -- Live grep search configuration
+    grep = {
+      max_file_size = 10 * 1024 * 1024, -- Skip files larger than 10MB
+      max_matches_per_file = 200, -- Maximum matches per file
+      smart_case = true, -- Case-insensitive unless query has uppercase
+      time_budget_ms = 150, -- Max search time in ms per call (prevents UI freeze, 0 = no limit)
+      modes = { 'plain', 'regex', 'fuzzy' }, -- Available grep modes and their cycling order
    }
 })
 ```
@@ -273,11 +304,63 @@ Select multiple files and send them to Neovim's quickfix list (keymaps are confi
 - `<Tab>` - Toggle selection for the current file (shows thick border `▊` in signcolumn)
 - `<C-q>` - Send selected files to quickfix list and close picker

+#### Live Grep Search Modes
+
+Live grep supports three search modes, cycled with `<S-Tab>`:
+
+- **Plain text** (default) - The query is matched literally. Special regex characters like `.`, `*`, `(`, `)`, `$` have no special meaning. This is the safest mode for searching code containing regex metacharacters.
+- **Regex** - The query is interpreted as a regular expression. Supports character classes (`[a-z]`), quantifiers (`+`, `*`, `{n}`), alternation (`foo|bar`), anchors (`^`, `$`), word boundaries (`\b`), and more.
+- **Fuzzy** - The query is fuzzy matched using Smith-Waterman scoring. Accommodates typos and scattered characters (e.g., "mtxlk" matches "mutex_lock"). Results are filtered by a quality threshold to avoid overly fuzzy matches.
+
+The current mode is shown on the right side of the input field (e.g., `plain`, `regex`, `fuzzy`) with color-coded highlighting.
+
+You can customize which modes are available and their cycling order globally in your configuration, or per-call when invoking `live_grep()`.
+
+**Global configuration:**
+
+```lua
+require('fff').setup({
+  grep = {
+    modes = { 'plain', 'regex' }, -- Only plain and regex, no fuzzy
+  }
+})
+```
+
+**Per-call configuration:**
+
+```lua
+-- Only fuzzy and plain modes for this specific grep
+require('fff').live_grep({
+  grep = {
+    modes = { 'fuzzy', 'plain' },
+  }
+})
+
+-- Single mode (hides mode indicator completely)
+require('fff').live_grep({
+  grep = {
+    modes = { 'fuzzy' },
+  }
+})
+```
+
+When only one mode is configured, the mode indicator is hidden completely and the cycle keybind does nothing.
+
+#### Cross-Mode Suggestions
+
+When a search returns no results, FFF automatically queries the opposite search mode and displays the results as suggestions:
+
+- **File search with no matches** → shows suggested **content matches** (grep results) for the same query
+- **Grep search with no matches** → shows suggested **file name matches** for the same query
+
+Suggestions are clearly labeled with a "No results found. Suggested ..." banner (highlighted with `hl.suggestion_header`). You can navigate and select suggestion items just like normal results — selecting a grep suggestion will open the file at the matching line.
+
 #### Git Status Highlighting

 FFF integrates with git to show file status through sign column indicators (enabled by default) and optional filename text coloring.

 **Sign Column Indicators** (enabled by default) - Border characters shown in the sign column:
+
 ```lua
 hl = {
  git_sign_staged = 'FFFGitSignStaged',
@@ -292,6 +375,7 @@ hl = {
 **Text Highlights** (opt-in) - Apply colors to filenames based on git status:

 To enable git status text coloring, set `git.status_text_color = true`:
+
 ```lua
 require('fff').setup({
  git = {
@@ -311,6 +395,7 @@ require('fff').setup({
 The plugin provides sensible default highlight groups that link to common git highlight groups (e.g., GitSignsAdd, GitSignsChange). You can override these with your own custom highlight groups to match your colorscheme.

 **Example - Custom Bright Colors for Text:**
+
 ```lua
 vim.api.nvim_set_hl(0, 'CustomGitModified', { fg = '#FFA500' })
 vim.api.nvim_set_hl(0, 'CustomGitUntracked', { fg = '#00FF00' })
@@ -0,0 +1,20 @@
+[package]
+name = "fff-c"
+version = "0.1.0"
+edition = "2024"
+description = "C FFI bindings for fff-core - use from any language with C FFI support"
+license = "MIT"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+mimalloc.workspace = true
+once_cell.workspace = true
+tracing.workspace = true
+git2.workspace = true
+
+fff-core = { path = "../fff-core" }
+fff-query-parser = { path = "../fff-query-parser" }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
@@ -0,0 +1,223 @@
+//! FFI-compatible type definitions
+//!
+//! These types use #[repr(C)] for C ABI compatibility and implement
+//! serde traits for JSON serialization.
+
+use std::ffi::{CString, c_char};
+use std::ptr;
+
+use fff_core::git::format_git_status;
+use fff_core::{FileItem, Location, Score, SearchResult};
+use serde::{Deserialize, Serialize};
+
+/// Result type returned by all FFI functions
+/// Returned as a heap-allocated pointer that must be freed with fff_free_result
+#[repr(C)]
+pub struct FffResult {
+    /// Whether the operation succeeded
+    pub success: bool,
+    /// JSON data on success (null-terminated string, caller must free)
+    pub data: *mut c_char,
+    /// Error message on failure (null-terminated string, caller must free)
+    pub error: *mut c_char,
+}
+
+impl FffResult {
+    /// Create a successful result with no data, returned as heap pointer
+    pub fn ok_empty() -> *mut Self {
+        Box::into_raw(Box::new(FffResult {
+            success: true,
+            data: ptr::null_mut(),
+            error: ptr::null_mut(),
+        }))
+    }
+
+    /// Create a successful result with data, returned as heap pointer
+    pub fn ok_data(data: &str) -> *mut Self {
+        Box::into_raw(Box::new(FffResult {
+            success: true,
+            data: CString::new(data).unwrap_or_default().into_raw(),
+            error: ptr::null_mut(),
+        }))
+    }
+
+    /// Create an error result, returned as heap pointer
+    pub fn err(error: &str) -> *mut Self {
+        Box::into_raw(Box::new(FffResult {
+            success: false,
+            data: ptr::null_mut(),
+            error: CString::new(error).unwrap_or_default().into_raw(),
+        }))
+    }
+}
+
+/// Initialization options (JSON-deserializable)
+#[derive(Debug, Deserialize)]
+pub struct InitOptions {
+    /// Base directory to index (required)
+    pub base_path: String,
+    /// Path to frecency database (optional, omit to skip frecency initialization)
+    pub frecency_db_path: Option<String>,
+    /// Path to query history database (optional, omit to skip query tracker initialization)
+    pub history_db_path: Option<String>,
+    /// Use unsafe no-lock mode for databases (optional, defaults to false)
+    #[serde(default)]
+    pub use_unsafe_no_lock: bool,
+}
+
+/// Search options (JSON-deserializable)
+#[derive(Debug, Default, Deserialize)]
+pub struct SearchOptions {
+    /// Maximum threads for parallel search (0 = auto)
+    pub max_threads: Option<usize>,
+    /// Current file path (for deprioritization)
+    pub current_file: Option<String>,
+    /// Combo boost score multiplier
+    pub combo_boost_multiplier: Option<i32>,
+    /// Minimum combo count for boost
+    pub min_combo_count: Option<u32>,
+    /// Page index for pagination
+    pub page_index: Option<usize>,
+    /// Page size for pagination
+    pub page_size: Option<usize>,
+}
+
+/// Scan progress (JSON-serializable)
+#[derive(Debug, Serialize)]
+pub struct ScanProgress {
+    pub scanned_files_count: usize,
+    pub is_scanning: bool,
+}
+
+/// File item for JSON serialization
+#[derive(Debug, Serialize)]
+pub struct FileItemJson {
+    pub path: String,
+    pub relative_path: String,
+    pub file_name: String,
+    pub size: u64,
+    pub modified: u64,
+    pub access_frecency_score: i64,
+    pub modification_frecency_score: i64,
+    pub total_frecency_score: i64,
+    pub git_status: String,
+    pub is_binary: bool,
+}
+
+impl FileItemJson {
+    pub fn from_file_item(item: &FileItem) -> Self {
+        FileItemJson {
+            path: item.path.to_string_lossy().to_string(),
+            relative_path: item.relative_path.clone(),
+            file_name: item.file_name.clone(),
+            size: item.size,
+            modified: item.modified,
+            access_frecency_score: item.access_frecency_score,
+            modification_frecency_score: item.modification_frecency_score,
+            total_frecency_score: item.total_frecency_score,
+            git_status: format_git_status(item.git_status).to_string(),
+            is_binary: item.is_binary,
+        }
+    }
+}
+
+/// Score for JSON serialization
+#[derive(Debug, Serialize)]
+pub struct ScoreJson {
+    pub total: i32,
+    pub base_score: i32,
+    pub filename_bonus: i32,
+    pub special_filename_bonus: i32,
+    pub frecency_boost: i32,
+    pub distance_penalty: i32,
+    pub current_file_penalty: i32,
+    pub combo_match_boost: i32,
+    pub exact_match: bool,
+    pub match_type: String,
+}
+
+impl ScoreJson {
+    pub fn from_score(score: &Score) -> Self {
+        ScoreJson {
+            total: score.total,
+            base_score: score.base_score,
+            filename_bonus: score.filename_bonus,
+            special_filename_bonus: score.special_filename_bonus,
+            frecency_boost: score.frecency_boost,
+            distance_penalty: score.distance_penalty,
+            current_file_penalty: score.current_file_penalty,
+            combo_match_boost: score.combo_match_boost,
+            exact_match: score.exact_match,
+            match_type: score.match_type.to_string(),
+        }
+    }
+}
+
+/// Location for JSON serialization
+#[derive(Debug, Serialize)]
+#[serde(tag = "type")]
+pub enum LocationJson {
+    #[serde(rename = "line")]
+    Line { line: i32 },
+    #[serde(rename = "position")]
+    Position { line: i32, col: i32 },
+    #[serde(rename = "range")]
+    Range {
+        start: PositionJson,
+        end: PositionJson,
+    },
+}
+
+#[derive(Debug, Serialize)]
+pub struct PositionJson {
+    pub line: i32,
+    pub col: i32,
+}
+
+impl LocationJson {
+    pub fn from_location(loc: &Location) -> Self {
+        match loc {
+            Location::Line(line) => LocationJson::Line { line: *line },
+            Location::Position { line, col } => LocationJson::Position {
+                line: *line,
+                col: *col,
+            },
+            Location::Range { start, end } => LocationJson::Range {
+                start: PositionJson {
+                    line: start.0,
+                    col: start.1,
+                },
+                end: PositionJson {
+                    line: end.0,
+                    col: end.1,
+                },
+            },
+        }
+    }
+}
+
+/// Search result for JSON serialization
+#[derive(Debug, Serialize)]
+pub struct SearchResultJson {
+    pub items: Vec<FileItemJson>,
+    pub scores: Vec<ScoreJson>,
+    pub total_matched: usize,
+    pub total_files: usize,
+    pub location: Option<LocationJson>,
+}
+
+impl SearchResultJson {
+    pub fn from_search_result(result: &SearchResult) -> Self {
+        SearchResultJson {
+            items: result
+                .items
+                .iter()
+                .map(|item| FileItemJson::from_file_item(item))
+                .collect(),
+            scores: result.scores.iter().map(ScoreJson::from_score).collect(),
+            total_matched: result.total_matched,
+            total_files: result.total_files,
+            location: result.location.as_ref().map(LocationJson::from_location),
+        }
+    }
+}
@@ -0,0 +1,708 @@
+//! C FFI bindings for fff-core
+//!
+//! This crate provides C-compatible FFI exports that can be used from any language
+//! with C FFI support (Bun, Node.js, Python, Ruby, etc.).
+//!
+//! All functions return a pointer to a heap-allocated `FffResult` struct containing
+//! success status and either data (as JSON string) or an error message.
+//! Memory must be freed using `fff_free_result`.
+
+use std::ffi::{CStr, CString, c_char};
+use std::path::PathBuf;
+use std::time::Duration;
+
+mod ffi_types;
+
+use fff_core::file_picker::FilePicker;
+use fff_core::frecency::FrecencyTracker;
+use fff_core::query_tracker::QueryTracker;
+use fff_core::{DbHealthChecker, FuzzySearchOptions, PaginationArgs, QueryParser};
+use fff_core::{FILE_PICKER, FRECENCY, QUERY_TRACKER};
+use ffi_types::{FffResult, InitOptions, ScanProgress, SearchOptions};
+use mimalloc::MiMalloc;
+
+#[global_allocator]
+static GLOBAL: MiMalloc = MiMalloc;
+
+/// Helper to convert C string to Rust &str.
+///
+/// Returns `None` if the pointer is null or the string is not valid UTF-8.
+/// This is more efficient than `to_string_lossy()` as it returns a borrowed
+/// `&str` directly without `Cow` overhead, and avoids replacement character
+/// scanning since callers are expected to provide valid UTF-8.
+unsafe fn cstr_to_str<'a>(s: *const c_char) -> Option<&'a str> {
+    if s.is_null() {
+        None
+    } else {
+        unsafe { CStr::from_ptr(s).to_str().ok() }
+    }
+}
+
+/// Initialize the file finder with the given options (JSON string)
+///
+/// # Safety
+/// `opts_json` must be a valid null-terminated UTF-8 string
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_init(opts_json: *const c_char) -> *mut FffResult {
+    let opts_str = match unsafe { cstr_to_str(opts_json) } {
+        Some(s) => s,
+        None => return FffResult::err("Options JSON is null or invalid UTF-8"),
+    };
+
+    let opts: InitOptions = match serde_json::from_str(opts_str) {
+        Ok(o) => o,
+        Err(e) => return FffResult::err(&format!("Failed to parse options: {}", e)),
+    };
+
+    // Initialize frecency tracker if path is provided
+    if let Some(frecency_path) = opts.frecency_db_path {
+        // Ensure directory exists
+        if let Some(parent) = PathBuf::from(&frecency_path).parent() {
+            let _ = std::fs::create_dir_all(parent);
+        }
+
+        let mut frecency = match FRECENCY.write() {
+            Ok(f) => f,
+            Err(e) => return FffResult::err(&format!("Failed to acquire frecency lock: {}", e)),
+        };
+        *frecency = None;
+        match FrecencyTracker::new(&frecency_path, opts.use_unsafe_no_lock) {
+            Ok(tracker) => *frecency = Some(tracker),
+            Err(e) => return FffResult::err(&format!("Failed to init frecency db: {}", e)),
+        }
+        drop(frecency);
+    }
+
+    // Initialize query tracker if path is provided
+    if let Some(history_path) = opts.history_db_path {
+        // Ensure directory exists
+        if let Some(parent) = PathBuf::from(&history_path).parent() {
+            let _ = std::fs::create_dir_all(parent);
+        }
+
+        let mut query_tracker = match QUERY_TRACKER.write() {
+            Ok(q) => q,
+            Err(e) => {
+                return FffResult::err(&format!("Failed to acquire query tracker lock: {}", e));
+            }
+        };
+        *query_tracker = None;
+        match QueryTracker::new(&history_path, opts.use_unsafe_no_lock) {
+            Ok(tracker) => *query_tracker = Some(tracker),
+            Err(e) => return FffResult::err(&format!("Failed to init query tracker db: {}", e)),
+        }
+        drop(query_tracker);
+    }
+
+    // Initialize file picker
+    let mut file_picker = match FILE_PICKER.write() {
+        Ok(f) => f,
+        Err(e) => return FffResult::err(&format!("Failed to acquire file picker lock: {}", e)),
+    };
+
+    if file_picker.is_some() {
+        // Already initialized, clean up first
+        if let Some(mut picker) = file_picker.take() {
+            picker.stop_background_monitor();
+        }
+    }
+
+    match FilePicker::new(opts.base_path) {
+        Ok(picker) => {
+            *file_picker = Some(picker);
+            FffResult::ok_empty()
+        }
+        Err(e) => FffResult::err(&format!("Failed to init file picker: {}", e)),
+    }
+}
+
+/// Destroy all resources and clean up
+#[unsafe(no_mangle)]
+pub extern "C" fn fff_destroy() -> *mut FffResult {
+    // Clean up file picker
+    if let Ok(mut file_picker) = FILE_PICKER.write()
+        && let Some(mut picker) = file_picker.take()
+    {
+        picker.stop_background_monitor();
+    }
+
+    // Clean up frecency
+    if let Ok(mut frecency) = FRECENCY.write() {
+        *frecency = None;
+    }
+
+    // Clean up query tracker
+    if let Ok(mut query_tracker) = QUERY_TRACKER.write() {
+        *query_tracker = None;
+    }
+
+    FffResult::ok_empty()
+}
+
+// ============================================================================
+// Search Functions
+// ============================================================================
+
+/// Perform fuzzy search on indexed files
+///
+/// # Safety
+/// `query` and `opts_json` must be valid null-terminated UTF-8 strings
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_search(
+    query: *const c_char,
+    opts_json: *const c_char,
+) -> *mut FffResult {
+    let query_str = match unsafe { cstr_to_str(query) } {
+        Some(s) => s,
+        None => return FffResult::err("Query is null or invalid UTF-8"),
+    };
+
+    let opts: SearchOptions = if opts_json.is_null() {
+        SearchOptions::default()
+    } else {
+        unsafe { cstr_to_str(opts_json) }
+            .and_then(|s| serde_json::from_str(s).ok())
+            .unwrap_or_default()
+    };
+
+    let file_picker_guard = match FILE_PICKER.read() {
+        Ok(f) => f,
+        Err(e) => return FffResult::err(&format!("Failed to acquire file picker lock: {}", e)),
+    };
+
+    let picker = match file_picker_guard.as_ref() {
+        Some(p) => p,
+        None => return FffResult::err("File picker not initialized. Call fff_init first."),
+    };
+
+    let base_path = picker.base_path();
+    let min_combo_count = opts.min_combo_count.unwrap_or(3);
+
+    // Get last same query entry for combo matching
+    let last_same_query_entry = {
+        let query_tracker = match QUERY_TRACKER.read() {
+            Ok(q) => q,
+            Err(_) => return FffResult::err("Failed to acquire query tracker lock"),
+        };
+
+        query_tracker.as_ref().and_then(|tracker| {
+            tracker
+                .get_last_query_entry(query_str, base_path, min_combo_count)
+                .ok()
+                .flatten()
+        })
+    };
+
+    // Parse the query
+    let parser = QueryParser::default();
+    let parsed = parser.parse(query_str);
+
+    let results = FilePicker::fuzzy_search(
+        picker.get_files(),
+        query_str,
+        parsed,
+        FuzzySearchOptions {
+            max_threads: opts.max_threads.unwrap_or(0),
+            current_file: opts.current_file.as_deref(),
+            project_path: Some(picker.base_path()),
+            last_same_query_match: last_same_query_entry.as_ref(),
+            combo_boost_score_multiplier: opts.combo_boost_multiplier.unwrap_or(100),
+            min_combo_count,
+            pagination: PaginationArgs {
+                offset: opts.page_index.unwrap_or(0),
+                limit: opts.page_size.unwrap_or(100),
+            },
+        },
+    );
+
+    // Convert to JSON
+    let json_result = ffi_types::SearchResultJson::from_search_result(&results);
+    match serde_json::to_string(&json_result) {
+        Ok(json) => FffResult::ok_data(&json),
+        Err(e) => FffResult::err(&format!("Failed to serialize results: {}", e)),
+    }
+}
+
+// ============================================================================
+// File Index Functions
+// ============================================================================
+
+/// Trigger a rescan of the file index
+#[unsafe(no_mangle)]
+pub extern "C" fn fff_scan_files() -> *mut FffResult {
+    let mut file_picker = match FILE_PICKER.write() {
+        Ok(f) => f,
+        Err(e) => return FffResult::err(&format!("Failed to acquire file picker lock: {}", e)),
+    };
+
+    let picker = match file_picker.as_mut() {
+        Some(p) => p,
+        None => return FffResult::err("File picker not initialized"),
+    };
+
+    match picker.trigger_rescan() {
+        Ok(_) => FffResult::ok_empty(),
+        Err(e) => FffResult::err(&format!("Failed to trigger rescan: {}", e)),
+    }
+}
+
+/// Check if a scan is currently in progress
+#[unsafe(no_mangle)]
+pub extern "C" fn fff_is_scanning() -> bool {
+    FILE_PICKER
+        .read()
+        .ok()
+        .and_then(|guard| guard.as_ref().map(|p| p.is_scan_active()))
+        .unwrap_or(false)
+}
+
+/// Get scan progress information
+#[unsafe(no_mangle)]
+pub extern "C" fn fff_get_scan_progress() -> *mut FffResult {
+    let file_picker = match FILE_PICKER.read() {
+        Ok(f) => f,
+        Err(e) => return FffResult::err(&format!("Failed to acquire file picker lock: {}", e)),
+    };
+
+    let picker = match file_picker.as_ref() {
+        Some(p) => p,
+        None => return FffResult::err("File picker not initialized"),
+    };
+
+    let progress = picker.get_scan_progress();
+    let result = ScanProgress {
+        scanned_files_count: progress.scanned_files_count,
+        is_scanning: progress.is_scanning,
+    };
+
+    match serde_json::to_string(&result) {
+        Ok(json) => FffResult::ok_data(&json),
+        Err(e) => FffResult::err(&format!("Failed to serialize progress: {}", e)),
+    }
+}
+
+/// Wait for initial scan to complete
+#[unsafe(no_mangle)]
+pub extern "C" fn fff_wait_for_scan(timeout_ms: u64) -> *mut FffResult {
+    let file_picker = match FILE_PICKER.read() {
+        Ok(f) => f,
+        Err(e) => return FffResult::err(&format!("Failed to acquire file picker lock: {}", e)),
+    };
+
+    let picker = match file_picker.as_ref() {
+        Some(p) => p,
+        None => return FffResult::err("File picker not initialized"),
+    };
+
+    let timeout = Duration::from_millis(timeout_ms);
+    let start = std::time::Instant::now();
+    let mut sleep_duration = Duration::from_millis(1);
+
+    while picker.is_scan_active() {
+        if start.elapsed() >= timeout {
+            return FffResult::ok_data("false");
+        }
+        std::thread::sleep(sleep_duration);
+        sleep_duration = std::cmp::min(sleep_duration * 2, Duration::from_millis(50));
+    }
+
+    FffResult::ok_data("true")
+}
+
+/// Restart indexing in a new directory
+///
+/// # Safety
+/// `new_path` must be a valid null-terminated UTF-8 string
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_restart_index(new_path: *const c_char) -> *mut FffResult {
+    let path_str = match unsafe { cstr_to_str(new_path) } {
+        Some(s) => s,
+        None => return FffResult::err("Path is null or invalid UTF-8"),
+    };
+
+    let path = PathBuf::from(&path_str);
+    if !path.exists() {
+        return FffResult::err(&format!("Path does not exist: {}", path_str));
+    }
+
+    let canonical_path = match fff_core::path_utils::canonicalize(&path) {
+        Ok(p) => p,
+        Err(e) => return FffResult::err(&format!("Failed to canonicalize path: {}", e)),
+    };
+
+    let mut file_picker = match FILE_PICKER.write() {
+        Ok(f) => f,
+        Err(e) => return FffResult::err(&format!("Failed to acquire file picker lock: {}", e)),
+    };
+
+    // Stop existing picker
+    if let Some(mut picker) = file_picker.take() {
+        picker.stop_background_monitor();
+    }
+
+    // Create new picker
+    match FilePicker::new(canonical_path.to_string_lossy().to_string()) {
+        Ok(picker) => {
+            *file_picker = Some(picker);
+            FffResult::ok_empty()
+        }
+        Err(e) => FffResult::err(&format!("Failed to init file picker: {}", e)),
+    }
+}
+
+// ============================================================================
+// Frecency Functions
+// ============================================================================
+
+/// Track file access for frecency scoring
+///
+/// # Safety
+/// `file_path` must be a valid null-terminated UTF-8 string
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_track_access(file_path: *const c_char) -> *mut FffResult {
+    let path_str = match unsafe { cstr_to_str(file_path) } {
+        Some(s) => s,
+        None => return FffResult::err("File path is null or invalid UTF-8"),
+    };
+
+    let file_path = PathBuf::from(&path_str);
+
+    // Track in frecency DB
+    let frecency_guard = match FRECENCY.read() {
+        Ok(f) => f,
+        Err(e) => return FffResult::err(&format!("Failed to acquire frecency lock: {}", e)),
+    };
+
+    let frecency = match frecency_guard.as_ref() {
+        Some(f) => f,
+        None => return FffResult::ok_data("false"), // Frecency not initialized, skip
+    };
+
+    if let Err(e) = frecency.track_access(&file_path) {
+        return FffResult::err(&format!("Failed to track access: {}", e));
+    }
+    drop(frecency_guard);
+
+    // Update in file picker
+    let mut file_picker = match FILE_PICKER.write() {
+        Ok(f) => f,
+        Err(e) => return FffResult::err(&format!("Failed to acquire file picker lock: {}", e)),
+    };
+
+    let picker = match file_picker.as_mut() {
+        Some(p) => p,
+        None => return FffResult::ok_data("false"),
+    };
+
+    let frecency_guard = match FRECENCY.read() {
+        Ok(f) => f,
+        Err(_) => return FffResult::ok_data("false"),
+    };
+
+    if let Some(ref frecency) = *frecency_guard {
+        let _ = picker.update_single_file_frecency(&file_path, frecency);
+    }
+
+    FffResult::ok_data("true")
+}
+
+// ============================================================================
+// Git Functions
+// ============================================================================
+
+/// Refresh git status cache
+#[unsafe(no_mangle)]
+pub extern "C" fn fff_refresh_git_status() -> *mut FffResult {
+    match FilePicker::refresh_git_status_global() {
+        Ok(count) => FffResult::ok_data(&count.to_string()),
+        Err(e) => FffResult::err(&format!("Failed to refresh git status: {}", e)),
+    }
+}
+
+// ============================================================================
+// Query Tracking Functions
+// ============================================================================
+
+/// Track query completion for smart suggestions
+///
+/// # Safety
+/// `query` and `file_path` must be valid null-terminated UTF-8 strings
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_track_query(
+    query: *const c_char,
+    file_path: *const c_char,
+) -> *mut FffResult {
+    let query_str = match unsafe { cstr_to_str(query) } {
+        Some(s) => s,
+        None => return FffResult::err("Query is null or invalid UTF-8"),
+    };
+
+    let path_str = match unsafe { cstr_to_str(file_path) } {
+        Some(s) => s,
+        None => return FffResult::err("File path is null or invalid UTF-8"),
+    };
+
+    let file_path = match fff_core::path_utils::canonicalize(path_str) {
+        Ok(p) => p,
+        Err(e) => return FffResult::err(&format!("Failed to canonicalize path: {}", e)),
+    };
+
+    let project_path = {
+        let file_picker = match FILE_PICKER.read() {
+            Ok(f) => f,
+            Err(_) => return FffResult::ok_data("false"),
+        };
+        match file_picker.as_ref() {
+            Some(p) => p.base_path().to_path_buf(),
+            None => return FffResult::ok_data("false"),
+        }
+    };
+
+    let mut query_tracker = match QUERY_TRACKER.write() {
+        Ok(q) => q,
+        Err(_) => return FffResult::ok_data("false"),
+    };
+
+    if let Some(ref mut tracker) = *query_tracker
+        && let Err(e) = tracker.track_query_completion(query_str, &project_path, &file_path)
+    {
+        return FffResult::err(&format!("Failed to track query: {}", e));
+    }
+
+    FffResult::ok_data("true")
+}
+
+/// Get historical query by offset (0 = most recent)
+#[unsafe(no_mangle)]
+pub extern "C" fn fff_get_historical_query(offset: u64) -> *mut FffResult {
+    let project_path = {
+        let file_picker = match FILE_PICKER.read() {
+            Ok(f) => f,
+            Err(_) => return FffResult::ok_data("null"),
+        };
+        match file_picker.as_ref() {
+            Some(p) => p.base_path().to_path_buf(),
+            None => return FffResult::ok_data("null"),
+        }
+    };
+
+    let query_tracker = match QUERY_TRACKER.read() {
+        Ok(q) => q,
+        Err(_) => return FffResult::ok_data("null"),
+    };
+
+    let tracker = match query_tracker.as_ref() {
+        Some(t) => t,
+        None => return FffResult::ok_data("null"),
+    };
+
+    match tracker.get_historical_query(&project_path, offset as usize) {
+        Ok(Some(query)) => {
+            let json = serde_json::to_string(&query).unwrap_or_else(|_| "null".to_string());
+            FffResult::ok_data(&json)
+        }
+        Ok(None) => FffResult::ok_data("null"),
+        Err(e) => FffResult::err(&format!("Failed to get historical query: {}", e)),
+    }
+}
+
+/// Get health check information
+///
+/// # Safety
+/// `test_path` can be null or a valid null-terminated UTF-8 string
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_health_check(test_path: *const c_char) -> *mut FffResult {
+    let test_path = unsafe { cstr_to_str(test_path) }
+        .filter(|s| !s.is_empty())
+        .map(PathBuf::from)
+        .unwrap_or_else(|| std::env::current_dir().unwrap_or_default());
+
+    let mut health = serde_json::Map::new();
+    health.insert(
+        "version".to_string(),
+        serde_json::Value::String(env!("CARGO_PKG_VERSION").to_string()),
+    );
+
+    // Git info
+    let mut git_info = serde_json::Map::new();
+    let git_version = git2::Version::get();
+    let (major, minor, rev) = git_version.libgit2_version();
+    git_info.insert(
+        "libgit2_version".to_string(),
+        serde_json::Value::String(format!("{}.{}.{}", major, minor, rev)),
+    );
+
+    match git2::Repository::discover(&test_path) {
+        Ok(repo) => {
+            git_info.insert("available".to_string(), serde_json::Value::Bool(true));
+            git_info.insert(
+                "repository_found".to_string(),
+                serde_json::Value::Bool(true),
+            );
+            if let Some(workdir) = repo.workdir() {
+                git_info.insert(
+                    "workdir".to_string(),
+                    serde_json::Value::String(workdir.to_string_lossy().to_string()),
+                );
+            }
+        }
+        Err(e) => {
+            git_info.insert("available".to_string(), serde_json::Value::Bool(true));
+            git_info.insert(
+                "repository_found".to_string(),
+                serde_json::Value::Bool(false),
+            );
+            git_info.insert(
+                "error".to_string(),
+                serde_json::Value::String(e.message().to_string()),
+            );
+        }
+    }
+    health.insert("git".to_string(), serde_json::Value::Object(git_info));
+
+    // File picker info
+    let mut picker_info = serde_json::Map::new();
+    match FILE_PICKER.read() {
+        Ok(guard) => {
+            if let Some(ref picker) = *guard {
+                picker_info.insert("initialized".to_string(), serde_json::Value::Bool(true));
+                picker_info.insert(
+                    "base_path".to_string(),
+                    serde_json::Value::String(picker.base_path().to_string_lossy().to_string()),
+                );
+                picker_info.insert(
+                    "is_scanning".to_string(),
+                    serde_json::Value::Bool(picker.is_scan_active()),
+                );
+                let progress = picker.get_scan_progress();
+                picker_info.insert(
+                    "indexed_files".to_string(),
+                    serde_json::Value::Number(progress.scanned_files_count.into()),
+                );
+            } else {
+                picker_info.insert("initialized".to_string(), serde_json::Value::Bool(false));
+            }
+        }
+        Err(_) => {
+            picker_info.insert("initialized".to_string(), serde_json::Value::Bool(false));
+            picker_info.insert(
+                "error".to_string(),
+                serde_json::Value::String("Failed to acquire lock".to_string()),
+            );
+        }
+    }
+    health.insert(
+        "file_picker".to_string(),
+        serde_json::Value::Object(picker_info),
+    );
+
+    // Frecency info
+    let mut frecency_info = serde_json::Map::new();
+    match FRECENCY.read() {
+        Ok(guard) => {
+            frecency_info.insert(
+                "initialized".to_string(),
+                serde_json::Value::Bool(guard.is_some()),
+            );
+            if let Some(ref frecency) = *guard
+                && let Ok(health_data) = frecency.get_health()
+            {
+                let mut db_health = serde_json::Map::new();
+                db_health.insert(
+                    "path".to_string(),
+                    serde_json::Value::String(health_data.path),
+                );
+                db_health.insert(
+                    "disk_size".to_string(),
+                    serde_json::Value::Number(health_data.disk_size.into()),
+                );
+                frecency_info.insert(
+                    "db_healthcheck".to_string(),
+                    serde_json::Value::Object(db_health),
+                );
+            }
+        }
+        Err(_) => {
+            frecency_info.insert("initialized".to_string(), serde_json::Value::Bool(false));
+        }
+    }
+    health.insert(
+        "frecency".to_string(),
+        serde_json::Value::Object(frecency_info),
+    );
+
+    // Query tracker info
+    let mut query_info = serde_json::Map::new();
+    match QUERY_TRACKER.read() {
+        Ok(guard) => {
+            query_info.insert(
+                "initialized".to_string(),
+                serde_json::Value::Bool(guard.is_some()),
+            );
+            if let Some(ref tracker) = *guard
+                && let Ok(health_data) = tracker.get_health()
+            {
+                let mut db_health = serde_json::Map::new();
+                db_health.insert(
+                    "path".to_string(),
+                    serde_json::Value::String(health_data.path),
+                );
+                db_health.insert(
+                    "disk_size".to_string(),
+                    serde_json::Value::Number(health_data.disk_size.into()),
+                );
+                query_info.insert(
+                    "db_healthcheck".to_string(),
+                    serde_json::Value::Object(db_health),
+                );
+            }
+        }
+        Err(_) => {
+            query_info.insert("initialized".to_string(), serde_json::Value::Bool(false));
+        }
+    }
+    health.insert(
+        "query_tracker".to_string(),
+        serde_json::Value::Object(query_info),
+    );
+
+    match serde_json::to_string(&health) {
+        Ok(json) => FffResult::ok_data(&json),
+        Err(e) => FffResult::err(&format!("Failed to serialize health check: {}", e)),
+    }
+}
+
+/// Free a result returned by any fff_* function
+///
+/// # Safety
+/// `result_ptr` must be a valid pointer returned by a fff_* function
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_free_result(result_ptr: *mut FffResult) {
+    if result_ptr.is_null() {
+        return;
+    }
+
+    unsafe {
+        let result = Box::from_raw(result_ptr);
+        if !result.data.is_null() {
+            drop(CString::from_raw(result.data));
+        }
+        if !result.error.is_null() {
+            drop(CString::from_raw(result.error));
+        }
+        // Box will be dropped here, freeing the FffResult struct
+    }
+}
+
+/// Free a string returned by fff_* functions
+///
+/// # Safety
+/// `s` must be a valid C string allocated by this library
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_free_string(s: *mut c_char) {
+    unsafe {
+        if !s.is_null() {
+            drop(CString::from_raw(s));
+        }
+    }
+}
@@ -0,0 +1,65 @@
+[package]
+name = "fff-core"
+version = "0.1.0"
+edition = "2024"
+description = "High-performance file finder core library"
+license = "MIT"
+
+[lib]
+path = "src/lib.rs"
+crate-type = ["rlib", "staticlib", "cdylib"]
+
+[features]
+default = []
+# Enable C FFI exports
+ffi = []
+
+[dependencies]
+# Workspace dependencies
+ahash = { workspace = true }
+rayon = { workspace = true }
+smallvec = { workspace = true }
+thiserror = { workspace = true }
+tracing = { workspace = true }
+
+# Local crates
+fff-query-parser = { path = "../fff-query-parser" }
+
+# External dependencies
+bindet = { workspace = true }
+blake3 = { workspace = true }
+chrono = { workspace = true }
+dirs = { workspace = true }
+git2 = { workspace = true }
+glidesort = { workspace = true }
+grep-matcher = { workspace = true }
+grep-searcher = { workspace = true }
+memchr = "2"
+heed = { workspace = true }
+ignore = { workspace = true }
+memmap2 = { workspace = true }
+neo_frizbee = { workspace = true }
+notify = { workspace = true }
+notify-debouncer-full = { workspace = true }
+once_cell = { workspace = true }
+parking_lot = { workspace = true }
+pathdiff = { workspace = true }
+regex = { workspace = true }
+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 }
+
+# Platform-specific: Use vendored OpenSSL on non-Windows (Linux, macOS)
+[target.'cfg(not(windows))'.dependencies]
+openssl = { version = "0.10", features = ["vendored"] }
+
+# Platform-specific: dunce for Windows to avoid \\?\ extended path prefix
+[target.'cfg(windows)'.dependencies]
+dunce = { workspace = true }
+
+[dev-dependencies]
+criterion = { version = "0.5", features = ["html_reports"] }
+rand = { version = "0.8", features = ["small_rng"] }
+tempfile = "3.8"
@@ -0,0 +1,16 @@
+fn main() {
+    // 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");
+    }
+}
@@ -22,6 +22,7 @@ pub struct BackgroundWatcher {

 const DEBOUNCE_TIMEOUT: Duration = Duration::from_millis(250);
 const MAX_PATHS_THRESHOLD: usize = 1024;
+const MAX_SELECTIVE_WATCH_DIRS: usize = 100;

 impl BackgroundWatcher {
    pub fn new(base_path: PathBuf, git_workdir: Option<PathBuf>) -> Result<Self, Error> {
@@ -64,8 +65,39 @@ impl BackgroundWatcher {
            config,
        )?;

-        debouncer.watch(base_path.as_path(), RecursiveMode::Recursive)?;
-        info!("File watcher initizlieed for path: {}", base_path.display());
+        // Watch only non-ignored directories to avoid flooding the OS event buffer.
+        // On macOS, FSEvents has a fixed-size kernel buffer — watching huge gitignored
+        // directories like `target/` in rust causes buffer overflow, which drops real source file
+        // events. Instead we watch the root non-recursively (for top-level file changes
+        // and new directory detection) and each non-ignored subdirectory recursively.
+        let watch_dirs = collect_non_ignored_dirs(&base_path);
+
+        if watch_dirs.len() > MAX_SELECTIVE_WATCH_DIRS {
+            tracing::warn!(
+                "Too many non-ignored directories ({}/{}) can't efficiently watch them",
+                watch_dirs.len(),
+                MAX_SELECTIVE_WATCH_DIRS
+            );
+            debouncer.watch(base_path.as_path(), RecursiveMode::Recursive)?;
+        } else {
+            debouncer.watch(base_path.as_path(), RecursiveMode::NonRecursive)?;
+
+            for dir in &watch_dirs {
+                match debouncer.watch(dir.as_path(), RecursiveMode::Recursive) {
+                    Ok(()) => {}
+                    Err(e) => {
+                        // Non-fatal: directory may have been removed between discovery and watch
+                        warn!("Failed to watch directory {}: {}", dir.display(), e);
+                    }
+                }
+            }
+        }
+
+        info!(
+            "File watcher initialized for {} directories under {}",
+            watch_dirs.len(),
+            base_path.display()
+        );

        Ok(debouncer)
    }
@@ -116,6 +148,18 @@ fn handle_debounced_events(events: Vec<DebouncedEvent>, git_workdir: &Option<Pat
            continue;
        }

+        // When macOS FSEvents (or other backends) overflow their event buffer, the kernel
+        // drops individual events and emits a Rescan flag telling us to re-scan the subtree.
+        // Without handling this, modified source files can be silently missed.
+        if debounced_event.event.need_rescan() {
+            warn!(
+                "Received rescan event for paths {:?}, triggering full rescan",
+                debounced_event.event.paths
+            );
+            need_full_rescan = true;
+            break;
+        }
+
        tracing::debug!(event = ?debounced_event.event, "Processing FS event");
        for path in &debounced_event.event.paths {
            if is_ignore_definition_path(path) {
@@ -209,11 +253,13 @@ fn handle_debounced_events(events: Vec<DebouncedEvent>, git_workdir: &Option<Pat
        // Apply file removals
        for path in paths_to_remove {
            picker.remove_file_by_path(path);
+            // No need to invalidate mmap — the FileItem (and its mmap) is dropped
        }

        // Apply file additions/modifications and collect paths for git status update
        let mut files_to_update_git_status = Vec::with_capacity(paths_to_add_or_modify.len());
        for path in paths_to_add_or_modify {
+            // on_create_or_modify clears the mmap internally when modified time changes
            if let Some(file) = picker.on_create_or_modify(path) {
                files_to_update_git_status.push(file.path.clone());
            }
@@ -252,6 +298,10 @@ fn handle_debounced_events(events: Vec<DebouncedEvent>, git_workdir: &Option<Pat
 fn trigger_full_rescan() {
    info!("Triggering full filesystem rescan");

+    // Note: no need to clear mmaps — they are backed by the kernel page cache
+    // and automatically reflect file changes. Old FileItems (and their mmaps)
+    // are dropped when the picker rebuilds its file list.
+
    let Ok(mut file_picker_guard) = FILE_PICKER.write() else {
        error!("Failed to acquire file picker write lock for full rescan");
        return;
@@ -324,3 +374,38 @@ fn is_ignore_definition_path(path: &Path) -> bool {
        Some(".ignore") | Some(".gitignore")
    )
 }
+
+/// Collects immediate non-ignored subdirectories of `base_path` using the `ignore` crate
+/// to respect .gitignore, .ignore, and global gitignore rules. This is used to set up
+/// selective file watching — only non-ignored directories get a recursive watcher,
+/// preventing gitignored directories like `target/` from flooding the OS event buffer.
+fn collect_non_ignored_dirs(base_path: &Path) -> Vec<PathBuf> {
+    use ignore::WalkBuilder;
+
+    let walker = WalkBuilder::new(base_path)
+        .hidden(false)
+        .git_ignore(true)
+        .git_exclude(true)
+        .git_global(true)
+        .ignore(true)
+        .follow_links(false)
+        .max_depth(Some(1))
+        .build();
+
+    let mut dirs = Vec::new();
+    for entry in walker {
+        let Ok(entry) = entry else { continue };
+        let path = entry.path();
+
+        // Skip the root directory itself
+        if path == base_path {
+            continue;
+        }
+
+        if path.is_dir() && !is_git_file(path) {
+            dirs.push(path.to_path_buf());
+        }
+    }
+
+    dirs
+}
@@ -0,0 +1,319 @@
+//! Constraint filtering engine for fff.
+//!
+//! This module provides the core constraint application logic that filters items
+//! based on parsed query constraints (extensions, path segments, globs, git status, etc.).
+//!
+//! The filtering is generic over the [`Constrainable`] trait, allowing reuse across
+//! different search modes (file picker, live grep, etc.).
+
+use ahash::AHashSet;
+use fff_query_parser::{Constraint, GitStatusFilter};
+use smallvec::SmallVec;
+use zlob::{ZlobFlags, zlob_match_paths};
+
+use crate::git::is_modified_status;
+
+/// Minimum item count before switching to parallel iteration with rayon.
+/// Below this threshold, the overhead of thread pool dispatch outweighs the benefit.
+const PAR_THRESHOLD: usize = 10_000;
+
+/// Trait for items that can be filtered by constraints.
+/// Implement this for any searchable item type (files, grep results, etc.).
+pub trait Constrainable {
+    /// The file's relative path (e.g. "src/main.rs")
+    fn relative_path(&self) -> &str;
+
+    /// The file's lowercased relative path for case-insensitive matching
+    fn relative_path_lower(&self) -> &str;
+
+    /// The file name component (e.g. "main.rs")
+    fn file_name(&self) -> &str;
+
+    /// The git status of this item, if available
+    fn git_status(&self) -> Option<git2::Status>;
+}
+
+/// Check if file extension matches (without allocation)
+#[inline]
+pub fn file_has_extension(file_name: &str, ext: &str) -> bool {
+    if file_name.len() <= ext.len() + 1 {
+        return false;
+    }
+    let start = file_name.len() - ext.len() - 1;
+    file_name.as_bytes().get(start) == Some(&b'.')
+        && file_name[start + 1..].eq_ignore_ascii_case(ext)
+}
+
+/// Check if path contains segment (without allocation)
+#[inline]
+pub fn path_contains_segment(path: &str, segment: &str) -> bool {
+    let path_bytes = path.as_bytes();
+    let segment_len = segment.len();
+
+    // Check segment/ at start
+    if path.len() > segment_len
+        && path_bytes.get(segment_len) == Some(&b'/')
+        && path[..segment_len].eq_ignore_ascii_case(segment)
+    {
+        return true;
+    }
+
+    // Check /segment/ anywhere using byte scanning
+    if path.len() < segment_len + 2 {
+        return false;
+    }
+
+    for i in 0..path.len().saturating_sub(segment_len + 1) {
+        if path_bytes[i] == b'/' {
+            let start = i + 1;
+            let end = start + segment_len;
+            if end < path.len()
+                && path_bytes[end] == b'/'
+                && path[start..end].eq_ignore_ascii_case(segment)
+            {
+                return true;
+            }
+        }
+    }
+    false
+}
+
+/// Check if an item at given index matches a constraint (single-pass friendly, allocation-free)
+#[inline]
+fn item_matches_constraint_at_index<T: Constrainable>(
+    item: &T,
+    item_index: usize,
+    constraint: &Constraint<'_>,
+    glob_results: &[(bool, AHashSet<usize>)],
+    glob_idx: &mut usize,
+    negate: bool,
+) -> bool {
+    let matches = match constraint {
+        Constraint::Extension(ext) => file_has_extension(item.file_name(), ext),
+        Constraint::Glob(_) => {
+            let result = glob_results
+                .get(*glob_idx)
+                .map(|(is_neg, set)| {
+                    let matched = set.contains(&item_index);
+                    if *is_neg { !matched } else { matched }
+                })
+                .unwrap_or(true);
+            *glob_idx += 1;
+            return if negate { !result } else { result };
+        }
+        Constraint::PathSegment(segment) => path_contains_segment(item.relative_path(), segment),
+        Constraint::GitStatus(status_filter) => match (item.git_status(), status_filter) {
+            (Some(status), GitStatusFilter::Modified) => is_modified_status(status),
+            (Some(status), GitStatusFilter::Untracked) => status.contains(git2::Status::WT_NEW),
+            (Some(status), GitStatusFilter::Staged) => status.intersects(
+                git2::Status::INDEX_NEW
+                    | git2::Status::INDEX_MODIFIED
+                    | git2::Status::INDEX_DELETED
+                    | git2::Status::INDEX_RENAMED
+                    | git2::Status::INDEX_TYPECHANGE,
+            ),
+            (Some(status), GitStatusFilter::Unmodified) => status.is_empty(),
+            (None, GitStatusFilter::Unmodified) => true,
+            (None, _) => false,
+        },
+        Constraint::Not(inner) => {
+            return item_matches_constraint_at_index(
+                item,
+                item_index,
+                inner,
+                glob_results,
+                glob_idx,
+                !negate,
+            );
+        }
+
+        // only works with negation
+        Constraint::Text(text) => item.relative_path_lower().contains(text),
+
+        // Parts and Exclude are handled at a higher level
+        Constraint::Parts(_) | Constraint::Exclude(_) | Constraint::FileType(_) => true,
+    };
+
+    if negate { !matches } else { matches }
+}
+
+/// Apply constraint-based prefiltering in a single pass over all items.
+/// Returns `None` if no constraints are present, `Some(filtered)` otherwise.
+/// Multiple extension constraints (*.rs *.ts) are combined with OR logic.
+/// All other constraints are combined with AND logic.
+///
+/// Uses parallel iteration via rayon when the item count exceeds [`PAR_THRESHOLD`].
+pub fn apply_constraints<'a, T: Constrainable + Sync>(
+    items: &'a [T],
+    constraints: &[Constraint<'_>],
+) -> Option<Vec<&'a T>> {
+    if constraints.is_empty() {
+        return None;
+    }
+
+    // Separate extension constraints from other constraints — they use OR logic
+    let mut extensions: SmallVec<[&str; 8]> = SmallVec::new();
+    let mut other_constraints: SmallVec<[&Constraint<'_>; 8]> = SmallVec::new();
+
+    for constraint in constraints {
+        match constraint {
+            Constraint::Extension(ext) => extensions.push(ext),
+            _ => other_constraints.push(constraint),
+        }
+    }
+
+    // Only collect paths if we have glob constraints (expensive)
+    let has_globs = other_constraints
+        .iter()
+        .any(|c| matches!(c, Constraint::Glob(_) | Constraint::Not(_)));
+
+    let glob_results = if has_globs {
+        let paths: Vec<&str> = items.iter().map(|f| f.relative_path()).collect();
+        precompute_glob_matches(&other_constraints, &paths)
+    } else {
+        Vec::new()
+    };
+
+    let matches_constraints = |i: usize, item: &T| -> bool {
+        if !extensions.is_empty()
+            && !extensions
+                .iter()
+                .any(|ext| file_has_extension(item.file_name(), ext))
+        {
+            return false;
+        }
+
+        let mut glob_idx = 0;
+        other_constraints.iter().all(|constraint| {
+            item_matches_constraint_at_index(
+                item,
+                i,
+                constraint,
+                &glob_results,
+                &mut glob_idx,
+                false,
+            )
+        })
+    };
+
+    let filtered: Vec<&T> = if items.len() >= PAR_THRESHOLD {
+        use rayon::prelude::*;
+        items
+            .par_iter()
+            .enumerate()
+            .filter(|(i, item)| matches_constraints(*i, item))
+            .map(|(_, item)| item)
+            .collect()
+    } else {
+        items
+            .iter()
+            .enumerate()
+            .filter(|(i, item)| matches_constraints(*i, item))
+            .map(|(_, item)| item)
+            .collect()
+    };
+
+    Some(filtered)
+}
+
+fn precompute_glob_matches<'a>(
+    constraints: &[&Constraint<'a>],
+    paths: &[&str],
+) -> Vec<(bool, AHashSet<usize>)> {
+    let mut results = Vec::new();
+    for constraint in constraints {
+        collect_glob_indices(constraint, paths, &mut results, false);
+    }
+    results
+}
+
+fn collect_glob_indices<'a>(
+    constraint: &Constraint<'a>,
+    paths: &[&str],
+    results: &mut Vec<(bool, AHashSet<usize>)>,
+    is_negated: bool,
+) {
+    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()));
+            }
+        }
+        Constraint::Not(inner) => {
+            collect_glob_indices(inner, paths, results, !is_negated);
+        }
+        _ => {}
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_file_has_extension() {
+        assert!(file_has_extension("file.rs", "rs"));
+        assert!(file_has_extension("file.RS", "rs")); // case-insensitive
+        assert!(file_has_extension("file.test.rs", "rs"));
+        assert!(file_has_extension("a.rs", "rs"));
+
+        assert!(!file_has_extension("file.tsx", "rs"));
+        assert!(!file_has_extension("rs", "rs")); // too short
+        assert!(!file_has_extension(".rs", "rs")); // just extension
+        assert!(!file_has_extension("file.rsx", "rs")); // different extension
+        assert!(!file_has_extension("filers", "rs")); // no dot
+    }
+
+    #[test]
+    fn test_path_contains_segment() {
+        // Segment at start
+        assert!(path_contains_segment("src/lib.rs", "src"));
+        assert!(path_contains_segment("SRC/lib.rs", "src")); // case-insensitive
+
+        // Segment in middle
+        assert!(path_contains_segment("app/src/lib.rs", "src"));
+        assert!(path_contains_segment("app/SRC/lib.rs", "src"));
+
+        // Multiple levels
+        assert!(path_contains_segment("core/workflow/src/main.rs", "src"));
+        assert!(path_contains_segment(
+            "core/workflow/src/main.rs",
+            "workflow"
+        ));
+        assert!(path_contains_segment("core/workflow/src/main.rs", "core"));
+
+        // Should not match partial segments
+        assert!(!path_contains_segment("source/lib.rs", "src"));
+        assert!(!path_contains_segment("mysrc/lib.rs", "src"));
+
+        // Should not match filename
+        assert!(!path_contains_segment("lib/src", "src"));
+
+        // Edge cases
+        assert!(!path_contains_segment("", "src"));
+        assert!(!path_contains_segment("src", "src")); // no trailing slash
+    }
+}
@@ -0,0 +1,31 @@
+use crate::error::Result;
+
+/// Health information about a database
+#[derive(Debug, Clone)]
+pub struct DbHealth {
+    /// Path to the database file
+    pub path: String,
+    /// Size on disk in bytes
+    pub disk_size: u64,
+    /// Entry counts by table name
+    pub entry_counts: Vec<(&'static str, u64)>,
+}
+
+pub trait DbHealthChecker {
+    fn get_env(&self) -> &heed::Env;
+    fn count_entries(&self) -> Result<Vec<(&'static str, u64)>>;
+
+    fn get_health(&self) -> Result<DbHealth> {
+        let env = self.get_env();
+
+        let size = env.real_disk_size().map_err(crate::error::Error::EnvOpen)?;
+        let path = env.path().to_string_lossy().to_string();
+        let entry_counts = self.count_entries()?;
+
+        Ok(DbHealth {
+            path,
+            disk_size: size,
+            entry_counts,
+        })
+    }
+}
@@ -45,13 +45,4 @@ pub enum Error {
    Git(#[from] git2::Error),
 }

-impl From<Error> for mlua::Error {
-    fn from(value: Error) -> Self {
-        let string_value = value.to_string();
-
-        ::tracing::error!(string_value);
-        mlua::Error::RuntimeError(string_value)
-    }
-}
-
 pub type Result<T> = std::result::Result<T, Error>;
@@ -2,13 +2,14 @@ use crate::background_watcher::BackgroundWatcher;
 use crate::error::Error;
 use crate::frecency::FrecencyTracker;
 use crate::git::GitStatusCache;
-use crate::location::parse_location;
 use crate::query_tracker::QueryMatchEntry;
 use crate::score::match_and_score_files;
 use crate::types::{FileItem, PaginationArgs, ScoringContext, SearchResult};
+use fff_query_parser::FFFQuery;
 use git2::{Repository, Status, StatusOptions};
 use rayon::prelude::*;
 use std::fmt::Debug;
+use std::io::Read;
 use std::path::{Path, PathBuf};
 use std::sync::{
    Arc,
@@ -19,6 +20,25 @@ use tracing::{Level, debug, error, info, warn};

 use crate::{FILE_PICKER, FRECENCY};

+/// Detect if a file is binary by checking for NUL bytes in the first 512 bytes.
+/// This is the same heuristic used by git and grep — simple, fast, and sufficient.
+#[inline]
+fn detect_binary(path: &Path, size: u64) -> bool {
+    // Empty files are not binary
+    if size == 0 {
+        return false;
+    }
+
+    let Ok(file) = std::fs::File::open(path) else {
+        return false;
+    };
+    let mut reader = std::io::BufReader::with_capacity(1024, file);
+
+    let mut buf = [0u8; 512];
+    let n = reader.read(&mut buf).unwrap_or(0);
+    buf[..n].contains(&0)
+}
+
 #[derive(Debug, Clone, Copy)]
 pub struct FuzzySearchOptions<'a> {
    pub max_threads: usize,
@@ -77,19 +97,17 @@ impl FileItem {
            Err(_) => (0, 0),
        };

-        Self {
+        let is_binary = detect_binary(&path, size);
+
+        Self::new_raw(
            path,
-            relative_path_lower: relative_path.to_lowercase(),
            relative_path,
-            file_name_lower: name.to_lowercase(),
-            file_name: name,
+            name,
            size,
            modified,
-            access_frecency_score: 0,
-            modification_frecency_score: 0,
-            total_frecency_score: 0,
            git_status,
-        }
+            is_binary,
+        )
    }

    pub fn update_frecency_scores(&mut self, tracker: &FrecencyTracker) -> Result<(), Error> {
@@ -175,14 +193,29 @@ impl FilePicker {
        Ok(picker)
    }

+    /// Perform fuzzy search on files with a pre-parsed query.
+    ///
+    /// The query should be parsed using `QueryParser::parse()` before calling this function.
+    /// This allows the caller to handle location parsing and other preprocessing.
+    ///
+    /// # Arguments
+    /// * `files` - Slice of files to search
+    /// * `query` - The raw query string (used for max_typos calculation and debugging)
+    /// * `parsed` - Pre-parsed query result (can be None for simple single-token queries)
+    /// * `options` - Search options including pagination, threading, and scoring parameters
+    ///
+    /// # Returns
+    /// SearchResult containing matched files, scores, and location information
    pub fn fuzzy_search<'a>(
        files: &'a [FileItem],
        query: &'a str,
+        parsed: Option<FFFQuery<'a>>,
        options: FuzzySearchOptions<'a>,
    ) -> SearchResult<'a> {
        let max_threads = options.max_threads.max(1);
        debug!(
            ?query,
+            parsed_is_some = parsed.is_some(),
            pagination = ?options.pagination,
            ?max_threads,
            current_file = ?options.current_file,
@@ -190,13 +223,26 @@ impl FilePicker {
        );

        let total_files = files.len();
-        let (query, location) = parse_location(query);
+
+        // Extract location from parsed query
+        let location = parsed.as_ref().and_then(|p| p.location);
+
+        // Get effective query for max_typos calculation (without location suffix)
+        let effective_query = match &parsed {
+            Some(p) => match &p.fuzzy_query {
+                fff_query_parser::FuzzyQuery::Text(t) => *t,
+                fff_query_parser::FuzzyQuery::Parts(parts) if !parts.is_empty() => parts[0],
+                _ => query.trim(),
+            },
+            None => query.trim(),
+        };

        // small queries with a large number of results can match absolutely everything
-        let max_typos = (query.len() as u16 / 4).clamp(2, 6);
+        let max_typos = (effective_query.len() as u16 / 4).clamp(2, 6);

        let context = ScoringContext {
-            query,
+            raw_query: query,
+            parsed_query: parsed,
            project_path: options.project_path,
            max_typos,
            max_threads,
@@ -209,7 +255,6 @@ impl FilePicker {

        let time = std::time::Instant::now();

-        // Match, score, and paginate files (all done in sort_and_truncate)
        let (items, scores, total_matched) = match_and_score_files(files, &context);

        debug!(
@@ -382,6 +427,12 @@ impl FilePicker {
                    let modified = modified.as_secs();
                    if file.modified < modified {
                        file.modified = modified;
+
+                        // TODO figure out if we actually need to remap the memory or invalidate
+                        // mapping here because on linux and macos with the shared map opening it
+                        // should be automatically available everywhere automatically which saves
+                        // some time from doing extra remapping on every search
+                        file.invalidate_mmap();
                    }
                }

@@ -0,0 +1,43 @@
+//! fff-core - High-performance file finder library
+//!
+//! This crate provides the core file indexing and fuzzy search functionality.
+//! It maintains global state for the file picker, frecency tracker, and query tracker.
+
+mod background_watcher;
+pub mod constraints;
+mod db_healthcheck;
+mod error;
+pub mod file_picker;
+pub mod frecency;
+pub mod git;
+pub mod grep;
+pub mod path_utils;
+pub mod query_tracker;
+pub mod score;
+mod sort_buffer;
+pub mod types;
+
+use file_picker::FilePicker;
+use frecency::FrecencyTracker;
+use once_cell::sync::Lazy;
+use query_tracker::QueryTracker;
+use std::sync::RwLock;
+
+// Global state - same pattern as fff-nvim
+pub static FRECENCY: Lazy<RwLock<Option<FrecencyTracker>>> = Lazy::new(|| RwLock::new(None));
+pub static FILE_PICKER: Lazy<RwLock<Option<FilePicker>>> = Lazy::new(|| RwLock::new(None));
+pub static QUERY_TRACKER: Lazy<RwLock<Option<QueryTracker>>> = Lazy::new(|| RwLock::new(None));
+
+// Re-export main types for convenience
+pub use db_healthcheck::{DbHealth, DbHealthChecker};
+pub use error::{Error, Result};
+pub use file_picker::{FuzzySearchOptions, ScanProgress};
+pub use types::{FileItem, PaginationArgs, Score, ScoringContext, SearchResult};
+
+// Re-export grep types
+pub use grep::{GrepMatch, GrepMode, GrepResult, GrepSearchOptions};
+
+// Re-export query parser types (including Location which moved there)
+pub use fff_query_parser::{
+    Constraint, FFFQuery, FuzzyQuery, Location, QueryParser, location::parse_location,
+};
@@ -0,0 +1,152 @@
+//! Path utility functions for file picker scoring
+
+use std::path::{Path, PathBuf};
+
+/// Canonicalize a path, resolving symlinks and producing an absolute path.
+///
+/// On Windows, uses `dunce::canonicalize` to avoid the `\\?\` extended-length path prefix
+/// that `std::fs::canonicalize` produces. Neovim cannot open paths with this prefix.
+/// On other platforms, delegates directly to `std::fs::canonicalize`.
+#[cfg(windows)]
+pub fn canonicalize(path: impl AsRef<Path>) -> std::io::Result<PathBuf> {
+    dunce::canonicalize(path)
+}
+
+#[cfg(not(windows))]
+pub fn canonicalize(path: impl AsRef<Path>) -> std::io::Result<PathBuf> {
+    std::fs::canonicalize(path)
+}
+
+/// Calculate distance penalty based on directory proximity
+/// Returns a negative penalty score based on how far the candidate is from the current file
+pub fn calculate_distance_penalty(current_file: Option<&str>, candidate_path: &str) -> i32 {
+    let Some(ref current_path) = current_file else {
+        return 0; // No penalty if no current file
+    };
+
+    let current_dir = if let Some(parent) = std::path::Path::new(current_path).parent() {
+        parent.to_string_lossy().to_string()
+    } else {
+        String::new()
+    };
+
+    let candidate_dir = if let Some(parent) = std::path::Path::new(candidate_path).parent() {
+        parent.to_string_lossy().to_string()
+    } else {
+        String::new()
+    };
+
+    if current_dir == candidate_dir {
+        return 0; // Same directory, no penalty
+    }
+
+    let current_parts: Vec<&str> = current_dir
+        .split(std::path::MAIN_SEPARATOR)
+        .filter(|s| !s.is_empty())
+        .collect();
+    let candidate_parts: Vec<&str> = candidate_dir
+        .split(std::path::MAIN_SEPARATOR)
+        .filter(|s| !s.is_empty())
+        .collect();
+
+    let common_len = current_parts
+        .iter()
+        .zip(candidate_parts.iter())
+        .take_while(|(a, b)| a == b)
+        .count();
+
+    let current_depth_from_common = current_parts.len() - common_len;
+
+    if current_depth_from_common == 0 {
+        return 0; // Current file is at the common ancestor level
+    }
+
+    let penalty = -(current_depth_from_common as i32);
+
+    penalty.max(-20)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    #[cfg(not(target_family = "windows"))]
+    fn test_calculate_distance_penalty() {
+        assert_eq!(
+            calculate_distance_penalty(None, "examples/user/test/mod.rs"),
+            0
+        );
+        // Same directory
+        assert_eq!(
+            calculate_distance_penalty(
+                Some("examples/user/test/main.rs"),
+                "examples/user/test/mod.rs"
+            ),
+            0
+        );
+        //
+        // One level apart
+        assert_eq!(
+            calculate_distance_penalty(
+                Some("examples/user/test/subdir/file.rs"),
+                "examples/user/test/mod.rs"
+            ),
+            -1
+        );
+        //
+        // Different subdirectories (same parent)
+        assert_eq!(
+            calculate_distance_penalty(
+                Some("examples/user/test/dir1/file.rs"),
+                "examples/user/test/dir2/mod.rs"
+            ),
+            -1
+        );
+
+        assert_eq!(
+            calculate_distance_penalty(
+                Some("examples/audio-announce/src/lib/audio-announce.rs"),
+                "examples/audio-announce/src/main.rs"
+            ),
+            -1
+        );
+
+        assert_eq!(
+            calculate_distance_penalty(
+                Some("examples/audio-announce/src/audio-announce.rs"),
+                "examples/pixel/src/main.rs"
+            ),
+            -2
+        );
+
+        // Root level files
+        assert_eq!(calculate_distance_penalty(Some("main.rs"), "lib.rs"), 0);
+    }
+
+    #[test]
+    #[cfg(target_family = "windows")]
+    fn distance_penalty_works_on_windows() {
+        assert_eq!(
+            calculate_distance_penalty(None, "examples\\user\\test\\mod.rs"),
+            0
+        );
+        // Same directory
+        assert_eq!(
+            calculate_distance_penalty(
+                Some("examples\\user\\test\\main.rs"),
+                "examples\\user\\test\\mod.rs"
+            ),
+            0
+        );
+        //
+        // One level apart
+        assert_eq!(
+            calculate_distance_penalty(
+                Some("examples\\user\\test\\subdir\\file.rs"),
+                "examples\\user\\test\\mod.rs"
+            ),
+            -1
+        );
+    }
+}
@@ -31,8 +31,10 @@ pub struct QueryTracker {
    env: Env,
    // Database for (project_path, query) -> QueryMatchEntry mappings
    query_file_db: Database<Bytes, SerdeBincode<QueryMatchEntry>>,
-    // Database for project_path -> VecDeque<HistoryEntry> mappings
+    // Database for project_path -> VecDeque<HistoryEntry> mappings (file picker)
    query_history_db: Database<Bytes, SerdeBincode<VecDeque<HistoryEntry>>>,
+    // Database for project_path -> VecDeque<HistoryEntry> mappings (grep)
+    grep_query_history_db: Database<Bytes, SerdeBincode<VecDeque<HistoryEntry>>>,
 }

 impl DbHealthChecker for QueryTracker {
@@ -45,10 +47,15 @@ impl DbHealthChecker for QueryTracker {

        let count_queries = self.query_file_db.len(&rtxn).map_err(Error::DbRead)?;
        let count_histories = self.query_history_db.len(&rtxn).map_err(Error::DbRead)?;
+        let count_grep_histories = self
+            .grep_query_history_db
+            .len(&rtxn)
+            .map_err(Error::DbRead)?;

        Ok(vec![
            ("query_file_entries", count_queries),
            ("query_history_entries", count_histories),
+            ("grep_query_history_entries", count_grep_histories),
        ])
    }
 }
@@ -77,6 +84,9 @@ impl QueryTracker {
        let query_history_db = env
            .create_database(&mut wtxn, Some("query_history"))
            .map_err(Error::DbCreate)?;
+        let grep_query_history_db = env
+            .create_database(&mut wtxn, Some("grep_query_history"))
+            .map_err(Error::DbCreate)?;

        wtxn.commit().map_err(Error::DbCommit)?;

@@ -84,6 +94,7 @@ impl QueryTracker {
            env,
            query_file_db,
            query_history_db,
+            grep_query_history_db,
        })
    }

@@ -115,6 +126,57 @@ impl QueryTracker {
        Ok(*blake3::hash(project_str.as_bytes()).as_bytes())
    }

+    /// Append a query to a history database within an existing write transaction.
+    fn append_to_history(
+        db: &Database<Bytes, SerdeBincode<VecDeque<HistoryEntry>>>,
+        wtxn: &mut heed::RwTxn,
+        project_key: &[u8; 32],
+        query: &str,
+        now: u64,
+    ) -> Result<(), Error> {
+        let mut history = db
+            .get(wtxn, project_key)
+            .map_err(Error::DbRead)?
+            .unwrap_or_default();
+
+        history.push_back(HistoryEntry {
+            query: query.to_string(),
+            timestamp: now,
+        });
+        while history.len() > MAX_HISTORY_ENTRIES {
+            history.pop_front();
+        }
+
+        db.put(wtxn, project_key, &history)
+            .map_err(Error::DbWrite)?;
+        Ok(())
+    }
+
+    /// Read a query from a history database at a specific offset.
+    /// offset=0 returns most recent, offset=1 returns 2nd most recent, etc.
+    fn read_history_at_offset(
+        db: &Database<Bytes, SerdeBincode<VecDeque<HistoryEntry>>>,
+        env: &Env,
+        project_key: &[u8; 32],
+        offset: usize,
+    ) -> Result<Option<String>, Error> {
+        let rtxn = env.read_txn().map_err(Error::DbStartReadTxn)?;
+
+        let mut history = db
+            .get(&rtxn, project_key)
+            .map_err(Error::DbRead)?
+            .unwrap_or_default();
+
+        // history is FIFO, last element is most recent
+        if history.len() > offset {
+            let index = history.len() - 1 - offset;
+            let record = history.remove(index);
+            Ok(record.map(|r| r.query))
+        } else {
+            Ok(None)
+        }
+    }
+
    pub fn track_query_completion(
        &mut self,
        query: &str,
@@ -166,24 +228,7 @@ impl QueryTracker {

        // Update query history database
        let project_key = Self::create_project_key(project_path)?;
-        let mut history = self
-            .query_history_db
-            .get(&wtxn, &project_key)
-            .map_err(Error::DbRead)?
-            .unwrap_or_default();
-
-        let history_entry = HistoryEntry {
-            query: query.to_string(),
-            timestamp: now,
-        };
-        history.push_back(history_entry);
-        while history.len() > MAX_HISTORY_ENTRIES {
-            history.pop_front();
-        }
-
-        self.query_history_db
-            .put(&mut wtxn, &project_key, &history)
-            .map_err(Error::DbWrite)?;
+        Self::append_to_history(&self.query_history_db, &mut wtxn, &project_key, query, now)?;

        wtxn.commit().map_err(Error::DbCommit)?;

@@ -237,32 +282,47 @@ impl QueryTracker {
        }
    }

-    /// Get query from history at a specific offset
+    /// Get query from file picker history at a specific offset.
    /// offset=0 returns most recent query, offset=1 returns 2nd most recent, etc.
-    /// Returns None if offset exceeds history length
    pub fn get_historical_query(
        &self,
        project_path: &Path,
        offset: usize,
    ) -> Result<Option<String>, Error> {
        let project_key = Self::create_project_key(project_path)?;
-        let rtxn = self.env.read_txn().map_err(Error::DbStartReadTxn)?;
+        Self::read_history_at_offset(&self.query_history_db, &self.env, &project_key, offset)
+    }

-        let mut history = self
-            .query_history_db
-            .get(&rtxn, &project_key)
-            .map_err(Error::DbRead)?
-            .unwrap_or_default();
+    /// Track a grep query in the grep-specific history.
+    /// Only records query history (no file association tracking needed for grep).
+    pub fn track_grep_query(&mut self, query: &str, project_path: &Path) -> Result<(), Error> {
+        let now = self.get_now();
+        let project_key = Self::create_project_key(project_path)?;
+        let mut wtxn = self.env.write_txn().map_err(Error::DbStartWriteTxn)?;

-        // history is FIFO, last element is most recent
-        if history.len() > offset {
-            let index = history.len() - 1 - offset;
-            let record = history.remove(index);
+        Self::append_to_history(
+            &self.grep_query_history_db,
+            &mut wtxn,
+            &project_key,
+            query,
+            now,
+        )?;

-            Ok(record.map(|r| r.query))
-        } else {
-            Ok(None)
-        }
+        wtxn.commit().map_err(Error::DbCommit)?;
+
+        tracing::debug!(?query, "Tracked grep query");
+        Ok(())
+    }
+
+    /// Get grep query from history at a specific offset.
+    /// offset=0 returns most recent grep query, offset=1 returns 2nd most recent, etc.
+    pub fn get_historical_grep_query(
+        &self,
+        project_path: &Path,
+        offset: usize,
+    ) -> Result<Option<String>, Error> {
+        let project_key = Self::create_project_key(project_path)?;
+        Self::read_history_at_offset(&self.grep_query_history_db, &self.env, &project_key, offset)
    }
 }

@@ -1,64 +1,195 @@
 use crate::{
+    constraints::apply_constraints,
    git::is_modified_status,
    path_utils::calculate_distance_penalty,
    sort_buffer::{sort_by_key_with_buffer, sort_with_buffer},
    types::{FileItem, Score, ScoringContext},
 };
+use fff_query_parser::FuzzyQuery;
 use neo_frizbee::Scoring;
 use rayon::prelude::*;
 use std::path::MAIN_SEPARATOR;

+// like cow but better
+pub(crate) enum FileItems<'a> {
+    /// All files — borrows the original owned slice, zero allocation.
+    All(&'a [FileItem]),
+    /// Filtered subset — owns references produced by constraint filtering.
+    Filtered(Vec<&'a FileItem>),
+}
+
+impl<'a> FileItems<'a> {
+    #[inline]
+    #[allow(dead_code)]
+    fn len(&self) -> usize {
+        match self {
+            FileItems::All(s) => s.len(),
+            FileItems::Filtered(v) => v.len(),
+        }
+    }
+
+    #[inline]
+    #[allow(dead_code)]
+    fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    #[inline]
+    fn get(&self, index: usize) -> Option<&'a FileItem> {
+        match self {
+            FileItems::All(s) => s.get(index),
+            FileItems::Filtered(v) => v.get(index).copied(),
+        }
+    }
+
+    /// Build the haystack of relative paths (original casing) for fuzzy matching.
+    /// neo_frizbee lowercases internally for comparison but preserves original casing
+    /// for capitalization_bonus and matching_case_bonus scoring.
+    fn relative_paths(&self) -> Vec<&'a str> {
+        match self {
+            FileItems::All(s) => s.iter().map(|f| f.relative_path.as_str()).collect(),
+            FileItems::Filtered(v) => v.iter().map(|f| f.relative_path.as_str()).collect(),
+        }
+    }
+
+    /// Index into the file list. Panics if out of bounds (like slice indexing).
+    #[inline]
+    fn index(&self, index: usize) -> &'a FileItem {
+        match self {
+            FileItems::All(s) => &s[index],
+            FileItems::Filtered(v) => v[index],
+        }
+    }
+}
+
+/// Match files against all fuzzy parts.
+/// Single part: use optimized batch matching.
+/// Multiple parts: each part must match, scores are summed (Nucleo-style).
+/// Parts with less than 2 characters are skipped.
+fn match_fuzzy_parts(
+    fuzzy_parts: &[&str],
+    working_files: &FileItems<'_>,
+    options: &neo_frizbee::Config,
+) -> Vec<neo_frizbee::Match> {
+    if fuzzy_parts.is_empty() {
+        return vec![];
+    }
+
+    let haystack: Vec<&str> = working_files.relative_paths();
+
+    // Filter out parts that are too short (< 2 chars)
+    let valid_parts: Vec<&str> = fuzzy_parts
+        .iter()
+        .copied()
+        .filter(|p| p.len() >= 2)
+        .collect();
+
+    if valid_parts.is_empty() {
+        tracing::debug!("match_fuzzy_parts: no valid parts after filtering, returning empty");
+        return vec![];
+    }
+
+    if valid_parts.len() == 1 {
+        let matches = neo_frizbee::match_list(valid_parts[0], &haystack, options);
+        return matches;
+    }
+
+    // Multiple parts - match first part, then filter by remaining parts
+    // TODO figure out if we can move this logic to my frizbee fork at least
+    let mut matches = neo_frizbee::match_list(valid_parts[0], &haystack, options);
+    for part in valid_parts[1..].iter() {
+        let mut part_options = *options;
+        part_options.max_typos = options.max_typos.map(|t| t.min(part.len() as u16));
+
+        matches = matches
+            .into_iter()
+            .filter_map(|mut m| {
+                let path = haystack.get(m.index as usize)?;
+                let part_matches = neo_frizbee::match_list(part, &[*path], &part_options);
+                let part_match = part_matches.first()?;
+
+                // Sum scores
+                let total = (m.score as u32).saturating_add(part_match.score as u32);
+                m.score = total.min(u16::MAX as u32) as u16;
+                Some(m)
+            })
+            .collect();
+
+        if matches.is_empty() {
+            break;
+        }
+    }
+
+    matches
+}
+
 pub fn match_and_score_files<'a>(
    files: &'a [FileItem],
    context: &ScoringContext,
 ) -> (Vec<&'a FileItem>, Vec<Score>, usize) {
-    if context.query.len() < 2 {
-        return score_all_by_frecency(files, context);
-    }
-
    if files.is_empty() {
        return (vec![], vec![], 0);
    }

-    let has_uppercase_letter = context.query.chars().any(|c| c.is_uppercase());
+    let parsed = &context.parsed_query;
+    let working_files: FileItems<'a> = match parsed.as_ref().and_then(|p| {
+        if p.constraints.is_empty() {
+            None
+        } else {
+            apply_constraints(files, &p.constraints)
+        }
+    }) {
+        Some(filtered) if !filtered.is_empty() => FileItems::Filtered(filtered),
+        Some(_) => {
+            return (vec![], vec![], 0);
+        }
+        None => FileItems::All(files),
+    };
+
+    let query_trimmed: &str = context.raw_query.trim();
+    let single_part_storage: [&str; 1] = [query_trimmed];
+
+    let fuzzy_parts: &[&str] = match parsed {
+        None => {
+            tracing::debug!("STEP 3: Query too short (<2 chars), returning frecency-sorted");
+            if query_trimmed.len() < 2 {
+                return score_filtered_by_frecency(&working_files, context);
+            }
+            &single_part_storage
+        }
+        Some(p) => match &p.fuzzy_query {
+            FuzzyQuery::Text(t) if t.len() >= 2 => std::slice::from_ref(t),
+            FuzzyQuery::Parts(parts) if !parts.is_empty() => parts.as_slice(),
+            _ => {
+                return score_filtered_by_frecency(&working_files, context);
+            }
+        },
+    };
+
+    let has_uppercase = fuzzy_parts
+        .iter()
+        .any(|p| p.chars().any(|c| c.is_uppercase()));
+    let query_contains_path_separator = fuzzy_parts.iter().any(|p| p.contains(MAIN_SEPARATOR));
+
    let options = neo_frizbee::Config {
        prefilter: true,
        max_typos: Some(context.max_typos),
        sort: false,
        scoring: Scoring {
-            capitalization_bonus: if has_uppercase_letter { 8 } else { 0 },
-            matching_case_bonus: if has_uppercase_letter { 4 } else { 0 },
+            capitalization_bonus: if has_uppercase { 8 } else { 0 },
+            matching_case_bonus: if has_uppercase { 4 } else { 0 },
            ..Default::default()
        },
    };

-    let query_contains_path_separator = context.query.contains(MAIN_SEPARATOR);
-    let haystack: Vec<&str> = files
-        .iter()
-        .map(|f| f.relative_path_lower.as_str())
-        .collect();
-    tracing::debug!(
-        "Starting fuzzy search for query '{}' in {} files",
-        context.query,
-        haystack.len()
-    );
-    let path_matches = neo_frizbee::match_list(context.query, &haystack, &options);
-    tracing::debug!(
-        "Matched {} files for query '{}'",
-        path_matches.len(),
-        context.query
-    );
-
-    // assume that filename should only match if the path matches
-    // we should actually incorporate this bonus by getting this information from neo_frizbee directly
-    // instead of spawning a separate matching process, but it's okay for the beta
-    // Use sequential iteration - this is a simple filtering operation that's faster without Rayon overhead
+    let path_matches = match_fuzzy_parts(fuzzy_parts, &working_files, &options);
+    let primary_text = fuzzy_parts[0]; // Use first part for filename matching
    let haystack_of_filenames: Vec<&str> = path_matches
        .iter()
        .filter_map(|m| {
-            files
+            working_files
                .get(m.index as usize)
-                .map(|f| f.file_name_lower.as_str())
+                .map(|f| f.file_name.as_str())
        })
        .collect();

@@ -70,13 +201,13 @@ pub fn match_and_score_files<'a>(
        // Sequential matching is faster for small result sets (< 1000 matches)
        let mut list = if haystack_of_filenames.len() > 1000 {
            neo_frizbee::match_list_parallel(
-                context.query,
+                primary_text,
                &haystack_of_filenames,
                &options,
                context.max_threads,
            )
        } else {
-            neo_frizbee::match_list(context.query, &haystack_of_filenames, &options)
+            neo_frizbee::match_list(primary_text, &haystack_of_filenames, &options)
        };

        // Sequential sort is faster for small lists
@@ -95,7 +226,7 @@ pub fn match_and_score_files<'a>(
        .enumerate()
        .map(|(index, path_match)| {
            let file_idx = path_match.index as usize;
-            let file = &files[file_idx];
+            let file = working_files.index(file_idx);

            let mut base_score = path_match.score as i32;
            let frecency_boost = base_score.saturating_mul(file.total_frecency_score as i32) / 100;
@@ -223,36 +354,39 @@ fn is_special_entry_point_file(filename: &str) -> bool {
    )
 }

-fn score_all_by_frecency<'a>(
-    files: &'a [FileItem],
+/// Score files by frecency when we have a filtered list (prefiltered by constraints)
+pub(crate) fn score_filtered_by_frecency<'a>(
+    files: &FileItems<'a>,
    context: &ScoringContext,
 ) -> (Vec<&'a FileItem>, Vec<Score>, usize) {
-    let results: Vec<_> = files
-        .par_iter()
-        .map(|file| {
-            let total_frecency_score = file.access_frecency_score as i32
-                + (file.modification_frecency_score as i32).saturating_mul(4);
+    let score_file = |file: &'a FileItem| {
+        let total_frecency_score = file.access_frecency_score as i32
+            + (file.modification_frecency_score as i32).saturating_mul(4);

-            let current_file_penalty =
-                calculate_current_file_penalty(file, total_frecency_score, context);
-            let total = total_frecency_score.saturating_add(current_file_penalty);
+        let current_file_penalty =
+            calculate_current_file_penalty(file, total_frecency_score, context);
+        let total = total_frecency_score.saturating_add(current_file_penalty);

-            let score = Score {
-                total,
-                base_score: 0,
-                filename_bonus: 0,
-                distance_penalty: 0,
-                special_filename_bonus: 0,
-                combo_match_boost: 0,
-                current_file_penalty,
-                frecency_boost: total_frecency_score,
-                exact_match: false,
-                match_type: "frecency",
-            };
+        let score = Score {
+            total,
+            base_score: 0,
+            filename_bonus: 0,
+            distance_penalty: 0,
+            special_filename_bonus: 0,
+            combo_match_boost: 0,
+            current_file_penalty,
+            frecency_boost: total_frecency_score,
+            exact_match: false,
+            match_type: "frecency",
+        };

-            (file, score)
-        })
-        .collect();
+        (file, score)
+    };
+
+    let results: Vec<_> = match files {
+        FileItems::All(s) => s.par_iter().map(&score_file).collect(),
+        FileItems::Filtered(v) => v.iter().map(|&file| score_file(file)).collect(),
+    };

    sort_and_paginate(results, context)
 }
@@ -351,19 +485,16 @@ mod tests {
    use std::path::PathBuf;

    fn create_test_file(path: &str, score: i32, modified: u64) -> (FileItem, Score) {
-        let file = FileItem {
-            path: PathBuf::from(path),
-            relative_path: path.to_string(),
-            relative_path_lower: path.to_lowercase(),
-            file_name: path.split('/').last().unwrap_or(path).to_string(),
-            file_name_lower: path.split('/').last().unwrap_or(path).to_lowercase(),
-            size: 0,
+        let file_name = path.split('/').last().unwrap_or(path).to_string();
+        let file = FileItem::new_raw(
+            PathBuf::from(path),
+            path.to_string(),
+            file_name,
+            0,
            modified,
-            access_frecency_score: 0,
-            modification_frecency_score: 0,
-            total_frecency_score: 0,
-            git_status: None,
-        };
+            None,
+            false,
+        );
        let score_obj = Score {
            total: score,
            base_score: score,
@@ -402,7 +533,8 @@ mod tests {
            .collect();

        let context = ScoringContext {
-            query: "test",
+            raw_query: "test",
+            parsed_query: None,
            max_threads: 1,
            max_typos: 2,
            current_file: None,
@@ -450,7 +582,8 @@ mod tests {
            .collect();

        let context = ScoringContext {
-            query: "test",
+            raw_query: "test",
+            parsed_query: None,
            max_threads: 1,
            max_typos: 2,
            current_file: None,
@@ -496,7 +629,8 @@ mod tests {
            .collect();

        let context = ScoringContext {
-            query: "test",
+            raw_query: "test",
+            parsed_query: None,
            max_threads: 1,
            max_typos: 2,
            current_file: None,
@@ -523,3 +657,64 @@ mod tests {
        assert_eq!(items[2].relative_path, "file3.rs");
    }
 }
+
+#[cfg(test)]
+mod multi_part_tests {
+    #[test]
+    fn test_single_path_matching() {
+        let path = "core_workflow_service/kafka_event_consumer/src/ai_part_extraction_request/ai_part_extraction_request_handler.rs";
+
+        // Test with max_typos = 2 (safe for short needles)
+        let options = neo_frizbee::Config {
+            prefilter: true,
+            max_typos: Some(2),
+            sort: false,
+            ..Default::default()
+        };
+
+        // Test "aipart" matching
+        let matches = neo_frizbee::match_list("aipart", &[path], &options);
+        println!("'aipart' matches (max_typos=2): {:?}", matches);
+        assert!(!matches.is_empty(), "'aipart' should match the path");
+
+        // Test "core" matching
+        let matches = neo_frizbee::match_list("core", &[path], &options);
+        println!("'core' matches (max_typos=2): {:?}", matches);
+        assert!(!matches.is_empty(), "'core' should match the path");
+
+        // Test "co" matching - need max_typos <= needle.len()
+        let co_options = neo_frizbee::Config {
+            max_typos: Some(2), // Safe: 2 <= len("co") = 2
+            ..options
+        };
+        let matches = neo_frizbee::match_list("co", &[path], &co_options);
+        println!("'co' matches (max_typos=2): {:?}", matches);
+        assert!(!matches.is_empty(), "'co' should match the path");
+    }
+
+    #[test]
+    fn test_lowercase_path_matching() {
+        // The actual paths are lowercased
+        let path = "core_workflow_service/kafka_event_consumer/src/ai_part_extraction_request/ai_part_extraction_request_handler.rs".to_lowercase();
+
+        let options = neo_frizbee::Config {
+            prefilter: true,
+            max_typos: Some(2),
+            sort: false,
+            ..Default::default()
+        };
+
+        // Test "co" matching on lowercase path
+        let matches = neo_frizbee::match_list("co", &[path.as_str()], &options);
+        println!("'co' matches lowercase path (max_typos=2): {:?}", matches);
+        assert!(!matches.is_empty(), "'co' should match the lowercase path");
+
+        // Test "core" matching on lowercase path
+        let matches = neo_frizbee::match_list("core", &[path.as_str()], &options);
+        println!("'core' matches lowercase path (max_typos=2): {:?}", matches);
+        assert!(
+            !matches.is_empty(),
+            "'core' should match the lowercase path"
+        );
+    }
+}
@@ -0,0 +1,214 @@
+use std::path::{Path, PathBuf};
+use std::sync::OnceLock;
+
+use memmap2::Mmap;
+
+use crate::constraints::Constrainable;
+use crate::query_tracker::QueryMatchEntry;
+use fff_query_parser::{FFFQuery, FuzzyQuery, Location};
+
+/// A single indexed file with metadata, frecency scores, and lazy mmap.
+///
+/// The `mmap` field holds the memory-mapped file contents, initialized lazily
+/// on the first grep access and cached for subsequent searches. The mmap is
+/// backed by the kernel page cache and automatically reflects file modifications
+/// — no manual invalidation is needed.
+///
+/// Thread-safety: `OnceLock` provides lock-free reads after initialization.
+/// Each file is only searched by one rayon worker at a time via `par_iter`.
+#[derive(Debug)]
+pub struct FileItem {
+    pub path: PathBuf,
+    pub relative_path: String,
+    pub relative_path_lower: String,
+    pub file_name: String,
+    pub file_name_lower: String,
+    pub size: u64,
+    pub modified: u64,
+    pub access_frecency_score: i64,
+    pub modification_frecency_score: i64,
+    pub total_frecency_score: i64,
+    pub git_status: Option<git2::Status>,
+    pub is_binary: bool,
+    /// Lazily-initialized memory-mapped file contents for grep.
+    /// Initialized on first grep access via `OnceLock`; lock-free on subsequent reads.
+    /// Automatically reflects file changes via the kernel page cache.
+    mmap: OnceLock<Mmap>,
+}
+
+impl Clone for FileItem {
+    fn clone(&self) -> Self {
+        Self {
+            path: self.path.clone(),
+            relative_path: self.relative_path.clone(),
+            relative_path_lower: self.relative_path_lower.clone(),
+            file_name: self.file_name.clone(),
+            file_name_lower: self.file_name_lower.clone(),
+            size: self.size,
+            modified: self.modified,
+            access_frecency_score: self.access_frecency_score,
+            modification_frecency_score: self.modification_frecency_score,
+            total_frecency_score: self.total_frecency_score,
+            git_status: self.git_status,
+            is_binary: self.is_binary,
+            // Don't clone the mmap — the clone lazily re-creates it on demand
+            mmap: OnceLock::new(),
+        }
+    }
+}
+
+const MAX_MMAP_FILE_SIZE: u64 = 10 * 1024 * 1024;
+
+impl FileItem {
+    /// Create a new `FileItem` with all fields specified and an empty (not yet loaded) mmap.
+    pub fn new_raw(
+        path: PathBuf,
+        relative_path: String,
+        file_name: String,
+        size: u64,
+        modified: u64,
+        git_status: Option<git2::Status>,
+        is_binary: bool,
+    ) -> Self {
+        Self {
+            relative_path_lower: relative_path.to_lowercase(),
+            file_name_lower: file_name.to_lowercase(),
+            path,
+            relative_path,
+            file_name,
+            size,
+            modified,
+            access_frecency_score: 0,
+            modification_frecency_score: 0,
+            total_frecency_score: 0,
+            git_status,
+            is_binary,
+            mmap: OnceLock::new(),
+        }
+    }
+
+    /// Invalidate the cached mmap so the next `get_mmap()` call creates a fresh one.
+    ///
+    /// Call this when the background watcher detects that the file has been modified.
+    /// While the kernel page cache reflects content changes automatically, a file
+    /// that is truncated (made smaller) while mapped can cause SIGBUS if the search
+    /// accesses pages beyond the new file size. Invalidating the mmap ensures a
+    /// fresh mapping with the correct size is created on the next access.
+    pub fn invalidate_mmap(&mut self) {
+        self.mmap = OnceLock::new();
+    }
+
+    /// Get the cached mmap or lazily create it. Returns `None` if the file
+    /// is too large, empty, or can't be opened/mapped.
+    ///
+    /// After the first call, this is lock-free (just an atomic load + pointer deref).
+    /// The mmap is backed by the kernel page cache and automatically reflects
+    /// file modifications — no manual invalidation is needed.
+    #[inline]
+    pub fn get_mmap(&self) -> Option<&Mmap> {
+        if let Some(mmap) = self.mmap.get() {
+            return Some(mmap);
+        }
+
+        if self.size == 0 || self.size > MAX_MMAP_FILE_SIZE {
+            return None;
+        }
+
+        let file = std::fs::File::open(&self.path).ok()?;
+        // SAFETY: The mmap is backed by the kernel page cache and automatically
+        // reflects file modifications. The only risk is SIGBUS if the file is
+        // truncated while mapped
+        let mmap = unsafe { Mmap::map(&file) }.ok()?;
+
+        // If another thread raced us, OnceLock discards our mmap and returns theirs.
+        // This is fine — the duplicate mmap is just dropped.
+        Some(self.mmap.get_or_init(|| mmap))
+    }
+}
+
+impl Constrainable for FileItem {
+    #[inline]
+    fn relative_path(&self) -> &str {
+        &self.relative_path
+    }
+
+    #[inline]
+    fn relative_path_lower(&self) -> &str {
+        &self.relative_path_lower
+    }
+
+    #[inline]
+    fn file_name(&self) -> &str {
+        &self.file_name
+    }
+
+    #[inline]
+    fn git_status(&self) -> Option<git2::Status> {
+        self.git_status
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct Score {
+    pub total: i32,
+    pub base_score: i32,
+    pub filename_bonus: i32,
+    pub special_filename_bonus: i32,
+    pub frecency_boost: i32,
+    pub distance_penalty: i32,
+    pub current_file_penalty: i32,
+    pub combo_match_boost: i32,
+    pub exact_match: bool,
+    pub match_type: &'static str,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub struct PaginationArgs {
+    pub offset: usize,
+    pub limit: usize,
+}
+
+/// Context for scoring files during search.
+///
+/// The `parsed_query` field contains the pre-parsed query with constraints,
+/// fuzzy parts, and location information. Parsing is done once at the API
+/// boundary and passed through.
+#[derive(Debug, Clone)]
+pub struct ScoringContext<'a> {
+    /// The original raw query string (for compatibility and debugging)
+    pub raw_query: &'a str,
+    /// Pre-parsed query containing constraints, fuzzy parts, and location
+    pub parsed_query: Option<FFFQuery<'a>>,
+    pub project_path: Option<&'a Path>,
+    pub current_file: Option<&'a str>,
+    pub max_typos: u16,
+    pub max_threads: usize,
+    pub last_same_query_match: Option<&'a QueryMatchEntry>,
+    pub combo_boost_score_multiplier: i32,
+    pub min_combo_count: u32,
+    pub pagination: PaginationArgs,
+}
+
+impl<'a> ScoringContext<'a> {
+    /// Get the effective fuzzy query string for matching.
+    /// Returns the first fuzzy part, or the raw query if no parsing was done.
+    pub fn effective_query(&self) -> &'a str {
+        match &self.parsed_query {
+            Some(p) => match &p.fuzzy_query {
+                FuzzyQuery::Text(t) => t,
+                FuzzyQuery::Parts(parts) if !parts.is_empty() => parts[0],
+                _ => self.raw_query.trim(),
+            },
+            None => self.raw_query.trim(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct SearchResult<'a> {
+    pub items: Vec<&'a FileItem>,
+    pub scores: Vec<Score>,
+    pub total_matched: usize,
+    pub total_files: usize,
+    pub location: Option<Location>,
+}
@@ -0,0 +1,84 @@
+[package]
+name = "fff-nvim"
+version = "0.1.0"
+edition = "2024"
+
+[lib]
+path = "src/lib.rs"
+crate-type = ["cdylib", "rlib"]
+
+[[bin]]
+name = "test_watcher"
+path = "src/bin/test_watcher.rs"
+
+[[bin]]
+name = "jemalloc_profile"
+path = "src/bin/jemalloc_profile.rs"
+
+[[bin]]
+name = "search_profiler"
+path = "src/bin/search_profiler.rs"
+
+[[bin]]
+name = "bench_search_only"
+path = "src/bin/bench_search_only.rs"
+
+[[bin]]
+name = "grep_profiler"
+path = "src/bin/grep_profiler.rs"
+
+[[bin]]
+name = "grep_vs_rg"
+path = "src/bin/grep_vs_rg.rs"
+
+[dependencies]
+# Workspace dependencies
+ahash = { workspace = true }
+rayon = { workspace = true }
+smallvec = { workspace = true }
+thiserror = { workspace = true }
+tracing = { workspace = true }
+
+# Local crates
+fff-core = { path = "../fff-core" }
+fff-query-parser = { path = "../fff-query-parser" }
+
+# External dependencies
+blake3 = "1.8.2"
+chrono = { version = "0.4", features = ["serde"] }
+ctrlc = "3.4.2"
+dirs = "5.0"
+git2 = { workspace = true }
+glidesort = "0.1"
+heed = "0.22.0"
+ignore = "0.4.22"
+mimalloc = "0.1.47"
+mlua = { version = "0.11.1", features = ["module", "luajit"] }
+neo_frizbee = { workspace = true }
+notify = "8.1.0"
+notify-debouncer-full = "0.6"
+once_cell = "1.20.2"
+pathdiff = "0.2.1"
+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"] }
+rand = { version = "0.8", features = ["small_rng"] }
+tempfile = "3.8"
+
+[[bench]]
+name = "indexing_and_search"
+harness = false
+
+[[bench]]
+name = "query_tracker_bench"
+harness = false
+
+# Platform-specific: Use vendored OpenSSL on non-Windows (Linux, macOS)
+# On Windows, git2 uses the native SChannel TLS backend
+[target.'cfg(not(windows))'.dependencies]
+openssl = { version = "0.10", features = ["vendored"] }
@@ -121,8 +121,7 @@ fn setup_once() -> Result<Vec<fff_nvim::types::FileItem>, String> {
        return Err("./big-repo directory does not exist. Run git clone https://github.com/torvalds/linux.git big-repo".to_string());
    }

-    let canonical_path = big_repo_path
-        .canonicalize()
+    let canonical_path = fff_core::path_utils::canonicalize(&big_repo_path)
        .map_err(|e| format!("Failed to canonicalize path: {}", e))?;
    eprintln!("  Path: {:?}", canonical_path);

@@ -166,7 +165,7 @@ fn bench_indexing(c: &mut Criterion) {
        return;
    }

-    let canonical_path = match big_repo_path.canonicalize() {
+    let canonical_path = match fff_core::path_utils::canonicalize(&big_repo_path) {
        Ok(p) => p,
        Err(e) => {
            eprintln!("⚠ Failed to canonicalize path: {}", e);
@@ -1,5 +1,6 @@
 /// Simple search profiler that directly uses scan_filesystem without background thread overhead
-use fff_nvim::file_picker::FilePicker;
+use fff_core::file_picker::FilePicker;
+use fff_core::{FileItem, FuzzySearchOptions, PaginationArgs, QueryParser};
 use std::time::Instant;

 fn main() {
@@ -12,9 +13,8 @@ fn main() {
        return;
    }

-    let canonical_path = big_repo_path
-        .canonicalize()
-        .expect("Failed to canonicalize path");
+    let canonical_path =
+        fff_core::path_utils::canonicalize(&big_repo_path).expect("Failed to canonicalize path");

    eprintln!("Loading files from: {:?}", canonical_path);

@@ -37,19 +37,15 @@ fn main() {
                let relative_path = relative.to_string_lossy().into_owned();
                let file_name = entry.file_name().to_string_lossy().into_owned();

-                files.push(fff_nvim::types::FileItem {
+                files.push(FileItem::new_raw(
                    path,
-                    relative_path_lower: relative_path.to_lowercase(),
                    relative_path,
-                    file_name_lower: file_name.to_lowercase(),
                    file_name,
-                    size: entry.metadata().ok().map_or(0, |m| m.len()),
-                    modified: 0,
-                    access_frecency_score: 0,
-                    modification_frecency_score: 0,
-                    total_frecency_score: 0,
-                    git_status: None,
-                });
+                    entry.metadata().ok().map_or(0, |m| m.len()),
+                    0,
+                    None,
+                    false,
+                ));
            });

        files
@@ -87,17 +83,20 @@ fn main() {
        let mut match_count = 0;

        for _ in 0..iterations {
+            let parser = QueryParser::default();
+            let parsed = parser.parse(query);
            let results = FilePicker::fuzzy_search(
                &files,
                query,
-                fff_nvim::file_picker::FuzzySearchOptions {
+                parsed,
+                FuzzySearchOptions {
                    max_threads: 4,
                    current_file: None,
                    project_path: None,
                    last_same_query_match: None,
                    combo_boost_score_multiplier: 100,
                    min_combo_count: 3,
-                    pagination: fff_nvim::types::PaginationArgs {
+                    pagination: PaginationArgs {
                        offset: 0,
                        limit: 100,
                    },
@@ -0,0 +1,199 @@
+use fff_core::FileItem;
+/// Fuzzy grep quality test against ~/dev/lightsource
+///
+/// Runs queries through the fuzzy grep pipeline and prints results
+/// so we can verify match quality.
+///
+/// Usage:
+///   cargo run --release --bin fuzzy_grep_test              # runs default test queries
+///   cargo run --release --bin fuzzy_grep_test -- "query"   # runs a single user query
+use fff_core::grep::{GrepMode, GrepSearchOptions, grep_search, parse_grep_query};
+use std::io::Read;
+use std::path::Path;
+use std::time::Instant;
+
+fn load_files(base_path: &Path) -> Vec<FileItem> {
+    use ignore::WalkBuilder;
+
+    let mut files = Vec::new();
+
+    WalkBuilder::new(base_path)
+        .hidden(false)
+        .git_ignore(true)
+        .git_exclude(true)
+        .git_global(true)
+        .ignore(true)
+        .follow_links(false)
+        .build()
+        .filter_map(|e| e.ok())
+        .filter(|e| e.file_type().is_some_and(|ft| ft.is_file()))
+        .for_each(|entry| {
+            let path = entry.path().to_path_buf();
+            let relative = pathdiff::diff_paths(&path, base_path).unwrap_or_else(|| path.clone());
+            let relative_path = relative.to_string_lossy().into_owned();
+            let file_name = entry.file_name().to_string_lossy().into_owned();
+            let size = entry.metadata().ok().map_or(0, |m| m.len());
+            let is_binary = detect_binary(&path, size);
+
+            files.push(FileItem::new_raw(
+                path,
+                relative_path,
+                file_name,
+                size,
+                0,
+                None,
+                is_binary,
+            ));
+        });
+
+    files
+}
+
+fn detect_binary(path: &Path, size: u64) -> bool {
+    if size == 0 {
+        return false;
+    }
+    let Ok(file) = std::fs::File::open(path) else {
+        return false;
+    };
+    let mut reader = std::io::BufReader::with_capacity(1024, file);
+    let mut buf = [0u8; 512];
+    let n = reader.read(&mut buf).unwrap_or(0);
+    buf[..n].contains(&0)
+}
+
+fn run_fuzzy_query(files: &[FileItem], query: &str, label: &str) {
+    let options = GrepSearchOptions {
+        max_file_size: 10 * 1024 * 1024,
+        max_matches_per_file: 200,
+        smart_case: true,
+        file_offset: 0,
+        page_limit: 100, // Get plenty of results
+        mode: GrepMode::Fuzzy,
+        time_budget_ms: 0, // No time limit — search all files
+    };
+
+    let parsed = parse_grep_query(query);
+    let start = Instant::now();
+    let result = grep_search(files, query, parsed, &options);
+    let elapsed = start.elapsed();
+
+    eprintln!("══════════════════════════════════════════════════════════════");
+    eprintln!("  Query: \"{}\"  ({})", query, label);
+    eprintln!(
+        "  Results: {} matches in {} files ({:.2}ms)",
+        result.matches.len(),
+        result.total_files_searched,
+        elapsed.as_secs_f64() * 1000.0,
+    );
+    eprintln!("══════════════════════════════════════════════════════════════");
+
+    if result.matches.is_empty() {
+        eprintln!("  (no matches)\n");
+        return;
+    }
+
+    // Group by file for readability
+    let mut current_file_idx = usize::MAX;
+    for (i, m) in result.matches.iter().enumerate() {
+        if m.file_index != current_file_idx {
+            current_file_idx = m.file_index;
+            let file = &result.files[m.file_index];
+            eprintln!("\n  ┌─ {}", file.relative_path);
+        }
+
+        // Truncate long lines for display
+        let display_line = if m.line_content.len() > 100 {
+            format!("{}...", &m.line_content[..100])
+        } else {
+            m.line_content.clone()
+        };
+
+        let score_str = m
+            .fuzzy_score
+            .map(|s| format!("score={}", s))
+            .unwrap_or_else(|| "no-score".to_string());
+
+        let offsets_str = if m.match_byte_offsets.is_empty() {
+            String::new()
+        } else {
+            // Show what text fragments are highlighted
+            let fragments: Vec<String> = m
+                .match_byte_offsets
+                .iter()
+                .filter_map(|&(s, e)| {
+                    m.line_content
+                        .get(s as usize..e as usize)
+                        .map(|frag| format!("\"{}\"", frag))
+                })
+                .collect();
+            format!(" hl=[{}]", fragments.join(","))
+        };
+
+        eprintln!(
+            "  │ L{:<5} [{}{}] {}",
+            m.line_number,
+            score_str,
+            offsets_str,
+            display_line.trim(),
+        );
+
+        // Cap output at 50 lines
+        if i >= 49 {
+            let remaining = result.matches.len() - 50;
+            if remaining > 0 {
+                eprintln!("  │ ... and {} more matches", remaining);
+            }
+            break;
+        }
+    }
+    eprintln!();
+}
+
+fn main() {
+    let args: Vec<String> = std::env::args().skip(1).collect();
+
+    let repo_path = std::path::PathBuf::from(
+        std::env::var("HOME").unwrap_or_else(|_| "/Users/neogoose".to_string()),
+    )
+    .join("dev/lightsource");
+
+    if !repo_path.exists() {
+        eprintln!("Repository not found at: {:?}", repo_path);
+        std::process::exit(1);
+    }
+
+    let canonical =
+        fff_core::path_utils::canonicalize(&repo_path).expect("Failed to canonicalize path");
+    eprintln!("=== Fuzzy Grep Quality Test ===");
+    eprintln!("Repository: {:?}\n", canonical);
+
+    eprintln!("Loading files...");
+    let load_start = Instant::now();
+    let files = load_files(&canonical);
+    let non_binary = files.iter().filter(|f| !f.is_binary).count();
+    eprintln!(
+        "Loaded {} files ({} non-binary) in {:.2}s\n",
+        files.len(),
+        non_binary,
+        load_start.elapsed().as_secs_f64()
+    );
+
+    if args.is_empty() {
+        // Run default test queries
+        run_fuzzy_query(&files, "shcema", "transposition of 'schema'");
+        run_fuzzy_query(&files, "SortedMap", "should match SortedArrayMap");
+        run_fuzzy_query(
+            &files,
+            "struct SortedMap",
+            "should NOT match SourcingProjectMetadataParts",
+        );
+    } else {
+        // Run user-provided queries
+        for query in &args {
+            run_fuzzy_query(&files, query, "user query");
+        }
+    }
+
+    eprintln!("=== Done ===");
+}
@@ -0,0 +1,402 @@
+use fff_core::FileItem;
+/// Live grep benchmark profiler for fff.nvim
+///
+/// Benchmarks the full grep pipeline against a large repository (Linux kernel).
+/// Measures cold-cache, warm-cache, and incremental typing latencies to simulate
+/// real user interaction patterns.
+///
+/// Uses direct WalkBuilder scanning (no background thread) for faster startup.
+///
+/// Usage:
+///   cargo build --release --bin grep_profiler
+///   ./target/release/grep_profiler [--path /path/to/repo]
+use fff_core::grep::{GrepSearchOptions, grep_search, parse_grep_query};
+use std::io::Read;
+use std::path::Path;
+use std::time::{Duration, Instant};
+
+fn load_files(base_path: &Path) -> Vec<FileItem> {
+    use ignore::WalkBuilder;
+
+    let mut files = Vec::new();
+
+    WalkBuilder::new(base_path)
+        .hidden(false)
+        .git_ignore(true)
+        .git_exclude(true)
+        .git_global(true)
+        .ignore(true)
+        .follow_links(false)
+        .build()
+        .filter_map(|e| e.ok())
+        .filter(|e| e.file_type().is_some_and(|ft| ft.is_file()))
+        .for_each(|entry| {
+            let path = entry.path().to_path_buf();
+            let relative = pathdiff::diff_paths(&path, base_path).unwrap_or_else(|| path.clone());
+            let relative_path = relative.to_string_lossy().into_owned();
+            let file_name = entry.file_name().to_string_lossy().into_owned();
+            let size = entry.metadata().ok().map_or(0, |m| m.len());
+            let is_binary = detect_binary(&path, size);
+
+            files.push(FileItem::new_raw(
+                path,
+                relative_path,
+                file_name,
+                size,
+                0,
+                None,
+                is_binary,
+            ));
+        });
+
+    files
+}
+
+fn detect_binary(path: &Path, size: u64) -> bool {
+    if size == 0 {
+        return false;
+    }
+    let Ok(file) = std::fs::File::open(path) else {
+        return false;
+    };
+    let mut reader = std::io::BufReader::with_capacity(1024, file);
+    let mut buf = [0u8; 512];
+    let n = reader.read(&mut buf).unwrap_or(0);
+    buf[..n].contains(&0)
+}
+
+struct BenchStats {
+    times: Vec<Duration>,
+}
+
+impl BenchStats {
+    fn new() -> Self {
+        Self { times: Vec::new() }
+    }
+
+    fn push(&mut self, d: Duration) {
+        self.times.push(d);
+    }
+
+    fn mean(&self) -> Duration {
+        let total: Duration = self.times.iter().sum();
+        total / self.times.len() as u32
+    }
+
+    fn median(&self) -> Duration {
+        let mut sorted = self.times.clone();
+        sorted.sort();
+        sorted[sorted.len() / 2]
+    }
+
+    fn p95(&self) -> Duration {
+        let mut sorted = self.times.clone();
+        sorted.sort();
+        let idx = ((sorted.len() as f64) * 0.95) as usize;
+        sorted[idx.min(sorted.len() - 1)]
+    }
+
+    fn p99(&self) -> Duration {
+        let mut sorted = self.times.clone();
+        sorted.sort();
+        let idx = ((sorted.len() as f64) * 0.99) as usize;
+        sorted[idx.min(sorted.len() - 1)]
+    }
+
+    fn min(&self) -> Duration {
+        *self.times.iter().min().unwrap()
+    }
+
+    fn max(&self) -> Duration {
+        *self.times.iter().max().unwrap()
+    }
+}
+
+struct GrepBench<'a> {
+    files: &'a [FileItem],
+    options: GrepSearchOptions,
+}
+
+impl<'a> GrepBench<'a> {
+    fn new(files: &'a [FileItem]) -> Self {
+        Self {
+            files,
+            options: GrepSearchOptions {
+                max_file_size: 10 * 1024 * 1024,
+                max_matches_per_file: 200,
+                smart_case: true,
+                file_offset: 0,
+                page_limit: 50,
+                mode: Default::default(),
+                time_budget_ms: 0,
+            },
+        }
+    }
+
+    /// Run a single grep search, return (duration, match_count, files_searched)
+    fn run_once(&self, query: &str) -> (Duration, usize, usize) {
+        let parsed = parse_grep_query(query);
+        let start = Instant::now();
+        let result = grep_search(self.files, query, parsed, &self.options);
+        let elapsed = start.elapsed();
+        (
+            elapsed,
+            result.total_match_count,
+            result.total_files_searched,
+        )
+    }
+
+    /// Benchmark a query with multiple iterations
+    fn bench_query(&self, query: &str, iterations: usize) -> (BenchStats, usize, usize) {
+        let mut stats = BenchStats::new();
+        let mut last_matches = 0;
+        let mut last_files_searched = 0;
+
+        for _ in 0..iterations {
+            let (elapsed, matches, files_searched) = self.run_once(query);
+            stats.push(elapsed);
+            last_matches = matches;
+            last_files_searched = files_searched;
+        }
+
+        (stats, last_matches, last_files_searched)
+    }
+}
+
+fn fmt_dur(d: Duration) -> String {
+    let us = d.as_micros();
+    if us > 1_000_000 {
+        format!("{:.2}s", d.as_secs_f64())
+    } else if us > 1000 {
+        format!("{:.2}ms", us as f64 / 1000.0)
+    } else {
+        format!("{}us", us)
+    }
+}
+
+fn print_row(name: &str, stats: &BenchStats, matches: usize, files_searched: usize, iters: usize) {
+    eprintln!(
+        "  {:<24} | {:>8} | {:>8} | {:>8} | {:>8} | {:>8} | {:>8} | {:>6} | {:>6} | {:>4}",
+        name,
+        fmt_dur(stats.mean()),
+        fmt_dur(stats.median()),
+        fmt_dur(stats.p95()),
+        fmt_dur(stats.p99()),
+        fmt_dur(stats.min()),
+        fmt_dur(stats.max()),
+        matches,
+        files_searched,
+        iters,
+    );
+}
+
+fn print_header() {
+    eprintln!(
+        "  {:<24} | {:>8} | {:>8} | {:>8} | {:>8} | {:>8} | {:>8} | {:>6} | {:>6} | {:>4}",
+        "Name", "Mean", "Median", "P95", "P99", "Min", "Max", "Match", "Files", "Iter"
+    );
+    eprintln!(
+        "  {:-<24}-+-{:-<8}-+-{:-<8}-+-{:-<8}-+-{:-<8}-+-{:-<8}-+-{:-<8}-+-{:-<6}-+-{:-<6}-+-{:-<4}",
+        "", "", "", "", "", "", "", "", "", ""
+    );
+}
+
+fn main() {
+    // Parse args
+    let args: Vec<String> = std::env::args().collect();
+    let repo_path = if let Some(idx) = args.iter().position(|a| a == "--path") {
+        args.get(idx + 1)
+            .map(|s| s.as_str())
+            .unwrap_or("./big-repo")
+    } else {
+        "./big-repo"
+    };
+
+    let repo = std::path::PathBuf::from(repo_path);
+    if !repo.exists() {
+        eprintln!("Repository not found at: {}", repo_path);
+        eprintln!("Usage: grep_profiler [--path /path/to/large/repo]");
+        std::process::exit(1);
+    }
+
+    let canonical = fff_core::path_utils::canonicalize(&repo).expect("Failed to canonicalize path");
+    eprintln!("=== FFF Live Grep Profiler ===");
+    eprintln!("Repository: {:?}", canonical);
+
+    // Direct file loading (no background thread)
+    eprintln!("\n[1/5] Loading files...");
+    let load_start = Instant::now();
+    let files = load_files(&canonical);
+    let load_time = load_start.elapsed();
+    let non_binary = files.iter().filter(|f| !f.is_binary).count();
+    let large_files = files.iter().filter(|f| f.size > 10 * 1024 * 1024).count();
+    eprintln!(
+        "  Loaded {} files in {:.2}s ({} non-binary, {} >10MB skipped)\n",
+        files.len(),
+        load_time.as_secs_f64(),
+        non_binary,
+        large_files,
+    );
+
+    let bench = GrepBench::new(&files);
+
+    eprintln!("[2/5] Cold cache benchmarks (first search, mmap not yet loaded)");
+    eprintln!("  Each query runs once with fresh FileItem mmaps.\n");
+    print_header();
+
+    let cold_queries: Vec<(&str, &str)> = vec![
+        ("cold_common_2char", "if"),
+        ("cold_common_word", "return"),
+        ("cold_specific_func", "mutex_lock"),
+        ("cold_struct_name", "inode_operations"),
+        ("cold_define", "MODULE_LICENSE"),
+        ("cold_rare_string", "phylink_ethtool"),
+        ("cold_path_filter", "printk *.c"),
+        ("cold_long_query", "static int __init"),
+    ];
+
+    for (name, query) in &cold_queries {
+        // Re-load files to get fresh FileItems with no cached mmaps
+        let fresh_files = load_files(&canonical);
+        let fresh_bench = GrepBench::new(&fresh_files);
+        let (stats, matches, files_searched) = fresh_bench.bench_query(query, 1);
+        print_row(name, &stats, matches, files_searched, 1);
+    }
+
+    eprintln!("\n[3/5] Warm cache benchmarks (mmap cache populated)");
+    eprintln!("  Running 3 warmup iterations, then measuring.\n");
+    print_header();
+
+    let warm_queries: Vec<(&str, &str, usize)> = vec![
+        ("warm_2char", "if", 10),
+        ("warm_common_word", "return", 10),
+        ("warm_function_call", "mutex_lock", 15),
+        ("warm_struct_name", "inode_operations", 15),
+        ("warm_define", "MODULE_LICENSE", 15),
+        ("warm_rare_string", "phylink_ethtool", 20),
+        ("warm_include", "#include", 10),
+        ("warm_comment", "TODO", 15),
+        ("warm_type_decl", "struct file", 15),
+        ("warm_error_path", "err = -EINVAL", 15),
+        ("warm_long_pattern", "static int __init", 15),
+        ("warm_very_common", "int", 10),
+        ("warm_single_char", "x", 10),
+        ("warm_path_constraint", "printk *.c", 15),
+        ("warm_dir_constraint", "mutex /kernel/", 15),
+    ];
+
+    // Warmup pass - populate mmap cache
+    for (_, query, _) in &warm_queries {
+        for _ in 0..3 {
+            bench.run_once(query);
+        }
+    }
+
+    for (name, query, iters) in &warm_queries {
+        let (stats, matches, files_searched) = bench.bench_query(query, *iters);
+        print_row(name, &stats, matches, files_searched, *iters);
+    }
+
+    eprintln!("\n[4/5] Incremental typing simulation");
+    eprintln!("  Simulates user typing character by character.\n");
+
+    let typing_sequences: Vec<(&str, Vec<&str>)> = vec![
+        (
+            "mutex_lock",
+            vec![
+                "m",
+                "mu",
+                "mut",
+                "mute",
+                "mutex",
+                "mutex_",
+                "mutex_l",
+                "mutex_lo",
+                "mutex_loc",
+                "mutex_lock",
+            ],
+        ),
+        ("printk", vec!["p", "pr", "pri", "prin", "print", "printk"]),
+        ("inode", vec!["i", "in", "ino", "inod", "inode"]),
+        ("kfree", vec!["k", "kf", "kfr", "kfre", "kfree"]),
+    ];
+
+    for (name, sequence) in &typing_sequences {
+        eprintln!("  Typing '{}' ({} keystrokes):", name, sequence.len());
+        eprintln!(
+            "    {:>16} | {:>8} | {:>6} | {:>6}",
+            "Query", "Latency", "Match", "Files"
+        );
+        eprintln!("    {:-<16}-+-{:-<8}-+-{:-<6}-+-{:-<6}", "", "", "", "");
+
+        for prefix in sequence {
+            let (elapsed, matches, files_searched) = bench.run_once(prefix);
+            eprintln!(
+                "    {:>16} | {:>8} | {:>6} | {:>6}",
+                format!("\"{}\"", prefix),
+                fmt_dur(elapsed),
+                matches,
+                files_searched,
+            );
+        }
+        eprintln!();
+    }
+
+    eprintln!("[5/5] Pagination benchmark");
+    eprintln!("  Testing page_offset performance for common query.\n");
+
+    let pagination_query = "return";
+    eprintln!("  Query: \"{}\"", pagination_query);
+    eprintln!(
+        "    {:>6} | {:>12} | {:>8} | {:>6} | {:>12}",
+        "Page", "File offset", "Latency", "Matches", "Next offset"
+    );
+    eprintln!(
+        "    {:-<6}-+-{:-<12}-+-{:-<8}-+-{:-<6}-+-{:-<12}",
+        "", "", "", "", ""
+    );
+
+    let mut file_offset = 0usize;
+    for page in 0..10 {
+        let parsed = parse_grep_query(pagination_query);
+        let opts = GrepSearchOptions {
+            max_file_size: 10 * 1024 * 1024,
+            max_matches_per_file: 200,
+            smart_case: true,
+            file_offset,
+            page_limit: 50,
+            mode: Default::default(),
+            time_budget_ms: 0,
+        };
+        let start = Instant::now();
+        let result = grep_search(&files, pagination_query, parsed, &opts);
+        let elapsed = start.elapsed();
+        eprintln!(
+            "    {:>6} | {:>12} | {:>8} | {:>6} | {:>12}",
+            page,
+            file_offset,
+            fmt_dur(elapsed),
+            result.matches.len(),
+            result.next_file_offset,
+        );
+
+        if result.next_file_offset == 0 || result.matches.is_empty() {
+            eprintln!("    (no more results)");
+            break;
+        }
+        file_offset = result.next_file_offset;
+    }
+
+    eprintln!("\n=== Summary ===");
+    let mmap_count = files.iter().filter(|f| f.get_mmap().is_some()).count();
+    eprintln!("  Files with cached mmap: {}", mmap_count);
+    eprintln!("  Total indexed files: {}", files.len());
+    eprintln!("  Non-binary files: {}", non_binary);
+    eprintln!("  Files > 10MB (skipped): {}", large_files);
+
+    std::thread::sleep(Duration::from_millis(100));
+
+    eprintln!("\nDone. For perf profiling:");
+    eprintln!("  perf record -g --call-graph dwarf -F 999 ./target/release/grep_profiler");
+    eprintln!("  perf report --no-children");
+}
@@ -0,0 +1,471 @@
+use fff_core::FileItem;
+/// FFF vs ripgrep comparison benchmark
+///
+/// Demonstrates why a persistent in-process search engine (fff) is fundamentally
+/// faster than shelling out to ripgrep on every keystroke (telescope/fzf-lua).
+///
+/// Each query is run N iterations to show the real-world advantage:
+/// - fff: pre-indexed files + cached mmaps = near-zero overhead per search
+/// - rg:  fork/exec + directory traversal + gitignore parsing + file opens per invocation
+///
+/// Sections:
+///   1. Raw engine speed — fff count-only vs rg --count-matches (N iterations)
+///   2. Full results     — fff collect-all vs rg full line output (N iterations)
+///   3. First-page       — fff paginated (50 results) vs rg telescope-style
+///      (spawn, stream 50 lines, kill) — the real UI scenario (N iterations)
+///
+/// The rg commands use telescope's default vimgrep_arguments:
+///   rg --color=never --no-heading --with-filename --line-number --column --smart-case
+///
+/// Usage:
+///   cargo build --release --bin grep_vs_rg
+///   ./target/release/grep_vs_rg [--path /path/to/repo] [--iters 5]
+use fff_core::grep::{GrepSearchOptions, grep_search, parse_grep_query};
+use std::io::Read;
+use std::path::Path;
+use std::process::Command;
+use std::time::{Duration, Instant};
+
+/// Number of times each query is repeated (overridable with --iters).
+const DEFAULT_ITERS: usize = 5;
+
+fn load_files(base_path: &Path) -> Vec<FileItem> {
+    use ignore::WalkBuilder;
+
+    let mut files = Vec::new();
+    WalkBuilder::new(base_path)
+        .hidden(false)
+        .git_ignore(true)
+        .git_exclude(true)
+        .git_global(true)
+        .ignore(true)
+        .follow_links(false)
+        .build()
+        .filter_map(|e| e.ok())
+        .filter(|e| e.file_type().is_some_and(|ft| ft.is_file()))
+        .for_each(|entry| {
+            let path = entry.path().to_path_buf();
+            let relative = pathdiff::diff_paths(&path, base_path).unwrap_or_else(|| path.clone());
+            let relative_path = relative.to_string_lossy().into_owned();
+            let file_name = entry.file_name().to_string_lossy().into_owned();
+            let size = entry.metadata().ok().map_or(0, |m| m.len());
+            let is_binary = detect_binary(&path, size);
+
+            files.push(FileItem::new_raw(
+                path,
+                relative_path,
+                file_name,
+                size,
+                0,
+                None,
+                is_binary,
+            ));
+        });
+    files
+}
+
+fn detect_binary(path: &Path, size: u64) -> bool {
+    if size == 0 {
+        return false;
+    }
+    let Ok(file) = std::fs::File::open(path) else {
+        return false;
+    };
+    let mut reader = std::io::BufReader::with_capacity(1024, file);
+    let mut buf = [0u8; 512];
+    let n = reader.read(&mut buf).unwrap_or(0);
+    buf[..n].contains(&0)
+}
+
+/// Telescope's default vimgrep_arguments applied to any rg command.
+/// Also limits rg's thread count to match rayon's pool (fair comparison).
+fn apply_telescope_args(cmd: &mut Command, threads: usize) {
+    cmd.arg("--color=never")
+        .arg("--no-heading")
+        .arg("--with-filename")
+        .arg("--line-number")
+        .arg("--column")
+        .arg("--smart-case")
+        .arg("--fixed-strings")
+        .arg("--max-filesize")
+        .arg("10M")
+        .arg("--threads")
+        .arg(threads.to_string());
+}
+
+/// Run ripgrep counting matches via --count-matches.
+fn run_rg_count(
+    repo_path: &Path,
+    pattern: &str,
+    case_insensitive: bool,
+    threads: usize,
+) -> (usize, Duration) {
+    let start = Instant::now();
+    let mut cmd = Command::new("rg");
+    cmd.arg("--count-matches").arg("--no-filename");
+    apply_telescope_args(&mut cmd, threads);
+    if case_insensitive {
+        cmd.arg("--ignore-case");
+    }
+    cmd.arg(pattern).current_dir(repo_path);
+
+    let output = cmd.output().expect("Failed to run rg");
+    let elapsed = start.elapsed();
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let count: usize = stdout
+        .lines()
+        .filter_map(|l| l.trim().parse::<usize>().ok())
+        .sum();
+    (count, elapsed)
+}
+
+/// Run ripgrep collecting full line output.
+fn run_rg_lines(
+    repo_path: &Path,
+    pattern: &str,
+    case_insensitive: bool,
+    threads: usize,
+) -> (usize, Duration) {
+    let start = Instant::now();
+    let mut cmd = Command::new("rg");
+    apply_telescope_args(&mut cmd, threads);
+    if case_insensitive {
+        cmd.arg("--ignore-case");
+    }
+    cmd.arg(pattern).current_dir(repo_path);
+
+    let output = cmd.output().expect("Failed to run rg");
+    let elapsed = start.elapsed();
+    let count = bytecount(&output.stdout, b'\n');
+    (count, elapsed)
+}
+
+/// Run ripgrep the way telescope/fzf-lua actually do it: spawn rg as a
+/// streaming subprocess, read stdout line-by-line, and kill the process
+/// after `limit` lines. This is the realistic "first page" scenario.
+fn run_rg_page(
+    repo_path: &Path,
+    pattern: &str,
+    case_insensitive: bool,
+    limit: usize,
+    threads: usize,
+) -> (usize, Duration) {
+    use std::io::{BufRead, BufReader};
+    use std::process::Stdio;
+
+    let start = Instant::now();
+    let mut rg_cmd = Command::new("rg");
+    apply_telescope_args(&mut rg_cmd, threads);
+    if case_insensitive {
+        rg_cmd.arg("--ignore-case");
+    }
+    rg_cmd
+        .arg(pattern)
+        .current_dir(repo_path)
+        .stdout(Stdio::piped())
+        .stderr(Stdio::null());
+
+    let mut child = rg_cmd.spawn().expect("Failed to spawn rg");
+    let stdout = child.stdout.take().expect("Failed to get rg stdout");
+    let reader = BufReader::new(stdout);
+
+    let mut count = 0;
+    for _line in reader.lines() {
+        if _line.is_err() {
+            break;
+        }
+        count += 1;
+        if count >= limit {
+            break;
+        }
+    }
+
+    // Kill rg immediately — this is what telescope does when the picker
+    // closes or the query changes (plenary.job:shutdown).
+    let _ = child.kill();
+    let _ = child.wait();
+    let elapsed = start.elapsed();
+
+    (count, elapsed)
+}
+
+fn bytecount(bytes: &[u8], needle: u8) -> usize {
+    bytes.iter().filter(|&&b| b == needle).count()
+}
+
+/// fff full: collects all GrepMatch structs (what the UI uses).
+fn run_fff_full(files: &[FileItem], query: &str) -> (usize, Duration) {
+    let parsed = parse_grep_query(query);
+    let options = GrepSearchOptions {
+        max_file_size: 10 * 1024 * 1024,
+        max_matches_per_file: usize::MAX,
+        smart_case: true,
+        file_offset: 0,
+        page_limit: usize::MAX,
+        mode: Default::default(),
+        time_budget_ms: 0,
+    };
+    let start = Instant::now();
+    let result = grep_search(files, query, parsed, &options);
+    let elapsed = start.elapsed();
+    (result.total_match_count, elapsed)
+}
+
+/// fff paginated: first 50 results only (real UI scenario).
+fn run_fff_page(files: &[FileItem], query: &str) -> (usize, Duration) {
+    let parsed = parse_grep_query(query);
+    let options = GrepSearchOptions {
+        max_file_size: 10 * 1024 * 1024,
+        max_matches_per_file: 200,
+        smart_case: true,
+        file_offset: 0,
+        page_limit: 50,
+        mode: Default::default(),
+        time_budget_ms: 0,
+    };
+    let start = Instant::now();
+    let result = grep_search(files, query, parsed, &options);
+    let elapsed = start.elapsed();
+    // Use matches.len() — the actual truncated page the UI would display,
+    // not total_match_count which includes overshoot from parallel batches.
+    (result.matches.len(), elapsed)
+}
+
+#[allow(dead_code)]
+struct IterStats {
+    min: Duration,
+    avg: Duration,
+    count: usize,
+}
+
+fn run_n<F: Fn() -> (usize, Duration)>(f: F, n: usize) -> IterStats {
+    let mut times = Vec::with_capacity(n);
+    let mut count = 0;
+    for _ in 0..n {
+        let (c, d) = f();
+        count = c;
+        times.push(d);
+    }
+    times.sort();
+    let min = times[0];
+    let avg = times.iter().sum::<Duration>() / n as u32;
+    IterStats { min, avg, count }
+}
+
+fn fmt_dur(d: Duration) -> String {
+    let us = d.as_micros();
+    if us > 1_000_000 {
+        format!("{:.2}s", d.as_secs_f64())
+    } else if us > 1000 {
+        format!("{:.1}ms", us as f64 / 1000.0)
+    } else {
+        format!("{}us", us)
+    }
+}
+
+fn ratio_str(a: Duration, b: Duration) -> String {
+    if a.is_zero() || b.is_zero() {
+        return "-".to_string();
+    }
+    let r = b.as_secs_f64() / a.as_secs_f64();
+    format!("{:.1}x", r)
+}
+
+fn main() {
+    let args: Vec<String> = std::env::args().collect();
+    let repo_path = if let Some(idx) = args.iter().position(|a| a == "--path") {
+        args.get(idx + 1)
+            .map(|s| s.as_str())
+            .unwrap_or("./big-repo")
+    } else {
+        "./big-repo"
+    };
+    let iters = if let Some(idx) = args.iter().position(|a| a == "--iters") {
+        args.get(idx + 1)
+            .and_then(|s| s.parse().ok())
+            .unwrap_or(DEFAULT_ITERS)
+    } else {
+        DEFAULT_ITERS
+    };
+
+    let repo = std::path::PathBuf::from(repo_path);
+    if !repo.exists() {
+        eprintln!("Repository not found at: {}", repo_path);
+        std::process::exit(1);
+    }
+
+    let canonical = fff_core::path_utils::canonicalize(&repo).expect("Failed to canonicalize path");
+
+    let rg_version = Command::new("rg")
+        .arg("--version")
+        .output()
+        .expect("ripgrep (rg) not found in PATH");
+    let rg_ver = String::from_utf8_lossy(&rg_version.stdout);
+
+    // Match rg's thread count to rayon's (both default to logical CPU count).
+    let threads = std::thread::available_parallelism()
+        .map(|n| n.get())
+        .unwrap_or(4);
+
+    eprintln!("=== FFF vs ripgrep (telescope-style) ===");
+    eprintln!("Repo:       {:?}", canonical);
+    eprintln!("rg:         {}", rg_ver.lines().next().unwrap_or("?"));
+    eprintln!("Threads:    {} (rg -j{} = rayon default)", threads, threads);
+    eprintln!("Iterations: {} per query", iters);
+    eprintln!();
+
+    eprintln!("[1/5] Indexing files...");
+    let files = load_files(&canonical);
+    let non_binary = files.iter().filter(|f| !f.is_binary).count();
+    eprintln!("  {} files ({} searchable)\n", files.len(), non_binary);
+
+    eprintln!("[2/5] Warming caches (fff mmap + OS page cache)...");
+    for q in &["return", "mutex", "struct", "include", "if", "int"] {
+        let _ = run_fff_page(&files, q);
+        let _ = run_rg_count(&canonical, q, true, threads);
+    }
+    eprintln!("  mmap cache: warmed\n");
+
+    // (name, query, case_insensitive_for_rg)
+    let queries: Vec<(&str, &str, bool)> = vec![
+        ("single_char", "x", true),
+        ("short_common", "if", true),
+        ("very_common", "int", true),
+        ("common_keyword", "return", true),
+        ("preprocessor", "#include", true),
+        ("function_call", "mutex_lock", true),
+        ("multi_word", "static int __init", true),
+        ("type_decl", "struct file", true),
+        ("macro_define", "MODULE_LICENSE", false),
+        ("kernel_api", "EXPORT_SYMBOL", false),
+        ("error_path", "err = -EINVAL", false),
+        ("comment_tag", "TODO", false),
+        ("struct_name", "inode_operations", true),
+        ("rare_symbol", "phylink_ethtool", true),
+        ("long_literal", "This program is free software", true),
+    ];
+
+    eprintln!(
+        "\n[4/5] Full results: fff (collect all) vs rg (full line output) ({} iters, showing min)\n",
+        iters
+    );
+    eprintln!(
+        "  {:<22} | {:>9} {:>10} | {:>9} {:>10} | {:>7}",
+        "Query", "fff min", "count", "rg min", "count", "fff/rg"
+    );
+    eprintln!(
+        "  {:-<22}-+-{:-<9}-{:-<10}-+-{:-<9}-{:-<10}-+-{:-<7}",
+        "", "", "", "", "", ""
+    );
+
+    let mut fff_full_total = Duration::ZERO;
+    let mut rg_full_total = Duration::ZERO;
+
+    for (name, query, ci) in &queries {
+        let q = *query;
+        let ci = *ci;
+        let fs = run_n(|| run_fff_full(&files, q), iters);
+        let rs = run_n(|| run_rg_lines(&canonical, q, ci, threads), iters);
+
+        eprintln!(
+            "  {:<22} | {:>9} {:>10} | {:>9} {:>10} | {:>7}",
+            name,
+            fmt_dur(fs.min),
+            fs.count,
+            fmt_dur(rs.min),
+            rs.count,
+            ratio_str(fs.min, rs.min),
+        );
+
+        fff_full_total += fs.min;
+        rg_full_total += rs.min;
+    }
+
+    eprintln!(
+        "  {:<22} | {:>9} {:>10} | {:>9} {:>10} | {:>7}",
+        "TOTAL",
+        fmt_dur(fff_full_total),
+        "",
+        fmt_dur(rg_full_total),
+        "",
+        ratio_str(fff_full_total, rg_full_total),
+    );
+
+    eprintln!(
+        "\n[5/5] First-page latency — the real UI scenario ({} iters, showing min)",
+        iters
+    );
+    eprintln!("  fff: paginated search (50 matches) from warm mmap cache");
+    eprintln!("  rg:  telescope-style (spawn, stream 50 lines, kill) — per-keystroke cost\n");
+    eprintln!(
+        "  {:<22} | {:>9} {:>10} | {:>9} {:>10} | {:>7}",
+        "Query", "fff min", "matches", "rg min", "matches", "fff/rg"
+    );
+    eprintln!(
+        "  {:-<22}-+-{:-<9}-{:-<10}-+-{:-<9}-{:-<10}-+-{:-<7}",
+        "", "", "", "", "", ""
+    );
+
+    let mut fff_page_total = Duration::ZERO;
+    let mut rg_page_total = Duration::ZERO;
+
+    for (name, query, ci) in &queries {
+        let q = *query;
+        let ci = *ci;
+        let fs = run_n(|| run_fff_page(&files, q), iters);
+        let rs = run_n(|| run_rg_page(&canonical, q, ci, 50, threads), iters);
+
+        eprintln!(
+            "  {:<22} | {:>9} {:>10} | {:>9} {:>10} | {:>7}",
+            name,
+            fmt_dur(fs.min),
+            fs.count,
+            fmt_dur(rs.min),
+            rs.count,
+            ratio_str(fs.min, rs.min),
+        );
+
+        fff_page_total += fs.min;
+        rg_page_total += rs.min;
+    }
+
+    eprintln!(
+        "  {:<22} | {:>9} {:>10} | {:>9} {:>10} | {:>7}",
+        "TOTAL",
+        fmt_dur(fff_page_total),
+        "",
+        fmt_dur(rg_page_total),
+        "",
+        ratio_str(fff_page_total, rg_page_total),
+    );
+
+    eprintln!(
+        "\n=== Summary (total min across all queries, {} iterations) ===\n",
+        iters
+    );
+    eprintln!(
+        "  {:>25} | {:>12} | {:>12} | {:>7}",
+        "", "fff", "rg", "speedup"
+    );
+    eprintln!("  {:->25}-+-{:->12}-+-{:->12}-+-{:->7}", "", "", "", "");
+    eprintln!(
+        "  {:>25} | {:>12} | {:>12} | {:>7}",
+        "full results (collect)",
+        fmt_dur(fff_full_total),
+        fmt_dur(rg_full_total),
+        ratio_str(fff_full_total, rg_full_total),
+    );
+    eprintln!(
+        "  {:>25} | {:>12} | {:>12} | {:>7}",
+        "first-page (UI latency)",
+        fmt_dur(fff_page_total),
+        fmt_dur(rg_page_total),
+        ratio_str(fff_page_total, rg_page_total),
+    );
+
+    eprintln!();
+    eprintln!("  Note: rg cost includes fork/exec + directory traversal + gitignore parsing");
+    eprintln!("  on EVERY invocation (= every keystroke in telescope/fzf-lua).");
+    eprintln!("  fff pays this cost once at startup, then searches from warm cached mmaps.");
+    eprintln!();
+}
@@ -1,4 +1,5 @@
-use fff_nvim::{FILE_PICKER, file_picker::FilePicker};
+use fff_core::file_picker::FilePicker;
+use fff_core::{FILE_PICKER, FuzzySearchOptions, PaginationArgs, QueryParser};
 use std::env;
 use std::thread;
 use std::time::Duration;
@@ -83,17 +84,20 @@ fn test_search_memory_pattern(
        let (result_count, _total_matched) = {
            let file_picker_guard = FILE_PICKER.read().unwrap();
            if let Some(ref picker) = *file_picker_guard {
+                let parser = QueryParser::default();
+                let parsed = parser.parse(&query);
                let search_result = FilePicker::fuzzy_search(
                    picker.get_files(),
                    &query,
-                    fff_nvim::file_picker::FuzzySearchOptions {
+                    parsed,
+                    FuzzySearchOptions {
                        max_threads: 1 + (i % 4),
                        current_file: None,
                        project_path: None,
                        last_same_query_match: None,
                        combo_boost_score_multiplier: 100,
                        min_combo_count: 3,
-                        pagination: fff_nvim::types::PaginationArgs {
+                        pagination: PaginationArgs {
                            offset: 0,
                            limit: 50 + (i % 50),
                        },
@@ -1,5 +1,5 @@
-use fff_nvim::FILE_PICKER;
-use fff_nvim::file_picker::FilePicker;
+use fff_core::file_picker::FilePicker;
+use fff_core::{FILE_PICKER, FileItem, FuzzySearchOptions, PaginationArgs, QueryParser};
 use std::time::{Duration, Instant};

 /// Wait for background scan to complete
@@ -58,7 +58,7 @@ fn init_file_picker(path: &str) -> Result<(), String> {
 }

 /// Get files snapshot from global state
-fn get_files() -> Result<Vec<fff_nvim::types::FileItem>, String> {
+fn get_files() -> Result<Vec<FileItem>, String> {
    let picker_guard = FILE_PICKER
        .read()
        .map_err(|_| "Failed to acquire read lock")?;
@@ -79,9 +79,8 @@ fn main() {
        return;
    }

-    let canonical_path = big_repo_path
-        .canonicalize()
-        .expect("Failed to canonicalize path");
+    let canonical_path =
+        fff_core::path_utils::canonicalize(&big_repo_path).expect("Failed to canonicalize path");

    eprintln!("Initializing FilePicker for: {:?}", canonical_path);
    init_file_picker(&canonical_path.to_string_lossy()).expect("Failed to init FilePicker");
@@ -119,19 +118,22 @@ fn main() {
    for (name, query, iterations) in test_queries {
        let start = Instant::now();
        let mut match_count = 0;
+        let parser = QueryParser::default();

        for _ in 0..iterations {
+            let parsed = parser.parse(query);
            let results = FilePicker::fuzzy_search(
                &files,
                query,
-                fff_nvim::file_picker::FuzzySearchOptions {
+                parsed,
+                FuzzySearchOptions {
                    max_threads: 4,
                    current_file: None,
                    project_path: None,
                    last_same_query_match: None,
                    combo_boost_score_multiplier: 100,
                    min_combo_count: 3,
-                    pagination: fff_nvim::types::PaginationArgs {
+                    pagination: PaginationArgs {
                        offset: 0,
                        limit: 100,
                    },
@@ -1,4 +1,5 @@
-use fff_nvim::{FILE_PICKER, file_picker::FilePicker};
+use fff_core::file_picker::FilePicker;
+use fff_core::{FILE_PICKER, FuzzySearchOptions, PaginationArgs, QueryParser};
 use std::env;
 use std::io::{self, Write};
 use std::thread;
@@ -196,20 +197,23 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
        let max_threads = 1 + (search_count % 8); // Vary thread count

        let search_start = Instant::now();
+        let parser = QueryParser::default();
        let (result_count, search_duration) = {
            let file_picker_guard = FILE_PICKER.read().unwrap();
            if let Some(ref picker) = *file_picker_guard {
+                let parsed = parser.parse(query);
                let search_result = FilePicker::fuzzy_search(
                    picker.get_files(),
                    query,
-                    fff_nvim::file_picker::FuzzySearchOptions {
+                    parsed,
+                    FuzzySearchOptions {
                        max_threads,
                        current_file: None,
                        project_path: None,
                        last_same_query_match: None,
                        combo_boost_score_multiplier: 100,
                        min_combo_count: 3,
-                        pagination: fff_nvim::types::PaginationArgs {
+                        pagination: PaginationArgs {
                            offset: 0,
                            limit: max_results,
                        },
@@ -2,7 +2,9 @@
 #![allow(dead_code)]
 #![allow(clippy::enum_variant_names)]

-use fff_nvim::{FILE_PICKER, FRECENCY, file_picker::FilePicker, git::format_git_status};
+use fff_core::file_picker::FilePicker;
+use fff_core::git::format_git_status;
+use fff_core::{FILE_PICKER, FRECENCY, FuzzySearchOptions, PaginationArgs, QueryParser};
 use std::env;
 use std::io::{self, Write};
 use std::sync::Arc;
@@ -15,7 +17,7 @@ fn cleanup_global_state() {
    {
        let mut file_picker = FILE_PICKER.write().unwrap();
        if let Some(mut picker) = file_picker.take() {
-            let _ = picker.stop_background_monitor();
+            picker.stop_background_monitor();
            drop(picker);
            println!("🧹 FilePicker cleaned up");
        }
@@ -156,17 +158,20 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
            let timestamp = chrono::Local::now().format("%H:%M:%S");
            let file_picker = FILE_PICKER.read().unwrap();
            let files = file_picker.as_ref().unwrap().get_files();
+            let parser = QueryParser::default();
+            let parsed = parser.parse("rs");
            let search_results = FilePicker::fuzzy_search(
                files,
                "rs",
-                fff_nvim::file_picker::FuzzySearchOptions {
+                parsed,
+                FuzzySearchOptions {
                    max_threads: 2,
                    current_file: None,
                    project_path: None,
                    last_same_query_match: None,
                    combo_boost_score_multiplier: 100,
                    min_combo_count: 3,
-                    pagination: fff_nvim::types::PaginationArgs {
+                    pagination: PaginationArgs {
                        offset: 0,
                        limit: 5,
                    },
@@ -0,0 +1,37 @@
+//! Error handling for fff-nvim
+//!
+//! This module provides utilities for converting fff_core errors to mlua errors.
+
+use fff_core::Error as CoreError;
+
+/// Convert a fff_core::Error to mlua::Error
+///
+/// This function is used because we can't implement From<CoreError> for mlua::Error
+/// due to Rust's orphan rules (both types are foreign to this crate).
+pub fn to_lua_error(err: CoreError) -> mlua::Error {
+    let string_value = err.to_string();
+    ::tracing::error!(string_value);
+    mlua::Error::RuntimeError(string_value)
+}
+
+/// Extension trait for Result<T, fff_core::Error> to convert to LuaResult<T>
+pub trait IntoLuaResult<T> {
+    fn into_lua_result(self) -> mlua::Result<T>;
+}
+
+impl<T> IntoLuaResult<T> for Result<T, CoreError> {
+    fn into_lua_result(self) -> mlua::Result<T> {
+        self.map_err(to_lua_error)
+    }
+}
+
+/// Extension trait for Result<T, PoisonError> to convert to Result<T, CoreError>
+pub trait IntoCoreError<T> {
+    fn with_lock_error(self, err: CoreError) -> Result<T, CoreError>;
+}
+
+impl<T, G> IntoCoreError<T> for Result<T, std::sync::PoisonError<G>> {
+    fn with_lock_error(self, err: CoreError) -> Result<T, CoreError> {
+        self.map_err(|_| err)
+    }
+}
@@ -1,56 +1,48 @@
-use crate::db_healthcheck::DbHealthChecker;
-use crate::error::Error;
-use crate::file_picker::{FilePicker, FuzzySearchOptions};
-use crate::frecency::FrecencyTracker;
-use crate::query_tracker::QueryTracker;
-use crate::types::PaginationArgs;
+use crate::path_shortening::shorten_path_with_cache;
+use error::{IntoCoreError, IntoLuaResult};
+use fff_core::file_picker::FilePicker;
+use fff_core::frecency::FrecencyTracker;
+use fff_core::query_tracker::QueryTracker;
+use fff_core::{DbHealthChecker, Error, FuzzySearchOptions, PaginationArgs, QueryParser};
+use fff_core::{FILE_PICKER, FRECENCY, QUERY_TRACKER};
+use mimalloc::MiMalloc;
 use mlua::prelude::*;
-use once_cell::sync::Lazy;
+use path_shortening::PathShortenStrategy;
 use std::path::{Path, PathBuf};
-use std::sync::RwLock;
 use std::time::Duration;

-mod background_watcher;
-mod db_healthcheck;
 mod error;
-pub mod file_picker;
-mod frecency;
-pub mod git;
-mod location;
 mod log;
-pub mod path_utils;
-pub mod query_tracker;
-pub mod score;
-mod sort_buffer;
-pub mod types;
-use mimalloc::MiMalloc;
+mod lua_types;
+mod path_shortening;

 #[global_allocator]
 static GLOBAL: MiMalloc = MiMalloc;

-pub static FRECENCY: Lazy<RwLock<Option<FrecencyTracker>>> = Lazy::new(|| RwLock::new(None));
-pub static FILE_PICKER: Lazy<RwLock<Option<FilePicker>>> = Lazy::new(|| RwLock::new(None));
-pub static QUERY_TRACKER: Lazy<RwLock<Option<QueryTracker>>> = Lazy::new(|| RwLock::new(None));
-
 pub fn init_db(
    _: &Lua,
    (frecency_db_path, history_db_path, use_unsafe_no_lock): (String, String, bool),
 ) -> LuaResult<bool> {
-    let mut frecency = FRECENCY.write().map_err(|_| Error::AcquireFrecencyLock)?;
+    let mut frecency = FRECENCY
+        .write()
+        .with_lock_error(Error::AcquireFrecencyLock)
+        .into_lua_result()?;
    if frecency.is_some() {
        *frecency = None;
    }
-    *frecency = Some(FrecencyTracker::new(&frecency_db_path, use_unsafe_no_lock)?);
+    *frecency =
+        Some(FrecencyTracker::new(&frecency_db_path, use_unsafe_no_lock).into_lua_result()?);
    tracing::info!("Frecency database initialized at {}", frecency_db_path);

    let mut query_tracker = QUERY_TRACKER
        .write()
-        .map_err(|_| Error::AcquireFrecencyLock)?;
+        .with_lock_error(Error::AcquireFrecencyLock)
+        .into_lua_result()?;
    if query_tracker.is_some() {
        *query_tracker = None;
    }

-    let tracker = QueryTracker::new(&history_db_path, use_unsafe_no_lock)?;
+    let tracker = QueryTracker::new(&history_db_path, use_unsafe_no_lock).into_lua_result()?;
    *query_tracker = Some(tracker);
    tracing::info!("Query tracker database initialized at {}", history_db_path);

@@ -58,7 +50,10 @@ pub fn init_db(
 }

 pub fn destroy_frecency_db(_: &Lua, _: ()) -> LuaResult<bool> {
-    let mut frecency = FRECENCY.write().map_err(|_| Error::AcquireFrecencyLock)?;
+    let mut frecency = FRECENCY
+        .write()
+        .with_lock_error(Error::AcquireFrecencyLock)
+        .into_lua_result()?;
    *frecency = None;
    Ok(true)
 }
@@ -66,24 +61,30 @@ pub fn destroy_frecency_db(_: &Lua, _: ()) -> LuaResult<bool> {
 pub fn destroy_query_db(_: &Lua, _: ()) -> LuaResult<bool> {
    let mut query_tracker = QUERY_TRACKER
        .write()
-        .map_err(|_| Error::AcquireFrecencyLock)?;
+        .with_lock_error(Error::AcquireFrecencyLock)
+        .into_lua_result()?;
    *query_tracker = None;
    Ok(true)
 }

 pub fn init_file_picker(_: &Lua, base_path: String) -> LuaResult<bool> {
-    let mut file_picker = FILE_PICKER.write().map_err(|_| Error::AcquireItemLock)?;
+    let mut file_picker = FILE_PICKER
+        .write()
+        .with_lock_error(Error::AcquireItemLock)
+        .into_lua_result()?;
    if file_picker.is_some() {
        return Ok(false);
    }

-    let picker = FilePicker::new(base_path)?;
+    let picker = FilePicker::new(base_path).into_lua_result()?;
    *file_picker = Some(picker);
    Ok(true)
 }

 fn reinit_file_picker_internal(path: &Path) -> Result<(), Error> {
-    let mut file_picker = FILE_PICKER.write().map_err(|_| Error::AcquireItemLock)?;
+    let mut file_picker = FILE_PICKER
+        .write()
+        .with_lock_error(Error::AcquireItemLock)?;

    // drop should clean it anyway but just to be extra sure
    if let Some(mut picker) = file_picker.take() {
@@ -105,7 +106,7 @@ pub fn restart_index_in_path(_: &Lua, new_path: String) -> LuaResult<()> {
        )));
    }

-    let canonical_path = path.canonicalize().map_err(|e| {
+    let canonical_path = fff_core::path_utils::canonicalize(&path).map_err(|e| {
        LuaError::RuntimeError(format!("Failed to canonicalize path '{}': {}", new_path, e))
    })?;

@@ -126,12 +127,16 @@ pub fn restart_index_in_path(_: &Lua, new_path: String) -> LuaResult<()> {
 }

 pub fn scan_files(_: &Lua, _: ()) -> LuaResult<()> {
-    let mut file_picker = FILE_PICKER.write().map_err(|_| Error::AcquireItemLock)?;
+    let mut file_picker = FILE_PICKER
+        .write()
+        .with_lock_error(Error::AcquireItemLock)
+        .into_lua_result()?;
    let picker = file_picker
        .as_mut()
-        .ok_or_else(|| Error::FilePickerMissing)?;
+        .ok_or(Error::FilePickerMissing)
+        .into_lua_result()?;

-    picker.trigger_rescan()?;
+    picker.trigger_rescan().into_lua_result()?;
    ::tracing::info!("scan_files trigger_rescan completed");
    Ok(())
 }
@@ -157,8 +162,12 @@ pub fn fuzzy_search_files(
        Option<usize>,
    ),
 ) -> LuaResult<LuaValue> {
-    let Some(ref picker) = *FILE_PICKER.read().map_err(|_| Error::AcquireItemLock)? else {
-        return Err(Error::FilePickerMissing)?;
+    let file_picker_guard = FILE_PICKER
+        .read()
+        .with_lock_error(Error::AcquireItemLock)
+        .into_lua_result()?;
+    let Some(ref picker) = *file_picker_guard else {
+        return Err(error::to_lua_error(Error::FilePickerMissing));
    };

    let base_path = picker.base_path();
@@ -167,7 +176,8 @@ pub fn fuzzy_search_files(
    let last_same_query_entry = {
        let query_tracker = QUERY_TRACKER
            .read()
-            .map_err(|_| Error::AcquireFrecencyLock)?;
+            .with_lock_error(Error::AcquireFrecencyLock)
+            .into_lua_result()?;

        if query_tracker.as_ref().is_none() {
            tracing::warn!("Query tracker not initialized");
@@ -176,7 +186,8 @@ pub fn fuzzy_search_files(
        query_tracker
            .as_ref()
            .map(|tracker| tracker.get_last_query_entry(&query, base_path, min_combo_count))
-            .transpose()?
+            .transpose()
+            .into_lua_result()?
            .flatten()
    };

@@ -190,9 +201,14 @@ pub fn fuzzy_search_files(
        "Fuzzy search parameters"
    );

+    // Parse the query once at the API boundary
+    let parser = QueryParser::default();
+    let parsed = parser.parse(&query);
+
    let results = FilePicker::fuzzy_search(
        picker.get_files(),
        &query,
+        parsed,
        FuzzySearchOptions {
            max_threads,
            current_file: current_file.as_deref(),
@@ -207,7 +223,61 @@ pub fn fuzzy_search_files(
        },
    );

-    results.into_lua(lua)
+    lua_types::SearchResultLua::from(results).into_lua(lua)
+}
+
+#[allow(clippy::type_complexity)]
+pub fn live_grep(
+    lua: &Lua,
+    (
+        query,
+        file_offset,
+        page_size,
+        max_file_size,
+        max_matches_per_file,
+        smart_case,
+        grep_mode,
+        time_budget_ms,
+    ): (
+        String,
+        Option<usize>,
+        Option<usize>,
+        Option<u64>,
+        Option<usize>,
+        Option<bool>,
+        Option<String>,
+        Option<u64>,
+    ),
+) -> LuaResult<LuaValue> {
+    let file_picker_guard = FILE_PICKER
+        .read()
+        .with_lock_error(Error::AcquireItemLock)
+        .into_lua_result()?;
+    let Some(ref picker) = *file_picker_guard else {
+        return Err(error::to_lua_error(Error::FilePickerMissing));
+    };
+
+    let parsed = fff_core::grep::parse_grep_query(&query);
+
+    let mode = match grep_mode.as_deref() {
+        Some("regex") => fff_core::GrepMode::Regex,
+        Some("fuzzy") => fff_core::GrepMode::Fuzzy,
+        _ => fff_core::GrepMode::PlainText, // "plain" or nil or unknown
+    };
+
+    let options = fff_core::GrepSearchOptions {
+        max_file_size: max_file_size.unwrap_or(10 * 1024 * 1024),
+        max_matches_per_file: max_matches_per_file.unwrap_or(200),
+        smart_case: smart_case.unwrap_or(true),
+        file_offset: file_offset.unwrap_or(0),
+        page_limit: page_size.unwrap_or(50),
+        mode,
+        time_budget_ms: time_budget_ms.unwrap_or(0),
+    };
+
+    let result = fff_core::grep::grep_search(picker.get_files(), &query, parsed, &options);
+
+    lua_types::GrepResultLua::from(result).into_lua(lua)
 }

 pub fn track_access(_: &Lua, file_path: String) -> LuaResult<bool> {
@@ -215,25 +285,50 @@ pub fn track_access(_: &Lua, file_path: String) -> LuaResult<bool> {

    // Track access in frecency DB (expensive LMDB write, ~100-200ms)
    // Do this WITHOUT holding FILE_PICKER lock to avoid blocking searches
-    let Some(ref frecency) = *FRECENCY.read().map_err(|_| Error::AcquireFrecencyLock)? else {
+    let frecency_guard = FRECENCY
+        .read()
+        .with_lock_error(Error::AcquireFrecencyLock)
+        .into_lua_result()?;
+    let Some(ref frecency) = *frecency_guard else {
        return Ok(false);
    };
-    frecency.track_access(file_path.as_path())?;
+    frecency
+        .track_access(file_path.as_path())
+        .into_lua_result()?;
+    drop(frecency_guard);

    // Quick lock to update single file's frecency score in picker
-    let Some(ref mut picker) = *FILE_PICKER.write().map_err(|_| Error::AcquireItemLock)? else {
-        return Err(Error::FilePickerMissing)?;
+    let mut file_picker = FILE_PICKER
+        .write()
+        .with_lock_error(Error::AcquireItemLock)
+        .into_lua_result()?;
+    let Some(ref mut picker) = *file_picker else {
+        return Err(error::to_lua_error(Error::FilePickerMissing));
    };
-    picker.update_single_file_frecency(&file_path, frecency)?;
+
+    let frecency_guard = FRECENCY
+        .read()
+        .with_lock_error(Error::AcquireFrecencyLock)
+        .into_lua_result()?;
+    let Some(ref frecency) = *frecency_guard else {
+        return Ok(false);
+    };
+    picker
+        .update_single_file_frecency(&file_path, frecency)
+        .into_lua_result()?;

    Ok(true)
 }

 pub fn get_scan_progress(lua: &Lua, _: ()) -> LuaResult<LuaValue> {
-    let file_picker = FILE_PICKER.read().map_err(|_| Error::AcquireItemLock)?;
+    let file_picker = FILE_PICKER
+        .read()
+        .with_lock_error(Error::AcquireItemLock)
+        .into_lua_result()?;
    let picker = file_picker
        .as_ref()
-        .ok_or_else(|| Error::FilePickerMissing)?;
+        .ok_or(Error::FilePickerMissing)
+        .into_lua_result()?;
    let progress = picker.get_scan_progress();

    let table = lua.create_table()?;
@@ -243,32 +338,63 @@ pub fn get_scan_progress(lua: &Lua, _: ()) -> LuaResult<LuaValue> {
 }

 pub fn is_scanning(_: &Lua, _: ()) -> LuaResult<bool> {
-    let file_picker = FILE_PICKER.read().map_err(|_| Error::AcquireItemLock)?;
+    let file_picker = FILE_PICKER
+        .read()
+        .with_lock_error(Error::AcquireItemLock)
+        .into_lua_result()?;
    let picker = file_picker
        .as_ref()
-        .ok_or_else(|| Error::FilePickerMissing)?;
+        .ok_or(Error::FilePickerMissing)
+        .into_lua_result()?;
    Ok(picker.is_scan_active())
 }

+pub fn get_git_root(_: &Lua, _: ()) -> LuaResult<Option<String>> {
+    let file_picker = FILE_PICKER
+        .read()
+        .with_lock_error(Error::AcquireItemLock)
+        .into_lua_result()?;
+    let Some(ref picker) = *file_picker else {
+        return Ok(None);
+    };
+
+    Ok(picker.git_root().map(|p| p.to_string_lossy().into_owned()))
+}
+
 pub fn refresh_git_status(_: &Lua, _: ()) -> LuaResult<usize> {
-    FilePicker::refresh_git_status_global().map_err(Into::into)
+    FilePicker::refresh_git_status_global().into_lua_result()
 }

 pub fn update_single_file_frecency(_: &Lua, file_path: String) -> LuaResult<bool> {
-    let Some(ref frecency) = *FRECENCY.read().map_err(|_| Error::AcquireFrecencyLock)? else {
+    let frecency_guard = FRECENCY
+        .read()
+        .with_lock_error(Error::AcquireFrecencyLock)
+        .into_lua_result()?;
+    let Some(ref frecency) = *frecency_guard else {
        return Ok(false);
    };
-    let Some(ref mut picker) = *FILE_PICKER.write().map_err(|_| Error::AcquireItemLock)? else {
-        return Err(Error::FilePickerMissing)?;
+
+    let mut file_picker = FILE_PICKER
+        .write()
+        .with_lock_error(Error::AcquireItemLock)
+        .into_lua_result()?;
+    let Some(ref mut picker) = *file_picker else {
+        return Err(error::to_lua_error(Error::FilePickerMissing));
    };

-    picker.update_single_file_frecency(&file_path, frecency)?;
+    picker
+        .update_single_file_frecency(&file_path, frecency)
+        .into_lua_result()?;
    Ok(true)
 }

 pub fn stop_background_monitor(_: &Lua, _: ()) -> LuaResult<bool> {
-    let Some(ref mut picker) = *FILE_PICKER.write().map_err(|_| Error::AcquireItemLock)? else {
-        return Err(Error::FilePickerMissing)?;
+    let mut file_picker = FILE_PICKER
+        .write()
+        .with_lock_error(Error::AcquireItemLock)
+        .into_lua_result()?;
+    let Some(ref mut picker) = *file_picker else {
+        return Err(error::to_lua_error(Error::FilePickerMissing));
    };

    picker.stop_background_monitor();
@@ -277,7 +403,10 @@ pub fn stop_background_monitor(_: &Lua, _: ()) -> LuaResult<bool> {
 }

 pub fn cleanup_file_picker(_: &Lua, _: ()) -> LuaResult<bool> {
-    let mut file_picker = FILE_PICKER.write().map_err(|_| Error::AcquireItemLock)?;
+    let mut file_picker = FILE_PICKER
+        .write()
+        .with_lock_error(Error::AcquireItemLock)
+        .into_lua_result()?;
    if let Some(picker) = file_picker.take() {
        drop(picker);
        ::tracing::info!("FilePicker cleanup completed");
@@ -295,14 +424,18 @@ pub fn cancel_scan(_: &Lua, _: ()) -> LuaResult<bool> {
 pub fn track_query_completion(_: &Lua, (query, file_path): (String, String)) -> LuaResult<bool> {
    // Get the project path before spawning thread
    let project_path = {
-        let Some(ref picker) = *FILE_PICKER.read().map_err(|_| Error::AcquireItemLock)? else {
+        let file_picker = FILE_PICKER
+            .read()
+            .with_lock_error(Error::AcquireItemLock)
+            .into_lua_result()?;
+        let Some(ref picker) = *file_picker else {
            return Ok(false);
        };
        picker.base_path().to_path_buf()
    };

    // Canonicalize the file path before spawning thread
-    let file_path = match PathBuf::from(&file_path).canonicalize() {
+    let file_path = match fff_core::path_utils::canonicalize(&file_path) {
        Ok(path) => path,
        Err(e) => {
            tracing::warn!(?file_path, error = ?e, "Failed to canonicalize file path for tracking");
@@ -329,29 +462,90 @@ pub fn track_query_completion(_: &Lua, (query, file_path): (String, String)) ->

 pub fn get_historical_query(_: &Lua, offset: usize) -> LuaResult<Option<String>> {
    let project_path = {
-        let Some(ref picker) = *FILE_PICKER.read().map_err(|_| Error::AcquireItemLock)? else {
+        let file_picker = FILE_PICKER
+            .read()
+            .with_lock_error(Error::AcquireItemLock)
+            .into_lua_result()?;
+        let Some(ref picker) = *file_picker else {
            return Ok(None);
        };
        picker.base_path().to_path_buf()
    };

-    let Some(ref tracker) = *QUERY_TRACKER
+    let query_tracker = QUERY_TRACKER
        .read()
-        .map_err(|_| Error::AcquireFrecencyLock)?
-    else {
+        .with_lock_error(Error::AcquireFrecencyLock)
+        .into_lua_result()?;
+    let Some(ref tracker) = *query_tracker else {
        return Ok(None);
    };

    tracker
        .get_historical_query(&project_path, offset)
-        .map_err(Into::into)
+        .into_lua_result()
+}
+
+pub fn track_grep_query(_: &Lua, query: String) -> LuaResult<bool> {
+    let project_path = {
+        let file_picker = FILE_PICKER
+            .read()
+            .with_lock_error(Error::AcquireItemLock)
+            .into_lua_result()?;
+        let Some(ref picker) = *file_picker else {
+            return Ok(false);
+        };
+        picker.base_path().to_path_buf()
+    };
+
+    std::thread::spawn(move || {
+        if let Ok(Some(tracker)) = QUERY_TRACKER.write().as_deref_mut()
+            && let Err(e) = tracker.track_grep_query(&query, &project_path)
+        {
+            tracing::error!(
+                query = %query,
+                error = ?e,
+                "Failed to track grep query"
+            );
+        }
+    });
+
+    Ok(true)
+}
+
+pub fn get_historical_grep_query(_: &Lua, offset: usize) -> LuaResult<Option<String>> {
+    let project_path = {
+        let file_picker = FILE_PICKER
+            .read()
+            .with_lock_error(Error::AcquireItemLock)
+            .into_lua_result()?;
+        let Some(ref picker) = *file_picker else {
+            return Ok(None);
+        };
+        picker.base_path().to_path_buf()
+    };
+
+    let query_tracker = QUERY_TRACKER
+        .read()
+        .with_lock_error(Error::AcquireFrecencyLock)
+        .into_lua_result()?;
+    let Some(ref tracker) = *query_tracker else {
+        return Ok(None);
+    };
+
+    tracker
+        .get_historical_grep_query(&project_path, offset)
+        .into_lua_result()
 }

 pub fn wait_for_initial_scan(_: &Lua, timeout_ms: Option<u64>) -> LuaResult<bool> {
-    let file_picker = FILE_PICKER.read().map_err(|_| Error::AcquireItemLock)?;
+    let file_picker = FILE_PICKER
+        .read()
+        .with_lock_error(Error::AcquireItemLock)
+        .into_lua_result()?;
    let picker = file_picker
        .as_ref()
-        .ok_or_else(|| Error::FilePickerMissing)?;
+        .ok_or(Error::FilePickerMissing)
+        .into_lua_result()?;

    let timeout_ms = timeout_ms.unwrap_or(500);
    let timeout_duration = Duration::from_millis(timeout_ms);
@@ -446,8 +640,14 @@ pub fn health_check(lua: &Lua, test_path: Option<String>) -> LuaResult<LuaValue>
            frecency_info.set("initialized", guard.is_some())?;

            if let Some(ref frecency) = *guard {
-                match frecency.get_lua_helthcheckh(lua) {
-                    Ok(healthcheck_table) => {
+                match frecency.get_health() {
+                    Ok(health) => {
+                        let healthcheck_table = lua.create_table()?;
+                        healthcheck_table.set("path", health.path)?;
+                        healthcheck_table.set("disk_size", health.disk_size)?;
+                        for (name, count) in health.entry_counts {
+                            healthcheck_table.set(name, count)?;
+                        }
                        frecency_info.set("db_healthcheck", healthcheck_table)?;
                    }
                    Err(e) => {
@@ -468,8 +668,14 @@ pub fn health_check(lua: &Lua, test_path: Option<String>) -> LuaResult<LuaValue>
        Ok(guard) => {
            query_tracker_info.set("initialized", guard.is_some())?;
            if let Some(ref query_history) = *guard {
-                match query_history.get_lua_helthcheckh(lua) {
-                    Ok(healthcheck_table) => {
+                match query_history.get_health() {
+                    Ok(health) => {
+                        let healthcheck_table = lua.create_table()?;
+                        healthcheck_table.set("path", health.path)?;
+                        healthcheck_table.set("disk_size", health.disk_size)?;
+                        for (name, count) in health.entry_counts {
+                            healthcheck_table.set(name, count)?;
+                        }
                        query_tracker_info.set("db_healthcheck", healthcheck_table)?;
                    }
                    Err(e) => {
@@ -493,12 +699,22 @@ pub fn shorten_path(
    (path, max_size, strategy): (String, usize, Option<mlua::Value>),
 ) -> LuaResult<String> {
    let strategy = strategy
-        .map(path_utils::PathShortenStrategy::try_from)
+        .map(|v| -> LuaResult<PathShortenStrategy> {
+            match v {
+                mlua::Value::String(ref s) => {
+                    let name = s
+                        .to_str()
+                        .map(|s| s.to_owned())
+                        .unwrap_or_else(|_| "middle_number".to_string());
+                    Ok(PathShortenStrategy::from_name(&name))
+                }
+                _ => Ok(PathShortenStrategy::default()),
+            }
+        })
        .transpose()?
        .unwrap_or_default();

-    let path = PathBuf::from(&path);
-    path_utils::shorten_path(strategy, max_size, &path).map_err(Into::into)
+    shorten_path_with_cache(strategy, max_size, Path::new(&path)).map_err(LuaError::RuntimeError)
 }

 fn create_exports(lua: &Lua) -> LuaResult<LuaTable> {
@@ -518,6 +734,7 @@ fn create_exports(lua: &Lua) -> LuaResult<LuaTable> {
        "fuzzy_search_files",
        lua.create_function(fuzzy_search_files)?,
    )?;
+    exports.set("live_grep", lua.create_function(live_grep)?)?;
    exports.set("track_access", lua.create_function(track_access)?)?;
    exports.set("cancel_scan", lua.create_function(cancel_scan)?)?;
    exports.set("get_scan_progress", lua.create_function(get_scan_progress)?)?;
@@ -525,6 +742,7 @@ fn create_exports(lua: &Lua) -> LuaResult<LuaTable> {
        "refresh_git_status",
        lua.create_function(refresh_git_status)?,
    )?;
+    exports.set("get_git_root", lua.create_function(get_git_root)?)?;
    exports.set(
        "stop_background_monitor",
        lua.create_function(stop_background_monitor)?,
@@ -547,6 +765,11 @@ fn create_exports(lua: &Lua) -> LuaResult<LuaTable> {
        "get_historical_query",
        lua.create_function(get_historical_query)?,
    )?;
+    exports.set("track_grep_query", lua.create_function(track_grep_query)?)?;
+    exports.set(
+        "get_historical_grep_query",
+        lua.create_function(get_historical_grep_query)?,
+    )?;
    exports.set("health_check", lua.create_function(health_check)?)?;
    exports.set("shorten_path", lua.create_function(shorten_path)?)?;

@@ -1,4 +1,4 @@
-use crate::error::Error;
+use std::io;
 use std::path::Path;
 use tracing_appender::non_blocking;
 use tracing_subscriber::fmt::format::FmtSpan;
@@ -86,8 +86,8 @@ pub fn install_panic_hook() {
 /// * `log_level` - Log level (trace, debug, info, warn, error)
 ///
 /// # Returns
-/// * `Result<String, Error>` - Full path to the log file on success
-pub fn init_tracing(log_file_path: &str, log_level: Option<&str>) -> Result<String, Error> {
+/// * `Result<String, io::Error>` - Full path to the log file on success
+pub fn init_tracing(log_file_path: &str, log_level: Option<&str>) -> Result<String, io::Error> {
    // Install panic hook first (does nothing if already installed)
    install_panic_hook();

@@ -0,0 +1,183 @@
+//! Lua type conversions for fff-core types
+//!
+//! This module provides IntoLua implementations for core types.
+
+use fff_core::git::format_git_status;
+use fff_core::{FileItem, GrepResult, Location, Score, SearchResult};
+use mlua::prelude::*;
+
+/// Wrapper for SearchResult that implements IntoLua
+pub struct SearchResultLua<'a> {
+    inner: SearchResult<'a>,
+}
+
+impl<'a> From<SearchResult<'a>> for SearchResultLua<'a> {
+    fn from(inner: SearchResult<'a>) -> Self {
+        Self { inner }
+    }
+}
+
+/// Wrapper for GrepResult that implements IntoLua
+pub struct GrepResultLua<'a> {
+    inner: GrepResult<'a>,
+}
+
+impl<'a> From<GrepResult<'a>> for GrepResultLua<'a> {
+    fn from(inner: GrepResult<'a>) -> Self {
+        Self { inner }
+    }
+}
+
+struct LuaPosition((i32, i32));
+
+impl IntoLua for LuaPosition {
+    fn into_lua(self, lua: &Lua) -> LuaResult<LuaValue> {
+        let table = lua.create_table()?;
+        table.set("line", self.0.0)?;
+        table.set("col", self.0.1)?;
+        Ok(LuaValue::Table(table))
+    }
+}
+
+fn file_item_into_lua(item: &FileItem, lua: &Lua) -> LuaResult<LuaValue> {
+    let table = lua.create_table()?;
+    table.set("path", item.path.to_string_lossy().to_string())?;
+    table.set("relative_path", item.relative_path.clone())?;
+    table.set("name", item.file_name.clone())?;
+    table.set("size", item.size)?;
+    table.set("modified", item.modified)?;
+    table.set("access_frecency_score", item.access_frecency_score)?;
+    table.set(
+        "modification_frecency_score",
+        item.modification_frecency_score,
+    )?;
+    table.set("total_frecency_score", item.total_frecency_score)?;
+    table.set("git_status", format_git_status(item.git_status))?;
+    table.set("is_binary", item.is_binary)?;
+    Ok(LuaValue::Table(table))
+}
+
+fn score_into_lua(score: &Score, lua: &Lua) -> LuaResult<LuaValue> {
+    let table = lua.create_table()?;
+    table.set("total", score.total)?;
+    table.set("base_score", score.base_score)?;
+    table.set("filename_bonus", score.filename_bonus)?;
+    table.set("special_filename_bonus", score.special_filename_bonus)?;
+    table.set("frecency_boost", score.frecency_boost)?;
+    table.set("distance_penalty", score.distance_penalty)?;
+    table.set("current_file_penalty", score.current_file_penalty)?;
+    table.set("combo_match_boost", score.combo_match_boost)?;
+    table.set("match_type", score.match_type)?;
+    table.set("exact_match", score.exact_match)?;
+    Ok(LuaValue::Table(table))
+}
+
+impl IntoLua for SearchResultLua<'_> {
+    fn into_lua(self, lua: &Lua) -> LuaResult<LuaValue> {
+        let table = lua.create_table()?;
+
+        // Convert items
+        let items_table = lua.create_table()?;
+        for (i, item) in self.inner.items.iter().enumerate() {
+            items_table.set(i + 1, file_item_into_lua(item, lua)?)?;
+        }
+        table.set("items", items_table)?;
+
+        // Convert scores
+        let scores_table = lua.create_table()?;
+        for (i, score) in self.inner.scores.iter().enumerate() {
+            scores_table.set(i + 1, score_into_lua(score, lua)?)?;
+        }
+        table.set("scores", scores_table)?;
+
+        table.set("total_matched", self.inner.total_matched)?;
+        table.set("total_files", self.inner.total_files)?;
+
+        if let Some(location) = &self.inner.location {
+            let location_table = lua.create_table()?;
+
+            match location {
+                Location::Line(line) => {
+                    location_table.set("line", *line)?;
+                }
+                Location::Position { line, col } => {
+                    location_table.set("line", *line)?;
+                    location_table.set("col", *col)?;
+                }
+                Location::Range { start, end } => {
+                    location_table.set("start", LuaPosition(*start))?;
+                    location_table.set("end", LuaPosition(*end))?;
+                }
+            }
+
+            table.set("location", location_table)?;
+        }
+
+        Ok(LuaValue::Table(table))
+    }
+}
+
+impl IntoLua for GrepResultLua<'_> {
+    fn into_lua(self, lua: &Lua) -> LuaResult<LuaValue> {
+        let table = lua.create_table()?;
+
+        // Convert grep match items — each includes file metadata + match metadata
+        let items_table = lua.create_table()?;
+        for (i, m) in self.inner.matches.iter().enumerate() {
+            let item = lua.create_table()?;
+
+            // File metadata from the deduplicated files vec
+            let file = self.inner.files[m.file_index];
+            item.set("path", file.path.to_string_lossy().to_string())?;
+            item.set("relative_path", file.relative_path.as_str())?;
+            item.set("name", file.file_name.as_str())?;
+            item.set("is_binary", file.is_binary)?;
+            item.set("git_status", format_git_status(file.git_status))?;
+            item.set("size", file.size)?;
+            item.set("modified", file.modified)?;
+            item.set("total_frecency_score", file.total_frecency_score)?;
+            item.set("access_frecency_score", file.access_frecency_score)?;
+            item.set(
+                "modification_frecency_score",
+                file.modification_frecency_score,
+            )?;
+
+            // Match metadata
+            item.set("line_number", m.line_number)?;
+            item.set("col", m.col)?;
+            item.set("byte_offset", m.byte_offset)?;
+            item.set("line_content", m.line_content.as_str())?;
+
+            // Match byte ranges within line_content
+            let ranges = lua.create_table()?;
+            for (j, &(start, end)) in m.match_byte_offsets.iter().enumerate() {
+                let range = lua.create_table()?;
+                range.set(1, start)?;
+                range.set(2, end)?;
+                ranges.set(j + 1, range)?;
+            }
+            item.set("match_ranges", ranges)?;
+
+            // Fuzzy match score (only set in fuzzy grep mode, nil otherwise)
+            if let Some(score) = m.fuzzy_score {
+                item.set("fuzzy_score", score)?;
+            }
+
+            items_table.set(i + 1, item)?;
+        }
+        table.set("items", items_table)?;
+
+        table.set("total_matched", self.inner.total_match_count)?;
+        table.set("total_files_searched", self.inner.total_files_searched)?;
+        table.set("total_files", self.inner.total_files)?;
+        table.set("filtered_file_count", self.inner.filtered_file_count)?;
+        table.set("next_file_offset", self.inner.next_file_offset)?;
+
+        // Pass regex fallback error to Lua (nil if no error)
+        if let Some(ref err) = self.inner.regex_fallback_error {
+            table.set("regex_fallback_error", err.as_str())?;
+        }
+
+        Ok(LuaValue::Table(table))
+    }
+}
@@ -1,59 +1,12 @@
-use crate::error::{Error, Result};
+//! Path shortening utilities for display in Neovim UI
+//!
+//! This module provides functionality to shorten file paths for display
+//! in the picker UI with various strategies.
+
 use once_cell::sync::Lazy;
 use std::borrow::Cow;
-use std::path::Component;
-use std::path::MAIN_SEPARATOR;
-use std::{
-    path::{Path, PathBuf},
-    sync::RwLock,
-};
-
-pub fn calculate_distance_penalty(current_file: Option<&str>, candidate_path: &str) -> i32 {
-    let Some(ref current_path) = current_file else {
-        return 0; // No penalty if no current file
-    };
-
-    let current_dir = if let Some(parent) = std::path::Path::new(current_path).parent() {
-        parent.to_string_lossy().to_string()
-    } else {
-        String::new()
-    };
-
-    let candidate_dir = if let Some(parent) = std::path::Path::new(candidate_path).parent() {
-        parent.to_string_lossy().to_string()
-    } else {
-        String::new()
-    };
-
-    if current_dir == candidate_dir {
-        return 0; // Same directory, no penalty
-    }
-
-    let current_parts: Vec<&str> = current_dir
-        .split(std::path::MAIN_SEPARATOR)
-        .filter(|s| !s.is_empty())
-        .collect();
-    let candidate_parts: Vec<&str> = candidate_dir
-        .split(std::path::MAIN_SEPARATOR)
-        .filter(|s| !s.is_empty())
-        .collect();
-
-    let common_len = current_parts
-        .iter()
-        .zip(candidate_parts.iter())
-        .take_while(|(a, b)| a == b)
-        .count();
-
-    let current_depth_from_common = current_parts.len() - common_len;
-
-    if current_depth_from_common == 0 {
-        return 0; // Current file is at the common ancestor level
-    }
-
-    let penalty = -(current_depth_from_common as i32);
-
-    penalty.max(-20)
-}
+use std::path::{Component, MAIN_SEPARATOR, Path, PathBuf};
+use std::sync::RwLock;

 #[derive(Clone, Copy, Default)]
 pub enum PathShortenStrategy {
@@ -122,11 +75,15 @@ const DEFAULT_CACHE_SIZE: usize = 8192;
 static PATH_SHORTEN_CACHE: Lazy<RwLock<PathCache>> =
    Lazy::new(|| RwLock::new(PathCache::new(DEFAULT_CACHE_SIZE)));

-pub fn shorten_path(strategy: PathShortenStrategy, max_size: usize, path: &Path) -> Result<String> {
+pub fn shorten_path_with_cache(
+    strategy: PathShortenStrategy,
+    max_size: usize,
+    path: &Path,
+) -> Result<String, String> {
    {
        let cache = PATH_SHORTEN_CACHE
            .read()
-            .map_err(|_| Error::AcquirePathCacheLock)?;
+            .map_err(|_| "Failed to acquire path cache lock".to_string())?;
        if let Some(cached) = cache.get(path, max_size) {
            tracing::debug!("Cache hit for path '{}'", path.display());
            return Ok(cached.to_string());
@@ -137,28 +94,22 @@ pub fn shorten_path(strategy: PathShortenStrategy, max_size: usize, path: &Path)
    {
        let mut cache = PATH_SHORTEN_CACHE
            .write()
-            .map_err(|_| Error::AcquirePathCacheLock)?;
+            .map_err(|_| "Failed to acquire path cache lock".to_string())?;
        cache.insert(path.to_path_buf(), shortened.clone(), max_size);
    }

    Ok(shortened)
 }

-impl TryFrom<mlua::Value> for PathShortenStrategy {
-    type Error = mlua::Error;
-
-    fn try_from(value: mlua::Value) -> std::result::Result<Self, Self::Error> {
-        let strategy = match value {
-            mlua::Value::String(ref s) => match s.to_str()?.as_ref() {
-                "middle_number" => PathShortenStrategy::MiddleNumber,
-                "middle" => PathShortenStrategy::Middle,
-                "end" => PathShortenStrategy::End,
-                _ => PathShortenStrategy::MiddleNumber,
-            },
+impl PathShortenStrategy {
+    /// Parse a strategy from a string name
+    pub fn from_name(name: &str) -> Self {
+        match name {
+            "middle_number" => PathShortenStrategy::MiddleNumber,
+            "middle" => PathShortenStrategy::Middle,
+            "end" => PathShortenStrategy::End,
            _ => PathShortenStrategy::MiddleNumber,
-        };
-
-        Ok(strategy)
+        }
    }
 }

@@ -465,86 +416,6 @@ impl PathShortenStrategy {
 mod tests {
    use super::*;

-    #[test]
-    #[cfg(not(target_family = "windows"))]
-    fn test_calculate_distance_penalty() {
-        assert_eq!(
-            calculate_distance_penalty(None, "examples/user/test/mod.rs"),
-            0
-        );
-        // Same directory
-        assert_eq!(
-            calculate_distance_penalty(
-                Some("examples/user/test/main.rs"),
-                "examples/user/test/mod.rs"
-            ),
-            0
-        );
-        //
-        // One level apart
-        assert_eq!(
-            calculate_distance_penalty(
-                Some("examples/user/test/subdir/file.rs"),
-                "examples/user/test/mod.rs"
-            ),
-            -1
-        );
-        //
-        // Different subdirectories (same parent)
-        assert_eq!(
-            calculate_distance_penalty(
-                Some("examples/user/test/dir1/file.rs"),
-                "examples/user/test/dir2/mod.rs"
-            ),
-            -1
-        );
-
-        assert_eq!(
-            calculate_distance_penalty(
-                Some("examples/audio-announce/src/lib/audio-announce.rs"),
-                "examples/audio-announce/src/main.rs"
-            ),
-            -1
-        );
-
-        assert_eq!(
-            calculate_distance_penalty(
-                Some("examples/audio-announce/src/audio-announce.rs"),
-                "examples/pixel/src/main.rs"
-            ),
-            -2
-        );
-
-        // Root level files
-        assert_eq!(calculate_distance_penalty(Some("main.rs"), "lib.rs"), 0);
-    }
-
-    #[test]
-    #[cfg(target_family = "windows")]
-    fn distance_penalty_works_on_windows() {
-        assert_eq!(
-            calculate_distance_penalty(None, "examples\\user\\test\\mod.rs"),
-            0
-        );
-        // Same directory
-        assert_eq!(
-            calculate_distance_penalty(
-                Some("examples\\user\\test\\main.rs"),
-                "examples\\user\\test\\mod.rs"
-            ),
-            0
-        );
-        //
-        // One level apart
-        assert_eq!(
-            calculate_distance_penalty(
-                Some("examples\\user\\test\\subdir\\file.rs"),
-                "examples\\user\\test\\mod.rs"
-            ),
-            -1
-        );
-    }
-
    #[test]
    fn test_path_shorten_strategy_middle() {
        // Test with directory paths (not file paths) - this is what Lua passes
@@ -652,15 +523,15 @@ mod tests {
        let path = Path::new("home/user/projects/rust/project/src/components/ui");

        // First call should compute and cache
-        let result1 = shorten_path(PathShortenStrategy::MiddleNumber, 25, path).unwrap();
+        let result1 = shorten_path_with_cache(PathShortenStrategy::MiddleNumber, 25, path).unwrap();

        // Second call should hit cache
-        let result2 = shorten_path(PathShortenStrategy::MiddleNumber, 25, path).unwrap();
+        let result2 = shorten_path_with_cache(PathShortenStrategy::MiddleNumber, 25, path).unwrap();

        assert_eq!(result1, result2);

        // Different max_size should produce different result (more space = longer result)
-        let result3 = shorten_path(PathShortenStrategy::MiddleNumber, 50, path).unwrap();
+        let result3 = shorten_path_with_cache(PathShortenStrategy::MiddleNumber, 50, path).unwrap();
        assert!(
            result3.len() >= result1.len(),
            "More space should allow longer result"
@@ -0,0 +1,18 @@
+[package]
+name = "fff-query-parser"
+version = "0.1.0"
+edition = "2024"
+
+[lib]
+path = "src/lib.rs"
+
+[dependencies]
+smallvec = { workspace = true }
+zlob = { version = "1.2.8" }
+
+[dev-dependencies]
+criterion = { version = "0.5", features = ["html_reports"] }
+
+[[bench]]
+name = "parse_bench"
+harness = false
@@ -0,0 +1,180 @@
+use criterion::{BenchmarkId, Criterion, Throughput, black_box, criterion_group, criterion_main};
+use fff_query_parser::*;
+
+fn bench_parse_simple(c: &mut Criterion) {
+    let parser = QueryParser::default();
+
+    c.bench_function("parse_simple_text", |b| {
+        b.iter(|| parser.parse(black_box("hello world")));
+    });
+
+    c.bench_function("parse_extension", |b| {
+        b.iter(|| parser.parse(black_box("*.rs")));
+    });
+
+    c.bench_function("parse_text_with_extension", |b| {
+        b.iter(|| parser.parse(black_box("name *.rs")));
+    });
+}
+
+fn bench_parse_complex(c: &mut Criterion) {
+    let parser = QueryParser::default();
+
+    c.bench_function("parse_complex_mixed", |b| {
+        b.iter(|| parser.parse(black_box("src name *.rs !test /lib/ status:modified")));
+    });
+
+    c.bench_function("parse_glob", |b| {
+        b.iter(|| parser.parse(black_box("**/*.rs")));
+    });
+
+    c.bench_function("parse_multiple_constraints", |b| {
+        b.iter(|| parser.parse(black_box("*.rs *.toml *.md !test !node_modules /src/")));
+    });
+}
+
+fn bench_parse_realistic_queries(c: &mut Criterion) {
+    let parser = QueryParser::default();
+
+    let queries = vec![
+        "file",
+        "test",
+        "mod.rs",
+        "src/*.rs",
+        "lib test",
+        "*.rs !test",
+        "src/lib/*.rs",
+        "/src/ name",
+        "status:modified *.rs",
+        "type:rust test !node_modules",
+    ];
+
+    let mut group = c.benchmark_group("realistic_queries");
+    for query in queries.iter() {
+        group.throughput(Throughput::Bytes(query.len() as u64));
+        group.bench_with_input(BenchmarkId::from_parameter(query), query, |b, q| {
+            b.iter(|| parser.parse(black_box(q)));
+        });
+    }
+    group.finish();
+}
+
+fn bench_parse_various_lengths(c: &mut Criterion) {
+    let parser = QueryParser::default();
+
+    let short = "*.rs";
+    let medium = "src name *.rs !test";
+    let long = "src lib test name *.rs *.toml !node_modules !test /src/ /lib/ status:modified";
+    let very_long =
+        "a b c d e f g h i j k l m n o p q r s t u v w x y z *.rs *.toml *.md *.txt *.js";
+
+    let mut group = c.benchmark_group("query_lengths");
+
+    group.throughput(Throughput::Bytes(short.len() as u64));
+    group.bench_with_input(BenchmarkId::new("short", short.len()), &short, |b, q| {
+        b.iter(|| parser.parse(black_box(q)));
+    });
+
+    group.throughput(Throughput::Bytes(medium.len() as u64));
+    group.bench_with_input(BenchmarkId::new("medium", medium.len()), &medium, |b, q| {
+        b.iter(|| parser.parse(black_box(q)));
+    });
+
+    group.throughput(Throughput::Bytes(long.len() as u64));
+    group.bench_with_input(BenchmarkId::new("long", long.len()), &long, |b, q| {
+        b.iter(|| parser.parse(black_box(q)));
+    });
+
+    group.throughput(Throughput::Bytes(very_long.len() as u64));
+    group.bench_with_input(
+        BenchmarkId::new("very_long", very_long.len()),
+        &very_long,
+        |b, q| {
+            b.iter(|| parser.parse(black_box(q)));
+        },
+    );
+
+    group.finish();
+}
+
+fn bench_config_comparison(c: &mut Criterion) {
+    let file_picker = QueryParser::new(FilePickerConfig);
+    let grep = QueryParser::new(GrepConfig);
+
+    let query = "src name *.rs !test";
+
+    let mut group = c.benchmark_group("config_comparison");
+
+    group.bench_function("file_picker_config", |b| {
+        b.iter(|| file_picker.parse(black_box(query)));
+    });
+
+    group.bench_function("grep_config", |b| {
+        b.iter(|| grep.parse(black_box(query)));
+    });
+
+    group.finish();
+}
+
+fn bench_constraint_types(c: &mut Criterion) {
+    let parser = QueryParser::default();
+
+    let mut group = c.benchmark_group("constraint_types");
+
+    group.bench_function("extension", |b| {
+        b.iter(|| parser.parse(black_box("*.rs")));
+    });
+
+    group.bench_function("glob", |b| {
+        b.iter(|| parser.parse(black_box("**/*.rs")));
+    });
+
+    group.bench_function("exclude", |b| {
+        b.iter(|| parser.parse(black_box("!test")));
+    });
+
+    group.bench_function("path_segment", |b| {
+        b.iter(|| parser.parse(black_box("/src/")));
+    });
+
+    group.bench_function("git_status", |b| {
+        b.iter(|| parser.parse(black_box("status:modified")));
+    });
+
+    group.bench_function("file_type", |b| {
+        b.iter(|| parser.parse(black_box("type:rust")));
+    });
+
+    group.finish();
+}
+
+fn bench_worst_case(c: &mut Criterion) {
+    let parser = QueryParser::default();
+
+    // Worst case: many constraints that all need to be checked
+    let worst_case = "a b c d e f g h i j k l m n o p q r s t u v w x y z";
+
+    c.bench_function("worst_case_many_text_tokens", |b| {
+        b.iter(|| parser.parse(black_box(worst_case)));
+    });
+
+    // Many constraints
+    let many_constraints = "*.rs *.toml *.md *.txt *.js *.ts *.jsx *.tsx *.vue *.svelte";
+
+    c.bench_function("worst_case_many_constraints", |b| {
+        b.iter(|| parser.parse(black_box(many_constraints)));
+    });
+}
+
+criterion_group!(
+    benches,
+    bench_parse_simple,
+    bench_parse_complex,
+    bench_parse_realistic_queries,
+    bench_parse_various_lengths,
+    bench_config_comparison,
+    bench_constraint_types,
+    bench_worst_case,
+);
+
+criterion_main!(benches);
@@ -0,0 +1,109 @@
+use crate::constraints::Constraint;
+use zlob::{ZlobFlags, has_wildcards};
+
+/// Parser configuration trait - allows different picker types to customize parsing
+pub trait ParserConfig {
+    fn enable_glob(&self) -> bool {
+        true
+    }
+
+    /// Should parse extension shortcuts (e.g., *.rs)
+    fn enable_extension(&self) -> bool {
+        true
+    }
+
+    /// Should parse exclusion patterns (e.g., !test)
+    fn enable_exclude(&self) -> bool {
+        true
+    }
+
+    /// Should parse path segments (e.g., /src/)
+    fn enable_path_segments(&self) -> bool {
+        true
+    }
+
+    /// Should parse type constraints (e.g., type:rust)
+    fn enable_type_filter(&self) -> bool {
+        true
+    }
+
+    /// Should parse git status (e.g., status:modified)
+    fn enable_git_status(&self) -> bool {
+        true
+    }
+
+    /// Determine whether a token should be treated as a glob constraint.
+    ///
+    /// The default implementation delegates to `zlob::has_wildcards` with
+    /// `RECOMMENDED` flags, which recognises `*`, `?`, `[`, `{…}` etc.
+    ///
+    /// 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)
+    }
+
+    /// Custom constraint parsers for picker-specific needs
+    fn parse_custom<'a>(&self, _input: &'a str) -> Option<Constraint<'a>> {
+        None
+    }
+}
+
+/// Default configuration for file picker - all features enabled
+#[derive(Debug, Clone, Copy, Default)]
+pub struct FilePickerConfig;
+
+impl ParserConfig for FilePickerConfig {
+    // All defaults enabled
+}
+
+/// Configuration for full-text search (grep) - file constraints enabled for
+/// filtering which files to search, git status disabled since it's not useful
+/// when searching file contents.
+///
+/// Glob detection is narrowed: only patterns containing a path separator (`/`)
+/// or brace expansion (`{…}`) are treated as globs. Characters like `?` and
+/// `[` are extremely common in source code and must remain literal search text.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct GrepConfig;
+
+impl ParserConfig for GrepConfig {
+    fn enable_path_segments(&self) -> bool {
+        true
+    }
+
+    fn enable_git_status(&self) -> bool {
+        false
+    }
+
+    /// Only recognise globs that are clearly directory/path oriented.
+    ///
+    /// Characters like `?`, `[`, and bare `*` (without `/`) are extremely
+    /// common in source code (`foo?`, `arr[0]`, `*ptr`) and must NOT be
+    /// consumed as glob constraints. We only treat a token as a glob when
+    /// it contains path-oriented patterns:
+    ///
+    /// - Contains `/` → path glob (e.g. `src/**/*.rs`, `*/tests/*`)
+    /// - 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) {
+            return false;
+        }
+
+        let bytes = token.as_bytes();
+
+        // Contains path separator → clearly a path glob
+        if bytes.contains(&b'/') {
+            return true;
+        }
+
+        // Brace expansion → useful for directory alternatives
+        if bytes.contains(&b'{') && bytes.contains(&b'}') {
+            return true;
+        }
+
+        // Everything else (?, [, bare * without /) → treat as literal text
+        false
+    }
+}
@@ -0,0 +1,45 @@
+use smallvec::SmallVec;
+
+/// Constraint types that can be extracted from a query
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Constraint<'a> {
+    /// Match file extension: *.rs -> Extension("rs")
+    Extension(&'a str),
+
+    /// Glob pattern: **/*.rs -> Glob("**/*.rs")
+    Glob(&'a str),
+
+    /// Multiple text search parts: ["src", "name"]
+    /// Uses slice to avoid allocation
+    Parts(&'a [&'a str]),
+
+    /// Single text token (optimized case)
+    Text(&'a str),
+
+    /// Exclude pattern: !test -> Exclude(&["test"])
+    Exclude(&'a [&'a str]),
+
+    /// Path constraint: /src/ -> PathSegment("src")
+    PathSegment(&'a str),
+
+    /// File type constraint: type:rust -> FileType("rust")
+    FileType(&'a str),
+
+    /// Git status constraint: status:modified -> GitStatus(Modified)
+    GitStatus(GitStatusFilter),
+
+    /// Negation constraint: !extension:rs -> Not(Extension("rs"))
+    /// Negates the inner constraint
+    Not(Box<Constraint<'a>>),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum GitStatusFilter {
+    Modified,
+    Untracked,
+    Staged,
+    Unmodified,
+}
+
+/// Stack-allocated buffer for text parts (up to 16 parts without heap allocation)
+pub(crate) type TextPartsBuffer<'a> = SmallVec<[&'a str; 16]>;
@@ -0,0 +1,251 @@
+//! Fast, zero-allocation query parser for file search
+//!
+//! This parser takes a search query and extracts structured constraints
+//! while preserving text for fuzzy matching. Designed for maximum performance:
+//! - Zero allocations for queries with ≤8 constraints (SmallVec)
+//! - Single-pass parsing with minimal branching
+//! - Stack-allocated string buffers
+//!
+//! # Examples
+//!
+//! ```
+//! use fff_query_parser::{QueryParser, Constraint, FuzzyQuery};
+//!
+//! let parser = QueryParser::default();
+//!
+//! // Single-token queries return None (no parsing needed)
+//! let result = parser.parse("hello");
+//! assert!(result.is_none());
+//!
+//! // Multi-token queries are parsed
+//! let result = parser.parse("name *.rs").expect("Should parse");
+//! match &result.fuzzy_query {
+//!     FuzzyQuery::Text(text) => assert_eq!(*text, "name"),
+//!     _ => panic!("Expected text"),
+//! }
+//! assert!(matches!(result.constraints[0], Constraint::Extension("rs")));
+//!
+//! // Parse glob pattern with text
+//! let result = parser.parse("**/*.rs foo").expect("Should parse");
+//! assert!(matches!(result.constraints[0], Constraint::Glob("**/*.rs")));
+//!
+//! // Parse negation
+//! let result = parser.parse("!*.rs foo").expect("Should parse");
+//! match &result.constraints[0] {
+//!     Constraint::Not(inner) => {
+//!         assert!(matches!(inner.as_ref(), Constraint::Extension("rs")));
+//!     }
+//!     _ => panic!("Expected Not constraint"),
+//! }
+//! ```
+
+mod config;
+mod constraints;
+pub mod location;
+mod parser;
+
+pub use config::{FilePickerConfig, GrepConfig, ParserConfig};
+pub use constraints::{Constraint, GitStatusFilter};
+pub use location::Location;
+pub use parser::{FFFQuery, FuzzyQuery, QueryParser};
+
+// Re-export SmallVec for convenience
+pub use smallvec::SmallVec;
+
+/// Type alias for constraint vector - stack-allocated for ≤8 constraints
+pub type ConstraintVec<'a> = SmallVec<[Constraint<'a>; 8]>;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_empty_query() {
+        let parser = QueryParser::default();
+        let result = parser.parse("");
+        // Empty query returns None (single-token behavior)
+        assert!(result.is_none());
+    }
+
+    #[test]
+    fn test_whitespace_only() {
+        let parser = QueryParser::default();
+        let result = parser.parse("   ");
+        // Whitespace-only returns None
+        assert!(result.is_none());
+    }
+
+    #[test]
+    fn test_single_token() {
+        let parser = QueryParser::default();
+        let result = parser.parse("hello");
+        // Single token returns None (no parsing needed)
+        assert!(result.is_none());
+    }
+
+    #[test]
+    fn test_simple_text() {
+        let parser = QueryParser::default();
+        let result = parser
+            .parse("hello world")
+            .expect("Should parse multi-token");
+
+        match &result.fuzzy_query {
+            FuzzyQuery::Parts(parts) => {
+                assert_eq!(parts.len(), 2);
+                assert_eq!(parts[0], "hello");
+                assert_eq!(parts[1], "world");
+            }
+            _ => panic!("Expected Parts fuzzy query"),
+        }
+
+        assert_eq!(result.constraints.len(), 0);
+    }
+
+    #[test]
+    fn test_extension_only() {
+        let parser = QueryParser::default();
+        // Single constraint token - returns Some so constraint can be applied
+        let result = parser
+            .parse("*.rs")
+            .expect("Should parse single constraint");
+        assert!(matches!(result.fuzzy_query, FuzzyQuery::Empty));
+        assert_eq!(result.constraints.len(), 1);
+        assert!(matches!(result.constraints[0], Constraint::Extension("rs")));
+    }
+
+    #[test]
+    fn test_glob_pattern() {
+        let parser = QueryParser::default();
+        let result = parser
+            .parse("**/*.rs foo")
+            .expect("Should parse multi-token");
+        assert_eq!(result.constraints.len(), 1);
+        // Glob patterns with ** are treated as globs, not extensions
+        match &result.constraints[0] {
+            Constraint::Glob(pattern) => assert_eq!(*pattern, "**/*.rs"),
+            other => panic!("Expected Glob constraint, got {:?}", other),
+        }
+    }
+
+    #[test]
+    fn test_negation_pattern() {
+        let parser = QueryParser::default();
+        let result = parser.parse("!test foo").expect("Should parse multi-token");
+        assert_eq!(result.constraints.len(), 1);
+        match &result.constraints[0] {
+            Constraint::Not(inner) => {
+                assert!(matches!(**inner, Constraint::Text("test")));
+            }
+            _ => panic!("Expected Not constraint"),
+        }
+    }
+
+    #[test]
+    fn test_path_segment() {
+        let parser = QueryParser::default();
+        let result = parser.parse("/src/ foo").expect("Should parse multi-token");
+        assert_eq!(result.constraints.len(), 1);
+        assert!(matches!(
+            result.constraints[0],
+            Constraint::PathSegment("src")
+        ));
+    }
+
+    #[test]
+    fn test_git_status() {
+        let parser = QueryParser::default();
+        let result = parser
+            .parse("status:modified foo")
+            .expect("Should parse multi-token");
+        assert_eq!(result.constraints.len(), 1);
+        assert!(matches!(
+            result.constraints[0],
+            Constraint::GitStatus(GitStatusFilter::Modified)
+        ));
+    }
+
+    #[test]
+    fn test_file_type() {
+        let parser = QueryParser::default();
+        let result = parser
+            .parse("type:rust foo")
+            .expect("Should parse multi-token");
+        assert_eq!(result.constraints.len(), 1);
+        assert!(matches!(
+            result.constraints[0],
+            Constraint::FileType("rust")
+        ));
+    }
+
+    #[test]
+    fn test_complex_query() {
+        let parser = QueryParser::default();
+        let result = parser
+            .parse("src name *.rs !test /lib/ status:modified")
+            .expect("Should parse");
+
+        // Verify we have fuzzy text
+        match &result.fuzzy_query {
+            FuzzyQuery::Parts(parts) => {
+                assert_eq!(parts.len(), 2);
+                assert_eq!(parts[0], "src");
+                assert_eq!(parts[1], "name");
+            }
+            _ => panic!("Expected Parts fuzzy query"),
+        }
+
+        // Should have multiple constraints
+        assert!(result.constraints.len() >= 4);
+
+        // Verify specific constraints exist
+        let has_extension = result
+            .constraints
+            .iter()
+            .any(|c| matches!(c, Constraint::Extension("rs")));
+        let has_not = result
+            .constraints
+            .iter()
+            .any(|c| matches!(c, Constraint::Not(_)));
+        let has_path = result
+            .constraints
+            .iter()
+            .any(|c| matches!(c, Constraint::PathSegment("lib")));
+        let has_git_status = result
+            .constraints
+            .iter()
+            .any(|c| matches!(c, Constraint::GitStatus(_)));
+
+        assert!(has_extension, "Should have Extension constraint");
+        assert!(has_not, "Should have Not constraint");
+        assert!(has_path, "Should have PathSegment constraint");
+        assert!(has_git_status, "Should have GitStatus constraint");
+    }
+
+    #[test]
+    fn test_no_heap_allocation_for_small_queries() {
+        let parser = QueryParser::default();
+        let result = parser
+            .parse("*.rs *.toml !test")
+            .expect("Should parse multi-token");
+        // SmallVec should not have spilled to heap
+        assert!(!result.constraints.spilled());
+    }
+
+    #[test]
+    fn test_many_fuzzy_parts() {
+        let parser = QueryParser::default();
+        let result = parser
+            .parse("one two three four five six")
+            .expect("Should parse");
+
+        match &result.fuzzy_query {
+            FuzzyQuery::Parts(parts) => {
+                assert_eq!(parts.len(), 6);
+                assert_eq!(parts[0], "one");
+                assert_eq!(parts[5], "six");
+            }
+            _ => panic!("Expected Parts fuzzy query"),
+        }
+    }
+}
@@ -1,3 +1,14 @@
+//! Location parsing for file:line:col patterns
+//!
+//! Parses various location formats like:
+//! - `file:12` - Line number
+//! - `file:12:4` - Line and column
+//! - `file:12-114` - Line range
+//! - `file:12:4-20` - Column range on same line
+//! - `file:12:4-14:20` - Position range
+//! - `file(12)` - Visual Studio style line
+//! - `file(12,4)` - Visual Studio style line and column
+
 #[derive(Debug, Eq, PartialEq, Copy, Clone)]
 pub enum Location {
    Line(i32),
@@ -143,6 +154,22 @@ fn parse_vstudio_location(query: &str) -> Option<(&str, Location)> {
    None
 }

+/// Parse location from the end of a query string.
+///
+/// Returns the query without the location suffix, and the parsed location if found.
+///
+/// # Examples
+/// ```
+/// use fff_query_parser::location::{parse_location, Location};
+///
+/// let (query, loc) = parse_location("file:12");
+/// assert_eq!(query, "file");
+/// assert_eq!(loc, Some(Location::Line(12)));
+///
+/// let (query, loc) = parse_location("search term");
+/// assert_eq!(query, "search term");
+/// assert_eq!(loc, None);
+/// ```
 pub fn parse_location(query: &str) -> (&str, Option<Location>) {
    // simply ignore the last semicolon even if there are no additional location info
    let query = query.trim_end_matches([':', '-', '(']);
@@ -159,7 +186,7 @@ pub fn parse_location(query: &str) -> (&str, Option<Location>) {

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

    #[test]
    fn test_location_parsing() {
@@ -0,0 +1,671 @@
+use crate::ConstraintVec;
+use crate::config::ParserConfig;
+use crate::constraints::{Constraint, GitStatusFilter, TextPartsBuffer};
+use crate::location::{Location, parse_location};
+use zlob::{ZlobFlags, has_wildcards};
+
+#[derive(Debug, Clone, PartialEq)]
+#[allow(clippy::large_enum_variant)]
+pub enum FuzzyQuery<'a> {
+    Parts(TextPartsBuffer<'a>),
+    Text(&'a str),
+    Empty,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct FFFQuery<'a> {
+    /// Parsed constraints (stack-allocated for ≤8 constraints)
+    pub constraints: ConstraintVec<'a>,
+    pub fuzzy_query: FuzzyQuery<'a>,
+    /// Parsed location (e.g., file:12:4 -> line 12, col 4)
+    pub location: Option<Location>,
+}
+
+/// Main query parser - zero-cost wrapper around configuration
+#[derive(Debug)]
+pub struct QueryParser<C: ParserConfig> {
+    config: C,
+}
+
+impl<C: ParserConfig> QueryParser<C> {
+    pub fn new(config: C) -> Self {
+        Self { config }
+    }
+
+    pub fn parse<'a>(&self, query: &'a str) -> Option<FFFQuery<'a>> {
+        let query: &'a str = query;
+        let config: &C = &self.config;
+        let mut constraints = ConstraintVec::new();
+        let query = query.trim();
+
+        let whitespace_count = query.chars().filter(|c| c.is_whitespace()).count();
+
+        // Single token - check if it's a constraint or plain text
+        if whitespace_count == 0 {
+            // Try to parse as constraint first
+            if let Some(constraint) = parse_token(query, config) {
+                constraints.push(constraint);
+                return Some(FFFQuery {
+                    constraints,
+                    fuzzy_query: FuzzyQuery::Empty,
+                    location: None,
+                });
+            }
+
+            // Try to extract location from single token (e.g., "file:12")
+            let (query_without_loc, location) = parse_location(query);
+            if location.is_some() {
+                return Some(FFFQuery {
+                    constraints,
+                    fuzzy_query: FuzzyQuery::Text(query_without_loc),
+                    location,
+                });
+            }
+
+            // Plain text single token - return None (caller handles as simple fuzzy match)
+            return None;
+        }
+
+        // Stack-allocated buffer for text parts (up to 16 parts)
+        let mut text_parts = TextPartsBuffer::new();
+        let tokens = query.split_whitespace();
+
+        for token in tokens {
+            match parse_token(token, config) {
+                Some(constraint) => {
+                    constraints.push(constraint);
+                }
+                None => {
+                    text_parts.push(token);
+                }
+            }
+        }
+
+        // Try to extract location from the last fuzzy token
+        // e.g., "search file:12" -> fuzzy="search file", location=Line(12)
+        let location = if !text_parts.is_empty() {
+            let last_idx = text_parts.len() - 1;
+            let (without_loc, loc) = parse_location(text_parts[last_idx]);
+            if loc.is_some() {
+                // Update the last part to be without the location suffix
+                text_parts[last_idx] = without_loc;
+                loc
+            } else {
+                None
+            }
+        } else {
+            None
+        };
+
+        let fuzzy_query = if text_parts.is_empty() {
+            FuzzyQuery::Empty
+        } else if text_parts.len() == 1 {
+            // If the only remaining text is empty after location extraction, treat as Empty
+            if text_parts[0].is_empty() {
+                FuzzyQuery::Empty
+            } else {
+                FuzzyQuery::Text(text_parts[0])
+            }
+        } else {
+            // Filter out empty parts that might result from location extraction
+            if text_parts.iter().all(|p| p.is_empty()) {
+                FuzzyQuery::Empty
+            } else {
+                FuzzyQuery::Parts(text_parts)
+            }
+        };
+
+        Some(FFFQuery {
+            constraints,
+            fuzzy_query,
+            location,
+        })
+    }
+}
+
+impl Default for QueryParser<crate::FilePickerConfig> {
+    fn default() -> Self {
+        Self::new(crate::FilePickerConfig)
+    }
+}
+
+#[inline]
+fn parse_token<'a, C: ParserConfig>(token: &'a str, config: &C) -> Option<Constraint<'a>> {
+    // Backslash escape: \token → treat as literal text, skip all constraint parsing.
+    // The leading \ is stripped by the caller when building the search text.
+    if token.starts_with('\\') && token.len() > 1 {
+        return None;
+    }
+
+    let first_byte = token.as_bytes().first()?;
+
+    match first_byte {
+        b'*' if config.enable_extension() => {
+            // Ignore incomplete patterns like "*" or "*."
+            if token == "*" || token == "*." {
+                return None;
+            }
+
+            // Try extension first (*.rs) - simple patterns without additional wildcards
+            if let Some(constraint) = parse_extension(token) {
+                // 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) {
+                    return Some(constraint);
+                }
+            }
+            // Has wildcards -> use config-specific glob detection
+            if config.enable_glob() && config.is_glob_pattern(token) {
+                return Some(Constraint::Glob(token));
+            }
+            None
+        }
+        b'!' if config.enable_exclude() => parse_negation(token, config),
+        b'/' if config.enable_path_segments() => parse_path_segment(token),
+        _ if config.enable_path_segments() && token.ends_with('/') => {
+            // Handle trailing slash syntax: www/ -> PathSegment("www")
+            parse_path_segment_trailing(token)
+        }
+        _ => {
+            // Check for glob patterns using config-specific detection
+            if config.enable_glob() && config.is_glob_pattern(token) {
+                return Some(Constraint::Glob(token));
+            }
+
+            // Check for key:value patterns
+            if let Some(colon_idx) = memchr(b':', token.as_bytes()) {
+                let (key, value_with_colon) = token.split_at(colon_idx);
+                let value = &value_with_colon[1..]; // Skip the colon
+
+                match key {
+                    "type" if config.enable_type_filter() => {
+                        return Some(Constraint::FileType(value));
+                    }
+                    "status" | "st" | "g" | "git" if config.enable_git_status() => {
+                        return parse_git_status(value);
+                    }
+                    _ => {}
+                }
+            }
+
+            // Try custom parsers
+            config.parse_custom(token)
+        }
+    }
+}
+
+/// Find first occurrence of byte in slice (fast memchr-like implementation)
+#[inline]
+fn memchr(needle: u8, haystack: &[u8]) -> Option<usize> {
+    haystack.iter().position(|&b| b == needle)
+}
+
+/// Parse extension pattern: *.rs -> Extension("rs")
+#[inline]
+fn parse_extension(token: &str) -> Option<Constraint<'_>> {
+    if token.len() > 2 && token.starts_with("*.") {
+        Some(Constraint::Extension(&token[2..]))
+    } else {
+        None
+    }
+}
+
+/// Parse negation pattern: !*.rs -> Not(Extension("rs")), !test -> Not(Text("test"))
+/// This allows negating any constraint type
+#[inline]
+fn parse_negation<'a, C: ParserConfig>(token: &'a str, config: &C) -> Option<Constraint<'a>> {
+    if token.len() <= 1 {
+        return None;
+    }
+
+    let inner_token = &token[1..];
+
+    // Try to parse the inner token as any constraint
+    if let Some(inner_constraint) = parse_token_without_negation(inner_token, config) {
+        // Wrap it in a Not constraint
+        return Some(Constraint::Not(Box::new(inner_constraint)));
+    }
+
+    // If it's not a special constraint, treat it as negated text
+    // For backward compatibility with !test syntax
+    Some(Constraint::Not(Box::new(Constraint::Text(inner_token))))
+}
+
+/// Parse a token without checking for negation (to avoid infinite recursion)
+#[inline]
+fn parse_token_without_negation<'a, C: ParserConfig>(
+    token: &'a str,
+    config: &C,
+) -> Option<Constraint<'a>> {
+    // Backslash escape applies here too
+    if token.starts_with('\\') && token.len() > 1 {
+        return None;
+    }
+
+    let first_byte = token.as_bytes().first()?;
+
+    match first_byte {
+        b'*' if config.enable_extension() => {
+            // 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) {
+                    return Some(constraint);
+                }
+            }
+            // Has wildcards -> use config-specific glob detection
+            if config.enable_glob() && config.is_glob_pattern(token) {
+                return Some(Constraint::Glob(token));
+            }
+            None
+        }
+        b'/' if config.enable_path_segments() => parse_path_segment(token),
+        _ if config.enable_path_segments() && token.ends_with('/') => {
+            // Handle trailing slash syntax: www/ -> PathSegment("www")
+            parse_path_segment_trailing(token)
+        }
+        _ => {
+            // Check for glob patterns using config-specific detection
+            if config.enable_glob() && config.is_glob_pattern(token) {
+                return Some(Constraint::Glob(token));
+            }
+
+            // Check for key:value patterns
+            if let Some(colon_idx) = memchr(b':', token.as_bytes()) {
+                let (key, value_with_colon) = token.split_at(colon_idx);
+                let value = &value_with_colon[1..]; // Skip the colon
+
+                match key {
+                    "type" if config.enable_type_filter() => {
+                        return Some(Constraint::FileType(value));
+                    }
+                    "status" | "gi" | "g" | "st" if config.enable_git_status() => {
+                        return parse_git_status(value);
+                    }
+                    _ => {}
+                }
+            }
+
+            config.parse_custom(token)
+        }
+    }
+}
+
+/// Parse path segment: /src/ -> PathSegment("src")
+#[inline]
+fn parse_path_segment(token: &str) -> Option<Constraint<'_>> {
+    if token.len() > 1 && token.starts_with('/') {
+        let segment = token.trim_start_matches('/').trim_end_matches('/');
+        if !segment.is_empty() {
+            Some(Constraint::PathSegment(segment))
+        } else {
+            None
+        }
+    } else {
+        None
+    }
+}
+
+/// Parse path segment with trailing slash: www/ -> PathSegment("www")
+#[inline]
+fn parse_path_segment_trailing(token: &str) -> Option<Constraint<'_>> {
+    if token.len() > 1 && token.ends_with('/') {
+        let segment = token.trim_end_matches('/');
+        if !segment.is_empty() && !segment.contains('/') {
+            Some(Constraint::PathSegment(segment))
+        } else {
+            None
+        }
+    } else {
+        None
+    }
+}
+
+/// Parse git status filter: modified|m|untracked|u|staged|s
+#[inline]
+fn parse_git_status(value: &str) -> Option<Constraint<'_>> {
+    if value == "*" {
+        return None;
+    }
+
+    if "modified".starts_with(value) {
+        return Some(Constraint::GitStatus(GitStatusFilter::Modified));
+    }
+
+    if "untracked".starts_with(value) {
+        return Some(Constraint::GitStatus(GitStatusFilter::Untracked));
+    }
+
+    if "staged".starts_with(value) {
+        return Some(Constraint::GitStatus(GitStatusFilter::Staged));
+    }
+
+    if "clean".starts_with(value) {
+        return Some(Constraint::GitStatus(GitStatusFilter::Unmodified));
+    }
+
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::FilePickerConfig;
+
+    #[test]
+    fn test_parse_extension() {
+        assert_eq!(parse_extension("*.rs"), Some(Constraint::Extension("rs")));
+        assert_eq!(
+            parse_extension("*.toml"),
+            Some(Constraint::Extension("toml"))
+        );
+        assert_eq!(parse_extension("*"), None);
+        assert_eq!(parse_extension("*."), None);
+    }
+
+    #[test]
+    fn test_incomplete_patterns_ignored() {
+        let config = FilePickerConfig;
+        // Incomplete patterns should return None and be treated as noise
+        assert_eq!(parse_token("*", &config), None);
+        assert_eq!(parse_token("*.", &config), None);
+    }
+
+    #[test]
+    fn test_parse_path_segment() {
+        assert_eq!(
+            parse_path_segment("/src/"),
+            Some(Constraint::PathSegment("src"))
+        );
+        assert_eq!(
+            parse_path_segment("/lib"),
+            Some(Constraint::PathSegment("lib"))
+        );
+        assert_eq!(parse_path_segment("/"), None);
+    }
+
+    #[test]
+    fn test_parse_path_segment_trailing() {
+        assert_eq!(
+            parse_path_segment_trailing("www/"),
+            Some(Constraint::PathSegment("www"))
+        );
+        assert_eq!(
+            parse_path_segment_trailing("src/"),
+            Some(Constraint::PathSegment("src"))
+        );
+        // Should not match paths with multiple segments
+        assert_eq!(parse_path_segment_trailing("src/lib/"), None);
+        // Should not match without trailing slash
+        assert_eq!(parse_path_segment_trailing("www"), None);
+    }
+
+    #[test]
+    fn test_trailing_slash_in_query() {
+        let parser = QueryParser::new(FilePickerConfig);
+        let result = parser
+            .parse("www/ test")
+            .expect("Should parse multi-token query");
+        assert_eq!(result.constraints.len(), 1);
+        assert!(matches!(
+            result.constraints[0],
+            Constraint::PathSegment("www")
+        ));
+        assert!(matches!(result.fuzzy_query, FuzzyQuery::Text("test")));
+    }
+
+    #[test]
+    fn test_parse_git_status() {
+        assert_eq!(
+            parse_git_status("modified"),
+            Some(Constraint::GitStatus(GitStatusFilter::Modified))
+        );
+        assert_eq!(
+            parse_git_status("m"),
+            Some(Constraint::GitStatus(GitStatusFilter::Modified))
+        );
+        assert_eq!(
+            parse_git_status("untracked"),
+            Some(Constraint::GitStatus(GitStatusFilter::Untracked))
+        );
+        assert_eq!(parse_git_status("invalid"), None);
+    }
+
+    #[test]
+    fn test_memchr() {
+        assert_eq!(memchr(b':', b"type:rust"), Some(4));
+        assert_eq!(memchr(b':', b"nocolon"), None);
+        assert_eq!(memchr(b':', b":start"), Some(0));
+    }
+
+    #[test]
+    fn test_negation_text() {
+        let parser = QueryParser::new(FilePickerConfig);
+        // Need two tokens for parsing to return Some
+        let result = parser
+            .parse("!test foo")
+            .expect("Should parse multi-token query");
+        assert_eq!(result.constraints.len(), 1);
+        match &result.constraints[0] {
+            Constraint::Not(inner) => {
+                assert!(matches!(**inner, Constraint::Text("test")));
+            }
+            _ => panic!("Expected Not constraint"),
+        }
+    }
+
+    #[test]
+    fn test_negation_extension() {
+        let parser = QueryParser::new(FilePickerConfig);
+        let result = parser
+            .parse("!*.rs foo")
+            .expect("Should parse multi-token query");
+        assert_eq!(result.constraints.len(), 1);
+        match &result.constraints[0] {
+            Constraint::Not(inner) => {
+                assert!(matches!(**inner, Constraint::Extension("rs")));
+            }
+            _ => panic!("Expected Not(Extension) constraint"),
+        }
+    }
+
+    #[test]
+    fn test_negation_path_segment() {
+        let parser = QueryParser::new(FilePickerConfig);
+        let result = parser
+            .parse("!/src/ foo")
+            .expect("Should parse multi-token query");
+        assert_eq!(result.constraints.len(), 1);
+        match &result.constraints[0] {
+            Constraint::Not(inner) => {
+                assert!(matches!(**inner, Constraint::PathSegment("src")));
+            }
+            _ => panic!("Expected Not(PathSegment) constraint"),
+        }
+    }
+
+    #[test]
+    fn test_negation_git_status() {
+        let parser = QueryParser::new(FilePickerConfig);
+        let result = parser
+            .parse("!status:modified foo")
+            .expect("Should parse multi-token query");
+        assert_eq!(result.constraints.len(), 1);
+        match &result.constraints[0] {
+            Constraint::Not(inner) => {
+                assert!(matches!(
+                    **inner,
+                    Constraint::GitStatus(GitStatusFilter::Modified)
+                ));
+            }
+            _ => panic!("Expected Not(GitStatus) constraint"),
+        }
+    }
+
+    #[test]
+    fn test_backslash_escape_extension() {
+        let parser = QueryParser::new(FilePickerConfig);
+        let result = parser
+            .parse("\\*.rs foo")
+            .expect("Should parse multi-token query");
+        // \*.rs should NOT be parsed as an Extension constraint
+        assert_eq!(result.constraints.len(), 0);
+        // Both tokens should be text
+        match result.fuzzy_query {
+            FuzzyQuery::Parts(parts) => {
+                assert_eq!(parts.len(), 2);
+                assert_eq!(parts[0], "\\*.rs");
+                assert_eq!(parts[1], "foo");
+            }
+            _ => panic!("Expected Parts, got {:?}", result.fuzzy_query),
+        }
+    }
+
+    #[test]
+    fn test_backslash_escape_path_segment() {
+        let parser = QueryParser::new(FilePickerConfig);
+        let result = parser
+            .parse("\\/src/ foo")
+            .expect("Should parse multi-token query");
+        assert_eq!(result.constraints.len(), 0);
+        match result.fuzzy_query {
+            FuzzyQuery::Parts(parts) => {
+                assert_eq!(parts[0], "\\/src/");
+                assert_eq!(parts[1], "foo");
+            }
+            _ => panic!("Expected Parts, got {:?}", result.fuzzy_query),
+        }
+    }
+
+    #[test]
+    fn test_backslash_escape_negation() {
+        let parser = QueryParser::new(FilePickerConfig);
+        let result = parser
+            .parse("\\!test foo")
+            .expect("Should parse multi-token query");
+        assert_eq!(result.constraints.len(), 0);
+    }
+
+    #[test]
+    fn test_grep_question_mark_is_text() {
+        use crate::GrepConfig;
+        let parser = QueryParser::new(GrepConfig);
+        // Single token "foo?" should return None (treated as plain text by caller)
+        let result = parser.parse("foo?");
+        assert!(result.is_none(), "foo? should be plain text in grep mode");
+    }
+
+    #[test]
+    fn test_grep_bracket_is_text() {
+        use crate::GrepConfig;
+        let parser = QueryParser::new(GrepConfig);
+        let result = parser.parse("arr[0] something");
+        let result = result.expect("Should parse multi-token query");
+        // arr[0] should NOT be a glob in grep mode
+        assert_eq!(result.constraints.len(), 0);
+    }
+
+    #[test]
+    fn test_grep_path_glob_is_constraint() {
+        use crate::GrepConfig;
+        let parser = QueryParser::new(GrepConfig);
+        let result = parser
+            .parse("pattern src/**/*.rs")
+            .expect("Should parse with path glob");
+        // src/**/*.rs contains / so it should be treated as a glob
+        assert_eq!(result.constraints.len(), 1);
+        assert!(matches!(
+            result.constraints[0],
+            Constraint::Glob("src/**/*.rs")
+        ));
+    }
+
+    #[test]
+    fn test_grep_brace_is_constraint() {
+        use crate::GrepConfig;
+        let parser = QueryParser::new(GrepConfig);
+        let result = parser
+            .parse("pattern {src,lib}")
+            .expect("Should parse with brace expansion");
+        assert_eq!(result.constraints.len(), 1);
+        assert!(matches!(
+            result.constraints[0],
+            Constraint::Glob("{src,lib}")
+        ));
+    }
+
+    #[test]
+    fn test_grep_bare_star_is_text() {
+        use crate::GrepConfig;
+        let parser = QueryParser::new(GrepConfig);
+        // "a*b" contains * but no / or {} — should be text in grep mode
+        let result = parser.parse("a*b something");
+        let result = result.expect("Should parse");
+        assert_eq!(
+            result.constraints.len(),
+            0,
+            "bare * without / should be text"
+        );
+    }
+
+    #[test]
+    fn test_grep_negated_text() {
+        use crate::GrepConfig;
+        let parser = QueryParser::new(GrepConfig);
+        let result = parser
+            .parse("pattern !test")
+            .expect("Should parse negated text in grep mode");
+        assert_eq!(result.constraints.len(), 1);
+        match &result.constraints[0] {
+            Constraint::Not(inner) => {
+                assert!(
+                    matches!(**inner, Constraint::Text("test")),
+                    "Expected Not(Text(\"test\")), got Not({:?})",
+                    inner
+                );
+            }
+            other => panic!("Expected Not constraint, got {:?}", other),
+        }
+    }
+
+    #[test]
+    fn test_grep_negated_path_segment() {
+        use crate::GrepConfig;
+        let parser = QueryParser::new(GrepConfig);
+        let result = parser
+            .parse("pattern !/src/")
+            .expect("Should parse negated path segment in grep mode");
+        assert_eq!(result.constraints.len(), 1);
+        match &result.constraints[0] {
+            Constraint::Not(inner) => {
+                assert!(
+                    matches!(**inner, Constraint::PathSegment("src")),
+                    "Expected Not(PathSegment(\"src\")), got Not({:?})",
+                    inner
+                );
+            }
+            other => panic!("Expected Not constraint, got {:?}", other),
+        }
+    }
+
+    #[test]
+    fn test_grep_negated_extension() {
+        use crate::GrepConfig;
+        let parser = QueryParser::new(GrepConfig);
+        let result = parser
+            .parse("pattern !*.rs")
+            .expect("Should parse negated extension in grep mode");
+        assert_eq!(result.constraints.len(), 1);
+        match &result.constraints[0] {
+            Constraint::Not(inner) => {
+                assert!(
+                    matches!(**inner, Constraint::Extension("rs")),
+                    "Expected Not(Extension(\"rs\")), got Not({:?})",
+                    inner
+                );
+            }
+            other => panic!("Expected Not constraint, got {:?}", other),
+        }
+    }
+}
@@ -0,0 +1,9 @@
+[package]
+name = "grep-searcher"
+version = "0.1.16"
+edition = "2024"
+
+[dependencies]
+bstr = { version = "1.6.2", default-features = false, features = ["std"] }
+grep-matcher = { workspace = true }
+memchr = "2.6.3"
@@ -0,0 +1,17 @@
+/*!
+Simplified grep-searcher for fff.nvim.
+
+Provides line-oriented search over byte slices with optional multi-line support.
+Only `search_slice` is supported -- no file/reader/mmap search.
+*/
+
+#![deny(missing_docs)]
+
+pub use crate::{
+    searcher::{Searcher, SearcherBuilder},
+    sink::{Sink, SinkError, SinkFinish, SinkMatch},
+};
+
+pub mod lines;
+mod searcher;
+mod sink;
@@ -0,0 +1,234 @@
+/*!
+A collection of routines for performing operations on lines.
+*/
+
+use {
+    bstr::ByteSlice,
+    grep_matcher::{LineTerminator, Match},
+};
+
+/// An explicit iterator over lines in a particular slice of bytes.
+///
+/// This iterator avoids borrowing the bytes themselves, and instead requires
+/// callers to explicitly provide the bytes when moving through the iterator.
+///
+/// Line terminators are considered part of the line they terminate. All lines
+/// yielded by the iterator are guaranteed to be non-empty.
+#[derive(Debug)]
+pub struct LineStep {
+    line_term: u8,
+    pos: usize,
+    end: usize,
+}
+
+impl LineStep {
+    /// Create a new line iterator over the given range of bytes using the
+    /// given line terminator.
+    pub fn new(line_term: u8, start: usize, end: usize) -> LineStep {
+        LineStep {
+            line_term,
+            pos: start,
+            end,
+        }
+    }
+
+    /// Like next, but returns a `Match` instead of a tuple.
+    #[inline(always)]
+    pub fn next_match(&mut self, bytes: &[u8]) -> Option<Match> {
+        self.next_impl(bytes).map(|(s, e)| Match::new(s, e))
+    }
+
+    #[inline(always)]
+    fn next_impl(&mut self, mut bytes: &[u8]) -> Option<(usize, usize)> {
+        bytes = &bytes[..self.end];
+        match bytes[self.pos..].find_byte(self.line_term) {
+            None => {
+                if self.pos < bytes.len() {
+                    let m = (self.pos, bytes.len());
+                    assert!(m.0 <= m.1);
+
+                    self.pos = m.1;
+                    Some(m)
+                } else {
+                    None
+                }
+            }
+            Some(line_end) => {
+                let m = (self.pos, self.pos + line_end + 1);
+                assert!(m.0 <= m.1);
+
+                self.pos = m.1;
+                Some(m)
+            }
+        }
+    }
+}
+
+/// Count the number of occurrences of `line_term` in `bytes`.
+pub fn count(bytes: &[u8], line_term: u8) -> u64 {
+    memchr::memchr_iter(line_term, bytes).count() as u64
+}
+
+/// Given a line that possibly ends with a terminator, return that line without
+/// the terminator.
+#[inline(always)]
+pub fn without_terminator(bytes: &[u8], line_term: LineTerminator) -> &[u8] {
+    let line_term = line_term.as_bytes();
+    let start = bytes.len().saturating_sub(line_term.len());
+    if bytes.get(start..) == Some(line_term) {
+        return &bytes[..bytes.len() - line_term.len()];
+    }
+    bytes
+}
+
+/// Return the start and end offsets of the lines containing the given range
+/// of bytes.
+///
+/// Line terminators are considered part of the line they terminate.
+#[inline(always)]
+pub fn locate(bytes: &[u8], line_term: u8, range: Match) -> Match {
+    let line_start = bytes[..range.start()]
+        .rfind_byte(line_term)
+        .map_or(0, |i| i + 1);
+    let line_end = if range.end() > line_start && bytes[range.end() - 1] == line_term {
+        range.end()
+    } else {
+        bytes[range.end()..]
+            .find_byte(line_term)
+            .map_or(bytes.len(), |i| range.end() + i + 1)
+    };
+    Match::new(line_start, line_end)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const SHERLOCK: &'static str = "\
+For the Doctor Watsons of this world, as opposed to the Sherlock
+Holmeses, success in the province of detective work must always
+be, to a very large extent, the result of luck. Sherlock Holmes
+can extract a clew from a wisp of straw or a flake of cigar ash;
+but Doctor Watson has to have it taken out for him and dusted,
+and exhibited clearly, with a label attached.\
+";
+
+    fn m(start: usize, end: usize) -> Match {
+        Match::new(start, end)
+    }
+
+    fn lines(text: &str) -> Vec<&str> {
+        let mut results = vec![];
+        let mut it = LineStep::new(b'\n', 0, text.len());
+        while let Some(m) = it.next_match(text.as_bytes()) {
+            results.push(&text[m]);
+        }
+        results
+    }
+
+    fn line_ranges(text: &str) -> Vec<std::ops::Range<usize>> {
+        let mut results = vec![];
+        let mut it = LineStep::new(b'\n', 0, text.len());
+        while let Some(m) = it.next_match(text.as_bytes()) {
+            results.push(m.start()..m.end());
+        }
+        results
+    }
+
+    fn loc(text: &str, start: usize, end: usize) -> Match {
+        locate(text.as_bytes(), b'\n', Match::new(start, end))
+    }
+
+    #[test]
+    fn line_count() {
+        assert_eq!(0, count(b"", b'\n'));
+        assert_eq!(1, count(b"\n", b'\n'));
+        assert_eq!(2, count(b"\n\n", b'\n'));
+        assert_eq!(2, count(b"a\nb\nc", b'\n'));
+    }
+
+    #[test]
+    fn line_locate() {
+        let t = SHERLOCK;
+        let lines = line_ranges(t);
+
+        assert_eq!(
+            loc(t, lines[0].start, lines[0].end),
+            m(lines[0].start, lines[0].end)
+        );
+        assert_eq!(
+            loc(t, lines[0].start + 1, lines[0].end),
+            m(lines[0].start, lines[0].end)
+        );
+        assert_eq!(
+            loc(t, lines[0].end - 1, lines[0].end),
+            m(lines[0].start, lines[0].end)
+        );
+        assert_eq!(
+            loc(t, lines[0].end, lines[0].end),
+            m(lines[1].start, lines[1].end)
+        );
+
+        assert_eq!(
+            loc(t, lines[5].start, lines[5].end),
+            m(lines[5].start, lines[5].end)
+        );
+        assert_eq!(
+            loc(t, lines[5].start + 1, lines[5].end),
+            m(lines[5].start, lines[5].end)
+        );
+        assert_eq!(
+            loc(t, lines[5].end - 1, lines[5].end),
+            m(lines[5].start, lines[5].end)
+        );
+        assert_eq!(
+            loc(t, lines[5].end, lines[5].end),
+            m(lines[5].start, lines[5].end)
+        );
+    }
+
+    #[test]
+    fn line_locate_weird() {
+        assert_eq!(loc("", 0, 0), m(0, 0));
+
+        assert_eq!(loc("\n", 0, 1), m(0, 1));
+        assert_eq!(loc("\n", 1, 1), m(1, 1));
+
+        assert_eq!(loc("\n\n", 0, 0), m(0, 1));
+        assert_eq!(loc("\n\n", 0, 1), m(0, 1));
+        assert_eq!(loc("\n\n", 1, 1), m(1, 2));
+        assert_eq!(loc("\n\n", 1, 2), m(1, 2));
+        assert_eq!(loc("\n\n", 2, 2), m(2, 2));
+
+        assert_eq!(loc("a\nb\nc", 0, 1), m(0, 2));
+        assert_eq!(loc("a\nb\nc", 1, 2), m(0, 2));
+        assert_eq!(loc("a\nb\nc", 2, 3), m(2, 4));
+        assert_eq!(loc("a\nb\nc", 3, 4), m(2, 4));
+        assert_eq!(loc("a\nb\nc", 4, 5), m(4, 5));
+        assert_eq!(loc("a\nb\nc", 5, 5), m(4, 5));
+    }
+
+    #[test]
+    fn line_iter() {
+        assert_eq!(lines("abc"), vec!["abc"]);
+
+        assert_eq!(lines("abc\n"), vec!["abc\n"]);
+        assert_eq!(lines("abc\nxyz"), vec!["abc\n", "xyz"]);
+        assert_eq!(lines("abc\nxyz\n"), vec!["abc\n", "xyz\n"]);
+
+        assert_eq!(lines("abc\n\n"), vec!["abc\n", "\n"]);
+        assert_eq!(lines("abc\n\n\n"), vec!["abc\n", "\n", "\n"]);
+        assert_eq!(lines("abc\n\nxyz"), vec!["abc\n", "\n", "xyz"]);
+        assert_eq!(lines("abc\n\nxyz\n"), vec!["abc\n", "\n", "xyz\n"]);
+        assert_eq!(lines("abc\nxyz\n\n"), vec!["abc\n", "xyz\n", "\n"]);
+
+        assert_eq!(lines("\n"), vec!["\n"]);
+        assert_eq!(lines(""), Vec::<&str>::new());
+    }
+
+    #[test]
+    fn line_iter_empty() {
+        let mut it = LineStep::new(b'\n', 0, 0);
+        assert_eq!(it.next_match(b"abc"), None);
+    }
+}
@@ -0,0 +1,212 @@
+use grep_matcher::{LineMatchKind, Matcher};
+
+use crate::{
+    lines::{self, LineStep},
+    searcher::{Config, Range, Searcher},
+    sink::{Sink, SinkError, SinkFinish, SinkMatch},
+};
+
+#[derive(Debug)]
+pub(crate) struct Core<'s, M: 's, S> {
+    config: &'s Config,
+    matcher: M,
+    searcher: &'s Searcher,
+    sink: S,
+    pos: usize,
+    absolute_byte_offset: u64,
+    line_number: Option<u64>,
+    last_line_counted: usize,
+    last_line_visited: usize,
+}
+
+impl<'s, M: Matcher, S: Sink> Core<'s, M, S> {
+    pub(crate) fn new(searcher: &'s Searcher, matcher: M, sink: S) -> Core<'s, M, S> {
+        let line_number = if searcher.config.line_number {
+            Some(1)
+        } else {
+            None
+        };
+        Core {
+            config: &searcher.config,
+            matcher,
+            searcher,
+            sink,
+            pos: 0,
+            absolute_byte_offset: 0,
+            line_number,
+            last_line_counted: 0,
+            last_line_visited: 0,
+        }
+    }
+
+    pub(crate) fn pos(&self) -> usize {
+        self.pos
+    }
+
+    pub(crate) fn set_pos(&mut self, pos: usize) {
+        self.pos = pos;
+    }
+
+    pub(crate) fn matched(&mut self, buf: &[u8], range: &Range) -> Result<bool, S::Error> {
+        self.sink_matched(buf, range)
+    }
+
+    pub(crate) fn find(&mut self, slice: &[u8]) -> Result<Option<Range>, S::Error> {
+        match self.matcher.find(slice) {
+            Err(err) => Err(S::Error::error_message(err)),
+            Ok(m) => Ok(m),
+        }
+    }
+
+    fn shortest_match(&mut self, slice: &[u8]) -> Result<Option<usize>, S::Error> {
+        match self.matcher.shortest_match(slice) {
+            Err(err) => Err(S::Error::error_message(err)),
+            Ok(m) => Ok(m),
+        }
+    }
+
+    pub(crate) fn begin(&mut self) -> Result<bool, S::Error> {
+        self.sink.begin(self.searcher)
+    }
+
+    pub(crate) fn finish(&mut self, byte_count: u64) -> Result<(), S::Error> {
+        self.sink.finish(self.searcher, &SinkFinish { byte_count })
+    }
+
+    pub(crate) fn match_by_line(&mut self, buf: &[u8]) -> Result<bool, S::Error> {
+        if self.is_line_by_line_fast() {
+            self.match_by_line_fast(buf)
+        } else {
+            self.match_by_line_slow(buf)
+        }
+    }
+
+    fn match_by_line_slow(&mut self, buf: &[u8]) -> Result<bool, S::Error> {
+        debug_assert!(!self.searcher.multi_line_with_matcher(&self.matcher));
+
+        let range = Range::new(self.pos(), buf.len());
+        let mut stepper =
+            LineStep::new(self.config.line_term.as_byte(), range.start(), range.end());
+        while let Some(line) = stepper.next_match(buf) {
+            let matched = {
+                let slice = lines::without_terminator(&buf[line], self.config.line_term);
+                self.shortest_match(slice)?.is_some()
+            };
+            self.set_pos(line.end());
+            if matched && !self.sink_matched(buf, &line)? {
+                return Ok(false);
+            }
+        }
+        Ok(true)
+    }
+
+    fn match_by_line_fast(&mut self, buf: &[u8]) -> Result<bool, S::Error> {
+        while !buf[self.pos()..].is_empty() {
+            if let Some(line) = self.find_by_line_fast(buf)? {
+                self.set_pos(line.end());
+                if !self.sink_matched(buf, &line)? {
+                    return Ok(false);
+                }
+            } else {
+                break;
+            }
+        }
+        self.set_pos(buf.len());
+        Ok(true)
+    }
+
+    #[inline(always)]
+    fn find_by_line_fast(&mut self, buf: &[u8]) -> Result<Option<Range>, S::Error> {
+        debug_assert!(!self.searcher.multi_line_with_matcher(&self.matcher));
+        debug_assert!(self.is_line_by_line_fast());
+
+        let mut pos = self.pos();
+        while !buf[pos..].is_empty() {
+            match self.matcher.find_candidate_line(&buf[pos..]) {
+                Err(err) => return Err(S::Error::error_message(err)),
+                Ok(None) => return Ok(None),
+                Ok(Some(LineMatchKind::Confirmed(i))) => {
+                    let line = lines::locate(
+                        buf,
+                        self.config.line_term.as_byte(),
+                        Range::zero(i).offset(pos),
+                    );
+                    if line.start() == buf.len() {
+                        pos = buf.len();
+                        continue;
+                    }
+                    return Ok(Some(line));
+                }
+                Ok(Some(LineMatchKind::Candidate(i))) => {
+                    let line = lines::locate(
+                        buf,
+                        self.config.line_term.as_byte(),
+                        Range::zero(i).offset(pos),
+                    );
+                    let slice = lines::without_terminator(&buf[line], self.config.line_term);
+                    if self
+                        .matcher
+                        .is_match(slice)
+                        .map_err(S::Error::error_message)?
+                    {
+                        return Ok(Some(line));
+                    }
+                    pos = line.end();
+                }
+            }
+        }
+        Ok(None)
+    }
+
+    #[inline(always)]
+    fn sink_matched(&mut self, buf: &[u8], range: &Range) -> Result<bool, S::Error> {
+        self.count_lines(buf, range.start());
+        let offset = self.absolute_byte_offset + range.start() as u64;
+        let linebuf = &buf[*range];
+        let keepgoing = self.sink.matched(
+            self.searcher,
+            &SinkMatch {
+                bytes: linebuf,
+                absolute_byte_offset: offset,
+                line_number: self.line_number,
+                buffer: buf,
+                bytes_range_in_buffer: range.start()..range.end(),
+            },
+        )?;
+        if !keepgoing {
+            return Ok(false);
+        }
+        self.last_line_visited = range.end();
+        Ok(true)
+    }
+
+    fn count_lines(&mut self, buf: &[u8], upto: usize) {
+        if let Some(ref mut line_number) = self.line_number {
+            if self.last_line_counted >= upto {
+                return;
+            }
+            let slice = &buf[self.last_line_counted..upto];
+            let count = lines::count(slice, self.config.line_term.as_byte());
+            *line_number += count;
+            self.last_line_counted = upto;
+        }
+    }
+
+    fn is_line_by_line_fast(&self) -> bool {
+        debug_assert!(!self.searcher.multi_line_with_matcher(&self.matcher));
+        if let Some(line_term) = self.matcher.line_terminator() {
+            if line_term.as_byte() == b'\x00' {
+                return false;
+            }
+            if line_term == self.config.line_term {
+                return true;
+            }
+        }
+        if let Some(non_matching) = self.matcher.non_matching_bytes()
+            && non_matching.contains(self.config.line_term.as_byte())
+        {
+            return true;
+        }
+        false
+    }
+}
@@ -0,0 +1,128 @@
+use grep_matcher::Matcher;
+
+use crate::{
+    lines,
+    searcher::{Config, Range, Searcher, core::Core},
+    sink::Sink,
+};
+
+#[derive(Debug)]
+pub(crate) struct SliceByLine<'s, M, S> {
+    core: Core<'s, M, S>,
+    slice: &'s [u8],
+}
+
+impl<'s, M: Matcher, S: Sink> SliceByLine<'s, M, S> {
+    pub(crate) fn new(
+        searcher: &'s Searcher,
+        matcher: M,
+        slice: &'s [u8],
+        write_to: S,
+    ) -> SliceByLine<'s, M, S> {
+        debug_assert!(!searcher.multi_line_with_matcher(&matcher));
+
+        SliceByLine {
+            core: Core::new(searcher, matcher, write_to),
+            slice,
+        }
+    }
+
+    pub(crate) fn run(mut self) -> Result<(), S::Error> {
+        if self.core.begin()? {
+            while !self.slice[self.core.pos()..].is_empty()
+                && self.core.match_by_line(self.slice)?
+            {}
+        }
+        let byte_count = self.slice.len() as u64;
+        self.core.finish(byte_count)
+    }
+}
+
+#[derive(Debug)]
+pub(crate) struct MultiLine<'s, M, S> {
+    config: &'s Config,
+    core: Core<'s, M, S>,
+    slice: &'s [u8],
+    last_match: Option<Range>,
+}
+
+impl<'s, M: Matcher, S: Sink> MultiLine<'s, M, S> {
+    pub(crate) fn new(
+        searcher: &'s Searcher,
+        matcher: M,
+        slice: &'s [u8],
+        write_to: S,
+    ) -> MultiLine<'s, M, S> {
+        debug_assert!(searcher.multi_line_with_matcher(&matcher));
+
+        MultiLine {
+            config: &searcher.config,
+            core: Core::new(searcher, matcher, write_to),
+            slice,
+            last_match: None,
+        }
+    }
+
+    pub(crate) fn run(mut self) -> Result<(), S::Error> {
+        if self.core.begin()? {
+            let mut keepgoing = true;
+            while !self.slice[self.core.pos()..].is_empty() && keepgoing {
+                keepgoing = self.sink()?;
+            }
+            if keepgoing && let Some(last_match) = self.last_match.take() {
+                self.sink_matched(&last_match)?;
+            }
+        }
+        let byte_count = self.slice.len() as u64;
+        self.core.finish(byte_count)
+    }
+
+    fn sink(&mut self) -> Result<bool, S::Error> {
+        let mat = match self.find()? {
+            Some(range) => range,
+            None => {
+                self.core.set_pos(self.slice.len());
+                return Ok(true);
+            }
+        };
+        self.advance(&mat);
+
+        let line = lines::locate(self.slice, self.config.line_term.as_byte(), mat);
+        match self.last_match.take() {
+            None => {
+                self.last_match = Some(line);
+                Ok(true)
+            }
+            Some(last_match) => {
+                if last_match.end() >= line.start() {
+                    self.last_match = Some(last_match.with_end(line.end()));
+                    Ok(true)
+                } else {
+                    self.last_match = Some(line);
+                    self.sink_matched(&last_match)
+                }
+            }
+        }
+    }
+
+    fn sink_matched(&mut self, range: &Range) -> Result<bool, S::Error> {
+        if range.is_empty() {
+            return Ok(false);
+        }
+        self.core.matched(self.slice, range)
+    }
+
+    fn find(&mut self) -> Result<Option<Range>, S::Error> {
+        self.core
+            .find(&self.slice[self.core.pos()..])
+            .map(|m| m.map(|m| m.offset(self.core.pos())))
+    }
+
+    fn advance(&mut self, range: &Range) {
+        self.core.set_pos(range.end());
+        if range.is_empty() && self.core.pos() < self.slice.len() {
+            let newpos = self.core.pos() + 1;
+            self.core.set_pos(newpos);
+        }
+    }
+}
@@ -0,0 +1,205 @@
+use grep_matcher::{LineTerminator, Match, Matcher};
+
+use crate::{
+    searcher::glue::{MultiLine, SliceByLine},
+    sink::{Sink, SinkError},
+};
+
+mod core;
+mod glue;
+
+/// We use this type alias since we want the ergonomics of a matcher's `Match`
+/// type, but in practice, we use it for arbitrary ranges, so give it a more
+/// accurate name. This is only used in the searcher's internals.
+type Range = Match;
+
+/// An error that can occur when building a searcher.
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[non_exhaustive]
+pub(crate) enum ConfigError {
+    /// Occurs when a matcher reports a line terminator that is different than
+    /// the one configured in the searcher.
+    MismatchedLineTerminators {
+        /// The matcher's line terminator.
+        matcher: LineTerminator,
+        /// The searcher's line terminator.
+        searcher: LineTerminator,
+    },
+}
+
+impl std::error::Error for ConfigError {}
+
+impl std::fmt::Display for ConfigError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match *self {
+            ConfigError::MismatchedLineTerminators { matcher, searcher } => {
+                write!(
+                    f,
+                    "grep config error: mismatched line terminators, \
+                     matcher has {:?} but searcher has {:?}",
+                    matcher, searcher
+                )
+            }
+        }
+    }
+}
+
+/// The internal configuration of a searcher.
+#[derive(Clone, Debug)]
+pub(crate) struct Config {
+    /// The line terminator to use.
+    pub(crate) line_term: LineTerminator,
+    /// Whether to count line numbers.
+    pub(crate) line_number: bool,
+    /// Whether to enable matching across multiple lines.
+    multi_line: bool,
+}
+
+impl Default for Config {
+    fn default() -> Config {
+        Config {
+            line_term: LineTerminator::default(),
+            line_number: true,
+            multi_line: false,
+        }
+    }
+}
+
+/// A builder for configuring a searcher.
+#[derive(Clone, Debug)]
+pub struct SearcherBuilder {
+    config: Config,
+}
+
+impl Default for SearcherBuilder {
+    fn default() -> SearcherBuilder {
+        SearcherBuilder::new()
+    }
+}
+
+impl SearcherBuilder {
+    /// Create a new searcher builder with a default configuration.
+    pub fn new() -> SearcherBuilder {
+        SearcherBuilder {
+            config: Config::default(),
+        }
+    }
+
+    /// Build a searcher.
+    pub fn build(&self) -> Searcher {
+        Searcher {
+            config: self.config.clone(),
+        }
+    }
+
+    /// Whether to count and include line numbers with matching lines.
+    pub fn line_number(&mut self, yes: bool) -> &mut SearcherBuilder {
+        self.config.line_number = yes;
+        self
+    }
+
+    /// Whether to enable multi line search or not.
+    pub fn multi_line(&mut self, yes: bool) -> &mut SearcherBuilder {
+        self.config.multi_line = yes;
+        self
+    }
+}
+
+/// A searcher executes searches over a haystack and writes results to a caller
+/// provided sink.
+#[derive(Clone, Debug)]
+pub struct Searcher {
+    pub(crate) config: Config,
+}
+
+impl Searcher {
+    /// Create a new searcher with a default configuration.
+    pub fn new() -> Searcher {
+        SearcherBuilder::new().build()
+    }
+
+    /// Execute a search over the given slice and write the results to the
+    /// given sink.
+    pub fn search_slice<M, S>(
+        &mut self,
+        matcher: M,
+        slice: &[u8],
+        write_to: S,
+    ) -> Result<(), S::Error>
+    where
+        M: Matcher,
+        S: Sink,
+    {
+        self.check_config(&matcher)
+            .map_err(S::Error::error_message)?;
+
+        if self.multi_line_with_matcher(&matcher) {
+            MultiLine::new(self, matcher, slice, write_to).run()
+        } else {
+            SliceByLine::new(self, matcher, slice, write_to).run()
+        }
+    }
+
+    /// Check that the searcher's configuration and the matcher are consistent.
+    fn check_config<M: Matcher>(&self, matcher: M) -> Result<(), ConfigError> {
+        let matcher_line_term = match matcher.line_terminator() {
+            None => return Ok(()),
+            Some(line_term) => line_term,
+        };
+        if matcher_line_term != self.config.line_term {
+            return Err(ConfigError::MismatchedLineTerminators {
+                matcher: matcher_line_term,
+                searcher: self.config.line_term,
+            });
+        }
+        Ok(())
+    }
+}
+
+impl Default for Searcher {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Configuration query methods used by the sink and internal search core.
+impl Searcher {
+    /// Returns the line terminator used by this searcher.
+    #[inline]
+    pub fn line_terminator(&self) -> LineTerminator {
+        self.config.line_term
+    }
+
+    /// Returns true if and only if this searcher is configured to count line
+    /// numbers.
+    #[inline]
+    pub fn line_number(&self) -> bool {
+        self.config.line_number
+    }
+
+    /// Returns true if and only if this searcher is configured to perform
+    /// multi line search.
+    #[inline]
+    pub fn multi_line(&self) -> bool {
+        self.config.multi_line
+    }
+
+    /// Returns true if and only if this searcher will choose a multi-line
+    /// strategy given the provided matcher.
+    pub fn multi_line_with_matcher<M: Matcher>(&self, matcher: M) -> bool {
+        if !self.multi_line() {
+            return false;
+        }
+        if let Some(line_term) = matcher.line_terminator()
+            && line_term == self.line_terminator()
+        {
+            return false;
+        }
+        if let Some(non_matching) = matcher.non_matching_bytes()
+            && non_matching.contains(self.line_terminator().as_byte())
+        {
+            return false;
+        }
+        true
+    }
+}
@@ -0,0 +1,138 @@
+use std::io;
+
+use crate::searcher::Searcher;
+
+/// A trait that describes errors that can be reported by searchers and
+/// implementations of `Sink`.
+pub trait SinkError: Sized {
+    /// A constructor for converting any value that satisfies the
+    /// `std::fmt::Display` trait into an error.
+    fn error_message<T: std::fmt::Display>(message: T) -> Self;
+
+    /// A constructor for converting I/O errors that occur while searching into
+    /// an error of this type.
+    fn error_io(err: io::Error) -> Self {
+        Self::error_message(err)
+    }
+}
+
+impl SinkError for io::Error {
+    fn error_message<T: std::fmt::Display>(message: T) -> io::Error {
+        io::Error::other(message.to_string())
+    }
+
+    fn error_io(err: io::Error) -> io::Error {
+        err
+    }
+}
+
+/// A trait that defines how results from searchers are handled.
+///
+/// The searcher follows the "push" model: the searcher drives execution and
+/// pushes results back to the caller via this trait.
+pub trait Sink {
+    /// The type of an error that should be reported by a searcher.
+    type Error: SinkError;
+
+    /// This method is called whenever a match is found.
+    ///
+    /// If this returns `true`, then searching continues. If this returns
+    /// `false`, then searching is stopped immediately and `finish` is called.
+    fn matched(&mut self, _searcher: &Searcher, _mat: &SinkMatch<'_>) -> Result<bool, Self::Error>;
+
+    /// This method is called when a search has begun, before any search is
+    /// executed. By default, this does nothing.
+    #[inline]
+    fn begin(&mut self, _searcher: &Searcher) -> Result<bool, Self::Error> {
+        Ok(true)
+    }
+
+    /// This method is called when a search has completed. By default, this
+    /// does nothing.
+    #[inline]
+    fn finish(&mut self, _searcher: &Searcher, _: &SinkFinish) -> Result<(), Self::Error> {
+        Ok(())
+    }
+}
+
+impl<S: Sink> Sink for &mut S {
+    type Error = S::Error;
+
+    #[inline]
+    fn matched(&mut self, searcher: &Searcher, mat: &SinkMatch<'_>) -> Result<bool, S::Error> {
+        (**self).matched(searcher, mat)
+    }
+
+    #[inline]
+    fn begin(&mut self, searcher: &Searcher) -> Result<bool, S::Error> {
+        (**self).begin(searcher)
+    }
+
+    #[inline]
+    fn finish(&mut self, searcher: &Searcher, sink_finish: &SinkFinish) -> Result<(), S::Error> {
+        (**self).finish(searcher, sink_finish)
+    }
+}
+
+/// Summary data reported at the end of a search.
+#[derive(Clone, Debug)]
+pub struct SinkFinish {
+    pub(crate) byte_count: u64,
+}
+
+impl SinkFinish {
+    /// Return the total number of bytes searched.
+    #[inline]
+    pub fn byte_count(&self) -> u64 {
+        self.byte_count
+    }
+}
+
+/// A type that describes a match reported by a searcher.
+#[derive(Clone, Debug)]
+pub struct SinkMatch<'b> {
+    pub(crate) bytes: &'b [u8],
+    pub(crate) absolute_byte_offset: u64,
+    pub(crate) line_number: Option<u64>,
+    pub(crate) buffer: &'b [u8],
+    pub(crate) bytes_range_in_buffer: std::ops::Range<usize>,
+}
+
+impl<'b> SinkMatch<'b> {
+    /// Returns the bytes for all matching lines, including the line
+    /// terminators, if they exist.
+    #[inline]
+    pub fn bytes(&self) -> &'b [u8] {
+        self.bytes
+    }
+
+    /// Returns the absolute byte offset of the start of this match. This
+    /// offset is absolute in that it is relative to the very beginning of the
+    /// input in a search.
+    #[inline]
+    pub fn absolute_byte_offset(&self) -> u64 {
+        self.absolute_byte_offset
+    }
+
+    /// Returns the line number of the first line in this match, if available.
+    ///
+    /// Line numbers are only available when the search builder is instructed
+    /// to compute them.
+    #[inline]
+    pub fn line_number(&self) -> Option<u64> {
+        self.line_number
+    }
+
+    /// Exposes as much of the underlying buffer that was searched as possible.
+    #[inline]
+    pub fn buffer(&self) -> &'b [u8] {
+        self.buffer
+    }
+
+    /// Returns a range that corresponds to where [`SinkMatch::bytes`] appears
+    /// in [`SinkMatch::buffer`].
+    #[inline]
+    pub fn bytes_range_in_buffer(&self) -> std::ops::Range<usize> {
+        self.bytes_range_in_buffer.clone()
+    }
+}
@@ -1,4 +1,4 @@
-*fff.nvim.txt*        For Neovim >= 0.10.0       Last change: 2026 February 07
+*fff.nvim.txt*        For Neovim >= 0.10.0       Last change: 2026 February 16

 ==============================================================================
 Table of Contents                                 *fff.nvim-table-of-contents*
@@ -74,6 +74,20 @@ LAZY.NVIM
          "ff", -- try it if you didn't it is a banger keybinding for a picker
          function() require('fff').find_files() end,
          desc = 'FFFind files',
+        },
+        {
+          "fg",
+          function() require('fff').live_grep() end,
+          desc = 'LiFFFe grep',
+        },
+        {
+          "fz",
+          function() require('fff').live_grep({
+        grep = {
+          modes = { 'fuzzy', 'plain' }
+        }
+          }) end,
+          desc = 'Live fffuzy grep',
        }
      }
    }
@@ -169,6 +183,8 @@ all available options:
          -- multi-select keymaps for quickfix
          toggle_select = '<Tab>',
          send_to_quickfix = '<C-q>',
+          -- grep mode: cycle between plain text, regex, and fuzzy search
+          toggle_grep_regex = '<S-Tab>',
        },
        hl = {
          border = 'FloatBorder',
@@ -207,6 +223,13 @@ all available options:
          git_sign_renamed_selected = 'FFFGitSignRenamedSelected',
          git_sign_untracked_selected = 'FFFGitSignUntrackedSelected',
          git_sign_ignored_selected = 'FFFGitSignIgnoredSelected',
+          -- Grep highlights
+          grep_match = 'IncSearch',               -- Highlight for matched text in grep results
+          grep_line_number = 'LineNr',            -- Highlight for :line:col location
+          grep_regex_active = 'DiagnosticInfo',   -- Highlight for keybind + label when regex is on
+          grep_regex_inactive = 'Comment',        -- Highlight for keybind + label when regex is off
+          -- Cross-mode suggestion highlights
+          suggestion_header = 'WarningMsg',       -- Highlight for the "No results found. Suggested..." banner
        },
        -- Store file open frecency
        frecency = {
@@ -233,6 +256,14 @@ all available options:
          enabled = true,
          log_file = vim.fn.stdpath('log') .. '/fff.log',
          log_level = 'info',
+        },
+        -- Live grep search configuration
+        grep = {
+          max_file_size = 10 * 1024 * 1024, -- Skip files larger than 10MB
+          max_matches_per_file = 200, -- Maximum matches per file
+          smart_case = true, -- Case-insensitive unless query has uppercase
+          time_budget_ms = 150, -- Max search time in ms per call (prevents UI freeze, 0 = no limit)
+          modes = { 'plain', 'regex', 'fuzzy' }, -- Available grep modes and their cycling order
        }
    })
 <
@@ -291,6 +322,66 @@ configurable):
 - `<C-q>` - Send selected files to quickfix list and close picker


+LIVE GREP SEARCH MODES
+
+Live grep supports three search modes, cycled with `<S-Tab>`:
+
+- **Plain text** (default) - The query is matched literally. Special regex characters like `.`, `*`, `(`, `)`, `$` have no special meaning. This is the safest mode for searching code containing regex metacharacters.
+- **Regex** - The query is interpreted as a regular expression. Supports character classes (`[a-z]`), quantifiers (`+`, `*`, `{n}`), alternation (`foo|bar`), anchors (`^`, `$`), word boundaries (`\b`), and more.
+- **Fuzzy** - The query is fuzzy matched using Smith-Waterman scoring. Accommodates typos and scattered characters (e.g., "mtxlk" matches "mutex_lock"). Results are filtered by a quality threshold to avoid overly fuzzy matches.
+
+The current mode is shown on the right side of the input field (e.g., `plain`,
+`regex`, `fuzzy`) with color-coded highlighting.
+
+You can customize which modes are available and their cycling order globally in
+your configuration, or per-call when invoking `live_grep()`.
+
+**Global configuration:**
+
+>lua
+    require('fff').setup({
+      grep = {
+        modes = { 'plain', 'regex' }, -- Only plain and regex, no fuzzy
+      }
+    })
+<
+
+**Per-call configuration:**
+
+>lua
+    -- Only fuzzy and plain modes for this specific grep
+    require('fff').live_grep({
+      grep = {
+        modes = { 'fuzzy', 'plain' },
+      }
+    })
+    
+    -- Single mode (hides mode indicator completely)
+    require('fff').live_grep({
+      grep = {
+        modes = { 'fuzzy' },
+      }
+    })
+<
+
+When only one mode is configured, the mode indicator is hidden completely and
+the cycle keybind does nothing.
+
+
+CROSS-MODE SUGGESTIONS
+
+When a search returns no results, FFF automatically queries the opposite search
+mode and displays the results as suggestions:
+
+- **File search with no matches** → shows suggested **content matches** (grep results) for the same query
+- **Grep search with no matches** → shows suggested **file name matches** for the same query
+
+Suggestions are clearly labeled with a "No results found. Suggested …" banner
+(highlighted with `hl.suggestion_header`). You can navigate and select
+suggestion items just like normal results — selecting a grep suggestion will
+open the file at the matching line.
+
+
 GIT STATUS HIGHLIGHTING

 FFF integrates with git to show file status through sign column indicators
@@ -64,11 +64,11 @@
        ]
      },
      "locked": {
-        "lastModified": 1767926800,
-        "narHash": "sha256-x0n73J6ufD/EhDlVdcoAmF0OQHZ+b0a2cKDc8RZyt+o=",
+        "lastModified": 1770865833,
+        "narHash": "sha256-oiARqnlvaW6pVGheVi4ye6voqCwhg5hCcGish2ZvQzI=",
        "owner": "oxalica",
        "repo": "rust-overlay",
-        "rev": "499e9eed88ff9494b6604205b42847e847dfeb91",
+        "rev": "c8cfbe26238638e2f3a2c0ae7e8d240f5e4ded85",
        "type": "github"
      },
      "original": {
@@ -41,18 +41,19 @@
          src = craneLib.cleanCargoSource ./.;
          strictDeps = true;

-          nativeBuildInputs = [ pkgs.pkg-config pkgs.perl ];
+          nativeBuildInputs = [ pkgs.pkg-config pkgs.perl pkgs.zig pkgs.llvmPackages.libclang.lib ];
          buildInputs = with pkgs; [
            # Add additional build inputs here
            openssl
          ];
+          LIBCLANG_PATH = "${pkgs.llvmPackages.libclang.lib}/lib";
        };

        my-crate = craneLib.buildPackage (
          commonArgs
          // {
            cargoArtifacts = craneLib.buildDepsOnly commonArgs;
-
+            doCheck = false;
          }
        );
        # Copies the dynamic library into the target/release folder
@@ -146,6 +146,7 @@ local function init()
      send_to_quickfix = '<C-q>',
      focus_list = '<leader>l',
      focus_preview = '<leader>p',
+      toggle_grep_regex = '<S-Tab>',
    },
    hl = {
      border = 'FloatBorder',
@@ -184,6 +185,14 @@ local function init()
      git_sign_renamed_selected = 'FFFGitSignRenamedSelected',
      git_sign_untracked_selected = 'FFFGitSignUntrackedSelected',
      git_sign_ignored_selected = 'FFFGitSignIgnoredSelected',
+      -- Grep highlights
+      grep_match = 'IncSearch', -- Highlight for matched text in grep results
+      grep_line_number = 'LineNr', -- Highlight for :line:col location in grep results
+      grep_regex_active = 'DiagnosticInfo', -- Highlight for keybind + label when regex is on
+      grep_regex_inactive = 'Comment', -- Highlight for keybind + label when regex is off (plain mode)
+      grep_fuzzy_active = 'DiagnosticHint', -- Highlight for keybind + label when fuzzy is on
+      -- Cross-mode suggestion highlights
+      suggestion_header = 'WarningMsg', -- Highlight for the "No results found. Suggested..." banner
    },
    frecency = {
      enabled = true,
@@ -208,6 +217,13 @@ local function init()
      log_file = vim.fn.stdpath('log') .. '/fff.log',
      log_level = 'info',
    },
+    grep = {
+      max_file_size = 10 * 1024 * 1024, -- Skip files larger than 10MB
+      max_matches_per_file = 200, -- Maximum matches per file
+      smart_case = true, -- Case-insensitive unless query has uppercase
+      time_budget_ms = 150, -- Max search time in ms per call (prevents UI freeze, 0 = no limit)
+      modes = { 'plain', 'regex', 'fuzzy' }, -- Available grep modes and their cycling order
+    },
  }

  local migrated_user_config = handle_deprecated_config(config)
@@ -230,6 +246,7 @@ end
 function M.toggle_debug()
  local old_debug_state = state.config.debug.show_scores
  state.config.debug.show_scores = not state.config.debug.show_scores
+  state.config.debug.show_file_info = state.config.debug.show_scores
  local status = state.config.debug.show_scores and 'enabled' or 'disabled'
  vim.notify('FFF debug scores ' .. status, vim.log.levels.INFO)
  return old_debug_state ~= state.config.debug.show_scores
@@ -71,6 +71,32 @@ local function cleanup_file_operation()
  end
 end

+--- Process raw chunk data into complete lines, joining any leftover bytes
+--- from the previous chunk and storing any trailing partial line for the next.
+--- @param data string Raw chunk data
+--- @return string[] Complete lines (may be empty if the entire chunk is a partial line)
+local function split_chunk_with_remainder(data)
+  if not data or data == '' then return {} end
+
+  local fo = M.state.file_operation
+  local prefix = fo and fo.remainder or ''
+  local combined = prefix .. data
+
+  local lines = vim.split(combined, '\n', { plain = true })
+
+  if combined:sub(-1) ~= '\n' then
+    -- Data doesn't end on a line boundary: last element is a partial line
+    local partial = table.remove(lines) or ''
+    if fo then fo.remainder = partial end
+  else
+    -- Data ends on a line boundary: remove the trailing empty element
+    if #lines > 0 and lines[#lines] == '' then table.remove(lines) end
+    if fo then fo.remainder = '' end
+  end
+
+  return lines
+end
+
 local function init_dynamic_loading_async(file_path, callback)
  cleanup_file_operation()

@@ -79,7 +105,15 @@ local function init_dynamic_loading_async(file_path, callback)
  M.state.has_more_content = true
  M.state.is_loading = false

+  local generation = M.state.preview_generation
+
  vim.uv.fs_open(file_path, 'r', 438, function(err, fd)
+    -- Stale callback: preview moved on to a different file
+    if M.state.preview_generation ~= generation then
+      if fd then pcall(vim.uv.fs_close, fd) end
+      return
+    end
+
    if err or not fd then
      callback(false, 'Failed to open file: ' .. (err or 'unknown error'))
      return
@@ -89,6 +123,7 @@ local function init_dynamic_loading_async(file_path, callback)
      fd = fd,
      file_path = file_path,
      position = 0,
+      remainder = '',
    }

    callback(true)
@@ -103,9 +138,13 @@ local function load_forward_chunk_async(target_size, callback)

  M.state.is_loading = true
  local chunk_size = target_size or (M.config.chunk_size or 16384)
+  local generation = M.state.preview_generation

  vim.uv.fs_read(M.state.file_operation.fd, chunk_size, M.state.file_operation.position, function(err, data)
    vim.schedule(function()
+      -- Stale callback: a newer preview has started, discard this result
+      if M.state.preview_generation ~= generation then return end
+
      M.state.is_loading = false

      if err then
@@ -115,8 +154,14 @@ local function load_forward_chunk_async(target_size, callback)

      if not data or #data == 0 then
        M.state.has_more_content = false
+        -- Flush any remaining partial line as the final piece of data
+        local final_remainder = M.state.file_operation and M.state.file_operation.remainder or ''
        cleanup_file_operation()
-        callback('', nil)
+        if final_remainder ~= '' then
+          callback(final_remainder .. '\n', nil)
+        else
+          callback('', nil)
+        end
        return
      end

@@ -135,8 +180,15 @@ local function load_next_chunk_async(chunk_size, callback)
  load_forward_chunk_async(chunk_size, callback)
 end

+-- Forward declaration for ensure_content_loaded_async (used in read_file_streaming_async callback)
+local ensure_content_loaded_async
+
 local function read_file_streaming_async(file_path, bufnr, callback)
+  local generation = M.state.preview_generation
+
  init_dynamic_loading_async(file_path, function(success, error_msg)
+    if M.state.preview_generation ~= generation then return end
+
    if not success then
      callback(nil, error_msg)
      return
@@ -159,22 +211,26 @@ local function read_file_streaming_async(file_path, bufnr, callback)
    end

    load_next_chunk_async(initial_chunk_size, function(data, err)
+      if M.state.preview_generation ~= generation then return end
+
      if data and data ~= '' then
-        -- there seems to be no other way to append the buffer other than the lines :(
-        local lines = vim.split(data, '\n', { plain = true })
+        local lines = split_chunk_with_remainder(data)
        M.state.loaded_lines = #lines
        M.state.content_height = #lines

        -- If we have a location and didn't load enough lines, try to load more
+        local loading_more = false
        if M.state.location then
          local target_line = location_utils.get_target_line(M.state.location)
          if target_line and #lines < target_line and M.state.has_more_content then
-            -- Schedule additional loading after the initial callback
-            vim.schedule(function() ensure_content_loaded_async(target_line) end)
+            loading_more = true
+            vim.schedule(function()
+              if M.state.preview_generation == generation then ensure_content_loaded_async(target_line) end
+            end)
          end
        end

-        callback(lines, err)
+        callback(lines, err, loading_more)
      else
        callback(nil, err)
      end
@@ -182,7 +238,7 @@ local function read_file_streaming_async(file_path, bufnr, callback)
  end)
 end

-local function ensure_content_loaded_async(target_line)
+ensure_content_loaded_async = function(target_line)
  if not M.state.bufnr or not vim.api.nvim_buf_is_valid(M.state.bufnr) then return end
  if not M.state.has_more_content or M.state.is_loading then return end

@@ -191,46 +247,39 @@ local function ensure_content_loaded_async(target_line)

  if current_buffer_lines >= buffer_needed then return end

-  if current_buffer_lines < buffer_needed then
-    local loading_line = string.format('Loading more content... (%d lines loaded)', M.state.loaded_lines)
-    append_buffer_lines(M.state.bufnr, { '', loading_line })
-  end
+  local generation = M.state.preview_generation

-  load_next_chunk_async(M.config.chunk_size, function(data, err)
-    if err then
-      vim.notify('Error loading file content: ' .. err, vim.log.levels.ERROR)
-      -- Remove loading message on error
-      local total_lines = vim.api.nvim_buf_line_count(M.state.bufnr)
-      if total_lines >= 2 then
-        local existing_lines = vim.api.nvim_buf_get_lines(M.state.bufnr, 0, total_lines - 2, false)
-        set_buffer_lines(M.state.bufnr, existing_lines)
-      end
-      return
-    end
+  -- Use a larger chunk to reach the target faster instead of many small 8KB reads
+  local lines_needed = buffer_needed - current_buffer_lines
+  local estimated_bytes = math.max(M.config.chunk_size, lines_needed * 120)
+
+  load_next_chunk_async(estimated_bytes, function(data, err)
+    -- Stale callback: preview moved on to a different file
+    if M.state.preview_generation ~= generation then return end
+    if not M.state.bufnr or not vim.api.nvim_buf_is_valid(M.state.bufnr) then return end
+
+    if err then return end

    if data and data ~= '' then
-      local chunk_lines = vim.split(data, '\n', { plain = true })
-      local total_lines = vim.api.nvim_buf_line_count(M.state.bufnr)
-
-      if total_lines >= 2 then
-        local existing_lines = vim.api.nvim_buf_get_lines(M.state.bufnr, 0, total_lines - 2, false)
-        local new_content = vim.list_extend(existing_lines, chunk_lines)
-        set_buffer_lines(M.state.bufnr, new_content)
-      else
-        append_buffer_lines(M.state.bufnr, chunk_lines)
-      end
+      local chunk_lines = split_chunk_with_remainder(data)
+      if #chunk_lines > 0 then append_buffer_lines(M.state.bufnr, chunk_lines) end

      M.state.content_height = vim.api.nvim_buf_line_count(M.state.bufnr)
      M.state.loaded_lines = M.state.content_height
-    else
-      -- No more data available - remove the loading message
-      local total_lines = vim.api.nvim_buf_line_count(M.state.bufnr)
-      if total_lines >= 2 then
-        local existing_lines = vim.api.nvim_buf_get_lines(M.state.bufnr, 0, total_lines - 2, false)
-        set_buffer_lines(M.state.bufnr, existing_lines)
-        M.state.content_height = #existing_lines
-        M.state.loaded_lines = M.state.content_height
+
+      -- If we still haven't loaded enough, schedule another chunk
+      if M.state.loaded_lines < buffer_needed and M.state.has_more_content then
+        vim.schedule(function()
+          if M.state.preview_generation == generation then ensure_content_loaded_async(target_line) end
+        end)
+      else
+        -- Enough content loaded — re-apply location highlighting so the
+        -- preview scrolls to the correct line now that it exists in the buffer
+        M.apply_location_highlighting(M.state.bufnr)
      end
+    else
+      -- EOF with no additional data — apply highlighting with whatever we have
+      M.apply_location_highlighting(M.state.bufnr)
    end
  end)
 end
@@ -267,6 +316,7 @@ M.state = {
  file_operation = nil, -- Ongoing file operation: {fd?: any, file_path?: string, position?: number}
  location = nil, -- Current location data for highlighting
  location_namespace = nil, -- Namespace for location highlighting
+  preview_generation = 0, -- Monotonically increasing token to detect stale async callbacks
 }

 --- Setup preview configuration
@@ -291,166 +341,6 @@ function M.is_big_file(file_path, bufnr)
  return false
 end

--- Check if file is binary (async version)
--- @param file_path string Path to the file
--- @param callback function Callback with (is_binary: boolean)
-function M.is_binary_file_async(file_path, callback)
-  local ext = vim.fn.fnamemodify(file_path, ':e')
-  local binary_extensions = {
-    'jpg',
-    'jpeg',
-    'png',
-    'gif',
-    'bmp',
-    'tiff',
-    'tif',
-    'webp',
-    'ico',
-    'pdf',
-    'ps',
-    'eps',
-    'heic',
-    'avif',
-    -- Archives
-    'zip',
-    'rar',
-    '7z',
-    'tar',
-    'gz',
-    'bz2',
-    'xz',
-    -- Executables
-    'exe',
-    'dll',
-    'so',
-    'dylib',
-    'bin',
-    -- Audio/Video
-    'mp3',
-    'mp4',
-    'avi',
-    'mkv',
-    'wav',
-    'flac',
-    'ogg',
-    -- Other binary formats
-    'db',
-    'sqlite',
-    'dat',
-    'bin',
-    'iso',
-  }
-
-  for _, binary_ext in ipairs(binary_extensions) do
-    if ext == binary_ext then
-      callback(true)
-      return
-    end
-  end
-
-  if M.config.binary_file_threshold <= 0 then
-    callback(false)
-    return
-  end
-
-  vim.uv.fs_open(file_path, 'r', 438, function(err, fd)
-    if err or not fd then
-      callback(false)
-      return
-    end
-
-    vim.uv.fs_read(fd, M.config.binary_file_threshold, 0, function(read_err, chunk)
-      vim.uv.fs_close(fd)
-
-      vim.schedule(function()
-        if read_err or not chunk then
-          callback(false)
-          return
-        end
-
-        if chunk:find('\0') then
-          callback(true)
-          return
-        end
-
-        local printable_count = 0
-        local total_count = #chunk
-
-        for i = 1, total_count do
-          local byte = chunk:byte(i)
-          -- Printable ASCII range + common control chars (tab, newline, carriage return)
-          if (byte >= 32 and byte <= 126) or byte == 9 or byte == 10 or byte == 13 then
-            printable_count = printable_count + 1
-          end
-        end
-
-        local printable_ratio = printable_count / total_count
-        callback(printable_ratio < 0.8) -- More aggressive: If less than 80% printable, consider binary
-      end)
-    end)
-  end)
-end
-
--- Check if file is binary (sync version kept for compatibility)
--- @param file_path string Path to the file
--- @return boolean True if file appears to be binary
-function M.is_binary_file(file_path)
-  local ext = vim.fn.fnamemodify(file_path, ':e')
-  local binary_extensions = {
-    'jpg',
-    'jpeg',
-    'png',
-    'gif',
-    'bmp',
-    'tiff',
-    'tif',
-    'webp',
-    'ico',
-    'pdf',
-    'ps',
-    'eps',
-    'heic',
-    'avif',
-    -- Archives
-    'zip',
-    'rar',
-    '7z',
-    'tar',
-    'gz',
-    'bz2',
-    'xz',
-    -- Executables
-    'exe',
-    'dll',
-    'so',
-    'dylib',
-    'bin',
-    -- Audio/Video
-    'mp3',
-    'mp4',
-    'avi',
-    'mkv',
-    'wav',
-    'flac',
-    'ogg',
-    'aac',
-    -- Other binary formats
-    'db',
-    'sqlite',
-    'dat',
-    'bin',
-    'iso',
-  }
-
-  for _, binary_ext in ipairs(binary_extensions) do
-    if ext == binary_ext then return true end
-  end
-
-  -- For sync version, just return false for unknown extensions to avoid blocking
-  -- The main preview logic will handle this with async detection
-  return false
-end
-
 --- Get file information
 --- @param file_path string Path to the file
 --- @return table | nil File information
@@ -536,6 +426,48 @@ function M.create_file_info_content(file, info, file_index)
  return lines
 end

+--- Create file info content for grep mode items.
+--- Shows grep-specific metadata: match location, frecency, file info.
+---@param item table Grep match item with file + match metadata
+---@param info table File system information from get_file_info
+---@return table Lines for the file info content
+function M.create_grep_file_info_content(item, info)
+  local lines = {}
+
+  -- Match location info
+  local match_count = item.match_ranges and #item.match_ranges or 0
+  table.insert(
+    lines,
+    string.format('Match: line %d, col %d │ Ranges: %d', item.line_number or 0, (item.col or 0) + 1, match_count)
+  )
+  table.insert(
+    lines,
+    string.format('Byte Offset: %-12d │ Size: %s', item.byte_offset or 0, info.size_formatted or 'N/A')
+  )
+  table.insert(lines, string.format('Type: %-8s │ Git: %s', info.filetype or 'text', item.git_status or 'clean'))
+
+  -- Fuzzy match score (only available in fuzzy grep mode)
+  if item.fuzzy_score then table.insert(lines, string.format('Fuzzy Score: %d', item.fuzzy_score)) end
+
+  -- Frecency info
+  local total = item.total_frecency_score or 0
+  local acc = item.access_frecency_score or 0
+  local mod = item.modification_frecency_score or 0
+  table.insert(lines, string.format('Frecency: total=%d, access=%d, modification=%d', total, acc, mod))
+
+  -- Ordering explanation
+  table.insert(lines, 'Order: files sorted by frecency desc, matches by line asc')
+  table.insert(lines, '')
+
+  -- Time information section
+  table.insert(lines, 'TIMINGS')
+  table.insert(lines, string.rep('─', 50))
+  table.insert(lines, string.format('Modified: %s', info.modified_formatted or 'N/A'))
+  table.insert(lines, string.format('Last Access: %s', info.accessed_formatted or 'N/A'))
+
+  return lines
+end
+
 --- Preview a regular file
 --- @param file_path string Path to the file
 --- @param bufnr number Buffer number for preview
@@ -573,12 +505,14 @@ function M.preview_file(file_path, bufnr)
      vim.api.nvim_buf_set_option(bufnr, 'readonly', true)
      vim.api.nvim_buf_set_option(bufnr, 'buftype', 'nofile')
      vim.api.nvim_buf_set_option(bufnr, 'wrap', file_config.wrap_lines or M.config.wrap_lines)
-      vim.api.nvim_buf_set_option(bufnr, 'number', M.config.line_numbers)

      M.state.scroll_offset = 0

      -- Apply location highlighting if available (delayed to ensure buffer is ready)
-      vim.schedule(function() M.apply_location_highlighting(bufnr) end)
+      local gen = M.state.preview_generation
+      vim.schedule(function()
+        if M.state.preview_generation == gen then M.apply_location_highlighting(bufnr) end
+      end)

      return true
    end
@@ -586,10 +520,11 @@ function M.preview_file(file_path, bufnr)

  M.state.current_file = file_path
  M.state.bufnr = bufnr
+  local generation = M.state.preview_generation

-  read_file_streaming_async(file_path, bufnr, function(content, err)
-    if M.state.current_file ~= file_path then
-      -- User has moved to a different file, ignore this result
+  read_file_streaming_async(file_path, bufnr, function(content, err, loading_more)
+    if M.state.preview_generation ~= generation then
+      -- Preview moved on to a different file, discard
      cleanup_file_operation()
      return
    end
@@ -602,6 +537,9 @@ function M.preview_file(file_path, bufnr)
    end

    if M.state.current_file == file_path then
+      -- Guard against buffer being destroyed while async read was in-flight
+      if not vim.api.nvim_buf_is_valid(bufnr) then return end
+
      M.clear_preview_visual_state(bufnr)
      set_buffer_lines(bufnr, content)

@@ -611,13 +549,18 @@ function M.preview_file(file_path, bufnr)
      vim.api.nvim_buf_set_option(bufnr, 'readonly', true)
      vim.api.nvim_buf_set_option(bufnr, 'buftype', 'nofile')
      vim.api.nvim_buf_set_option(bufnr, 'wrap', file_config.wrap_lines or M.config.wrap_lines)
-      vim.api.nvim_buf_set_option(bufnr, 'number', M.config.line_numbers)

      M.state.content_height = #content
      M.state.scroll_offset = 0

-      -- Apply location highlighting if available (delayed to ensure buffer is ready)
-      vim.schedule(function() M.apply_location_highlighting(bufnr) end)
+      -- Apply location highlighting if available (delayed to ensure buffer is ready).
+      -- Skip when more content is being loaded asynchronously to reach the target line —
+      -- ensure_content_loaded_async will re-apply highlighting once the target is in the buffer.
+      if not loading_more then
+        vim.schedule(function()
+          if M.state.preview_generation == generation then M.apply_location_highlighting(bufnr) end
+        end)
+      end
    end
  end)

@@ -693,15 +636,13 @@ end
 --- @param file_path string Path to the file or directory
 --- @param bufnr number Buffer number for preview
 --- @param location table|nil Optional location data for highlighting
+--- @param is_binary boolean|nil Whether the file is binary (from Rust indexer)
 --- @return boolean if the preview was successful
-function M.preview(file_path, bufnr, location)
-  if not file_path or file_path == '' then
-    -- Don't immediately clear - let the previous content stay visible
-    -- Only clear if we really need to show "No file selected"
-    -- M.clear_buffer(bufnr)
-    -- set_buffer_lines(bufnr, { 'No file selected' })
-    return false
-  end
+function M.preview(file_path, bufnr, location, is_binary)
+  if not file_path or file_path == '' then return false end
+
+  -- Bump generation to invalidate any in-flight async callbacks from previous previews
+  M.state.preview_generation = M.state.preview_generation + 1

  if M.state.file_handle then
    M.state.file_handle:close()
@@ -726,7 +667,7 @@ function M.preview(file_path, bufnr, location)
    local win_height = vim.api.nvim_win_get_height(M.state.winid) - 2

    return image.display_image(file_path, bufnr, win_width, win_height)
-  elseif M.is_binary_file(file_path) then
+  elseif is_binary then
    return M.preview_binary_file(file_path, bufnr)
  else
    return M.preview_file(file_path, bufnr)
@@ -778,8 +719,9 @@ end
 function M.set_preview_window(winid) M.state.winid = winid end

 --- Update file info buffer
--- @param file table File information from search results
+--- @param file table File information from search results (or grep match item)
 --- @param bufnr number Buffer number for file info
+--- @param file_index number|nil Index of the file in search results (for score lookup, file mode only)
 --- @return boolean Success status
 function M.update_file_info_buffer(file, bufnr, file_index)
  if not file then
@@ -793,7 +735,13 @@ function M.update_file_info_buffer(file, bufnr, file_index)
    return false
  end

-  local file_info_lines = M.create_file_info_content(file, info, file_index)
+  -- Detect grep mode items by the presence of line_number (grep-specific field)
+  local file_info_lines
+  if file.line_number ~= nil then
+    file_info_lines = M.create_grep_file_info_content(file, info)
+  else
+    file_info_lines = M.create_file_info_content(file, info, file_index)
+  end
  set_buffer_lines(bufnr, file_info_lines)

  vim.api.nvim_buf_set_option(bufnr, 'modifiable', false)
@@ -848,6 +796,9 @@ function M.clear_buffer(bufnr)
 end

 function M.clear()
+  -- Bump generation to invalidate any in-flight async callbacks
+  M.state.preview_generation = M.state.preview_generation + 1
+
  cleanup_file_operation()

  M.state.loaded_lines = 0
@@ -883,7 +834,16 @@ function M.apply_location_highlighting(bufnr)

  if M.state.winid and vim.api.nvim_win_is_valid(M.state.winid) then
    local target_line = location_utils.get_target_line(M.state.location)
-    if target_line then M.scroll_to_line(target_line) end
+    if target_line then
+      local buffer_lines = vim.api.nvim_buf_line_count(bufnr)
+      if target_line > buffer_lines and M.state.has_more_content then
+        -- Target line is beyond loaded content — load more first.
+        -- ensure_content_loaded_async will re-apply highlighting when done.
+        ensure_content_loaded_async(target_line)
+        return
+      end
+      M.scroll_to_line(target_line)
+    end
  end
 end

@@ -38,5 +38,17 @@ M.init_query_db = rust_module.init_query_db
 M.destroy_query_db = rust_module.destroy_query_db
 M.track_query_completion = rust_module.track_query_completion
 M.get_historical_query = rust_module.get_historical_query
+M.track_grep_query = rust_module.track_grep_query
+M.get_historical_grep_query = rust_module.get_historical_grep_query
+
+-- Git functions
+M.get_git_root = rust_module.get_git_root
+
+-- Grep functions
+M.live_grep = rust_module.live_grep
+
+-- Utility functions
+M.health_check = rust_module.health_check
+M.shorten_path = rust_module.shorten_path

 return M
@@ -0,0 +1,254 @@
+--- Grep Renderer
+--- Custom renderer for live grep results with file grouping.
+--- Consecutive matches from the same file are grouped under a file header line.
+--- The header reuses the same rendering as the file picker list (file_renderer)
+--- for visual consistency — same icon, filename, directory path, git highlights.
+local M = {}
+
+local file_renderer = require('fff.file_renderer')
+
+--- Build the file group header line using the same layout as file_renderer.
+--- Delegates to file_renderer.render_line (with combo disabled).
+---@param item table Grep match item (used for file metadata)
+---@param ctx table Render context
+---@return string The header line string
+local function build_group_header(item, ctx)
+  -- file_renderer.render_line checks (item_idx == 1 and ctx.has_combo) for combo header.
+  -- We pass item_idx=0 and disable has_combo to suppress combo logic entirely.
+  local saved_has_combo = ctx.has_combo
+  ctx.has_combo = false
+  local lines = file_renderer.render_line(item, ctx, 0)
+  ctx.has_combo = saved_has_combo
+  return lines[1]
+end
+
+--- Apply highlights for a file group header line using file_renderer.
+--- Delegates to file_renderer.apply_highlights so all highlight groups
+--- (icon, filename, git text color, directory path, git sign) match exactly.
+---@param item table Grep match item
+---@param ctx table Render context
+---@param buf number Buffer handle
+---@param ns_id number Namespace id
+---@param row number 0-based row in buffer (header line)
+local function apply_group_header_highlights(item, ctx, buf, ns_id, row)
+  local line_content = vim.api.nvim_buf_get_lines(buf, row, row + 1, false)[1] or ''
+  -- file_renderer.apply_highlights uses 1-based line_idx and checks (cursor == item_idx).
+  -- Pass item_idx=0 so the header is never treated as the cursor item.
+  local saved_cursor = ctx.cursor
+  ctx.cursor = -1
+  file_renderer.apply_highlights(item, ctx, 0, buf, ns_id, row + 1, line_content)
+  ctx.cursor = saved_cursor
+end
+
+--- Render a grep match line (grouped: no filename, just location + content).
+--- Format: " :line:col  matched line content"
+---@param item table Grep match item
+---@param ctx table Render context
+---@return string The match line string
+local function render_match_line(item, ctx)
+  local location = string.format(':%d:%d', item.line_number or 0, (item.col or 0) + 1)
+  local separator = '  '
+  local raw_content = item.line_content or ''
+  local leading_ws = #raw_content - #raw_content:match('^%s*(.*)')
+  local content = vim.trim(raw_content)
+
+  -- Indent + location + separator + content
+  local indent = ' '
+  -- Prefix is always ASCII so byte length == display width
+  local prefix_display_w = #indent + #location + #separator
+  local available = ctx.win_width - prefix_display_w - 2
+  local was_truncated = false
+  local content_display_w = vim.fn.strdisplaywidth(content)
+  if content_display_w > available and available > 3 then
+    -- UTF-8 aware truncation: binary search for the character count that
+    -- fits within the available display width (handles multi-byte and wide chars)
+    local nchars = vim.fn.strchars(content)
+    local lo, hi = 0, nchars
+    while lo < hi do
+      local mid = math.floor((lo + hi + 1) / 2)
+      if vim.fn.strdisplaywidth(vim.fn.strcharpart(content, 0, mid)) <= available - 1 then
+        lo = mid
+      else
+        hi = mid - 1
+      end
+    end
+    content = vim.fn.strcharpart(content, 0, lo) .. '…'
+    was_truncated = true
+  end
+
+  local line = indent .. location .. separator .. content
+  local padding = math.max(0, ctx.win_width - vim.fn.strdisplaywidth(line) + 5)
+
+  -- Store transient data on item for highlight pass
+  item._leading_ws = leading_ws
+  item._was_truncated = was_truncated
+  item._match_indent = #indent
+  item._content_offset = prefix_display_w -- byte offset where content starts in the line
+  item._trimmed_content = content -- trimmed content string for treesitter parsing
+
+  return line .. string.rep(' ', padding)
+end
+
+--- Apply highlights for a grouped match line.
+---@param item table Grep match item
+---@param ctx table Render context
+---@param item_idx number 1-based item index
+---@param buf number Buffer handle
+---@param ns_id number Namespace id
+---@param row number 0-based row in buffer
+---@param line_content string The rendered line text
+local function apply_match_highlights(item, ctx, item_idx, buf, ns_id, row, line_content)
+  local config = ctx.config
+  local is_cursor = item_idx == ctx.cursor
+  local indent = item._match_indent or 1
+
+  -- 1. Cursor line highlight — use hl_group + hl_eol instead of line_hl_group
+  -- so that higher-priority inline extmarks (IncSearch match ranges at 200)
+  -- cleanly override both fg and bg on the cursor line.
+  if is_cursor then
+    vim.api.nvim_buf_set_extmark(buf, ns_id, row, 0, {
+      end_col = 0,
+      end_row = row + 1,
+      hl_group = config.hl.cursor,
+      hl_eol = true,
+      priority = 100,
+    })
+  end
+
+  -- 2. Location (:line:col) dimmed — use extmark with priority so it layers with cursor
+  local location_str = string.format(':%d:%d', item.line_number or 0, (item.col or 0) + 1)
+  local loc_start = indent
+  local loc_end = loc_start + #location_str
+  if loc_end <= #line_content then
+    pcall(vim.api.nvim_buf_set_extmark, buf, ns_id, row, loc_start, {
+      end_col = loc_end,
+      hl_group = config.hl.grep_line_number or 'LineNr',
+      priority = 150,
+    })
+  end
+
+  -- 3. Separator dimmed
+  local sep_start = loc_end
+  local sep_end = sep_start + 2
+  if sep_end <= #line_content then
+    pcall(vim.api.nvim_buf_set_extmark, buf, ns_id, row, sep_start, {
+      end_col = sep_end,
+      hl_group = 'Comment',
+      priority = 150,
+    })
+  end
+
+  -- 4. Treesitter syntax highlighting for the content portion.
+  -- Priority 120: above CursorLine (100) so syntax is visible on cursor line,
+  -- below IncSearch match ranges (200) so search matches take precedence.
+  local content_start = sep_end
+  if item._trimmed_content and item.name then
+    local ts_hl = require('fff.treesitter_hl')
+    -- Resolve language once per file group (cache on the render context)
+    ctx._ts_lang_cache = ctx._ts_lang_cache or {}
+    local lang = ctx._ts_lang_cache[item.name]
+    if lang == nil then
+      lang = ts_hl.lang_from_filename(item.name) or false
+      ctx._ts_lang_cache[item.name] = lang
+    end
+    if lang then
+      local highlights = ts_hl.get_line_highlights(item._trimmed_content, lang)
+      for _, hl in ipairs(highlights) do
+        local hl_start = content_start + hl.col
+        local hl_end = content_start + hl.end_col
+        if hl_start < #line_content and hl_end <= #line_content then
+          pcall(vim.api.nvim_buf_set_extmark, buf, ns_id, row, hl_start, {
+            end_col = hl_end,
+            hl_group = hl.hl_group,
+            priority = 120,
+          })
+        end
+      end
+    end
+  end
+
+  -- 5. Match ranges highlighted with IncSearch
+  -- Use extmarks with priority > cursor line (100) so IncSearch renders
+  -- properly on the selected line instead of being overridden by CursorLine.
+  if item.match_ranges then
+    local leading_ws = item._leading_ws or 0
+    for _, range in ipairs(item.match_ranges) do
+      local raw_start = range[1] or 0
+      local raw_end = range[2] or 0
+      local adj_start = raw_start - leading_ws
+      local adj_end = raw_end - leading_ws
+      if adj_end > 0 then
+        adj_start = math.max(0, adj_start)
+        local hl_start = content_start + adj_start
+        local hl_end = content_start + adj_end
+        if hl_start < #line_content and hl_end <= #line_content then
+          pcall(vim.api.nvim_buf_set_extmark, buf, ns_id, row, hl_start, {
+            end_col = hl_end,
+            hl_group = config.hl.grep_match or 'IncSearch',
+            priority = 200,
+          })
+        end
+      end
+    end
+  end
+
+  -- 6. Selection marker (per-occurrence in grep mode)
+  if ctx.selected_items then
+    local key = string.format('%s:%d:%d', item.path, item.line_number or 0, item.col or 0)
+    if ctx.selected_items[key] then
+      vim.api.nvim_buf_set_extmark(buf, ns_id, row, 0, {
+        sign_text = '▊',
+        sign_hl_group = config.hl.selected or 'FFFSelected',
+        priority = 1001,
+      })
+    end
+  end
+end
+
+--- Render a single item's lines (called by list_renderer's generate_item_lines).
+--- Returns 2 lines [header, match] for the first match of a file group,
+--- or 1 line [match] for subsequent matches in the same file.
+---@param item table Grep match item
+---@param ctx table Render context
+---@param item_idx number 1-based item index
+---@return string[]
+function M.render_line(item, ctx, item_idx)
+  -- Track file grouping across the render pass via ctx
+  -- ctx._grep_last_file is reset each render (ctx is fresh per render_list call)
+  local is_new_group = (item.path ~= ctx._grep_last_file)
+  ctx._grep_last_file = item.path
+
+  local match_line = render_match_line(item, ctx)
+
+  if is_new_group then
+    local header_line = build_group_header(item, ctx)
+    item._has_group_header = true
+    return { header_line, match_line }
+  else
+    item._has_group_header = false
+    return { match_line }
+  end
+end
+
+--- Apply highlights for rendered lines (called by list_renderer's apply_all_highlights).
+--- line_idx is the 1-based index of the item's LAST line (the match line).
+--- If the item has a group header, it's at line_idx - 1.
+---@param item table Grep match item
+---@param ctx table Render context
+---@param item_idx number 1-based item index
+---@param buf number Buffer handle
+---@param ns_id number Namespace id
+---@param line_idx number 1-based line index of the match line
+---@param line_content string The rendered match line text
+function M.apply_highlights(item, ctx, item_idx, buf, ns_id, line_idx, line_content)
+  local row = line_idx - 1 -- 0-based for nvim API
+
+  -- Apply match line highlights
+  apply_match_highlights(item, ctx, item_idx, buf, ns_id, row, line_content)
+
+  -- If this item has a group header, highlight it (the line above)
+  -- using file_renderer for identical appearance to the file picker list.
+  if item._has_group_header then apply_group_header_highlights(item, ctx, buf, ns_id, row - 1) end
+end
+
+return M
@@ -0,0 +1,54 @@
+--- Grep search bridge — wraps the Rust `live_grep` FFI function
+--- with file-based pagination state tracking.
+---@class fff.grep
+local M = {}
+
+local fuzzy = require('fff.fuzzy')
+
+---@class fff.grep.SearchResult
+---@field items table[] Array of grep match items
+---@field total_matched number Total matches found in this call
+---@field total_files_searched number Files actually searched in this call
+---@field total_files number Total indexed files
+---@field filtered_file_count number Total searchable files after filtering
+---@field next_file_offset number File offset to pass for the next page (0 = no more results)
+
+local last_result = nil
+
+--- Perform a grep search.
+---@param query string The search query (may contain file constraints like *.rs)
+---@param file_offset? number Index into sorted file list to start from (default 0)
+---@param page_size? number Max matches to collect (default 50)
+---@param config? table Grep configuration overrides
+---@param grep_mode? string Search mode: "plain" (default), "regex", or "fuzzy"
+---@return fff.grep.SearchResult
+function M.search(query, file_offset, page_size, config, grep_mode)
+  local conf = config or {}
+  last_result = fuzzy.live_grep(
+    query or '',
+    file_offset or 0,
+    page_size or 50,
+    conf.max_file_size,
+    conf.max_matches_per_file,
+    conf.smart_case,
+    grep_mode or 'plain',
+    conf.time_budget_ms
+  )
+  return last_result
+end
+
+--- Get metadata from the last search result.
+---@return { total_matched: number, total_files_searched: number, total_files: number, next_file_offset: number }
+function M.get_search_metadata()
+  if not last_result then
+    return { total_matched = 0, total_files_searched = 0, total_files = 0, next_file_offset = 0 }
+  end
+  return {
+    total_matched = last_result.total_matched or 0,
+    total_files_searched = last_result.total_files_searched or 0,
+    total_files = last_result.total_files or 0,
+    next_file_offset = last_result.next_file_offset or 0,
+  }
+end
+
+return M
@@ -0,0 +1,278 @@
+--- List Renderer
+--- Handles all list rendering: line generation, virtual rows, bottom padding,
+--- buffer writes, cursor positioning, and highlight application.
+---
+--- Virtual rows (combo headers, grep file group headers) are decorations that
+--- belong to buffer rendering, NOT to the data model. The cursor and selection
+--- always operate on the items array (1-based indices), never on buffer lines.
+---
+--- Pagination is unaffected: Rust returns N items per page. The renderer may
+--- produce N + K buffer lines (where K = number of virtual header rows), but
+--- the page_size contract with Rust stays item-based.
+---
+--- Selection always operates on item.path keys. Virtual rows have no identity
+--- of their own — they derive from the item they belong to.
+local M = {}
+
+--- @class ListRenderContext
+--- @field config table User configuration
+--- @field items table[] Array of data items to render
+--- @field cursor number Current cursor position (1-based index into items)
+--- @field win_height number Window height in lines
+--- @field win_width number Window width in columns
+--- @field max_path_width number Actual text area width (excluding signcolumn)
+--- @field debug_enabled boolean Whether debug mode shows scores
+--- @field prompt_position string 'top' or 'bottom'
+--- @field has_combo boolean Whether combo boost is active
+--- @field combo_header_line string|nil Formatted combo header line
+--- @field combo_header_text_len number|nil Length of combo header text
+--- @field combo_item_index number|nil Index of item with combo (usually 1)
+--- @field display_start number Start index for displayed items (1)
+--- @field display_end number End index for displayed items (#items)
+--- @field iter_start number Iteration start
+--- @field iter_end number Iteration end
+--- @field iter_step number Iteration step (1 or -1)
+--- @field renderer table|nil Custom renderer with render_line/apply_highlights
+--- @field query string Current search query
+--- @field selected_files table<string, boolean> Selected file paths set
+--- @field mode string|nil Current mode (nil or 'grep')
+--- @field format_file_display function Helper for formatting file display
+
+--- @class ItemLineMapping
+--- @field first number First buffer line (1-based) this item occupies
+--- @field last number Last buffer line (1-based) — the selectable content line
+--- @field virtual_count number Number of virtual (header) lines before the content line
+
+--- @class ListRenderResult
+--- @field lines string[] All buffer lines (including virtual rows and padding)
+--- @field item_to_lines table<number, ItemLineMapping> Maps item index -> line range
+--- @field padding_offset number Number of empty lines prepended for bottom prompt
+--- @field total_content_lines number Lines before padding was applied
+
+--- Generate all display lines from items using the renderer.
+--- Each item may produce 1 or more lines (virtual header + content).
+--- When cross-mode suggestions are active, a suggestion banner is prepended
+--- (for top prompt) or appended (for bottom prompt) so it always appears
+--- above the suggestion items visually.
+--- @param ctx ListRenderContext
+--- @return string[] lines Array of line strings
+--- @return table<number, ItemLineMapping> item_to_lines
+local function generate_item_lines(ctx)
+  local lines = {}
+  local item_to_lines = {}
+
+  -- Cross-mode suggestion header: rendered above items visually.
+  -- For top prompt that means before items; for bottom prompt after items
+  -- (because bottom prompt iterates in reverse).
+  local suggestion_header_lines = {}
+  local has_suggestion_header = ctx.suggestion_source ~= nil and #ctx.items > 0
+  if has_suggestion_header then
+    table.insert(suggestion_header_lines, '')
+    local mode_label = ctx.suggestion_source == 'grep' and 'content matches' or 'file name matches'
+    table.insert(suggestion_header_lines, '  No results found. Suggested ' .. mode_label .. ':')
+    table.insert(suggestion_header_lines, '')
+  end
+
+  -- For top prompt: suggestion header goes before items
+  if has_suggestion_header and ctx.prompt_position ~= 'bottom' then
+    for _, hline in ipairs(suggestion_header_lines) do
+      table.insert(lines, hline)
+    end
+  end
+
+  local renderer = ctx.renderer
+  if not renderer then renderer = require('fff.file_renderer') end
+
+  for i = ctx.iter_start, ctx.iter_end, ctx.iter_step do
+    local item = ctx.items[i]
+    local item_start_line = #lines + 1
+
+    -- Renderer returns 1+ lines: virtual headers first, content line last.
+    -- This contract is shared by file_renderer (combo header) and
+    -- grep_renderer (file group header).
+    local item_lines = renderer.render_line(item, ctx, i)
+
+    for _, line in ipairs(item_lines) do
+      table.insert(lines, line)
+    end
+
+    local item_end_line = #lines
+    local virtual_count = item_end_line - item_start_line -- 0 if single line, 1 if header + content
+
+    item_to_lines[i] = {
+      first = item_start_line,
+      last = item_end_line,
+      virtual_count = virtual_count,
+    }
+  end
+
+  -- For bottom prompt: suggestion header goes after items (appears above visually)
+  if has_suggestion_header and ctx.prompt_position == 'bottom' then
+    for _, hline in ipairs(suggestion_header_lines) do
+      table.insert(lines, hline)
+    end
+  end
+
+  return lines, item_to_lines
+end
+
+--- Apply bottom padding: prepend empty lines so content sits at the bottom.
+--- Adjusts all line indices in item_to_lines accordingly.
+--- @param lines string[] Lines array (mutated)
+--- @param item_to_lines table<number, ItemLineMapping> Mapping (mutated)
+--- @param ctx ListRenderContext
+--- @return number padding_offset Number of empty lines prepended
+local function apply_bottom_padding(lines, item_to_lines, ctx)
+  if ctx.prompt_position ~= 'bottom' then return 0 end
+
+  local total_content_lines = #lines
+  local empty_lines_needed = math.max(0, ctx.win_height - total_content_lines)
+
+  if empty_lines_needed > 0 then
+    -- Prepend empty lines
+    for _ = empty_lines_needed, 1, -1 do
+      table.insert(lines, 1, string.rep(' ', ctx.win_width + 5))
+    end
+
+    -- Shift all line indices
+    for i = ctx.display_start, ctx.display_end do
+      if item_to_lines[i] then
+        item_to_lines[i].first = item_to_lines[i].first + empty_lines_needed
+        item_to_lines[i].last = item_to_lines[i].last + empty_lines_needed
+      end
+    end
+  end
+
+  return empty_lines_needed
+end
+
+--- Write lines to the buffer and position the cursor on the correct line.
+--- The cursor always targets the content line (last) of the current item,
+--- never a virtual header line.
+--- @param lines string[]
+--- @param item_to_lines table<number, ItemLineMapping>
+--- @param ctx ListRenderContext
+--- @param list_buf number Buffer handle
+--- @param list_win number Window handle
+--- @param ns_id number Namespace id
+local function update_buffer_and_cursor(lines, item_to_lines, ctx, list_buf, list_win, ns_id)
+  -- Resolve cursor to a buffer line — always the content line (last), not virtual rows
+  local cursor_line = 0
+  if #ctx.items > 0 and ctx.cursor >= 1 and ctx.cursor <= #ctx.items then
+    local cursor_item = item_to_lines[ctx.cursor]
+    if cursor_item then cursor_line = cursor_item.last end
+  end
+
+  vim.api.nvim_buf_set_option(list_buf, 'modifiable', true)
+  vim.api.nvim_buf_set_lines(list_buf, 0, -1, false, lines)
+  vim.api.nvim_buf_set_option(list_buf, 'modifiable', false)
+
+  vim.api.nvim_buf_clear_namespace(list_buf, ns_id, 0, -1)
+
+  if #ctx.items > 0 and cursor_line > 0 and cursor_line <= #lines then
+    vim.api.nvim_win_set_cursor(list_win, { cursor_line, 0 })
+  end
+end
+
+--- Apply highlights for all items using the renderer's apply_highlights.
+--- For each item, we pass the content line (last) to the renderer.
+--- Renderers that emit virtual rows (grep_renderer) handle their own
+--- header highlights internally via the item._has_group_header flag.
+--- @param lines string[]
+--- @param item_to_lines table<number, ItemLineMapping>
+--- @param ctx ListRenderContext
+--- @param list_buf number
+--- @param ns_id number
+local function apply_all_highlights(lines, item_to_lines, ctx, list_buf, ns_id)
+  local renderer = ctx.renderer
+  if not renderer then renderer = require('fff.file_renderer') end
+
+  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 not line_content then goto continue end
+
+    renderer.apply_highlights(item, ctx, i, list_buf, ns_id, line_idx, line_content)
+    ::continue::
+  end
+end
+
+--- Render the full item list into the buffer.
+--- This is the main entry point — replaces the inline rendering in picker_ui.
+---
+--- @param ctx ListRenderContext Render context built by picker_ui
+--- @param list_buf number List buffer handle
+--- @param list_win number List window handle
+--- @param ns_id number Highlight namespace
+--- @return table<number, ItemLineMapping> item_to_lines for combo/scrollbar use
+function M.render(ctx, list_buf, list_win, ns_id)
+  local lines, item_to_lines = generate_item_lines(ctx)
+
+  apply_bottom_padding(lines, item_to_lines, ctx)
+  update_buffer_and_cursor(lines, item_to_lines, ctx, list_buf, list_win, ns_id)
+
+  if #ctx.items > 0 then apply_all_highlights(lines, item_to_lines, ctx, list_buf, ns_id) end
+
+  -- Highlight the suggestion header lines (if present)
+  if ctx.suggestion_source and #ctx.items > 0 then
+    local suggestion_hl = ctx.config.hl.suggestion_header or 'WarningMsg'
+    for i = 0, #lines - 1 do
+      local line = lines[i + 1]
+      if line and line:match('^%s+No results found') then
+        pcall(vim.api.nvim_buf_add_highlight, list_buf, ns_id, suggestion_hl, i, 0, -1)
+      end
+    end
+  end
+
+  return item_to_lines
+end
+
+--- Get the buffer line for an item's content (selectable) line.
+--- Used by picker_ui for cursor positioning after navigation.
+--- @param item_to_lines table<number, ItemLineMapping>
+--- @param item_index number 1-based item index
+--- @return number|nil line 1-based buffer line, or nil if item not mapped
+function M.get_content_line(item_to_lines, item_index)
+  local mapping = item_to_lines[item_index]
+  if not mapping then return nil end
+  return mapping.last
+end
+
+--- Get the buffer line for an item's first line (may be a virtual header).
+--- Used by combo_renderer for overlay positioning.
+--- @param item_to_lines table<number, ItemLineMapping>
+--- @param item_index number 1-based item index
+--- @return number|nil line 1-based buffer line, or nil if item not mapped
+function M.get_first_line(item_to_lines, item_index)
+  local mapping = item_to_lines[item_index]
+  if not mapping then return nil end
+  return mapping.first
+end
+
+--- Check if an item has virtual (header) rows.
+--- @param item_to_lines table<number, ItemLineMapping>
+--- @param item_index number 1-based item index
+--- @return boolean
+function M.has_virtual_rows(item_to_lines, item_index)
+  local mapping = item_to_lines[item_index]
+  if not mapping then return false end
+  return mapping.virtual_count > 0
+end
+
+--- Count total buffer lines an item occupies (content + virtual).
+--- @param item_to_lines table<number, ItemLineMapping>
+--- @param item_index number 1-based item index
+--- @return number
+function M.get_line_count(item_to_lines, item_index)
+  local mapping = item_to_lines[item_index]
+  if not mapping then return 0 end
+  return mapping.last - mapping.first + 1
+end
+
+return M
@@ -38,6 +38,11 @@ function M.highlight_location(bufnr, location, namespace)
  local line_count = vim.api.nvim_buf_line_count(bufnr)
  local extmarks = {}

+  -- Grep mode: highlight all occurrences of the search pattern across visible lines
+  if location.grep_query and location.grep_query ~= '' then
+    return M.highlight_grep_matches(bufnr, location, namespace)
+  end
+
  if location.line then
    local target_line = math.max(1, math.min(location.line, line_count))

@@ -129,6 +134,98 @@ function M.highlight_location(bufnr, location, namespace)
  return #extmarks > 0 and extmarks or nil
 end

+--- Highlight all occurrences of a grep pattern in the preview buffer.
+--- For plain text and regex modes: highlights every match on all loaded lines
+--- using Lua string.find with the query text.
+--- For fuzzy mode: uses the pre-computed match byte offsets from Rust on the
+--- target line only, since the fuzzy needle (e.g. "shcema") won't match via
+--- literal search against the actual content (e.g. "schema").
+--- @param bufnr number Buffer number
+--- @param location table Location with .grep_query, .line, optional .col, optional .fuzzy_match_ranges
+--- @param namespace number Namespace for extmarks
+--- @return table|nil Highlight extmark details for cleanup
+function M.highlight_grep_matches(bufnr, location, namespace)
+  if not vim.api.nvim_buf_is_valid(bufnr) then return nil end
+
+  local line_count = vim.api.nvim_buf_line_count(bufnr)
+  local extmarks = {}
+
+  -- Target line highlighting is handled by the native `cursorline` window
+  -- option, which is enabled on the preview window in grep mode (picker_ui.lua).
+  -- The cursor is positioned on the target line by preview.scroll_to_line(),
+  -- giving standard CursorLine background + CursorLineNr line number styling
+  -- without conflicting with IncSearch match highlights.
+
+  -- Fuzzy mode: use pre-computed byte offsets from Rust's match_indices.
+  -- These are the exact matched character positions within the line, already
+  -- computed by the SIMD scoring + reference smith-waterman traceback.
+  -- We only highlight the target line since each fuzzy result has its own
+  -- unique set of matched positions.
+  if location.fuzzy_match_ranges and location.line then
+    local target_line = math.max(1, math.min(location.line, line_count))
+    for _, range in ipairs(location.fuzzy_match_ranges) do
+      local start_byte = range[1] -- 0-based byte offset
+      local end_byte = range[2] -- 0-based exclusive end
+      local ok, mark_id = pcall(vim.api.nvim_buf_set_extmark, bufnr, namespace, target_line - 1, start_byte, {
+        end_col = end_byte,
+        hl_group = 'IncSearch',
+        priority = 1000,
+      })
+      if ok then table.insert(extmarks, { id = mark_id, line = target_line - 1 }) end
+    end
+    return #extmarks > 0 and extmarks or nil
+  end
+
+  local query = location.grep_query
+
+  -- Extract the actual search text from the grep query (strip file constraints like *.rs /src/)
+  -- The query parser uses space-separated tokens; the first non-constraint token is the pattern.
+  -- Simple heuristic: strip tokens that look like constraints (start with *, /, or !)
+  local search_text = query
+  local parts = vim.split(query, '%s+')
+  local text_parts = {}
+  for _, part in ipairs(parts) do
+    if part ~= '' and not part:match('^[%*!/]') and not part:match('^%.') then table.insert(text_parts, part) end
+  end
+  if #text_parts > 0 then search_text = text_parts[1] end
+
+  if not search_text or search_text == '' then return nil end
+
+  -- Build case-insensitive pattern if the query has no uppercase (smart case)
+  local has_upper = search_text:match('[A-Z]')
+  local escaped = vim.pesc(search_text)
+
+  -- Highlight pattern occurrences in a window around the target line.
+  -- Limit to ±200 lines from target to keep it fast for large files.
+  local scan_start = 1
+  local scan_end = line_count
+  if location.line then
+    scan_start = math.max(1, location.line - 200)
+    scan_end = math.min(line_count, location.line + 200)
+  end
+  local lines = vim.api.nvim_buf_get_lines(bufnr, scan_start - 1, scan_end, false)
+  for idx, line in ipairs(lines) do
+    local i = scan_start + idx - 1
+    local search_line = has_upper and line or line:lower()
+    local search_pat = has_upper and escaped or escaped:lower()
+    local start_pos = 1
+    while true do
+      local s, e = search_line:find(search_pat, start_pos, true)
+      if not s then break end
+      -- s and e are 1-based byte positions; extmarks need 0-based
+      local ok, mark_id = pcall(vim.api.nvim_buf_set_extmark, bufnr, namespace, i - 1, s - 1, {
+        end_col = e,
+        hl_group = 'IncSearch',
+        priority = 1000,
+      })
+      if ok then table.insert(extmarks, { id = mark_id, line = i - 1 }) end
+      start_pos = e + 1
+    end
+  end
+
+  return #extmarks > 0 and extmarks or nil
+end
+
 --- Clear location highlights from a buffer
 --- @param bufnr number Buffer number
 --- @param namespace number Namespace for extmarks
@@ -1,6 +1,3 @@
-- PERF: By default, this plugin initializes itself lazily,
-- so we do not require any modules at the top of this module.
-
 local M = {}

 M.state = { initialized = false }
@@ -20,9 +17,41 @@ function M.find_files(opts)
  end
 end

+--- Live grep: search file contents in the current directory
+--- @param opts? table Optional configuration overrides
+--- @param opts.cwd? string Custom working directory
+--- @param opts.title? string Window title (default: "Live Grep")
+--- @param opts.prompt? string Input prompt text (default: "grep> ")
+--- @param opts.layout? table Layout overrides
+--- @param opts.grep? table Grep-specific overrides {max_file_size, smart_case, max_matches_per_file, modes}
+--- @param opts.grep.modes? table Available search modes and their cycling order (default: {'plain', 'regex', 'fuzzy'})
+function M.live_grep(opts)
+  local picker_ok, picker_ui = pcall(require, 'fff.picker_ui')
+  if not picker_ok then
+    vim.notify('Failed to load picker UI: ' .. picker_ui, vim.log.levels.ERROR)
+    return
+  end
+
+  local config = require('fff.conf').get()
+  local grep_renderer = require('fff.grep.grep_renderer')
+
+  local grep_config = vim.tbl_deep_extend('force', config.grep or {}, (opts and opts.grep) or {})
+
+  local picker_opts = vim.tbl_deep_extend('force', opts or {}, {
+    title = (opts and opts.title) or 'Live Grep',
+    mode = 'grep',
+    renderer = grep_renderer,
+    grep_config = grep_config,
+  })
+
+  picker_ui.open(picker_opts)
+end
+
 function M.find_in_git_root()
-  local git_root = vim.fn.system('git rev-parse --show-toplevel 2>/dev/null'):gsub('\n', '')
-  if vim.v.shell_error ~= 0 then
+  local fuzzy = require('fff.core').ensure_initialized()
+  local ok, git_root = pcall(fuzzy.get_git_root)
+
+  if not ok or not git_root then
    vim.notify('Not in a git repository', vim.log.levels.WARN)
    return
  end
@@ -56,10 +85,20 @@ function M.search(query, max_results)
  local fuzzy = require('fff.core').ensure_initialized()
  local config = require('fff.conf').get()
  max_results = max_results or config.max_results
+  local max_threads = config.max_threads or 4
  local combo_boost_score_multiplier = config.history and config.history.combo_boost_score_multiplier or 100
  local min_combo_count = config.history and config.history.min_combo_count or 3
-  local ok, search_result =
-    pcall(fuzzy.fuzzy_search_files, query, max_results, nil, nil, false, combo_boost_score_multiplier, min_combo_count)
+  -- Args: query, max_threads, current_file, combo_boost_score_multiplier, min_combo_count, offset, page_size
+  local ok, search_result = pcall(
+    fuzzy.fuzzy_search_files,
+    query,
+    max_threads,
+    nil,
+    combo_boost_score_multiplier,
+    min_combo_count,
+    0,
+    max_results
+  )
  if ok and search_result.items then return search_result.items end
  return {}
 end
@@ -1,29 +0,0 @@
-use crate::error::Result;
-use mlua::{Lua, Table};
-
-pub trait DbHealthChecker {
-    fn get_env(&self) -> &heed::Env;
-    fn count_entries(&self) -> Result<Vec<(&'static str, u64)>>;
-
-    fn get_lua_helthcheckh(&self, lua: &Lua) -> std::result::Result<Table, mlua::Error> {
-        let env = self.get_env();
-        let table = lua.create_table()?;
-
-        let size = env.real_disk_size().map_err(|e| {
-            mlua::Error::RuntimeError(format!("Failed to read db disk size: {}", e))
-        })?;
-        let path = env.path().to_string_lossy().to_string();
-        let entry_count = self
-            .count_entries()
-            .map_err(|e| mlua::Error::RuntimeError(format!("Failed to count db entries: {}", e)))?;
-
-        table.set("path", path)?;
-        table.set("disk_size", size)?;
-
-        for (name, count) in entry_count {
-            table.set(name, count)?;
-        }
-
-        Ok(table)
-    }
-}
@@ -1,18 +1,31 @@
 local download = require('fff.download')

+local is_windows = jit.os:lower() == 'windows'
+
 --- @return string
 local function get_lib_extension()
  if jit.os:lower() == 'mac' or jit.os:lower() == 'osx' then return '.dylib' end
-  if jit.os:lower() == 'windows' then return '.dll' end
+  if is_windows then return '.dll' end
  return '.so'
 end

-- search for the lib in the /target/release directory with and without the lib prefix
-- since MSVC doesn't include the prefix
-local info = debug.getinfo(1, 'S')
-local base_path = info and info.source and info.source:match('@?(.*/)') or ''
+--- Resolve a path to an absolute, clean form with native separators.
+--- Resolves `..` components and on Windows converts forward slashes to
+--- backslashes so that Windows APIs (LoadLibraryEx) can find the file.
+--- @param path string
+--- @return string
+local function resolve_path(path)
+  local resolved = vim.fn.fnamemodify(path, ':p')
+  if is_windows then resolved = resolved:gsub('/', '\\') end
+  return resolved
+end

-- Fallback: if base_path is nil, try to determine from current file path
+-- Determine base_path from the location of this Lua file
+local info = debug.getinfo(1, 'S')
+-- Match both forward and backslash directory separators for cross-platform support
+local base_path = info and info.source and info.source:match('@?(.*[/\\])') or ''
+
+-- Fallback: if base_path is empty, use vim APIs
 if not base_path or base_path == '' then
  base_path = vim.fn.fnamemodify(vim.fn.resolve(vim.fn.expand('<sfile>:p')), ':h') .. '/'
 end
@@ -33,7 +46,7 @@ end
 -- load the library directly from the first valid path we find
 local function try_load_library()
  for _, path_pattern in ipairs(paths) do
-    local actual_path = path_pattern:gsub('%?', 'fff_nvim')
+    local actual_path = resolve_path(path_pattern:gsub('%?', 'fff_nvim'))
    local stat = vim.uv.fs_stat(actual_path)
    if stat and stat.type == 'file' then
      local loader, err = package.loadlib(actual_path, 'luaopen_fff_nvim')
@@ -46,10 +59,15 @@ end

 local backend, load_err = try_load_library()
 if not backend or load_err then
+  local resolved = {}
+  for _, p in ipairs(paths) do
+    table.insert(resolved, resolve_path(p:gsub('%?', 'fff_nvim')))
+  end
+
  local err_msg = string.format(
    'Failed to load fff rust backend.\nError: %s\nSearched paths:\n%s\nMake sure binary exists or make it exists using \n `:lua require("fff.download").download_or_build_binary()`\nor\n`cargo build --release`\n(and rerun neovim after)',
    tostring(load_err),
-    vim.inspect(paths)
+    vim.inspect(resolved)
  )

  error(err_msg)
@@ -1,140 +0,0 @@
-use mlua::prelude::*;
-use std::path::{Path, PathBuf};
-
-use crate::{git::format_git_status, location::Location, query_tracker::QueryMatchEntry};
-
-#[derive(Debug, Clone)]
-pub struct FileItem {
-    pub path: PathBuf,
-    pub relative_path: String,
-    pub relative_path_lower: String,
-    pub file_name: String,
-    pub file_name_lower: String,
-    pub size: u64,
-    pub modified: u64,
-    pub access_frecency_score: i64,
-    pub modification_frecency_score: i64,
-    pub total_frecency_score: i64,
-    pub git_status: Option<git2::Status>,
-}
-
-#[derive(Debug, Clone)]
-pub struct Score {
-    pub total: i32,
-    pub base_score: i32,
-    pub filename_bonus: i32,
-    pub special_filename_bonus: i32,
-    pub frecency_boost: i32,
-    pub distance_penalty: i32,
-    pub current_file_penalty: i32,
-    pub combo_match_boost: i32,
-    pub exact_match: bool,
-    pub match_type: &'static str,
-}
-
-#[derive(Debug, Clone, Copy)]
-pub struct PaginationArgs {
-    pub offset: usize,
-    pub limit: usize,
-}
-
-#[derive(Debug, Clone)]
-pub struct ScoringContext<'a> {
-    pub query: &'a str,
-    pub project_path: Option<&'a Path>,
-    pub current_file: Option<&'a str>,
-    pub max_typos: u16,
-    pub max_threads: usize,
-    pub last_same_query_match: Option<&'a QueryMatchEntry>,
-    pub combo_boost_score_multiplier: i32,
-    pub min_combo_count: u32,
-    pub pagination: PaginationArgs,
-}
-
-#[derive(Debug, Clone, Default)]
-pub struct SearchResult<'a> {
-    pub items: Vec<&'a FileItem>,
-    pub scores: Vec<Score>,
-    pub total_matched: usize,
-    pub total_files: usize,
-    pub location: Option<Location>,
-}
-
-impl IntoLua for &FileItem {
-    fn into_lua(self, lua: &Lua) -> LuaResult<LuaValue> {
-        let table = lua.create_table()?;
-        table.set("path", self.path.to_string_lossy().to_string())?;
-        table.set("relative_path", self.relative_path.clone())?;
-        table.set("name", self.file_name.clone())?;
-        table.set("size", self.size)?;
-        table.set("modified", self.modified)?;
-        table.set("access_frecency_score", self.access_frecency_score)?;
-        table.set(
-            "modification_frecency_score",
-            self.modification_frecency_score,
-        )?;
-        table.set("total_frecency_score", self.total_frecency_score)?;
-        table.set("git_status", format_git_status(self.git_status))?;
-        Ok(LuaValue::Table(table))
-    }
-}
-
-impl IntoLua for Score {
-    fn into_lua(self, lua: &Lua) -> LuaResult<LuaValue> {
-        let table = lua.create_table()?;
-        table.set("total", self.total)?;
-        table.set("base_score", self.base_score)?;
-        table.set("filename_bonus", self.filename_bonus)?;
-        table.set("special_filename_bonus", self.special_filename_bonus)?;
-        table.set("frecency_boost", self.frecency_boost)?;
-        table.set("distance_penalty", self.distance_penalty)?;
-        table.set("current_file_penalty", self.current_file_penalty)?;
-        table.set("combo_match_boost", self.combo_match_boost)?;
-        table.set("match_type", self.match_type)?;
-        table.set("exact_match", self.exact_match)?;
-        Ok(LuaValue::Table(table))
-    }
-}
-
-struct LuaPosition((i32, i32));
-
-impl IntoLua for LuaPosition {
-    fn into_lua(self, lua: &Lua) -> LuaResult<LuaValue> {
-        let table = lua.create_table()?;
-        table.set("line", self.0.0)?;
-        table.set("col", self.0.1)?;
-        Ok(LuaValue::Table(table))
-    }
-}
-
-impl IntoLua for SearchResult<'_> {
-    fn into_lua(self, lua: &Lua) -> LuaResult<LuaValue> {
-        let table = lua.create_table()?;
-        table.set("items", self.items)?;
-        table.set("scores", self.scores)?;
-        table.set("total_matched", self.total_matched)?;
-        table.set("total_files", self.total_files)?;
-
-        if let Some(location) = &self.location {
-            let location_table = lua.create_table()?;
-
-            match location {
-                Location::Line(line) => {
-                    location_table.set("line", *line)?;
-                }
-                Location::Position { line, col } => {
-                    location_table.set("line", *line)?;
-                    location_table.set("col", *col)?;
-                }
-                Location::Range { start, end } => {
-                    location_table.set("start", LuaPosition(*start))?;
-                    location_table.set("end", LuaPosition(*end))?;
-                }
-            }
-
-            table.set("location", location_table)?;
-        }
-
-        Ok(LuaValue::Table(table))
-    }
-}
@@ -0,0 +1,117 @@
+--- Treesitter Highlight Extraction
+--- Extracts syntax highlights from a code string using treesitter.
+--- Uses a per-language scratch buffer pool to avoid repeated buffer creation.
+--- Results are returned as extmark-style tables { col, end_col, hl_group }.
+local M = {}
+
+--- Per-language scratch buffer cache
+--- @type table<string, number>
+local scratch_bufs = {}
+
+--- Get or create a scratch buffer for a given treesitter language.
+--- The buffer is reused across calls — content is overwritten each time.
+--- @param lang string Treesitter language name
+--- @return number buf Buffer handle
+local function get_scratch_buf(lang)
+  local buf = scratch_bufs[lang]
+  if buf and vim.api.nvim_buf_is_valid(buf) then return buf end
+
+  buf = vim.api.nvim_create_buf(false, true)
+  vim.api.nvim_buf_set_name(buf, 'fff://treesitter/' .. lang)
+  vim.bo[buf].bufhidden = 'hide'
+  vim.bo[buf].buftype = 'nofile'
+  vim.bo[buf].swapfile = false
+  vim.bo[buf].undolevels = -1
+  scratch_bufs[lang] = buf
+  return buf
+end
+
+--- Resolve a filename to a treesitter language.
+--- Returns nil if no parser is available.
+--- @param filename string File name (e.g. "foo.rs")
+--- @return string|nil lang Treesitter language name, or nil
+function M.lang_from_filename(filename)
+  if not filename or filename == '' then return nil end
+
+  -- Use vim.filetype.match to get the filetype from the filename
+  local ok, ft = pcall(vim.filetype.match, { filename = filename })
+  if not ok or not ft then return nil end
+
+  -- Convert filetype to treesitter language
+  local lang_ok, lang = pcall(vim.treesitter.language.get_lang, ft)
+  if not lang_ok or not lang then lang = ft end
+
+  -- Check if the parser is actually installed
+  local has_parser = pcall(vim.treesitter.language.add, lang)
+  if not has_parser then return nil end
+
+  return lang
+end
+
+--- Extract treesitter highlights for a single line of code.
+--- Returns an array of { col, end_col, hl_group } tables where col/end_col
+--- are 0-based byte offsets within the input string.
+---
+--- @param text string The line of code to highlight
+--- @param lang string Treesitter language name (from lang_from_filename)
+--- @return table[] highlights Array of { col: number, end_col: number, hl_group: string }
+function M.get_line_highlights(text, lang)
+  if not text or text == '' or not lang then return {} end
+
+  local buf = get_scratch_buf(lang)
+
+  -- Write the single line into the scratch buffer
+  vim.bo[buf].modifiable = true
+  vim.api.nvim_buf_set_lines(buf, 0, -1, false, { text })
+  vim.bo[buf].modifiable = false
+
+  -- Parse with treesitter
+  local ok, parser = pcall(vim.treesitter.get_parser, buf, lang)
+  if not ok or not parser then return {} end
+
+  local parse_ok = pcall(parser.parse, parser, true)
+  if not parse_ok then return {} end
+
+  local highlights = {}
+
+  parser:for_each_tree(function(tstree, tree)
+    if not tstree then return end
+    local root = tstree:root()
+    if not root then return end
+
+    local tree_lang = tree:lang()
+    local query_ok, query = pcall(vim.treesitter.query.get, tree_lang, 'highlights')
+    if not query_ok or not query then return end
+
+    for capture, node, metadata in query:iter_captures(root, buf, 0, 1) do
+      local name = query.captures[capture]
+      if name and name ~= 'spell' and name ~= 'conceal' then
+        local start_row, start_col, end_row, end_col = node:range()
+        -- Only process highlights on line 0 (our single line)
+        if start_row == 0 then
+          if end_row > 0 then end_col = #text end -- multi-line node: clamp to line end
+          if start_col < end_col then
+            highlights[#highlights + 1] = {
+              col = start_col,
+              end_col = end_col,
+              hl_group = '@' .. name .. '.' .. tree_lang,
+            }
+          end
+        end
+      end
+    end
+  end)
+
+  return highlights
+end
+
+--- Clean up all scratch buffers.
+--- Called when the picker closes.
+function M.cleanup()
+  for lang, buf in pairs(scratch_bufs) do
+    if buf and vim.api.nvim_buf_is_valid(buf) then pcall(vim.api.nvim_buf_delete, buf, { force = true }) end
+    scratch_bufs[lang] = nil
+  end
+end
+
+return M
@@ -0,0 +1,10 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# Native binaries (downloaded at install)
+bin/*.dylib
+bin/*.so
+bin/*.dll
@@ -0,0 +1,198 @@
+# fff - Fast File Finder
+
+High-performance fuzzy file finder for Bun, powered by Rust. Perfect for LLM agent tools that need to search through codebases.
+
+## Features
+
+- **Blazing fast** - Rust-powered fuzzy search with parallel processing
+- **Smart ranking** - Frecency-based scoring (frequency + recency)
+- **Git-aware** - Shows file git status in results
+- **Query history** - Learns from your search patterns
+- **Type-safe** - Full TypeScript support with Result types
+
+## Installation
+
+```bash
+bun add @ff-labs/bun
+```
+
+The native binary will be downloaded automatically during installation.
+
+## Quick Start
+
+```typescript
+import { FileFinder } from "fff";
+
+// Initialize with a directory
+const result = FileFinder.init({ basePath: "/path/to/project" });
+if (!result.ok) {
+  console.error(result.error);
+  process.exit(1);
+}
+
+// Wait for initial scan
+FileFinder.waitForScan(5000);
+
+// Search for files
+const search = FileFinder.search("main.ts");
+if (search.ok) {
+  for (const item of search.value.items) {
+    console.log(item.relativePath);
+  }
+}
+
+// Cleanup when done
+FileFinder.destroy();
+```
+
+## API Reference
+
+### `FileFinder.init(options)`
+
+Initialize the file finder.
+
+```typescript
+interface InitOptions {
+  basePath: string;           // Directory to index (required)
+  frecencyDbPath?: string;    // Frecency DB path (omit to skip frecency)
+  historyDbPath?: string;     // History DB path (omit to skip query tracking)
+  useUnsafeNoLock?: boolean;  // Faster but less safe DB mode
+}
+
+const result = FileFinder.init({ basePath: "/my/project" });
+```
+
+### `FileFinder.search(query, options?)`
+
+Search for files.
+
+```typescript
+interface SearchOptions {
+  maxThreads?: number;          // Parallel threads (0 = auto)
+  currentFile?: string;         // Deprioritize this file
+  comboBoostMultiplier?: number; // Query history boost
+  minComboCount?: number;        // Min history matches
+  pageIndex?: number;            // Pagination offset
+  pageSize?: number;             // Results per page
+}
+
+const result = FileFinder.search("main.ts", { pageSize: 10 });
+if (result.ok) {
+  console.log(`Found ${result.value.totalMatched} files`);
+}
+```
+
+### Query Syntax
+
+- `foo bar` - Match files containing "foo" and "bar"
+- `src/` - Match files in src directory
+- `file.ts:42` - Match file.ts with line 42
+- `file.ts:42:10` - Match with line and column
+
+### `FileFinder.trackAccess(filePath)`
+
+Track file access for frecency scoring.
+
+```typescript
+// Call when user opens a file
+FileFinder.trackAccess("/path/to/file.ts");
+```
+
+### `FileFinder.trackQuery(query, selectedFile)`
+
+Track query completion for smart suggestions.
+
+```typescript
+// Call when user selects a file from search
+FileFinder.trackQuery("main", "/path/to/main.ts");
+```
+
+### `FileFinder.healthCheck(testPath?)`
+
+Get diagnostic information.
+
+```typescript
+const health = FileFinder.healthCheck();
+if (health.ok) {
+  console.log(`Version: ${health.value.version}`);
+  console.log(`Indexed: ${health.value.filePicker.indexedFiles} files`);
+}
+```
+
+### Other Methods
+
+- `FileFinder.scanFiles()` - Trigger rescan
+- `FileFinder.isScanning()` - Check scan status
+- `FileFinder.getScanProgress()` - Get scan progress
+- `FileFinder.waitForScan(timeoutMs)` - Wait for scan
+- `FileFinder.reindex(newPath)` - Change indexed directory
+- `FileFinder.refreshGitStatus()` - Refresh git cache
+- `FileFinder.getHistoricalQuery(offset)` - Get past queries
+- `FileFinder.destroy()` - Cleanup resources
+
+## Result Types
+
+All methods return a `Result<T>` type for explicit error handling:
+
+```typescript
+type Result<T> = 
+  | { ok: true; value: T }
+  | { ok: false; error: string };
+
+const result = FileFinder.search("foo");
+if (result.ok) {
+  // result.value is SearchResult
+} else {
+  // result.error is string
+}
+```
+
+## Search Result Types
+
+```typescript
+interface SearchResult {
+  items: FileItem[];
+  scores: Score[];
+  totalMatched: number;
+  totalFiles: number;
+  location?: Location;
+}
+
+interface FileItem {
+  path: string;
+  relativePath: string;
+  fileName: string;
+  size: number;
+  modified: number;
+  gitStatus: string; // 'clean', 'modified', 'untracked', etc.
+}
+```
+
+## Building from Source
+
+If prebuilt binaries aren't available for your platform:
+
+```bash
+# Clone the repository
+git clone https://github.com/dmtrKovalenko/fff.nvim
+cd fff.nvim
+
+# Build the C library
+cargo build --release -p fff-c
+
+# The binary will be at target/release/libfff_c.{so,dylib,dll}
+```
+
+## CLI Tools
+
+```bash
+# Download binary manually
+bunx fff download [version]
+
+# Show platform info
+bunx fff info
+```
+
+## License
+
+MIT
@@ -0,0 +1,51 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "fff",
+      "devDependencies": {
+        "@types/bun": "^1.3.8",
+        "typescript": "^5.0.0",
+      },
+      "peerDependencies": {
+        "bun": ">=1.0.0",
+      },
+    },
+  },
+  "packages": {
+    "@oven/bun-darwin-aarch64": ["@oven/bun-darwin-aarch64@1.3.9", "", { "os": "darwin", "cpu": "arm64" }, "sha512-df7smckMWSUfaT5mzwN9Lfpd3ZGkOqo+vmQ8VV2a32gl14v6uZ/qeeo+1RlANXn8M0uzXPWWCkrKZIWSZUR0qw=="],
+
+    "@oven/bun-darwin-x64": ["@oven/bun-darwin-x64@1.3.9", "", { "os": "darwin", "cpu": "x64" }, "sha512-YiLxfsPzQqaVvT2a+nxH9do0YfUjrlxF3tKP0b1DDgvfgCcVKGsrQH3Wa82qHgL4dnT8h2bqi94JxXESEuPmcA=="],
+
+    "@oven/bun-darwin-x64-baseline": ["@oven/bun-darwin-x64-baseline@1.3.9", "", { "os": "darwin", "cpu": "x64" }, "sha512-XbhsA2XAFzvFr0vPSV6SNqGxab4xHKdPmVTLqoSHAx9tffrSq/012BDptOskulwnD+YNsrJUx2D2Ve1xvfgGcg=="],
+
+    "@oven/bun-linux-aarch64": ["@oven/bun-linux-aarch64@1.3.9", "", { "os": "linux", "cpu": "arm64" }, "sha512-VaNQTu0Up4gnwZLQ6/Hmho6jAlLxTQ1PwxEth8EsXHf82FOXXPV5OCQ6KC9mmmocjKlmWFaIGebThrOy8DUo4g=="],
+
+    "@oven/bun-linux-aarch64-musl": ["@oven/bun-linux-aarch64-musl@1.3.9", "", { "os": "linux", "cpu": "arm64" }, "sha512-t8uimCVBTw5f9K2QTZE5wN6UOrFETNrh/Xr7qtXT9nAOzaOnIFvYA+HcHbGfi31fRlCVfTxqm/EiCwJ1gEw9YQ=="],
+
+    "@oven/bun-linux-x64": ["@oven/bun-linux-x64@1.3.9", "", { "os": "linux", "cpu": "x64" }, "sha512-oQyAW3+ugulvXTZ+XYeUMmNPR94sJeMokfHQoKwPvVwhVkgRuMhcLGV2ZesHCADVu30Oz2MFXbgdC8x4/o9dRg=="],
+
+    "@oven/bun-linux-x64-baseline": ["@oven/bun-linux-x64-baseline@1.3.9", "", { "os": "linux", "cpu": "x64" }, "sha512-nZ12g22cy7pEOBwAxz2tp0wVqekaCn9QRKuGTHqOdLlyAqR4SCdErDvDhUWd51bIyHTQoCmj72TegGTgG0WNPw=="],
+
+    "@oven/bun-linux-x64-musl": ["@oven/bun-linux-x64-musl@1.3.9", "", { "os": "linux", "cpu": "x64" }, "sha512-4ZjIUgCxEyKwcKXideB5sX0KJpnHTZtu778w73VNq2uNH2fNpMZv98+DBgJyQ9OfFoRhmKn1bmLmSefvnHzI9w=="],
+
+    "@oven/bun-linux-x64-musl-baseline": ["@oven/bun-linux-x64-musl-baseline@1.3.9", "", { "os": "linux", "cpu": "x64" }, "sha512-3FXQgtYFsT0YOmAdMcJn56pLM5kzSl6y942rJJIl5l2KummB9Ea3J/vMJMzQk7NCAGhleZGWU/pJSS/uXKGa7w=="],
+
+    "@oven/bun-windows-x64": ["@oven/bun-windows-x64@1.3.9", "", { "os": "win32", "cpu": "x64" }, "sha512-/d6vAmgKvkoYlsGPsRPlPmOK1slPis/F40UG02pYwypTH0wmY0smgzdFqR4YmryxFh17XrW1kITv+U99Oajk9Q=="],
+
+    "@oven/bun-windows-x64-baseline": ["@oven/bun-windows-x64-baseline@1.3.9", "", { "os": "win32", "cpu": "x64" }, "sha512-a/+hSrrDpMD7THyXvE2KJy1skxzAD0cnW4K1WjuI/91VqsphjNzvf5t/ZgxEVL4wb6f+hKrSJ5J3aH47zPr61g=="],
+
+    "@types/bun": ["@types/bun@1.3.8", "", { "dependencies": { "bun-types": "1.3.8" } }, "sha512-3LvWJ2q5GerAXYxO2mffLTqOzEu5qnhEAlh48Vnu8WQfnmSwbgagjGZV6BoHKJztENYEDn6QmVd949W4uESRJA=="],
+
+    "@types/node": ["@types/node@25.2.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-BkmoP5/FhRYek5izySdkOneRyXYN35I860MFAGupTdebyE66uZaR+bXLHq8k4DirE5DwQi3NuhvRU1jqTVwUrQ=="],
+
+    "bun": ["bun@1.3.9", "", { "optionalDependencies": { "@oven/bun-darwin-aarch64": "1.3.9", "@oven/bun-darwin-x64": "1.3.9", "@oven/bun-darwin-x64-baseline": "1.3.9", "@oven/bun-linux-aarch64": "1.3.9", "@oven/bun-linux-aarch64-musl": "1.3.9", "@oven/bun-linux-x64": "1.3.9", "@oven/bun-linux-x64-baseline": "1.3.9", "@oven/bun-linux-x64-musl": "1.3.9", "@oven/bun-linux-x64-musl-baseline": "1.3.9", "@oven/bun-windows-x64": "1.3.9", "@oven/bun-windows-x64-baseline": "1.3.9" }, "os": [ "linux", "win32", "darwin", ], "cpu": [ "x64", "arm64", ], "bin": { "bun": "bin/bun.exe", "bunx": "bin/bunx.exe" } }, "sha512-v5hkh1us7sMNjfimWE70flYbD5I1/qWQaqmJ45q2qk5H/7muQVa478LSVRSFyGTBUBog2LsPQnfIRdjyWJRY+A=="],
+
+    "bun-types": ["bun-types@1.3.8", "", { "dependencies": { "@types/node": "*" } }, "sha512-fL99nxdOWvV4LqjmC+8Q9kW3M4QTtTR1eePs94v5ctGqU8OeceWrSUaRw3JYb7tU3FkMIAjkueehrHPPPGKi5Q=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}
@@ -0,0 +1,222 @@
+#!/usr/bin/env bun
+/**
+ * Interactive file finder demo
+ * 
+ * Usage: 
+ *   bunx fff-demo [directory]
+ *   bun examples/search.ts [directory]
+ * 
+ * Indexes the specified directory (or cwd) and provides an interactive
+ * search prompt with detailed metadata about results.
+ */
+
+import { FileFinder } from "../src/index";
+import * as readline from "readline";
+
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const BLUE = "\x1b[34m";
+const MAGENTA = "\x1b[35m";
+const CYAN = "\x1b[36m";
+const RED = "\x1b[31m";
+
+function formatGitStatus(status: string): string {
+  switch (status) {
+    case "modified":
+      return `${YELLOW}M${RESET}`;
+    case "untracked":
+      return `${GREEN}?${RESET}`;
+    case "added":
+      return `${GREEN}A${RESET}`;
+    case "deleted":
+      return `${RED}D${RESET}`;
+    case "renamed":
+      return `${BLUE}R${RESET}`;
+    case "clear":
+    case "current":
+      return `${DIM} ${RESET}`;
+    default:
+      return `${DIM}${status.charAt(0)}${RESET}`;
+  }
+}
+
+function formatScore(score: number): string {
+  if (score >= 100) return `${GREEN}${score}${RESET}`;
+  if (score >= 50) return `${YELLOW}${score}${RESET}`;
+  if (score > 0) return `${DIM}${score}${RESET}`;
+  return `${DIM}0${RESET}`;
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}K`;
+  return `${(bytes / 1024 / 1024).toFixed(1)}M`;
+}
+
+function formatTime(unixSeconds: number): string {
+  if (unixSeconds === 0) return "unknown";
+  const date = new Date(unixSeconds * 1000);
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffMins = Math.floor(diffMs / 60000);
+  const diffHours = Math.floor(diffMs / 3600000);
+  const diffDays = Math.floor(diffMs / 86400000);
+
+  if (diffMins < 1) return "just now";
+  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffHours < 24) return `${diffHours}h ago`;
+  if (diffDays < 7) return `${diffDays}d ago`;
+  return date.toLocaleDateString();
+}
+
+async function main() {
+  const targetDir = process.argv[2] || process.cwd();
+  
+  console.log(`${BOLD}${CYAN}fff - Fast File Finder Demo${RESET}\n`);
+
+  // Check library availability
+  if (!FileFinder.isAvailable()) {
+    console.error(`${RED}Error: Native library not found.${RESET}`);
+    console.error("Build with: cargo build --release -p fff-c");
+    process.exit(1);
+  }
+
+  // Initialize
+  console.log(`${DIM}Initializing index for: ${targetDir}${RESET}`);
+  const initResult = FileFinder.init({
+    basePath: targetDir,
+  });
+
+  if (!initResult.ok) {
+    console.error(`${RED}Init failed: ${initResult.error}${RESET}`);
+    process.exit(1);
+  }
+
+  // Wait for scan with progress
+  process.stdout.write(`${DIM}Scanning files...${RESET}`);
+  const startTime = Date.now();
+  let lastCount = 0;
+
+  while (FileFinder.isScanning()) {
+    const progress = FileFinder.getScanProgress();
+    if (progress.ok && progress.value.scannedFilesCount !== lastCount) {
+      lastCount = progress.value.scannedFilesCount;
+      process.stdout.write(`\r${DIM}Scanning files... ${lastCount}${RESET}   `);
+    }
+    await new Promise((r) => setTimeout(r, 50));
+  }
+
+  const scanTime = Date.now() - startTime;
+  const finalProgress = FileFinder.getScanProgress();
+  const totalFiles = finalProgress.ok ? finalProgress.value.scannedFilesCount : 0;
+
+  console.log(`\r${GREEN}✓${RESET} Indexed ${BOLD}${totalFiles}${RESET} files in ${scanTime}ms\n`);
+
+  // Show index info
+  const health = FileFinder.healthCheck();
+  if (health.ok) {
+    console.log(`${DIM}Version:${RESET}    ${health.value.version}`);
+    console.log(`${DIM}Base path:${RESET}  ${health.value.filePicker.basePath}`);
+    if (health.value.git.repositoryFound) {
+      console.log(`${DIM}Git root:${RESET}   ${health.value.git.workdir}`);
+    }
+  }
+
+  // Interactive search loop
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  console.log(`${BOLD}Enter a search query${RESET} (or 'q' to quit, empty for all files):\n`);
+
+  const prompt = () => {
+    rl.question(`${CYAN}search>${RESET} `, (query) => {
+      if (query.toLowerCase() === "q" || query.toLowerCase() === "quit") {
+        console.log(`\n${DIM}Goodbye!${RESET}`);
+        FileFinder.destroy();
+        rl.close();
+        process.exit(0);
+      }
+
+      const searchStart = Date.now();
+      const result = FileFinder.search(query, { pageSize: 15 });
+      const searchTime = Date.now() - searchStart;
+
+      if (!result.ok) {
+        console.log(`${RED}Search error: ${result.error}${RESET}\n`);
+        prompt();
+        return;
+      }
+
+      const { items, scores, totalMatched, totalFiles } = result.value;
+
+      console.log();
+      console.log(
+        `${DIM}Found ${BOLD}${totalMatched}${RESET}${DIM} matches in ${totalFiles} files (${searchTime}ms)${RESET}`
+      );
+      console.log();
+
+      if (items.length === 0) {
+        console.log(`${DIM}No matches found.${RESET}\n`);
+        prompt();
+        return;
+      }
+
+      // Header
+      console.log(
+        `${DIM}  Git │ Score │  Size  │  Modified  │ Path${RESET}`
+      );
+
+      // Results
+      for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        const score = scores[i];
+
+        const gitStatus = formatGitStatus(item.gitStatus);
+        const totalScore = formatScore(score.total);
+        const size = formatSize(item.size).padStart(6);
+        const modified = formatTime(item.modified).padEnd(10);
+        const path = item.relativePath;
+
+        console.log(
+          `   ${gitStatus}  │ ${totalScore.padStart(5)} │ ${size} │ ${modified} │ ${path}`
+        );
+
+        // Show score breakdown for top results
+        if (i < 3 && score.total > 0) {
+          const breakdown: string[] = [];
+          if (score.baseScore > 0) breakdown.push(`base:${score.baseScore}`);
+          if (score.filenameBonus > 0) breakdown.push(`filename:+${score.filenameBonus}`);
+          if (score.frecencyBoost > 0) breakdown.push(`frecency:+${score.frecencyBoost}`);
+          if (score.comboMatchBoost > 0) breakdown.push(`combo:+${score.comboMatchBoost}`);
+          if (score.distancePenalty < 0) breakdown.push(`distance:${score.distancePenalty}`);
+          if (score.exactMatch) breakdown.push(`${GREEN}exact${RESET}`);
+          
+          if (breakdown.length > 0) {
+            console.log(`${DIM}      │       │        │            │  └─ ${breakdown.join(", ")}${RESET}`);
+          }
+        }
+      }
+
+      if (totalMatched > items.length) {
+        console.log(
+          `${DIM}      │       │        │            │ ... and ${totalMatched - items.length} more${RESET}`
+        );
+      }
+
+      console.log();
+      prompt();
+    });
+  };
+
+  prompt();
+}
+
+main().catch((err) => {
+  console.error(`${RED}Fatal error: ${err.message}${RESET}`);
+  process.exit(1);
+});
@@ -0,0 +1,76 @@
+{
+  "name": "@ff-labs/bun",
+  "version": "0.1.37",
+  "private": false,
+  "nativeBinaryHash": "1537fc7",
+  "description": "High-performance fuzzy file finder for Bun - perfect for LLM agent tools",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "bin": {
+    "fff": "./scripts/cli.ts",
+    "fff-demo": "./examples/search.ts"
+  },
+  "files": [
+    "src",
+    "bin",
+    "scripts",
+    "examples"
+  ],
+  "scripts": {
+    "postinstall": "bun ./scripts/postinstall.ts",
+    "download": "bun ./scripts/cli.ts download",
+    "test": "bun test src/",
+    "typecheck": "tsc --noEmit",
+    "demo": "bun ./examples/search.ts"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dmtrKovalenko/fff.nvim.git",
+    "directory": "packages/fff"
+  },
+  "keywords": [
+    "file-finder",
+    "fuzzy-search",
+    "bun",
+    "ffi",
+    "llm-tools",
+    "agent-tools",
+    "fast",
+    "rust"
+  ],
+  "author": "Dmitry Kovalenko",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bugs": {
+    "url": "https://github.com/dmtrKovalenko/fff.nvim/issues"
+  },
+  "homepage": "https://github.com/dmtrKovalenko/fff.nvim#readme",
+  "devDependencies": {
+    "@types/bun": "^1.3.8",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "bun": ">=1.0.0"
+  }
+}
@@ -0,0 +1,131 @@
+#!/usr/bin/env bun
+/**
+ * CLI tool for fff package management
+ *
+ * Usage:
+ *   bunx fff download [hash]    - Download native binary
+ *   bunx fff info               - Show platform and binary info
+ *   bunx fff check              - Check for updates
+ */
+
+import { 
+  downloadBinary, 
+  getBinaryPath, 
+  findBinary, 
+  getInstalledHash,
+  checkForUpdate 
+} from "../src/download";
+import { getTriple, getLibExtension, getLibFilename } from "../src/platform";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+interface PackageJson {
+  version: string;
+  nativeBinaryHash?: string;
+}
+
+async function getPackageInfo(): Promise<PackageJson> {
+  const currentDir = dirname(fileURLToPath(import.meta.url));
+  const packageJsonPath = join(currentDir, "..", "package.json");
+  
+  try {
+    return await Bun.file(packageJsonPath).json();
+  } catch {
+    return { version: "unknown" };
+  }
+}
+
+async function main() {
+  switch (command) {
+    case "download": {
+      const hash = args[1];
+      console.log("fff: Downloading native library...");
+      try {
+        const resolvedHash = await downloadBinary(hash);
+        console.log(`fff: Download complete! (${resolvedHash})`);
+      } catch (error) {
+        console.error("fff: Download failed:", error);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "check": {
+      console.log("fff: Checking for updates...");
+      try {
+        const { currentHash, latestHash, updateAvailable } = await checkForUpdate();
+        console.log(`  Installed: ${currentHash || "not installed"}`);
+        console.log(`  Latest:    ${latestHash}`);
+        if (updateAvailable) {
+          console.log("");
+          console.log("  Update available! Run: bunx fff download");
+        } else {
+          console.log("");
+          console.log("  You're up to date!");
+        }
+      } catch (error) {
+        console.error("fff: Failed to check for updates:", error);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "info": {
+      const pkg = await getPackageInfo();
+      const installedHash = await getInstalledHash();
+      
+      console.log("fff - Fast File Finder");
+      console.log(`Package version: ${pkg.version}`);
+      console.log(`Binary hash: ${installedHash || "not installed"}`);
+      console.log("");
+      console.log("Platform Information:");
+      console.log(`  Triple: ${getTriple()}`);
+      console.log(`  Extension: ${getLibExtension()}`);
+      console.log(`  Library name: ${getLibFilename()}`);
+      console.log("");
+      console.log("Binary Status:");
+      const existing = findBinary();
+      if (existing) {
+        console.log(`  Found: ${existing}`);
+      } else {
+        console.log(`  Not found`);
+        console.log(`  Expected path: ${getBinaryPath()}`);
+      }
+      break;
+    }
+
+    case "version":
+    case "--version":
+    case "-v": {
+      const pkg = await getPackageInfo();
+      console.log(pkg.version);
+      break;
+    }
+
+    case "help":
+    case "--help":
+    case "-h":
+    default: {
+      const pkg = await getPackageInfo();
+      console.log(`fff - Fast File Finder CLI v${pkg.version}`);
+      console.log("");
+      console.log("Usage:");
+      console.log("  bunx fff download [hash]   Download native binary");
+      console.log("  bunx fff check             Check for updates");
+      console.log("  bunx fff info              Show platform and binary info");
+      console.log("  bunx fff version           Show version");
+      console.log("  bunx fff help              Show this help message");
+      console.log("");
+      console.log("Examples:");
+      console.log("  bunx fff download          Download binary for configured hash");
+      console.log("  bunx fff download latest   Download latest release");
+      console.log("  bunx fff download abc1234  Download specific commit hash");
+      break;
+    }
+  }
+}
+
+main();
@@ -0,0 +1,37 @@
+#!/usr/bin/env bun
+/**
+ * Postinstall script - automatically downloads the native binary
+ */
+
+import { downloadBinary, findBinary, getInstalledHash } from "../src/download";
+
+async function main() {
+  // Check if binary already exists (dev build or previous download)
+  const existing = findBinary();
+  if (existing) {
+    const hash = await getInstalledHash();
+    console.log(`fff: Native library found at ${existing}`);
+    if (hash) {
+      console.log(`fff: Version: ${hash}`);
+    }
+    return;
+  }
+
+  console.log("fff: Native library not found, downloading...");
+
+  try {
+    const hash = await downloadBinary();
+    console.log(`fff: Native library installed successfully! (${hash})`);
+  } catch (error) {
+    console.error("fff: Failed to download native library:", error);
+    console.error("");
+    console.error("fff: You can build from source instead:");
+    console.error("  cd node_modules/fff && cargo build --release -p fff-c");
+    console.error("");
+    console.error("fff: Or run `bunx fff download` after fixing network issues.");
+    // Don't exit with error - allow install to complete
+    // The error will surface when the user tries to use the library
+  }
+}
+
+main();
@@ -0,0 +1,316 @@
+/**
+ * Binary download utilities for fff
+ *
+ * Downloads prebuilt binaries from GitHub releases based on commit hash.
+ * The release tag corresponds to the short commit SHA (7 characters).
+ */
+
+import { existsSync, mkdirSync, writeFileSync, chmodSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+import { getTriple, getLibExtension, getLibFilename } from "./platform";
+
+const GITHUB_REPO = "dmtrKovalenko/fff.nvim";
+const GITHUB_API = "https://api.github.com";
+
+/**
+ * Get the current file's directory
+ */
+function getCurrentDir(): string {
+  const url = import.meta.url;
+  if (url.startsWith("file://")) {
+    return dirname(fileURLToPath(url));
+  }
+  return dirname(url);
+}
+
+/**
+ * Get the package root directory
+ */
+function getPackageDir(): string {
+  const currentDir = getCurrentDir();
+  return dirname(currentDir);
+}
+
+/**
+ * Get the path to package.json
+ */
+function getPackageJsonPath(): string {
+  return join(getPackageDir(), "package.json");
+}
+
+/**
+ * Get the directory where binaries are stored
+ */
+export function getBinDir(): string {
+  return join(getPackageDir(), "bin");
+}
+
+/**
+ * Get the full path to the native library
+ */
+export function getBinaryPath(): string {
+  const binDir = getBinDir();
+  return join(binDir, getLibFilename());
+}
+
+/**
+ * Check if the binary exists
+ */
+export function binaryExists(): boolean {
+  return existsSync(getBinaryPath());
+}
+
+/**
+ * Read package.json
+ */
+async function readPackageJson(): Promise<Record<string, unknown>> {
+  try {
+    return await Bun.file(getPackageJsonPath()).json();
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Write package.json
+ */
+async function writePackageJson(pkg: Record<string, unknown>): Promise<void> {
+  const content = JSON.stringify(pkg, null, 2) + "\n";
+  writeFileSync(getPackageJsonPath(), content);
+}
+
+/**
+ * Get the installed binary hash from package.json
+ */
+export async function getInstalledHash(): Promise<string | null> {
+  const pkg = await readPackageJson();
+  return (pkg.nativeBinaryHash as string) || null;
+}
+
+/**
+ * Update the installed hash in package.json
+ */
+async function setInstalledHash(hash: string): Promise<void> {
+  const pkg = await readPackageJson();
+  pkg.nativeBinaryHash = hash;
+  await writePackageJson(pkg);
+}
+
+/**
+ * Get the development binary path (for local development)
+ */
+export function getDevBinaryPath(): string | null {
+  const packageDir = getPackageDir();
+  const workspaceRoot = join(packageDir, "..", "..");
+
+  const possiblePaths = [
+    join(workspaceRoot, "target", "release", getLibFilename()),
+    join(workspaceRoot, "target", "debug", getLibFilename()),
+  ];
+
+  for (const path of possiblePaths) {
+    if (existsSync(path)) {
+      return path;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Find the binary, checking both installed and dev paths
+ */
+export function findBinary(): string | null {
+  const installedPath = getBinaryPath();
+  if (existsSync(installedPath)) {
+    return installedPath;
+  }
+  return getDevBinaryPath();
+}
+
+/**
+ * Fetch the latest release tag from GitHub
+ */
+async function fetchLatestReleaseTag(): Promise<string> {
+  const url = `${GITHUB_API}/repos/${GITHUB_REPO}/releases/latest`;
+  
+  const response = await fetch(url, {
+    headers: {
+      "Accept": "application/vnd.github.v3+json",
+      "User-Agent": "fff-bun-client",
+    },
+  });
+
+  if (!response.ok) {
+    // If no "latest" release, try getting the most recent prerelease
+    const allReleasesUrl = `${GITHUB_API}/repos/${GITHUB_REPO}/releases`;
+    const allResponse = await fetch(allReleasesUrl, {
+      headers: {
+        "Accept": "application/vnd.github.v3+json",
+        "User-Agent": "fff-bun-client",
+      },
+    });
+
+    if (!allResponse.ok) {
+      throw new Error(`Failed to fetch releases: ${allResponse.status}`);
+    }
+
+    const releases = await allResponse.json() as Array<{ tag_name: string }>;
+    if (releases.length === 0) {
+      throw new Error("No releases found");
+    }
+
+    return releases[0].tag_name;
+  }
+
+  const release = await response.json() as { tag_name: string };
+  return release.tag_name;
+}
+
+/**
+ * Resolve the hash to use for downloading
+ * If "latest", fetches the latest release tag from GitHub
+ */
+async function resolveHash(hash: string): Promise<string> {
+  if (hash === "latest") {
+    console.log("fff: Fetching latest release tag...");
+    return await fetchLatestReleaseTag();
+  }
+  return hash;
+}
+
+/**
+ * Download and verify checksum for a binary
+ */
+async function downloadWithChecksum(
+  binaryUrl: string,
+  checksumUrl: string,
+): Promise<Buffer> {
+  // Download binary
+  const binaryResponse = await fetch(binaryUrl);
+  if (!binaryResponse.ok) {
+    throw new Error(
+      `Failed to download binary: ${binaryResponse.status} ${binaryResponse.statusText}\nURL: ${binaryUrl}`,
+    );
+  }
+
+  const binaryBuffer = Buffer.from(await binaryResponse.arrayBuffer());
+
+  // Try to download and verify checksum
+  try {
+    const checksumResponse = await fetch(checksumUrl);
+    if (checksumResponse.ok) {
+      const checksumText = await checksumResponse.text();
+      // Format: "hash  filename" or just "hash"
+      const expectedHash = checksumText.trim().split(/\s+/)[0];
+      
+      const actualHash = createHash("sha256").update(binaryBuffer).digest("hex");
+      
+      if (actualHash !== expectedHash) {
+        throw new Error(
+          `Checksum mismatch!\nExpected: ${expectedHash}\nActual: ${actualHash}`,
+        );
+      }
+      console.log("fff: Checksum verified ✓");
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("Checksum mismatch")) {
+      throw error;
+    }
+    // Checksum file not found, continue without verification
+    console.log("fff: Checksum file not available, skipping verification");
+  }
+
+  return binaryBuffer;
+}
+
+/**
+ * Download the binary from GitHub releases
+ * @param hash - The commit hash (release tag) to download, or "latest"
+ */
+export async function downloadBinary(hash?: string): Promise<string> {
+  const currentHash = await getInstalledHash();
+  const packageHash = hash || currentHash || "latest";
+  const resolvedHash = await resolveHash(packageHash);
+  
+  const triple = getTriple();
+  const ext = getLibExtension();
+
+  // Binary name format: c-lib-{triple}.{ext}
+  const binaryName = `c-lib-${triple}.${ext}`;
+  const baseUrl = `https://github.com/${GITHUB_REPO}/releases/download/${resolvedHash}`;
+  const binaryUrl = `${baseUrl}/${binaryName}`;
+  const checksumUrl = `${baseUrl}/${binaryName}.sha256`;
+
+  console.log(`fff: Downloading native library for ${triple}...`);
+  console.log(`fff: Release: ${resolvedHash}`);
+  console.log(`fff: URL: ${binaryUrl}`);
+
+  const binaryBuffer = await downloadWithChecksum(binaryUrl, checksumUrl);
+
+  const binDir = getBinDir();
+  if (!existsSync(binDir)) {
+    mkdirSync(binDir, { recursive: true });
+  }
+
+  const binaryPath = getBinaryPath();
+  writeFileSync(binaryPath, binaryBuffer);
+
+  // Save the hash to package.json
+  await setInstalledHash(resolvedHash);
+
+  // Make executable on Unix
+  if (process.platform !== "win32") {
+    chmodSync(binaryPath, 0o755);
+  }
+
+  console.log(`fff: Binary downloaded to ${binaryPath}`);
+  return resolvedHash;
+}
+
+/**
+ * Check if an update is available
+ */
+export async function checkForUpdate(): Promise<{
+  currentHash: string | null;
+  latestHash: string;
+  updateAvailable: boolean;
+}> {
+  const currentHash = await getInstalledHash();
+  const latestHash = await fetchLatestReleaseTag();
+  
+  return {
+    currentHash,
+    latestHash,
+    updateAvailable: currentHash !== latestHash,
+  };
+}
+
+/**
+ * Ensure the binary exists, downloading if necessary
+ */
+export async function ensureBinary(): Promise<string> {
+  const existingPath = findBinary();
+  if (existingPath) {
+    return existingPath;
+  }
+
+  await downloadBinary();
+  return getBinaryPath();
+}
+
+/**
+ * Download binary, with fallback to cargo build instructions
+ */
+export async function downloadOrBuild(): Promise<void> {
+  try {
+    await downloadBinary();
+  } catch (error) {
+    console.error(`fff: Failed to download binary: ${error}`);
+    console.error(`fff: You can build from source instead:`);
+    console.error(`  cargo build --release -p fff-c`);
+    throw error;
+  }
+}
@@ -0,0 +1,356 @@
+/**
+ * Bun FFI bindings for the fff-c native library
+ *
+ * This module uses Bun's native FFI to call into the Rust C library.
+ * All functions follow the Result pattern for error handling.
+ */
+
+import { dlopen, FFIType, ptr, CString, read, type Pointer } from "bun:ffi";
+import { findBinary, ensureBinary } from "./download";
+import type { Result } from "./types";
+import { err } from "./types";
+
+// Define the FFI symbols
+const ffiDefinition = {
+  // Lifecycle
+  fff_init: {
+    args: [FFIType.cstring],
+    returns: FFIType.ptr,
+  },
+  fff_destroy: {
+    args: [],
+    returns: FFIType.ptr,
+  },
+
+  // Search
+  fff_search: {
+    args: [FFIType.cstring, FFIType.cstring],
+    returns: FFIType.ptr,
+  },
+
+  // File index
+  fff_scan_files: {
+    args: [],
+    returns: FFIType.ptr,
+  },
+  fff_is_scanning: {
+    args: [],
+    returns: FFIType.bool,
+  },
+  fff_get_scan_progress: {
+    args: [],
+    returns: FFIType.ptr,
+  },
+  fff_wait_for_scan: {
+    args: [FFIType.u64],
+    returns: FFIType.ptr,
+  },
+  fff_restart_index: {
+    args: [FFIType.cstring],
+    returns: FFIType.ptr,
+  },
+
+  // Frecency
+  fff_track_access: {
+    args: [FFIType.cstring],
+    returns: FFIType.ptr,
+  },
+
+  // Git
+  fff_refresh_git_status: {
+    args: [],
+    returns: FFIType.ptr,
+  },
+
+  // Query tracking
+  fff_track_query: {
+    args: [FFIType.cstring, FFIType.cstring],
+    returns: FFIType.ptr,
+  },
+  fff_get_historical_query: {
+    args: [FFIType.u64],
+    returns: FFIType.ptr,
+  },
+
+  // Utilities
+  fff_health_check: {
+    args: [FFIType.cstring],
+    returns: FFIType.ptr,
+  },
+
+  // Memory management
+  fff_free_result: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
+  fff_free_string: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
+} as const;
+
+type FFFLibrary = ReturnType<typeof dlopen<typeof ffiDefinition>>;
+
+// Library instance (lazy loaded)
+let lib: FFFLibrary | null = null;
+
+/**
+ * Load the native library
+ */
+function loadLibrary(): FFFLibrary {
+  if (lib) return lib;
+
+  const binaryPath = findBinary();
+  if (!binaryPath) {
+    throw new Error(
+      "fff native library not found. Run `bunx fff download` or build from source with `cargo build --release -p fff-c`"
+    );
+  }
+
+  lib = dlopen(binaryPath, ffiDefinition);
+  return lib;
+}
+
+/**
+ * Encode a string for FFI (null-terminated)
+ */
+function encodeString(s: string): Uint8Array {
+  return new TextEncoder().encode(s + "\0");
+}
+
+/**
+ * Read a C string from a pointer
+ * Note: read.ptr() returns number but CString expects Pointer - we cast through unknown
+ */
+function readCString(pointer: Pointer | number | null): string | null {
+  if (pointer === null || pointer === 0) return null;
+  // CString constructor accepts Pointer, but read.ptr returns number
+  // Cast through unknown for runtime compatibility
+  return new CString(pointer as unknown as Pointer).toString();
+}
+
+/**
+ * Convert snake_case keys to camelCase recursively
+ */
+function snakeToCamel(obj: unknown): unknown {
+  if (obj === null || obj === undefined) return obj;
+  if (typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) return obj.map(snakeToCamel);
+
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+    const camelKey = key.replace(/_([a-z])/g, (_, letter) =>
+      letter.toUpperCase()
+    );
+    result[camelKey] = snakeToCamel(value);
+  }
+  return result;
+}
+
+/**
+ * Parse a FffResult from the FFI return value
+ * The result is a pointer to a struct: { success: bool, data: *char, error: *char }
+ */
+function parseResult<T>(resultPtr: Pointer | null): Result<T> {
+  if (resultPtr === null) {
+    return err("FFI returned null pointer");
+  }
+
+  // Read the struct fields
+  // FffResult layout: bool (1 byte + 7 padding) + pointer (8 bytes) + pointer (8 bytes)
+  // offset 0: success (bool, 1 byte)
+  // offset 8: data pointer (8 bytes)
+  // offset 16: error pointer (8 bytes)
+  const success = read.u8(resultPtr, 0) !== 0;
+  const dataPtr = read.ptr(resultPtr, 8);
+  const errorPtr = read.ptr(resultPtr, 16);
+
+  const library = loadLibrary();
+
+  if (success) {
+    const data = readCString(dataPtr);
+    // Free the result
+    library.symbols.fff_free_result(resultPtr);
+
+    if (data === null || data === "") {
+      return { ok: true, value: undefined as T };
+    }
+
+    try {
+      const parsed = JSON.parse(data);
+      // Convert snake_case to camelCase for TypeScript consumers
+      const transformed = snakeToCamel(parsed) as T;
+      return { ok: true, value: transformed };
+    } catch {
+      // For simple values like "true" or numbers
+      return { ok: true, value: data as T };
+    }
+  } else {
+    const errorMsg = readCString(errorPtr) || "Unknown error";
+    // Free the result
+    library.symbols.fff_free_result(resultPtr);
+    return err(errorMsg);
+  }
+}
+
+/**
+ * Initialize the file finder
+ */
+export function ffiInit(optsJson: string): Result<void> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_init(ptr(encodeString(optsJson)));
+  return parseResult<void>(resultPtr);
+}
+
+/**
+ * Destroy and clean up resources
+ */
+export function ffiDestroy(): Result<void> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_destroy();
+  return parseResult<void>(resultPtr);
+}
+
+/**
+ * Perform fuzzy search
+ */
+export function ffiSearch(query: string, optsJson: string): Result<unknown> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_search(
+    ptr(encodeString(query)),
+    ptr(encodeString(optsJson))
+  );
+  return parseResult<unknown>(resultPtr);
+}
+
+/**
+ * Trigger file scan
+ */
+export function ffiScanFiles(): Result<void> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_scan_files();
+  return parseResult<void>(resultPtr);
+}
+
+/**
+ * Check if scanning
+ */
+export function ffiIsScanning(): boolean {
+  const library = loadLibrary();
+  return library.symbols.fff_is_scanning() as boolean;
+}
+
+/**
+ * Get scan progress
+ */
+export function ffiGetScanProgress(): Result<unknown> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_get_scan_progress();
+  return parseResult<unknown>(resultPtr);
+}
+
+/**
+ * Wait for scan to complete
+ */
+export function ffiWaitForScan(timeoutMs: number): Result<boolean> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_wait_for_scan(BigInt(timeoutMs));
+  const result = parseResult<string>(resultPtr);
+  if (!result.ok) return result;
+  return { ok: true, value: result.value === "true" };
+}
+
+/**
+ * Restart index in new path
+ */
+export function ffiRestartIndex(newPath: string): Result<void> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_restart_index(
+    ptr(encodeString(newPath))
+  );
+  return parseResult<void>(resultPtr);
+}
+
+/**
+ * Track file access
+ */
+export function ffiTrackAccess(filePath: string): Result<boolean> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_track_access(
+    ptr(encodeString(filePath))
+  );
+  const result = parseResult<string>(resultPtr);
+  if (!result.ok) return result;
+  return { ok: true, value: result.value === "true" };
+}
+
+/**
+ * Refresh git status
+ */
+export function ffiRefreshGitStatus(): Result<number> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_refresh_git_status();
+  const result = parseResult<string>(resultPtr);
+  if (!result.ok) return result;
+  return { ok: true, value: parseInt(result.value, 10) };
+}
+
+/**
+ * Track query completion
+ */
+export function ffiTrackQuery(
+  query: string,
+  filePath: string
+): Result<boolean> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_track_query(
+    ptr(encodeString(query)),
+    ptr(encodeString(filePath))
+  );
+  const result = parseResult<string>(resultPtr);
+  if (!result.ok) return result;
+  return { ok: true, value: result.value === "true" };
+}
+
+/**
+ * Get historical query
+ */
+export function ffiGetHistoricalQuery(offset: number): Result<string | null> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_get_historical_query(BigInt(offset));
+  const result = parseResult<string>(resultPtr);
+  if (!result.ok) return result;
+  if (result.value === "null") return { ok: true, value: null };
+  return result;
+}
+
+/**
+ * Health check
+ */
+export function ffiHealthCheck(testPath: string): Result<unknown> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_health_check(
+    ptr(encodeString(testPath))
+  );
+  return parseResult<unknown>(resultPtr);
+}
+
+/**
+ * Ensure the library is loaded (for preloading)
+ */
+export async function ensureLoaded(): Promise<void> {
+  await ensureBinary();
+  loadLibrary();
+}
+
+/**
+ * Check if the library is available
+ */
+export function isAvailable(): boolean {
+  try {
+    loadLibrary();
+    return true;
+  } catch {
+    return false;
+  }
+}
@@ -0,0 +1,312 @@
+/**
+ * FileFinder - High-level API for the fff file finder
+ *
+ * This class provides a type-safe, ergonomic API for file finding operations.
+ * All methods return Result types for explicit error handling.
+ */
+
+import {
+  ffiInit,
+  ffiDestroy,
+  ffiSearch,
+  ffiScanFiles,
+  ffiIsScanning,
+  ffiGetScanProgress,
+  ffiWaitForScan,
+  ffiRestartIndex,
+  ffiTrackAccess,
+  ffiRefreshGitStatus,
+  ffiTrackQuery,
+  ffiGetHistoricalQuery,
+  ffiHealthCheck,
+  ensureLoaded,
+  isAvailable,
+} from "./ffi";
+
+import type {
+  Result,
+  InitOptions,
+  SearchOptions,
+  SearchResult,
+  ScanProgress,
+  HealthCheck,
+} from "./types";
+
+import { err, toInternalInitOptions, toInternalSearchOptions } from "./types";
+
+/**
+ * FileFinder - Fast file finder with fuzzy search
+ *
+ * @example
+ * ```typescript
+ * import { FileFinder } from "fff";
+ *
+ * // Initialize
+ * const result = FileFinder.init({ basePath: "/path/to/project" });
+ * if (!result.ok) {
+ *   console.error(result.error);
+ *   process.exit(1);
+ * }
+ *
+ * // Wait for initial scan
+ * FileFinder.waitForScan(5000);
+ *
+ * // Search for files
+ * const search = FileFinder.search("main.ts");
+ * if (search.ok) {
+ *   for (const item of search.value.items) {
+ *     console.log(item.relativePath);
+ *   }
+ * }
+ *
+ * // Cleanup
+ * FileFinder.destroy();
+ * ```
+ */
+export class FileFinder {
+  private static initialized = false;
+
+  /**
+   * Initialize the file finder with the given options.
+   *
+   * @param options - Initialization options
+   * @returns Result indicating success or failure
+   *
+   * @example
+   * ```typescript
+   * // Basic initialization
+   * FileFinder.init({ basePath: "/path/to/project" });
+   *
+   * // With custom database paths
+   * FileFinder.init({
+   *   basePath: "/path/to/project",
+   *   frecencyDbPath: "/custom/frecency.mdb",
+   *   historyDbPath: "/custom/history.mdb",
+   * });
+   *
+   * // Minimal mode (no databases - just omit db paths)
+   * FileFinder.init({ basePath: "/path/to/project" });
+   * ```
+   */
+  static init(options: InitOptions): Result<void> {
+    const internalOpts = toInternalInitOptions(options);
+    const result = ffiInit(JSON.stringify(internalOpts));
+
+    if (result.ok) {
+      this.initialized = true;
+    }
+
+    return result;
+  }
+
+  /**
+   * Destroy and clean up all resources.
+   *
+   * Call this when you're done using the file finder to free memory
+   * and stop background file watching.
+   */
+  static destroy(): Result<void> {
+    const result = ffiDestroy();
+    if (result.ok) {
+      this.initialized = false;
+    }
+    return result;
+  }
+
+  /**
+   * Search for files matching the query.
+   *
+   * The query supports fuzzy matching and special syntax:
+   * - `foo bar` - Match files containing "foo" and "bar"
+   * - `src/` - Match files in src directory
+   * - `file.ts:42` - Match file.ts with line 42
+   * - `file.ts:42:10` - Match file.ts with line 42, column 10
+   *
+   * @param query - Search query string
+   * @param options - Search options
+   * @returns Search results with matched files and scores
+   *
+   * @example
+   * ```typescript
+   * const result = FileFinder.search("main.ts", { pageSize: 10 });
+   * if (result.ok) {
+   *   console.log(`Found ${result.value.totalMatched} files`);
+   *   for (const item of result.value.items) {
+   *     console.log(item.relativePath);
+   *   }
+   * }
+   * ```
+   */
+  static search(query: string, options?: SearchOptions): Result<SearchResult> {
+    if (!this.initialized) {
+      return err("FileFinder not initialized. Call FileFinder.init() first.");
+    }
+
+    const internalOpts = toInternalSearchOptions(options);
+    const result = ffiSearch(query, JSON.stringify(internalOpts));
+
+    if (!result.ok) {
+      return result;
+    }
+
+    // The FFI returns the search result already parsed
+    return result as Result<SearchResult>;
+  }
+
+  /**
+   * Trigger a rescan of the indexed directory.
+   *
+   * This is useful after major file system changes that the
+   * background watcher might have missed.
+   */
+  static scanFiles(): Result<void> {
+    if (!this.initialized) {
+      return err("FileFinder not initialized. Call FileFinder.init() first.");
+    }
+    return ffiScanFiles();
+  }
+
+  /**
+   * Check if a scan is currently in progress.
+   */
+  static isScanning(): boolean {
+    if (!this.initialized) return false;
+    return ffiIsScanning();
+  }
+
+  /**
+   * Get the current scan progress.
+   */
+  static getScanProgress(): Result<ScanProgress> {
+    if (!this.initialized) {
+      return err("FileFinder not initialized. Call FileFinder.init() first.");
+    }
+    return ffiGetScanProgress() as Result<ScanProgress>;
+  }
+
+  /**
+   * Wait for the initial file scan to complete.
+   *
+   * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
+   * @returns true if scan completed, false if timed out
+   *
+   * @example
+   * ```typescript
+   * FileFinder.init({ basePath: "/path/to/project" });
+   * const completed = FileFinder.waitForScan(10000);
+   * if (!completed.ok || !completed.value) {
+   *   console.warn("Scan did not complete in time");
+   * }
+   * ```
+   */
+  static waitForScan(timeoutMs: number = 5000): Result<boolean> {
+    if (!this.initialized) {
+      return err("FileFinder not initialized. Call FileFinder.init() first.");
+    }
+    return ffiWaitForScan(timeoutMs);
+  }
+
+  /**
+   * Change the indexed directory to a new path.
+   *
+   * This stops the current file watcher and starts indexing the new directory.
+   *
+   * @param newPath - New directory path to index
+   */
+  static reindex(newPath: string): Result<void> {
+    if (!this.initialized) {
+      return err("FileFinder not initialized. Call FileFinder.init() first.");
+    }
+    return ffiRestartIndex(newPath);
+  }
+
+  /**
+   * Track file access for frecency scoring.
+   *
+   * Call this when a user opens a file to improve future search rankings.
+   *
+   * @param filePath - Absolute path to the accessed file
+   */
+  static trackAccess(filePath: string): Result<boolean> {
+    if (!this.initialized) {
+      return { ok: true, value: false };
+    }
+    return ffiTrackAccess(filePath);
+  }
+
+  /**
+   * Refresh the git status cache.
+   *
+   * @returns Number of files with updated git status
+   */
+  static refreshGitStatus(): Result<number> {
+    if (!this.initialized) {
+      return err("FileFinder not initialized. Call FileFinder.init() first.");
+    }
+    return ffiRefreshGitStatus();
+  }
+
+  /**
+   * Track query completion for smart suggestions.
+   *
+   * Call this when a user selects a file from search results.
+   * This helps improve future search rankings for similar queries.
+   *
+   * @param query - The search query that was used
+   * @param selectedFilePath - The file path that was selected
+   */
+  static trackQuery(query: string, selectedFilePath: string): Result<boolean> {
+    if (!this.initialized) {
+      return { ok: true, value: false };
+    }
+    return ffiTrackQuery(query, selectedFilePath);
+  }
+
+  /**
+   * Get a historical query by offset.
+   *
+   * @param offset - Offset from most recent (0 = most recent)
+   * @returns The historical query string, or null if not found
+   */
+  static getHistoricalQuery(offset: number): Result<string | null> {
+    if (!this.initialized) {
+      return { ok: true, value: null };
+    }
+    return ffiGetHistoricalQuery(offset);
+  }
+
+  /**
+   * Get health check information.
+   *
+   * Useful for debugging and verifying the file finder is working correctly.
+   *
+   * @param testPath - Optional path to test git repository detection
+   */
+  static healthCheck(testPath?: string): Result<HealthCheck> {
+    return ffiHealthCheck(testPath || "") as Result<HealthCheck>;
+  }
+
+  /**
+   * Check if the native library is available.
+   */
+  static isAvailable(): boolean {
+    return isAvailable();
+  }
+
+  /**
+   * Ensure the native library is loaded.
+   *
+   * This will download the binary if needed and load it.
+   * Useful for preloading before first use.
+   */
+  static async ensureLoaded(): Promise<void> {
+    return ensureLoaded();
+  }
+
+  /**
+   * Check if the file finder is initialized.
+   */
+  static isInitialized(): boolean {
+    return this.initialized;
+  }
+}
@@ -0,0 +1,230 @@
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import { FileFinder } from "./index";
+import { findBinary, getDevBinaryPath } from "./download";
+import { getTriple, getLibExtension, getLibFilename } from "./platform";
+
+const testDir = process.cwd();
+
+describe("Platform Detection", () => {
+  test("getTriple returns valid triple", () => {
+    const triple = getTriple();
+    expect(triple).toMatch(
+      /^(x86_64|aarch64|arm)-(apple-darwin|unknown-linux-(gnu|musl)|pc-windows-msvc)$/,
+    );
+  });
+
+  test("getLibExtension returns correct extension", () => {
+    const ext = getLibExtension();
+    const platform = process.platform;
+
+    if (platform === "darwin") {
+      expect(ext).toBe("dylib");
+    } else if (platform === "win32") {
+      expect(ext).toBe("dll");
+    } else {
+      expect(ext).toBe("so");
+    }
+  });
+
+  test("getLibFilename returns correct filename", () => {
+    const filename = getLibFilename();
+    const ext = getLibExtension();
+
+    if (process.platform === "win32") {
+      expect(filename).toBe(`fff_c.${ext}`);
+    } else {
+      expect(filename).toBe(`libfff_c.${ext}`);
+    }
+  });
+});
+
+describe("Binary Detection", () => {
+  test("getDevBinaryPath finds local build", () => {
+    const devPath = getDevBinaryPath();
+    expect(devPath).not.toBeNull();
+    expect(devPath).toContain("target/release");
+  });
+
+  test("findBinary returns a path", () => {
+    const path = findBinary();
+    expect(path).not.toBeNull();
+  });
+});
+
+describe("FileFinder - Health Check", () => {
+  test("healthCheck works before initialization", () => {
+    // Make sure we start fresh
+    FileFinder.destroy();
+
+    const result = FileFinder.healthCheck();
+    expect(result.ok).toBe(true);
+
+    if (result.ok) {
+      expect(result.value.version).toBeDefined();
+      expect(result.value.git.available).toBe(true);
+      expect(result.value.filePicker.initialized).toBe(false);
+    }
+  });
+});
+
+describe("FileFinder - Full Lifecycle", () => {
+  // Single beforeAll/afterAll for the entire test suite to avoid repeated init/destroy
+  beforeAll(() => {
+    FileFinder.destroy(); // Clean any previous state
+  });
+
+  afterAll(() => {
+    FileFinder.destroy();
+  });
+
+  test("init succeeds with valid path", () => {
+    const result = FileFinder.init({
+      basePath: testDir,
+    });
+
+    expect(result.ok).toBe(true);
+    expect(FileFinder.isInitialized()).toBe(true);
+  });
+
+  test("isScanning returns a boolean", () => {
+    const scanning = FileFinder.isScanning();
+    expect(typeof scanning).toBe("boolean");
+  });
+
+  test("getScanProgress returns valid data", () => {
+    const result = FileFinder.getScanProgress();
+    expect(result.ok).toBe(true);
+
+    if (result.ok) {
+      expect(typeof result.value.scannedFilesCount).toBe("number");
+      expect(typeof result.value.isScanning).toBe("boolean");
+    }
+  });
+
+  test("waitForScan completes", () => {
+    // Small timeout - scan should be fast or already done
+    const result = FileFinder.waitForScan(500);
+    expect(result.ok).toBe(true);
+  });
+
+  test("search with empty query returns all files", () => {
+    const result = FileFinder.search("");
+    expect(result.ok).toBe(true);
+
+    if (result.ok) {
+      // Empty query should return files (frecency-sorted)
+      expect(result.value.totalFiles).toBeGreaterThan(0);
+    }
+  });
+
+  test("search returns a valid result structure", () => {
+    const result = FileFinder.search("Cargo.toml");
+    expect(result.ok).toBe(true);
+
+    if (result.ok) {
+      expect(typeof result.value.totalMatched).toBe("number");
+      expect(typeof result.value.totalFiles).toBe("number");
+      expect(Array.isArray(result.value.items)).toBe(true);
+      expect(Array.isArray(result.value.scores)).toBe(true);
+    }
+  });
+
+  test("search returns empty for non-matching query", () => {
+    const result = FileFinder.search("xyznonexistentfilenamexyz123456");
+    expect(result.ok).toBe(true);
+
+    if (result.ok) {
+      expect(result.value.totalMatched).toBe(0);
+      expect(result.value.items.length).toBe(0);
+    }
+  });
+
+  test("search respects pageSize option", () => {
+    const result = FileFinder.search("ts", { pageSize: 3 });
+    expect(result.ok).toBe(true);
+
+    if (result.ok) {
+      expect(result.value.items.length).toBeLessThanOrEqual(3);
+    }
+  });
+
+  test("healthCheck shows initialized state", () => {
+    const result = FileFinder.healthCheck();
+    expect(result.ok).toBe(true);
+
+    if (result.ok) {
+      expect(result.value.filePicker.initialized).toBe(true);
+      expect(result.value.filePicker.basePath).toBeDefined();
+      expect(typeof result.value.filePicker.indexedFiles).toBe("number");
+    }
+  });
+
+  test("healthCheck detects git repository", () => {
+    const result = FileFinder.healthCheck(testDir);
+    expect(result.ok).toBe(true);
+
+    if (result.ok) {
+      expect(result.value.git.available).toBe(true);
+      expect(typeof result.value.git.repositoryFound).toBe("boolean");
+    }
+  });
+
+  test("destroy and re-init works", () => {
+    FileFinder.destroy();
+    expect(FileFinder.isInitialized()).toBe(false);
+
+    const result = FileFinder.init({
+      basePath: testDir,
+    });
+    expect(result.ok).toBe(true);
+    expect(FileFinder.isInitialized()).toBe(true);
+  });
+});
+
+describe("FileFinder - Error Handling", () => {
+  test("search fails when not initialized", () => {
+    FileFinder.destroy();
+
+    const result = FileFinder.search("test");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("not initialized");
+    }
+  });
+
+  test("getScanProgress fails when not initialized", () => {
+    const result = FileFinder.getScanProgress();
+    expect(result.ok).toBe(false);
+  });
+
+  test("init fails with invalid path", () => {
+    const result = FileFinder.init({
+      basePath: "/nonexistent/path/that/does/not/exist",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("Failed");
+    }
+  });
+});
+
+describe("Result Type Helpers", () => {
+  test("ok helper creates success result", async () => {
+    const { ok } = await import("./types");
+    const result = ok(42);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toBe(42);
+    }
+  });
+
+  test("err helper creates error result", async () => {
+    const { err } = await import("./types");
+    const result = err<number>("something went wrong");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBe("something went wrong");
+    }
+  });
+});
@@ -0,0 +1,69 @@
+/**
+ * fff - Fast File Finder
+ *
+ * High-performance fuzzy file finder for Bun, powered by Rust.
+ * Perfect for LLM agent tools that need to search through codebases.
+ *
+ * @example
+ * ```typescript
+ * import { FileFinder } from "fff";
+ *
+ * // Initialize with a directory
+ * const result = FileFinder.init({ basePath: "/path/to/project" });
+ * if (!result.ok) {
+ *   console.error(result.error);
+ *   process.exit(1);
+ * }
+ *
+ * // Wait for initial scan
+ * FileFinder.waitForScan(5000);
+ *
+ * // Search for files
+ * const search = FileFinder.search("main.ts");
+ * if (search.ok) {
+ *   for (const item of search.value.items) {
+ *     console.log(item.relativePath);
+ *   }
+ * }
+ *
+ * // Track file access (for frecency)
+ * FileFinder.trackAccess("/path/to/project/src/main.ts");
+ *
+ * // Cleanup when done
+ * FileFinder.destroy();
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Main API
+export { FileFinder } from "./finder";
+
+// Types
+export type {
+  Result,
+  InitOptions,
+  SearchOptions,
+  FileItem,
+  Score,
+  Location,
+  SearchResult,
+  ScanProgress,
+  HealthCheck,
+  DbHealth,
+} from "./types";
+
+// Result helpers
+export { ok, err } from "./types";
+
+// Binary management (for CLI tools)
+export {
+  downloadBinary,
+  ensureBinary,
+  binaryExists,
+  getBinaryPath,
+  findBinary,
+} from "./download";
+
+// Platform utilities
+export { getTriple, getLibExtension, getLibFilename } from "./platform";
@@ -0,0 +1,92 @@
+/**
+ * Platform detection utilities for downloading the correct binary
+ */
+
+import { execSync } from "node:child_process";
+
+/**
+ * Get the platform triple (e.g., "x86_64-unknown-linux-gnu")
+ */
+export function getTriple(): string {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  let osName: string;
+  if (platform === "darwin") {
+    osName = "apple-darwin";
+  } else if (platform === "linux") {
+    osName = detectLinuxLibc();
+  } else if (platform === "win32") {
+    osName = "pc-windows-msvc";
+  } else {
+    throw new Error(`Unsupported platform: ${platform}`);
+  }
+
+  const archName = normalizeArch(arch);
+  return `${archName}-${osName}`;
+}
+
+/**
+ * Detect whether we're on musl or glibc Linux
+ */
+function detectLinuxLibc(): string {
+  try {
+    const lddOutput = execSync("ldd --version 2>&1", {
+      encoding: "utf-8",
+      timeout: 5000,
+    });
+    if (lddOutput.toLowerCase().includes("musl")) {
+      return "unknown-linux-musl";
+    }
+  } catch {
+    // ldd failed, assume glibc
+  }
+  return "unknown-linux-gnu";
+}
+
+/**
+ * Normalize architecture name to Rust target format
+ */
+function normalizeArch(arch: string): string {
+  switch (arch) {
+    case "x64":
+    case "amd64":
+      return "x86_64";
+    case "arm64":
+      return "aarch64";
+    case "arm":
+      return "arm";
+    default:
+      throw new Error(`Unsupported architecture: ${arch}`);
+  }
+}
+
+/**
+ * Get the library file extension for the current platform
+ */
+export function getLibExtension(): "dylib" | "so" | "dll" {
+  switch (process.platform) {
+    case "darwin":
+      return "dylib";
+    case "win32":
+      return "dll";
+    default:
+      return "so";
+  }
+}
+
+/**
+ * Get the library filename prefix (empty on Windows)
+ */
+export function getLibPrefix(): string {
+  return process.platform === "win32" ? "" : "lib";
+}
+
+/**
+ * Get the full library filename for the current platform
+ */
+export function getLibFilename(): string {
+  const prefix = getLibPrefix();
+  const ext = getLibExtension();
+  return `${prefix}fff_c.${ext}`;
+}
@@ -0,0 +1,256 @@
+/**
+ * Result type for all operations - follows the Result pattern
+ */
+export type Result<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: string };
+
+/**
+ * Helper to create a successful result
+ */
+export function ok<T>(value: T): Result<T> {
+  return { ok: true, value };
+}
+
+/**
+ * Helper to create an error result
+ */
+export function err<T>(error: string): Result<T> {
+  return { ok: false, error };
+}
+
+/**
+ * Initialization options for the file finder
+ */
+export interface InitOptions {
+  /** Base directory to index (required) */
+  basePath: string;
+  /** Path to frecency database (optional, omit to skip frecency initialization) */
+  frecencyDbPath?: string;
+  /** Path to query history database (optional, omit to skip query tracker initialization) */
+  historyDbPath?: string;
+  /** Use unsafe no-lock mode for databases (optional, defaults to false) */
+  useUnsafeNoLock?: boolean;
+}
+
+/**
+ * Search options for fuzzy file search
+ */
+export interface SearchOptions {
+  /** Maximum threads for parallel search (0 = auto) */
+  maxThreads?: number;
+  /** Current file path (for deprioritization in results) */
+  currentFile?: string;
+  /** Combo boost score multiplier (default: 100) */
+  comboBoostMultiplier?: number;
+  /** Minimum combo count for boost (default: 3) */
+  minComboCount?: number;
+  /** Page index for pagination (default: 0) */
+  pageIndex?: number;
+  /** Page size for pagination (default: 100) */
+  pageSize?: number;
+}
+
+/**
+ * A file item in search results
+ */
+export interface FileItem {
+  /** Absolute path to the file */
+  path: string;
+  /** Path relative to the indexed directory */
+  relativePath: string;
+  /** File name only */
+  fileName: string;
+  /** File size in bytes */
+  size: number;
+  /** Last modified timestamp (Unix seconds) */
+  modified: number;
+  /** Frecency score based on access patterns */
+  accessFrecencyScore: number;
+  /** Frecency score based on modification time */
+  modificationFrecencyScore: number;
+  /** Combined frecency score */
+  totalFrecencyScore: number;
+  /** Git status: 'clean', 'modified', 'untracked', 'staged_new', etc. */
+  gitStatus: string;
+}
+
+/**
+ * Score breakdown for a search result
+ */
+export interface Score {
+  /** Total combined score */
+  total: number;
+  /** Base fuzzy match score */
+  baseScore: number;
+  /** Bonus for filename match */
+  filenameBonus: number;
+  /** Bonus for special filenames (index.ts, main.rs, etc.) */
+  specialFilenameBonus: number;
+  /** Boost from frecency */
+  frecencyBoost: number;
+  /** Penalty for distance in path */
+  distancePenalty: number;
+  /** Penalty if this is the current file */
+  currentFilePenalty: number;
+  /** Boost from query history combo matching */
+  comboMatchBoost: number;
+  /** Whether this was an exact match */
+  exactMatch: boolean;
+  /** Type of match: 'fuzzy', 'exact', 'prefix', etc. */
+  matchType: string;
+}
+
+/**
+ * Location in file (from query like "file.ts:42")
+ */
+export type Location =
+  | { type: "line"; line: number }
+  | { type: "position"; line: number; col: number }
+  | {
+      type: "range";
+      start: { line: number; col: number };
+      end: { line: number; col: number };
+    };
+
+/**
+ * Search result from fuzzy file search
+ */
+export interface SearchResult {
+  /** Matched file items */
+  items: FileItem[];
+  /** Corresponding scores for each item */
+  scores: Score[];
+  /** Total number of files that matched */
+  totalMatched: number;
+  /** Total number of indexed files */
+  totalFiles: number;
+  /** Location parsed from query (e.g., "file.ts:42:10") */
+  location?: Location;
+}
+
+/**
+ * Scan progress information
+ */
+export interface ScanProgress {
+  /** Number of files scanned so far */
+  scannedFilesCount: number;
+  /** Whether a scan is currently in progress */
+  isScanning: boolean;
+}
+
+/**
+ * Database health information
+ */
+export interface DbHealth {
+  /** Path to the database */
+  path: string;
+  /** Size of the database on disk in bytes */
+  diskSize: number;
+}
+
+/**
+ * Health check result
+ */
+export interface HealthCheck {
+  /** Library version */
+  version: string;
+  /** Git integration status */
+  git: {
+    /** Whether git2 library is available */
+    available: boolean;
+    /** Whether a git repository was found */
+    repositoryFound: boolean;
+    /** Git working directory path */
+    workdir?: string;
+    /** libgit2 version string */
+    libgit2Version: string;
+    /** Error message if git detection failed */
+    error?: string;
+  };
+  /** File picker status */
+  filePicker: {
+    /** Whether the file picker is initialized */
+    initialized: boolean;
+    /** Base path being indexed */
+    basePath?: string;
+    /** Whether a scan is in progress */
+    isScanning?: boolean;
+    /** Number of indexed files */
+    indexedFiles?: number;
+    /** Error message if there's an issue */
+    error?: string;
+  };
+  /** Frecency database status */
+  frecency: {
+    /** Whether frecency tracking is initialized */
+    initialized: boolean;
+    /** Database health information */
+    dbHealthcheck?: DbHealth;
+    /** Error message if there's an issue */
+    error?: string;
+  };
+  /** Query tracker status */
+  queryTracker: {
+    /** Whether query tracking is initialized */
+    initialized: boolean;
+    /** Database health information */
+    dbHealthcheck?: DbHealth;
+    /** Error message if there's an issue */
+    error?: string;
+  };
+}
+
+/**
+ * Internal: Options format sent to Rust FFI
+ * @internal
+ */
+export interface InitOptionsInternal {
+  base_path: string;
+  frecency_db_path?: string;
+  history_db_path?: string;
+  use_unsafe_no_lock: boolean;
+}
+
+/**
+ * Internal: Search options format sent to Rust FFI
+ * @internal
+ */
+export interface SearchOptionsInternal {
+  max_threads?: number;
+  current_file?: string;
+  combo_boost_multiplier?: number;
+  min_combo_count?: number;
+  page_index?: number;
+  page_size?: number;
+}
+
+/**
+ * Convert public InitOptions to internal format
+ * @internal
+ */
+export function toInternalInitOptions(opts: InitOptions): InitOptionsInternal {
+  return {
+    base_path: opts.basePath,
+    frecency_db_path: opts.frecencyDbPath,
+    history_db_path: opts.historyDbPath,
+    use_unsafe_no_lock: opts.useUnsafeNoLock ?? false,
+  };
+}
+
+/**
+ * Convert public SearchOptions to internal format
+ * @internal
+ */
+export function toInternalSearchOptions(
+  opts?: SearchOptions
+): SearchOptionsInternal {
+  return {
+    max_threads: opts?.maxThreads,
+    current_file: opts?.currentFile,
+    combo_boost_multiplier: opts?.comboBoostMultiplier,
+    min_combo_count: opts?.minComboCount,
+    page_index: opts?.pageIndex,
+    page_size: opts?.pageSize,
+  };
+}
@@ -0,0 +1,134 @@
+/**
+ * Test script for fff package
+ *
+ * Run with: bun packages/fff/test.ts
+ */
+
+import { FileFinder } from "./src/index";
+import { resolve, dirname } from "path";
+
+async function main() {
+  console.log("=== fff Test Script ===\n");
+
+  // Check if library is available
+  console.log("Checking library availability...");
+  const available = FileFinder.isAvailable();
+  console.log(`Library available: ${available}\n`);
+
+  if (!available) {
+    console.error("Native library not found!");
+    console.error("Build it with: cargo build --release -p fff-c");
+    process.exit(1);
+  }
+
+  // Health check (before init)
+  console.log("Health check (before init):");
+  const healthBefore = FileFinder.healthCheck();
+  if (healthBefore.ok) {
+    console.log(`  Version: ${healthBefore.value.version}`);
+    console.log(`  Git available: ${healthBefore.value.git.available}`);
+    console.log(`  File picker initialized: ${healthBefore.value.filePicker.initialized}`);
+  } else {
+    console.error(`  Error: ${healthBefore.error}`);
+  }
+  console.log();
+
+  // Initialize with the root project directory to test on more files
+  const testDir = resolve(dirname(import.meta.path), "../..");
+  console.log(`Initializing with base path: ${testDir}`);
+
+  const initResult = FileFinder.init({
+    basePath: testDir,
+  });
+
+  if (!initResult.ok) {
+    console.error(`Init failed: ${initResult.error}`);
+    process.exit(1);
+  }
+  console.log("Initialization successful!\n");
+
+  // Wait for scan with polling to show progress
+  console.log("Waiting for initial scan...");
+  const startTime = Date.now();
+  let lastCount = 0;
+  
+  while (FileFinder.isScanning()) {
+    const progress = FileFinder.getScanProgress();
+    if (progress.ok && progress.value.scannedFilesCount !== lastCount) {
+      lastCount = progress.value.scannedFilesCount;
+      console.log(`  Scanning: ${lastCount} files...`);
+    }
+    await new Promise((r) => setTimeout(r, 100));
+    
+    if (Date.now() - startTime > 30000) {
+      console.error("  Scan timeout after 30s");
+      break;
+    }
+  }
+
+  // Get final scan progress
+  const progress = FileFinder.getScanProgress();
+  if (progress.ok) {
+    console.log(`Scan complete: ${progress.value.scannedFilesCount} files indexed`);
+    console.log(`Scan time: ${Date.now() - startTime}ms`);
+  }
+  console.log();
+
+  // Search test
+  console.log("Searching for 'lib.rs'...");
+  const searchResult = FileFinder.search("lib.rs", { pageSize: 5 });
+
+  if (searchResult.ok) {
+    console.log(`Found ${searchResult.value.totalMatched} matches (showing first 5):\n`);
+    for (let i = 0; i < searchResult.value.items.length; i++) {
+      const item = searchResult.value.items[i];
+      const score = searchResult.value.scores[i];
+      console.log(`  ${item.relativePath}`);
+      console.log(`    Score: ${score.total} (base: ${score.baseScore}, filename: ${score.filenameBonus})`);
+      console.log(`    Git: ${item.gitStatus}`);
+    }
+  } else {
+    console.error(`Search failed: ${searchResult.error}`);
+  }
+  console.log();
+
+  // Search with different query
+  console.log("Searching for 'package.json'...");
+  const searchResult2 = FileFinder.search("package.json", { pageSize: 3 });
+
+  if (searchResult2.ok) {
+    console.log(`Found ${searchResult2.value.totalMatched} matches:\n`);
+    for (const item of searchResult2.value.items) {
+      console.log(`  ${item.relativePath}`);
+    }
+  } else {
+    console.error(`Search failed: ${searchResult2.error}`);
+  }
+  console.log();
+
+  // Health check (after init)
+  console.log("Health check (after init):");
+  const healthAfter = FileFinder.healthCheck();
+  if (healthAfter.ok) {
+    console.log(`  File picker initialized: ${healthAfter.value.filePicker.initialized}`);
+    console.log(`  Base path: ${healthAfter.value.filePicker.basePath}`);
+    console.log(`  Indexed files: ${healthAfter.value.filePicker.indexedFiles}`);
+    if (healthAfter.value.git.repositoryFound) {
+      console.log(`  Git workdir: ${healthAfter.value.git.workdir}`);
+    }
+  }
+  console.log();
+
+  // Cleanup
+  console.log("Cleaning up...");
+  const destroyResult = FileFinder.destroy();
+  if (destroyResult.ok) {
+    console.log("Cleanup successful!");
+  } else {
+    console.error(`Cleanup failed: ${destroyResult.error}`);
+  }
+
+  console.log("\n=== Test Complete ===");
+}
+
+main().catch(console.error);
@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "lib": ["ESNext"],
+    "types": ["bun"]
+  },
+  "include": ["src/**/*", "scripts/**/*", "*.ts"],
+  "exclude": ["node_modules", "dist", "bin"]
+}
@@ -71,13 +71,16 @@ vim.api.nvim_create_user_command('FFFDebug', function(opts)
  local config = require('fff.conf').get()
  if opts.args == 'toggle' or opts.args == '' then
    config.debug.show_scores = not config.debug.show_scores
+    config.debug.show_file_info = config.debug.show_scores
    local status = config.debug.show_scores and 'enabled' or 'disabled'
    vim.notify('FFF debug scores ' .. status, vim.log.levels.INFO)
  elseif opts.args == 'on' then
    config.debug.show_scores = true
+    config.debug.show_file_info = true
    vim.notify('FFF debug scores enabled', vim.log.levels.INFO)
  elseif opts.args == 'off' then
    config.debug.show_scores = false
+    config.debug.show_file_info = false
    vim.notify('FFF debug scores disabled', vim.log.levels.INFO)
  else
    vim.notify('Usage: :FFFDebug [on|off|toggle]', vim.log.levels.ERROR)
@@ -1,5 +1,5 @@
 [toolchain]
-channel = "nightly-2026-01-08"
+channel = "nightly-2026-02-10"
 components = [
  "clippy-preview",
  "rustfmt-preview",
@@ -0,0 +1,128 @@
+local fff_rust = require('fff.rust')
+
+--- Wait for the scan to fully complete, handling the startup race where
+--- the background thread hasn't set is_scanning=true yet.
+--- @param timeout_ms number Maximum time to wait in milliseconds
+local function wait_for_scan(timeout_ms)
+  -- Small sleep to let the background thread start and set is_scanning=true.
+  -- This handles the race between init_file_picker returning and the thread starting.
+  vim.wait(100, function() return false end)
+  fff_rust.wait_for_initial_scan(timeout_ms)
+end
+
+describe('fff.nvim core', function()
+  local test_dir
+
+  before_each(function()
+    -- Use the plugin's own repo directory as a known git repo for testing
+    test_dir = vim.fn.fnamemodify(debug.getinfo(1, 'S').source:sub(2), ':h:h')
+    -- Make sure it resolves to an actual directory
+    if vim.fn.isdirectory(test_dir) ~= 1 then test_dir = vim.fn.getcwd() end
+  end)
+
+  after_each(function()
+    -- Cleanup: stop background monitor and release the file picker
+    pcall(fff_rust.stop_background_monitor)
+    pcall(fff_rust.cleanup_file_picker)
+  end)
+
+  describe('init and scan', function()
+    it('should initialize the file picker and scan files', function()
+      local ok = fff_rust.init_file_picker(test_dir)
+      assert.is_true(ok)
+
+      wait_for_scan(10000)
+
+      local progress = fff_rust.get_scan_progress()
+      assert.is_not_nil(progress)
+      assert.is_number(progress.scanned_files_count)
+      assert.is_true(
+        progress.scanned_files_count > 0,
+        'expected scanned files > 0, got ' .. progress.scanned_files_count
+      )
+      assert.is_false(progress.is_scanning)
+    end)
+  end)
+
+  describe('fuzzy search', function()
+    it('should return results for a known query', function()
+      local ok = fff_rust.init_file_picker(test_dir)
+      assert.is_true(ok)
+      wait_for_scan(10000)
+
+      -- Search for "main" which should match main.lua and possibly other files
+      -- Args: query, max_threads, current_file, combo_boost_score_multiplier, min_combo_count, offset, page_size
+      local result = fff_rust.fuzzy_search_files('main', 2, nil, 100, 3, 0, 10)
+      assert.is_not_nil(result)
+      assert.is_not_nil(result.items)
+      assert.is_true(#result.items > 0, 'expected search results for "main"')
+
+      -- Each item should have required fields
+      local first = result.items[1]
+      assert.is_not_nil(first.relative_path)
+      assert.is_string(first.relative_path)
+    end)
+
+    it('should return empty results for nonsense query', function()
+      local ok = fff_rust.init_file_picker(test_dir)
+      assert.is_true(ok)
+      wait_for_scan(10000)
+
+      local result = fff_rust.fuzzy_search_files('zzzxxxqqq_no_match_ever', 2, nil, 100, 3, 0, 10)
+      assert.is_not_nil(result)
+      assert.is_not_nil(result.items)
+      assert.are.equal(0, #result.items)
+    end)
+  end)
+
+  describe('git root detection', function()
+    it('should return the git root for a git repository', function()
+      local ok = fff_rust.init_file_picker(test_dir)
+      assert.is_true(ok)
+      wait_for_scan(10000)
+
+      local git_root = fff_rust.get_git_root()
+      assert.is_not_nil(git_root, 'expected git root to be found in the plugin repo')
+      assert.is_string(git_root)
+      -- The git root should be a real directory
+      assert.are.equal(1, vim.fn.isdirectory(git_root), 'git root should be a valid directory: ' .. git_root)
+    end)
+
+    it('should return nil for a non-git directory', function()
+      -- Use a temp directory that is definitely not a git repo
+      local tmp_dir = vim.fn.tempname()
+      vim.fn.mkdir(tmp_dir, 'p')
+
+      local ok = fff_rust.init_file_picker(tmp_dir)
+      assert.is_true(ok)
+      wait_for_scan(10000)
+
+      local git_root = fff_rust.get_git_root()
+      assert.is_nil(git_root)
+
+      vim.fn.delete(tmp_dir, 'rf')
+    end)
+  end)
+
+  describe('health check', function()
+    it('should return version and component status', function()
+      local ok = fff_rust.init_file_picker(test_dir)
+      assert.is_true(ok)
+      wait_for_scan(10000)
+
+      local health = fff_rust.health_check(test_dir)
+      assert.is_not_nil(health)
+      assert.is_string(health.version)
+
+      -- Git info should be present
+      assert.is_not_nil(health.git)
+      assert.is_true(health.git.available)
+      assert.is_string(health.git.libgit2_version)
+
+      -- File picker should be initialized
+      assert.is_not_nil(health.file_picker)
+      assert.is_true(health.file_picker.initialized)
+      assert.is_string(health.file_picker.base_path)
+    end)
+  end)
+end)
@@ -0,0 +1,17 @@
+--- Minimal test runner for plenary busted-style tests
+--- Usage: nvim --headless -u tests/minimal_init.lua -c "PlenaryBustedDirectory tests/ {minimal_init = 'tests/minimal_init.lua'}"
+
+-- Set up runtimepath to include the plugin and plenary
+local plugin_dir = vim.fn.fnamemodify(vim.fn.resolve(vim.fn.expand('<sfile>:p')), ':h:h')
+local plenary_dir = os.getenv('PLENARY_DIR') or (plugin_dir .. '/../plenary.nvim')
+
+vim.opt.runtimepath:prepend(plugin_dir)
+vim.opt.runtimepath:prepend(plenary_dir)
+
+-- Disable swap files and other noise for testing
+vim.o.swapfile = false
+vim.o.backup = false
+vim.o.writebackup = false
+
+-- Set cwd to the plugin directory so test_dir resolution is reliable
+vim.cmd('cd ' .. vim.fn.fnameescape(plugin_dir))
Author	SHA1	Message	Date
Dmitriy Kovalenko	6a3e481175	fix: Only use static linking libraries on windows (#232 ) closes https://github.com/dmtrKovalenko/fff.nvim/issues/228	2026-02-16 12:12:51 -08:00
Dmitriy Kovalenko	29e13ac3d4	feat: Live grep (#231 ) * feat: Live grep * chore: Update docs for - feat: Live grep * chore: Update docs for - chore: Update docs for - feat: Live grep * fix formatting * chore: Update docs for - fix formatting	2026-02-15 21:42:42 -08:00
Dmitriy Kovalenko	c9137b19b6	fix: Windows long path prefix (#226 ) closes https://github.com/dmtrKovalenko/fff.nvim/issues/221	2026-02-12 00:39:07 -08:00
Dmitriy Kovalenko	00019beb0c	feat: Query parsing (HUGE THING READ CHANGELOG) (#224 ) * query parsing * chore: Update docs for - query parsing * query parsing * Bun ffi * chore: Update docs for - Bun ffi * fix cross + zig relation * chore: Update docs for - fix cross + zig relation * skip windows build * publish the release * window * correct linking for windows dll cdylib * chore: Update docs for - correct linking for windows dll cdylib * feat: Add aarch64 windows target * improve ffi str allocation * fix aarch windows * fix nix * improve allocations * chore: Update docs for - improve allocations * fix style	2026-02-11 23:58:11 -08:00