Improve NES Suggestion Clearing with Smarter Cursor-Aware Behavior (#37)

* feat: intelligent mechanism to handle clearing suggestion see #36

* docs: update Readme to include the new command

* fix: fix unused variable to satisfy luacheck

* tests: Adding cursor-aware suggestion tests

* feat: Adding new unified counter for clearing nes

* tests: Fixing tests for new clearing nes

* fix: Adding buffer validations to prevent errors

* docs: update readme with default config

* chore: clear unused variable

* fix: correct variable name

* chore: making opts inside nes table

* fix: satisfy the stylua test

* feat: Add type annotations

* docs: make nes options private

---------

Co-authored-by: Bassam Data <[email protected]>

Author: bassamsdata

README.md

@@ -39,6 +39,36 @@ return {
 }
 ```
 
+
+#### Clearing suggestions with Escape
+
+You can map the `<Esc>` key to clear suggestions while preserving its other functionality:
+
+```lua
+-- Clear copilot suggestion with Esc if visible, otherwise preserve default Esc behavior
+vim.keymap.set("n", "<esc>", function()
+    if not require('copilot-lsp.nes').clear() then
+        -- fallback to other functionality
+    end
+end, { desc = "Clear Copilot suggestion or fallback" })
+```
+
+## Default Configuration
+
+
+### NES (Next Edit Suggestion) Smart Clearing
+You don’t need to configure anything, but you can customize the defaults:
+`move_count_threshold` is the most important. It controls how many cursor moves happen before suggestions are cleared. Higher = slower to clear.
+
+```lua
+require('copilot-lsp').setup({
+  nes = {
+    move_count_threshold = 3,   -- Clear after 3 cursor movements
+  }
+})
+```
+
+
 ### Blink Integration
 
 ```lua

lua/copilot-lsp/config.lua

@@ -0,0 +1,31 @@
+---@class copilotlsp.config.nes
+---@field move_count_threshold integer Number of cursor movements before clearing suggestion
+---@field distance_threshold integer Maximum line distance before clearing suggestion
+---@field clear_on_large_distance boolean Whether to clear suggestion when cursor is far away
+---@field count_horizontal_moves boolean Whether to count horizontal cursor movements
+---@field reset_on_approaching boolean Whether to reset counter when approaching suggestion
+
+local M = {}
+
+---@class copilotlsp.config
+---@field nes copilotlsp.config.nes
+M.defaults = {
+    nes = {
+        move_count_threshold = 3,
+        distance_threshold = 40,
+        clear_on_large_distance = true,
+        count_horizontal_moves = true,
+        reset_on_approaching = true,
+    },
+}
+
+---@type copilotlsp.config
+M.config = vim.deepcopy(M.defaults)
+
+---@param opts? copilotlsp.config configuration to merge with defaults
+function M.setup(opts)
+    opts = opts or {}
+    M.config = vim.tbl_deep_extend("force", M.defaults, opts)
+end
+
+return M

lua/copilot-lsp/init.lua

@@ -0,0 +1,18 @@
+local config = require("copilot-lsp.config")
+
+---@class copilotlsp
+---@field defaults copilotlsp.config
+---@field config copilotlsp.config
+---@field setup fun(opts?: copilotlsp.config): nil
+local M = {}
+
+M.defaults = config.defaults
+M.config = config.config
+
+---@param opts? copilotlsp.config configuration to merge with defaults
+function M.setup(opts)
+    config.setup(opts)
+    M.config = config.config
+end
+
+return M

lua/copilot-lsp/nes/init.lua

@@ -14,6 +14,10 @@ local function handle_nes_response(err, result, ctx)
         -- vim.notify(err.message)
         return
     end
+    -- Validate buffer still exists before processing response
+    if not vim.api.nvim_buf_is_valid(ctx.bufnr) then
+        return
+    end
     for _, edit in ipairs(result.edits) do
         --- Convert to textEdit fields
         edit.newText = edit.text
@@ -119,4 +123,16 @@ function M.clear_suggestion(bufnr)
     nes_ui.clear_suggestion(bufnr, nes_ns)
 end
 
+--- Clear the current suggestion if it exists
+---@return boolean -- true if a suggestion was cleared, false if no suggestion existed
+function M.clear()
+    local buf = vim.api.nvim_get_current_buf()
+    if vim.b[buf].nes_state then
+        local ns = vim.b[buf].copilotlsp_nes_namespace_id or nes_ns
+        nes_ui.clear_suggestion(buf, ns)
+        return true
+    end
+    return false
+end
+
 return M

lua/copilot-lsp/nes/ui.lua

@@ -1,4 +1,5 @@
 local M = {}
+local config = require("copilot-lsp.config").config
 
 ---@param bufnr integer
 ---@param ns_id integer
@@ -10,6 +11,10 @@ end
 ---@param ns_id integer
 function M.clear_suggestion(bufnr, ns_id)
     bufnr = bufnr and bufnr > 0 and bufnr or vim.api.nvim_get_current_buf()
+    -- Validate buffer exists before accessing buffer-scoped variables
+    if not vim.api.nvim_buf_is_valid(bufnr) then
+        return
+    end
     if vim.b[bufnr].nes_jump then
         vim.b[bufnr].nes_jump = false
         return
@@ -21,7 +26,11 @@ function M.clear_suggestion(bufnr, ns_id)
         return
     end
 
+    -- Clear buffer variables
     vim.b[bufnr].nes_state = nil
+    vim.b[bufnr].copilotlsp_nes_cursor_moves = nil
+    vim.b[bufnr].copilotlsp_nes_last_line = nil
+    vim.b[bufnr].copilotlsp_nes_last_col = nil
 end
 
 ---@private
@@ -159,26 +168,110 @@ end
 function M._display_next_suggestion(bufnr, ns_id, edits)
     M.clear_suggestion(bufnr, ns_id)
     if not edits or #edits == 0 then
-        -- vim.notify("No suggestion available", vim.log.levels.INFO)
         return
     end
 
     local suggestion = edits[1]
-
     local preview = M._calculate_preview(bufnr, suggestion)
     M._display_preview(bufnr, ns_id, preview)
 
     vim.b[bufnr].nes_state = suggestion
+    vim.b[bufnr].copilotlsp_nes_namespace_id = ns_id
+    vim.b[bufnr].copilotlsp_nes_cursor_moves = 1
 
     vim.api.nvim_create_autocmd({ "CursorMoved", "CursorMovedI" }, {
         buffer = bufnr,
         callback = function()
-            if not vim.b.nes_state then
+            if not vim.b[bufnr].nes_state then
+                return true
+            end
+
+            -- Get cursor position
+            local cursor = vim.api.nvim_win_get_cursor(0)
+            local cursor_line = cursor[1] - 1 -- 0-indexed
+            local cursor_col = cursor[2]
+            local suggestion_line = suggestion.range.start.line
+
+            -- Store previous position
+            local last_line = vim.b[bufnr].copilotlsp_nes_last_line or cursor_line
+            local last_col = vim.b[bufnr].copilotlsp_nes_last_col or cursor_col
+
+            -- Update stored position
+            vim.b[bufnr].copilotlsp_nes_last_line = cursor_line
+            vim.b[bufnr].copilotlsp_nes_last_col = cursor_col
+
+            -- Calculate distance to suggestion
+            local line_distance = math.abs(cursor_line - suggestion_line)
+            local last_line_distance = math.abs(last_line - suggestion_line)
+
+            -- Check if cursor changed position on same line
+            local moved_horizontally = (cursor_line == last_line) and (cursor_col ~= last_col)
+
+            -- Get current mode
+            local mode = vim.api.nvim_get_mode().mode
+
+            -- Determine if we should count this movement
+            local should_count = false
+            local first_char = mode:sub(1, 1)
+
+            -- In insert mode, only count cursor movements, not text changes
+            if first_char == "i" then
+                if moved_horizontally or line_distance ~= last_line_distance then
+                    should_count = true
+                end
+            elseif first_char == "v" or first_char == "V" or mode == "\22" then
+                should_count = true
+            -- In normal mode with horizontal movement
+            elseif moved_horizontally and config.nes.count_horizontal_moves then
+                should_count = true
+            -- In normal mode with line changes
+            elseif line_distance > last_line_distance then
+                should_count = true
+            -- Moving toward suggestion in normal mode
+            elseif line_distance < last_line_distance and config.nes.reset_on_approaching then
+                if line_distance > 1 then -- Don't reset if 0 or 1 line away
+                    vim.b[bufnr].copilotlsp_nes_cursor_moves = 0
+                end
+            end
+
+            -- Update counter if needed
+            if should_count then
+                vim.b[bufnr].copilotlsp_nes_cursor_moves = (vim.b[bufnr].copilotlsp_nes_cursor_moves or 0) + 1
+            end
+
+            -- Clear if counter threshold reached
+            if vim.b[bufnr].copilotlsp_nes_cursor_moves >= config.nes.move_count_threshold then
+                vim.b[bufnr].copilotlsp_nes_cursor_moves = 0
+                vim.schedule(function()
+                    M.clear_suggestion(bufnr, ns_id)
+                end)
                 return true
             end
 
-            M.clear_suggestion(bufnr, ns_id)
-            return true
+            -- Optional: Clear on large distance
+            if config.nes.clear_on_large_distance and line_distance > config.nes.distance_threshold then
+                M.clear_suggestion(bufnr, ns_id)
+                return true
+            end
+
+            return false -- Keep the autocmd
+        end,
+    })
+    -- Also clear on text changes that affect the suggestion area
+    vim.api.nvim_create_autocmd({ "TextChanged", "TextChangedI" }, {
+        buffer = bufnr,
+        callback = function()
+            if not vim.b[bufnr].nes_state then
+                return true
+            end
+            -- Check if the text at the suggestion position has changed
+            local start_line = suggestion.range.start.line
+            -- If the lines are no longer in the buffer, clear the suggestion
+            if start_line >= vim.api.nvim_buf_line_count(bufnr) then
+                M.clear_suggestion(bufnr, ns_id)
+                return true
+            end
+            return false -- Keep the autocmd
         end,
     })
 end

tests/nes/test_ui_preview.lua

@@ -258,4 +258,97 @@ do
     end
 end
 
+T["ui_preview"]["cursor_aware_suggestion_clearing"] = function()
+    set_content("line1\nline2\nline3\nline4\nline5\nline6\nline7\nline8")
+    ref(child.get_screenshot())
+
+    -- Create a suggestion at line 3
+    local edit = {
+        range = {
+            start = { line = 2, character = 0 },
+            ["end"] = { line = 2, character = 0 },
+        },
+        newText = "suggested text ",
+    }
+
+    -- Display suggestion
+    child.g.test_edit = edit
+    child.lua_func(function()
+        local ns_id = vim.api.nvim_create_namespace("nes_test")
+        local edits = { vim.g.test_edit }
+        require("copilot-lsp.nes.ui")._display_next_suggestion(0, ns_id, edits)
+    end)
+    ref(child.get_screenshot())
+
+    -- Test 1: Moving cursor nearby shouldn't clear the suggestion (within counter threshold)
+    child.cmd("normal! gg") -- Move to first line (counter: 1 -> 2)
+    child.cmd("normal! j") -- Move to line 2 (counter: 2 -> 3)
+    child.lua_func(function()
+        vim.uv.sleep(500) -- Give time for autocmd to process
+    end)
+
+    -- Verify suggestion still exists (should be at threshold but not exceeded)
+    local suggestion_exists = child.lua_func(function()
+        return vim.b[0].nes_state ~= nil
+    end)
+    eq(suggestion_exists, true)
+    ref(child.get_screenshot())
+
+    -- Test 2: One more move should clear the suggestion (exceeds counter threshold)
+    child.cmd("normal! j")
+    child.cmd("normal! j")
+    child.cmd("normal! j")
+    child.cmd("normal! j")
+    child.cmd("normal! j")
+    child.lua_func(function()
+        vim.uv.sleep(500) -- Give time for autocmd to process
+    end)
+
+    -- Verify suggestion is cleared
+    local suggestion_cleared = child.lua_func(function()
+        return vim.b[0].nes_state == nil
+    end)
+    eq(suggestion_cleared, true)
+    ref(child.get_screenshot())
+end
+
+T["ui_preview"]["suggestion_preserves_on_movement_towards"] = function()
+    set_content("line1\nline2\nline3\nline4\nline5\nline6\nline7\nline8")
+    ref(child.get_screenshot())
+
+    -- Position cursor at line 8
+    child.cmd("normal! gg7j")
+
+    -- Create a suggestion at line 3
+    local edit = {
+        range = {
+            start = { line = 2, character = 0 },
+            ["end"] = { line = 2, character = 0 },
+        },
+        newText = "suggested text ",
+    }
+
+    -- Display suggestion
+    child.g.test_edit = edit
+    child.lua_func(function()
+        local ns_id = vim.api.nvim_create_namespace("nes_test")
+        local edits = { vim.g.test_edit }
+        require("copilot-lsp.nes.ui")._display_next_suggestion(0, ns_id, edits)
+    end)
+    ref(child.get_screenshot())
+
+    -- Test: Moving cursor towards the suggestion (even outside buffer zone) shouldn't clear it
+    child.cmd("normal! 4k") -- Move to line 4, moving towards the suggestion
+    child.lua_func(function()
+        vim.uv.sleep(500)
+    end)
+
+    -- Verify suggestion still exists
+    local suggestion_exists = child.lua_func(function()
+        return vim.b[0].nes_state ~= nil
+    end)
+    eq(suggestion_exists, true)
+    ref(child.get_screenshot())
+end
+
 return T