feat(terminal): improve visual mode handling and terminal focus logic

Change-Id: I2cfe67e68f381e234a32692e88f9febb7c8007cd
Signed-off-by: Thomas Kosiewski <[email protected]>

Author: ThomasK33

README.md

@@ -8,8 +8,8 @@ A Neovim plugin that integrates with Claude Code CLI to provide a seamless AI co
 
 ## Features
 
-- 🔄 **Pure Neovim WebSocket Server** - Zero external dependencies, uses only Neovim built-ins
-- 🌐 **RFC 6455 Compliant** - Full WebSocket protocol implementation with JSON-RPC 2.0
+- 🔄 **Pure Neovim WebSocket Server** (implemented with Neovim built-ins)
+- 🌐 **RFC 6455 Compliant** (WebSocket with JSON-RPC 2.0)
 - 🔍 Selection tracking to provide context to Claude
 - 🛠️ Integration with Neovim's buffer and window management
 - 📝 Support for file operations and diagnostics
@@ -22,7 +22,7 @@ A Neovim plugin that integrates with Claude Code CLI to provide a seamless AI co
 - Claude Code CLI installed and in your PATH
 - **Optional for terminal integration:** [folke/snacks.nvim](https://github.com/folke/snacks.nvim) - Terminal management plugin (can use native Neovim terminal as an alternative).
 
-**Zero External Dependencies**: The WebSocket server is implemented using pure Neovim built-ins (`vim.loop`, `vim.json`, `vim.schedule`) with no external Lua libraries required.
+The WebSocket server uses only Neovim built-ins (`vim.loop`, `vim.json`, `vim.schedule`) for its implementation.
 
 Note: The terminal feature can use `Snacks.nvim` or the native Neovim terminal. If `Snacks.nvim` is configured as the provider but is not available, it will fall back to the native terminal.
 
@@ -54,10 +54,10 @@ Add the following to your plugins configuration:
   config = true,
   -- Optional: Add convenient keymaps
   keys = {
-    { "<leader>cc", "<cmd>ClaudeCode<cr>", desc = "Toggle Claude Terminal" },
-    { "<leader>ck", "<cmd>ClaudeCodeSend<cr>", desc = "Send to Claude Code" },
-    { "<leader>co", "<cmd>ClaudeCodeOpen<cr>", desc = "Open Claude Terminal" },
-    { "<leader>cx", "<cmd>ClaudeCodeClose<cr>", desc = "Close Claude Terminal" },
+    { "<leader>ac", "<cmd>ClaudeCode<cr>", mode = { "n", "v" }, desc = "Toggle Claude Terminal" },
+    { "<leader>ak", "<cmd>ClaudeCodeSend<cr>", mode = { "n", "v" }, desc = "Send to Claude Code" },
+    { "<leader>ao", "<cmd>ClaudeCodeOpen<cr>", mode = { "n", "v" }, desc = "Open/Focus Claude Terminal" },
+    { "<leader>ax", "<cmd>ClaudeCodeClose<cr>", mode = { "n", "v" }, desc = "Close Claude Terminal" },
   },
 }
 ```
@@ -124,21 +124,21 @@ return {
     },
     config = true,
     keys = {
-      { "<leader>cc", "<cmd>ClaudeCode<cr>", desc = "Toggle Claude Terminal" },
-      { "<leader>ck", "<cmd>ClaudeCodeSend<cr>", desc = "Send to Claude Code" },
-      { "<leader>co", "<cmd>ClaudeCodeOpen<cr>", desc = "Open Claude Terminal" },
-      { "<leader>cx", "<cmd>ClaudeCodeClose<cr>", desc = "Close Claude Terminal" },
+      { "<leader>ac", "<cmd>ClaudeCode<cr>", mode = { "n", "v" }, desc = "Toggle Claude Terminal" },
+      { "<leader>ak", "<cmd>ClaudeCodeSend<cr>", mode = { "n", "v" }, desc = "Send to Claude Code" },
+      { "<leader>ao", "<cmd>ClaudeCodeOpen<cr>", mode = { "n", "v" }, desc = "Open/Focus Claude Terminal" },
+      { "<leader>ax", "<cmd>ClaudeCodeClose<cr>", mode = { "n", "v" }, desc = "Close Claude Terminal" },
     },
   },
 }
 ```
 
 This configuration:
 
