feat(nvim): refine grep results with a fuzzy filter

README.md

@@ -455,6 +455,8 @@ require('fff').setup({
     preview_scroll_down = '<C-d>',
     toggle_debug = '<F2>',
     cycle_grep_modes = '<S-Tab>',
+    -- grep mode only: fuzzy filter the current matches instead of searching again
+    toggle_grep_refine = '<C-g>',
     insert_newline_escape = '<C-CR>',
     -- grep mode only: jump cursor to first match of next/prev file group
     grep_jump_to_next_file = { '<C-A-n>', '<A-Down>' },
@@ -567,6 +569,12 @@ require('fff').live_grep({ query = 'user_file', grep = { modes = { 'definition_o
 local page = require('fff').content_search('user_file', { mode = 'definition_only' })
 ```
 
+### Refine grep results
+
+`<C-g>` (`keymaps.toggle_grep_refine`) collects every match of the current grep query and clears the prompt. What you type next fuzzy filters those matches by line content and file path instead of searching again. Matching is smart case, and words separated by spaces must all match. Filtered matches keep their grep order. The status shows the filtered and total counts and the collected query, highlighted with `hl.grep_refine_active` (default: `DiagnosticWarn`). Press `<C-g>` again to return to live grep with the original query.
+
+Collection ignores `grep.max_matches_per_file` and stops at 10,000 matches, shown as a `+` after the total. With nothing selected, `<C-q>` sends the filtered matches to the quickfix list.
+
 ### Constraints
 
 Both find and grep accept these tokens to refine a query:

lua/fff/conf.lua

@@ -38,6 +38,7 @@ local M = {}
 --- @field preview_scroll_down string
 --- @field toggle_debug string
 --- @field cycle_grep_modes string
+--- @field toggle_grep_refine string|string[]
 --- @field insert_newline_escape string
 --- @field cycle_previous_query string
 --- @field cycle_forward_query string
@@ -331,6 +332,8 @@ local function init()
       toggle_debug = '<F2>',
       -- Cycle between configured grep modes.
       cycle_grep_modes = '<S-Tab>',
+      -- grep mode only: fuzzy filter the current query's matches instead of searching again
+      toggle_grep_refine = '<C-g>',
       -- grep mode only: insert a literal `\n` to search across lines
       -- (requires a terminal with extended-key support to distinguish from <CR>)
       insert_newline_escape = '<C-CR>',
@@ -394,6 +397,7 @@ local function init()
       grep_plain_active = 'Comment', -- Highlight for keybind + label when regex is off
       grep_fuzzy_active = 'DiagnosticHint', -- Highlight for keybind + label when fuzzy is on
       grep_definition_active = 'DiagnosticOk', -- Highlight for the definitions-only mode
+      grep_refine_active = 'DiagnosticWarn', -- Highlight for the refine indicator
       -- Cross-mode suggestion highlights
       suggestion_header = 'WarningMsg', -- Highlight for the "No results found. Suggested..." banner
       -- File info panel highlights

lua/fff/picker_ui/grep_refine.lua

@@ -0,0 +1,106 @@
+local M = {}
+
+local grep = require('fff.picker_ui.grep_renderer')
+local picker_ui_state = require('fff.picker_ui.picker_ui_state')
+
+local S = picker_ui_state.state
+
+-- Same cap as the exhaustive quickfix search
+local MAX_MATCHES = 10000
+
+---@class fff.grep.RefineState
+---@field query string Grep query whose matches were collected
+---@field items fff.grep.Match[] Every collected match
+---@field haystack {text: string, idx: number}[] Fuzzy match targets, one per item
+---@field filtered fff.grep.Match[] Items matching the current prompt
+---@field truncated boolean True when collection stopped at the match cap
+
+local collect_matches
+
+--- Collect every match of the current grep query so the prompt can filter them.
+---@return boolean started False when there is nothing to refine
+function M.start()
+  if S.mode ~= 'grep' or S.refine or S.query == '' or S.suggestion_source then return false end
+
+  local items, truncated = collect_matches(S.query)
+  if #items == 0 then return false end
+
+  local haystack = {}
+  for i, item in ipairs(items) do
+    local content = item.is_binary_content and '' or (item.line_content or '')
+    haystack[i] = { text = content .. ' ' .. (item.relative_path or ''), idx = i }
+  end
+
+  S.refine = { query = S.query, items = items, haystack = haystack, filtered = items, truncated = truncated }
+  return true
+end
+
+--- Drop the collected matches.
+---@return string query The grep query to search again
+function M.stop()
+  local query = S.refine and S.refine.query or ''
+  S.refine = nil
+  return query
+end
+
+--- Fuzzy filter the collected matches, keeping grep order.
+---@param query string
+function M.filter(query)
+  local refine = S.refine
+  if not refine then return end
+  if query == '' then
+    refine.filtered = refine.items
+    return
+  end
+
+  local matched = vim.fn.matchfuzzy(refine.haystack, query, { key = 'text' })
+  local indices = {}
+  for i, entry in ipairs(matched) do
+    indices[i] = entry.idx
+  end
+  table.sort(indices)
+
+  local filtered = {}
+  for i, idx in ipairs(indices) do
+    filtered[i] = refine.items[idx]
+  end
+  refine.filtered = filtered
+end
+
+--- A page of filtered matches shaped like a grep search result.
+---@param offset number Index of the first match on the page (0-based)
+---@param page_size number
+---@return {items: fff.grep.Match[], total_matched: number, next_file_offset: number}
+function M.page(offset, page_size)
+  local filtered = S.refine and S.refine.filtered or {}
+  local items = {}
+  for i = offset + 1, math.min(offset + page_size, #filtered) do
+    items[#items + 1] = filtered[i]
+  end
+
+  local next_offset = offset + page_size
+  if next_offset >= #filtered then next_offset = 0 end
+
+  return { items = items, total_matched = #filtered, next_file_offset = next_offset }
+end
+
+collect_matches = function(query)
+  local config = vim.tbl_extend('force', S.grep_config or require('fff.conf').get().grep, { max_matches_per_file = 0 })
+  local definitions, others = {}, {}
+  local offset, count = 0, 0
+
+  repeat
+    local result = grep.search(query, offset, MAX_MATCHES - count, config, S.grep_mode)
+    for _, item in ipairs(result.items or {}) do
+      table.insert(item.is_definition and definitions or others, item)
+      count = count + 1
+    end
+    offset = result.next_file_offset or 0
+  until offset == 0 or count >= MAX_MATCHES
+
+  -- Each grep page lists its definitions first; keep that order across pages
+  vim.list_extend(definitions, others)
+  return definitions, offset ~= 0
+end
+
+return M

lua/fff/picker_ui/layout_manager.lua

@@ -137,6 +137,7 @@ function M.close()
   S.grep_config = nil
   S.grep_mode = 'plain'
   S.grep_regex_fallback_error = nil
+  S.refine = nil
   S.suggestion_items = nil
   S.suggestion_source = nil
   S.renderer = nil

lua/fff/picker_ui/picker_ui.lua

@@ -50,6 +50,7 @@ M.load_next_page = search_manager.load_next_page
 M.load_previous_page = search_manager.load_previous_page
 M.on_input_change = search_manager.on_input_change
 M.cycle_grep_modes = search_manager.cycle_grep_modes
+M.toggle_grep_refine = search_manager.toggle_grep_refine
 M.recall_query_from_history = search_manager.recall_query_from_history
 M.cycle_forward_query = search_manager.cycle_forward_query
 M.clear_query = search_manager.clear_query
@@ -95,7 +96,7 @@ local resume_state = { files = nil, grep = nil, last_mode = nil }
 
 --- Save the current picker state for later resume, then close.
 function M.close()
-  if M.state.query == '' then
+  if M.state.query == '' and not M.state.refine then
     layout_manager.close()
     return
   end
@@ -134,6 +135,7 @@ local function restore_from_state(state, source_label)
   M.state.mode = state.mode
   M.state.grep_config = state.grep_config
   M.state.grep_mode = state.grep_mode
+  M.state.refine = state.refine
   M.state.selected_files = vim.deepcopy(state.selected_files or {})
   M.state.selected_file_order = vim.deepcopy(state.selected_file_order or {})
   M.state.selected_items = vim.deepcopy(state.selected_items or {})
@@ -271,6 +273,7 @@ function M.toggle_debug()
     local current_renderer = M.state.renderer
     local current_grep_mode = M.state.grep_mode
     local current_grep_config = M.state.grep_config
+    local current_refine = M.state.refine
     local current_filtered_items = M.state.filtered_items
     local current_selected_files = M.state.selected_files
     local current_selected_file_order = M.state.selected_file_order
@@ -287,6 +290,7 @@ function M.toggle_debug()
     M.state.items = current_items
     M.state.cursor = current_cursor
     M.state.grep_mode = current_grep_mode
+    M.state.refine = current_refine
     M.state.filtered_items = current_filtered_items
     M.state.selected_files = current_selected_files
     M.state.selected_file_order = current_selected_file_order
@@ -316,12 +320,45 @@ function M.render_debounced()
   end)
 end
 
+local function update_refine_status()
+  local config = M.state.config
+  local refine = M.state.refine
+  local keybind = config.keymaps.toggle_grep_refine
+  if type(keybind) == 'table' then keybind = keybind[1] end
+
+  local count = string.format('%d/%d%s', #refine.filtered, #refine.items, refine.truncated and '+' or '')
+  local query = refine.query
+  if vim.fn.strchars(query) > 24 then query = vim.fn.strcharpart(query, 0, 23) .. '…' end
+  local label = (keybind and keybind .. ' ' or '') .. 'refine "' .. query .. '"'
+
+  local cache_key = 'refine' .. count .. label
+  if cache_key == M.state.last_status_info then return end
+  M.state.last_status_info = cache_key
+
+  vim.api.nvim_buf_clear_namespace(M.state.input_buf, M.state.ns_id, 0, -1)
+
+  local available_width = vim.api.nvim_win_get_width(M.state.input_win) - 2
+  local total_width = vim.fn.strdisplaywidth(count .. '  ' .. label)
+  vim.api.nvim_buf_set_extmark(M.state.input_buf, M.state.ns_id, 0, 0, {
+    virt_text = {
+      { count, 'LineNr' },
+      { '  ' .. label, config.hl.grep_refine_active or 'DiagnosticWarn' },
+    },
+    virt_text_win_col = math.max(0, available_width - total_width),
+  })
+end
+
 --- Update status information on the right side of input using virtual text
 function M.update_status(progress)
   if not M.state.active or not M.state.ns_id then return end
   local config = M.state.config
   if config == nil then return end
 
+  if M.state.refine then
+    update_refine_status()
+    return
+  end
+
   if M.state.mode == 'grep' then
     -- Determine available modes to decide if we should show the mode indicator
     -- Use grep_config.modes if provided, otherwise fall back to global config
@@ -469,7 +506,7 @@ function M.select(action)
   if not abs_path then return end
   local relative_path = vim.fn.fnamemodify(abs_path, ':.')
   local location = M.state.location -- Capture location before closing
-  local query = M.state.query -- Capture query before closing for tracking
+  local query = picker_ui_state.grep_query() -- Capture query before closing for tracking
   local mode = M.state.mode -- Capture mode before closing for tracking
   local suggestion_source = M.state.suggestion_source -- Capture suggestion context
   local config = M.state.config -- Capture config before M.close() resets state

lua/fff/picker_ui/picker_ui_state.lua

@@ -62,6 +62,8 @@ M.state = {
   grep_mode = 'plain',
   grep_config = nil,
   grep_regex_fallback_error = nil,
+  ---@type fff.grep.RefineState|nil Collected matches the prompt filters instead of searching
+  refine = nil,
 
   -- Selection state
   selected_files = {},
@@ -141,6 +143,7 @@ function M.reset_state()
   M.state.grep_mode = 'plain'
   M.state.grep_config = nil
   M.state.grep_regex_fallback_error = nil
+  M.state.refine = nil
 
   M.state.selected_files = {}
   M.state.selected_file_order = {}
@@ -160,6 +163,10 @@ function M.reset_state()
   M.state.updating_from_history = false
 end
 
+--- Grep query behind the results, which is not the prompt while refining
+--- @return string
+function M.grep_query() return M.state.refine and M.state.refine.query or M.state.query end
+
 -- Clear all selections
 function M.clear_selections()
   M.state.selected_files = {}

lua/fff/picker_ui/preview_manager.lua

@@ -176,7 +176,7 @@ function M.update_preview()
   if is_grep_item and item.line_number and item.line_number > 0 then
     effective_location = { line = item.line_number }
     if item.col and item.col > 0 then effective_location.col = item.col + 1 end
-    effective_location.grep_query = S.query
+    effective_location.grep_query = picker_ui_state.grep_query()
     if S.grep_mode == 'fuzzy' and item.match_ranges then effective_location.fuzzy_match_ranges = item.match_ranges end
   end
 

lua/fff/picker_ui/renderer.lua

@@ -93,11 +93,13 @@ local function render_grep_empty_state(ctx)
     table.insert(content, '  Start typing to search file contents...')
   end
   table.insert(content, '')
-  table.insert(content, '  Tips:')
-  table.insert(content, '    "pattern *.rs"    search only in Rust files')
-  table.insert(content, '    "pattern /src/"   limit search to src/ directory')
-  table.insert(content, '    "!test pattern"   exclude test files')
-  table.insert(content, '')
+  if not S.refine then
+    table.insert(content, '  Tips:')
+    table.insert(content, '    "pattern *.rs"    search only in Rust files')
+    table.insert(content, '    "pattern /src/"   limit search to src/ directory')
+    table.insert(content, '    "!test pattern"   exclude test files')
+    table.insert(content, '')
+  end
 
   if prompt_position == 'bottom' then
     local empty_needed = math.max(0, win_height - #content)