-1. Uses the `dir` parameter to specify the local path to your repository
-2. Sets `dev = true` to enable development mode
-3. Sets a more verbose log level for debugging
-4. Adds convenient keymaps for testing
+1. Specifies the local repository path using the `dir` parameter.
+2. Enables development mode via `dev = true`.
+3. Sets a more verbose `log_level` for debugging.
+4. Includes convenient keymaps for easier testing.
 
 ## Configuration
 
@@ -213,7 +213,7 @@ require("claudecode").setup({
 
    - Use normal Vim window navigation (`Ctrl+w` commands)
    - Or toggle the terminal with `:ClaudeCode`
-   - Open/focus with `:ClaudeCodeOpen`
+   - Open/focus with `:ClaudeCodeOpen` (can also be used from Visual mode to switch focus after selection)
    - Close with `:ClaudeCodeClose`
 
 4. Use Claude as normal - it will have access to your Neovim editor context!
@@ -233,12 +233,12 @@ require("claudecode").setup({
 No default keymaps are provided. Add your own in your configuration:
 
 ```lua
-vim.keymap.set("n", "<leader>cc", "<cmd>ClaudeCode<cr>", { desc = "Toggle Claude Terminal" })
-vim.keymap.set({"n", "v"}, "<leader>ck", "<cmd>ClaudeCodeSend<cr>", { desc = "Send to Claude Code" })
+vim.keymap.set({"n", "v"}, "<leader>ac", "<cmd>ClaudeCode<cr>", { desc = "Toggle Claude Terminal" })
+vim.keymap.set({"n", "v"}, "<leader>ak", "<cmd>ClaudeCodeSend<cr>", { desc = "Send to Claude Code" })
 
 -- Or more specific maps:
-vim.keymap.set("n", "<leader>co", "<cmd>ClaudeCodeOpen<cr>", { desc = "Open Claude Terminal" })
-vim.keymap.set("n", "<leader>cx", "<cmd>ClaudeCodeClose<cr>", { desc = "Close Claude Terminal" })
+vim.keymap.set({"n", "v"}, "<leader>ao", "<cmd>ClaudeCodeOpen<cr>", { desc = "Open/Focus Claude Terminal" })
+vim.keymap.set({"n", "v"}, "<leader>ax", "<cmd>ClaudeCodeClose<cr>", { desc = "Close Claude Terminal" })
 ```
 
 ## Architecture

lua/claudecode/terminal.lua

@@ -290,17 +290,18 @@ local function build_snacks_opts(effective_term_config_for_snacks, env_table)
       height = 0, -- 0 for full height in snacks.win
       relative = "editor",
       on_close = function(self) -- self here is the snacks.win instance
-        if managed_snacks_terminal and managed_snacks_terminal.winid == self.winid then
+        if managed_snacks_terminal and managed_snacks_terminal.win == self.win then
           managed_snacks_terminal = nil
         end
       end,
     },
   }
 end
 
--- Helper function to get the base claude command and necessary environment variables.
--- @return string|nil The base command string.
--- @return table|nil The environment variables table.
+--- Gets the base claude command and necessary environment variables.
+-- @local
+-- @return string|nil base_command The base command string, or nil on failure.
+-- @return table|nil env_table The environment variables table, or nil on failure.
 local function get_claude_command_and_env()
   local base_command = get_claude_command()
   if not base_command or base_command == "" then
@@ -321,6 +322,7 @@ local function get_claude_command_and_env()
 end
 
 --- Opens or focuses the Claude terminal.
+-- @param opts_override table (optional) Overrides for terminal appearance (split_side, split_width_percentage).
 function M.open(opts_override)
   local provider = get_effective_terminal_provider()
   local effective_config = build_effective_term_config(opts_override)
@@ -382,14 +384,14 @@ function M.close()
 end
 
 --- Toggles the Claude terminal open or closed.
+-- @param opts_override table (optional) Overrides for terminal appearance (split_side, split_width_percentage).
 function M.toggle(opts_override)
   local provider = get_effective_terminal_provider()
   local effective_config = build_effective_term_config(opts_override)
   local base_claude_command, claude_env_table = get_claude_command_and_env()
 
   if not base_claude_command then
-    -- Error already notified by the helper function
-    return
+    return -- Error already notified
   end
 
   if provider == "snacks" then
@@ -398,15 +400,51 @@ function M.toggle(opts_override)
       return
     end
     local snacks_opts = build_snacks_opts(effective_config, claude_env_table)
-    local term_instance = Snacks.terminal.toggle(base_claude_command, snacks_opts)
-    if term_instance and term_instance:valid() then
-      managed_snacks_terminal = term_instance
+
+    if managed_snacks_terminal and managed_snacks_terminal:valid() and managed_snacks_terminal.win then
+      local claude_term_neovim_win_id = managed_snacks_terminal.win
+      local current_neovim_win_id = vim.api.nvim_get_current_win()
+
+      if claude_term_neovim_win_id == current_neovim_win_id then
+        -- Snacks.terminal.toggle will return an invalid instance or nil.
+        -- The on_close callback (defined in build_snacks_opts) will set managed_snacks_terminal to nil.
+        local closed_instance = Snacks.terminal.toggle(base_claude_command, snacks_opts)
+        if closed_instance and closed_instance:valid() then
+          -- This would be unexpected if it was supposed to close and on_close fired.
+          -- As a fallback, ensure our state reflects what Snacks returned if it's somehow still valid.
+          managed_snacks_terminal = closed_instance
+        end
+      else
+        vim.api.nvim_set_current_win(claude_term_neovim_win_id)
+        if managed_snacks_terminal.buf and vim.api.nvim_buf_is_valid(managed_snacks_terminal.buf) then
+          if vim.api.nvim_buf_get_option(managed_snacks_terminal.buf, "buftype") == "terminal" then
+            vim.api.nvim_win_call(claude_term_neovim_win_id, function()
+              vim.cmd("startinsert")
+            end)
+          end
+        end
+      end
     else
-      managed_snacks_terminal = nil -- Snacks.toggle returns nil if closed or failed
+      local term_instance = Snacks.terminal.toggle(base_claude_command, snacks_opts)
+      if term_instance and term_instance:valid() and term_instance.win then
+        managed_snacks_terminal = term_instance
+      else
+        managed_snacks_terminal = nil -- Ensure it's nil if open failed or instance invalid
+        if not (term_instance == nil and managed_snacks_terminal == nil) then -- Avoid notify if toggle returned nil and we set to nil
+          vim.notify("Failed to open Snacks terminal or instance invalid after toggle.", vim.log.levels.WARN)
+        end
+      end
     end
   elseif provider == "native" then
     if is_fallback_terminal_valid() then
-      close_fallback_terminal()
+      local claude_term_neovim_win_id = managed_fallback_terminal_winid
+      local current_neovim_win_id = vim.api.nvim_get_current_win()
+
+      if claude_term_neovim_win_id == current_neovim_win_id then
+        close_fallback_terminal()
+      else
+        focus_fallback_terminal() -- This already calls startinsert
+      end
     else
       if not open_fallback_terminal(base_claude_command, claude_env_table, effective_config) then
         vim.notify("Failed to open Claude terminal using native fallback (toggle).", vim.log.levels.ERROR)
@@ -415,7 +453,10 @@ function M.toggle(opts_override)
   end
 end
 
--- Test helper function to access managed terminal for testing
+--- Gets the managed terminal instance for testing purposes.
+-- NOTE: This function is intended for use in tests to inspect internal state.
+-- The underscore prefix indicates it's not part of the public API for regular use.
+-- @return table|nil The managed Snacks terminal instance, or nil.
 function M._get_managed_terminal_for_test()
   return managed_snacks_terminal
 end

plugin/claudecode.lua

@@ -8,7 +8,6 @@ if vim.g.loaded_claudecode then
 end
 vim.g.loaded_claudecode = 1
 
--- If the user has set auto-load configuration, load it.
 -- Example in init.lua: vim.g.claudecode_auto_setup = { auto_start = true }
 if vim.g.claudecode_auto_setup then
   vim.defer_fn(function()
@@ -20,6 +19,10 @@ local terminal_ok, terminal = pcall(require, "claudecode.terminal")
 
 if terminal_ok then
   vim.api.nvim_create_user_command("ClaudeCode", function(_opts)
+    local current_mode = vim.fn.mode()
+    if current_mode == "v" or current_mode == "V" or current_mode == "\22" then -- \22 is CTRL-V for blockwise visual
+      vim.api.nvim_feedkeys(vim.api.nvim_replace_termcodes("<Esc>", true, false, true), "n", false)
+    end
     terminal.toggle({}) -- opts.fargs could be used for future enhancements
   end, {
     nargs = "?", -- Allow optional arguments for future enhancements