#+AUTHOR: hamidi-dev

* Kaleidosearch.nvim

A Neovim plugin that colorizes *multiple search terms* with *multiple distinct colors* for better visual tracking.

https://github.com/user-attachments/assets/50a7bbdb-62c5-4c70-be10-86c48ea44d26

** Features

- Highlight multiple search terms with different colors
- Navigate between matches using standard search commands (n/N)
- Add words incrementally without losing existing highlights
- Add word under cursor with a single keymap AND remove it (toggle)
- Add visual selection to highlights
- Optionally dim non-matching text to make colored words stand out
- dot-repeatable: Hit ~.~ at any point and the colors will change
- Colorize entire lines, giving identical lines the same color
- Vim ~word~ token mode respects your buffer's ~iskeyword~ setting
- Colorize real ~tiktoken~ token spans in the buffer

** Installation

Using your favorite plugin manager:

*** lazy.nvim
#+begin_src lua
{
  "hamidi-dev/kaleidosearch.nvim",
  dependencies = {
    "tpope/vim-repeat",       -- optional for dot-repeatability
    "stevearc/dressing.nvim", -- optional for nice input
  },

  config = function()
    require("kaleidosearch").setup({
      -- optional configuration
    })
  end,
}
#+end_src

*** packer.nvim
#+begin_src lua
use {
  'hamidi-dev/kaleidosearch.nvim',
  requires = {
    'tpope/vim-repeat',       -- optional for dot-repeatability
    'stevearc/dressing.nvim', -- optional for nice input
  },
  config = function()
    require('kaleidosearch').setup({
      -- optional configuration
    })
  end
}
#+end_src

** Usage

| Command                       | Description                                  |
|-------------------------------+----------------------------------------------|
| ~:Kaleidosearch word1 word2~  | Highlight specified words with colors        |
| ~:KaleidosearchClear~         | Clear all highlighted words                  |
| ~:KaleidosearchAddWord~       | Add a new word to existing highlights        |
| ~:KaleidosearchToggleCursorWord~ | Toggle word under cursor/selection highlight |
| ~:KaleidosearchColorWords~    | Colorize all vim ~word~ tokens in buffer    |
| ~:KaleidosearchColorWORDS~    | Colorize all vim ~WORD~ tokens in buffer    |
| ~:KaleidosearchColorLines~    | Colorize all lines, identical lines share colors |
| ~:KaleidosearchColorTokens~   | Colorize real ~tiktoken~ token spans in buffer |
| ~:KaleidosearchColorTokens!~  | Force token colorization for large buffers  |
| ~:KaleidosearchToggleTokens~  | Toggle ~tiktoken~ token span colors         |
| ~:KaleidosearchInfo~          | Show current Kaleidosearch session info     |

** Default Keymaps

| Keymap       | Action                                             |
|--------------+----------------------------------------------------|
| ~<leader>cs~ | Open prompt for words to colorize                  |
| ~<leader>cc~ | Clear all highlighted words (reset to clean slate) |
| ~<leader>cn~ | Add a new word to existing highlights              |
| ~<leader>ca~ | Add word under cursor to existing highlights       |
| ~<leader>cw~ | Colorize all vim ~word~ tokens in current buffer   |
| ~<leader>cW~ | Colorize all vim ~WORD~ tokens in current buffer   |
| ~<leader>cl~ | Colorize all lines in current buffer               |
| ~<leader>ct~ | Colorize real ~tiktoken~ tokens in current buffer  |

** Configuration

#+begin_src lua
require("kaleidosearch").setup({
  highlight_group_prefix = "WordColor_", -- Prefix for highlight groups
  case_sensitive = false,                -- Case sensitivity for matching
  whole_word_match = false,              -- Only match whole words, not substrings
  backdrop = {
    enabled = false,                     -- Dim non-matching text during word highlighting
    highlight_group = "KaleidosearchBackdrop", -- Linked to Comment by default
  },
  keymaps = {
    enabled = true,                      -- Set to false to disable default keymaps
    open = "<leader>cs",                 -- Open input prompt for search
    clear = "<leader>cc",                -- Clear highlights (reset to clean slate)
    add_new_word = "<leader>cn",         -- Add a new word to existing highlights
    add_cursor_word = "<leader>ca",      -- Add word under cursor to highlights OR current visual selection
    colorize_all_words = "<leader>cw",   -- Colorize all vim 'word' tokens
    colorize_all_WORDS = "<leader>cW",   -- Colorize all vim 'WORD' tokens
    colorize_all_lines = "<leader>cl",   -- Colorize all lines in current buffer
    colorize_tokens = "<leader>ct",      -- Colorize real tiktoken tokens
    opts = {
      noremap = true,
      silent = true,
    }
  },
  token_colors = {
    enabled = true,
    model = "gpt-4o",                    -- tiktoken model
    encoding = "o200k_base",             -- fallback encoding
    max_bytes = 200 * 1024,               -- skip larger buffers unless forced
    max_highlights = 20000,               -- skip huge token counts unless forced
    palette_size = 32,
    saturation = 0.55,
    lightness = 0.24,
    priority = 120,
    notify = true,
    highlight_group_prefix = "KaleidosearchToken",
  }
})
#+end_src

Token colorization shells out asynchronously through ~uv run --with tiktoken~ when ~uv~ is available, otherwise it uses ~python3~ or ~python~ with an installed ~tiktoken~ module. Regular ~:KaleidosearchClear~ and the clear keymap remove word, line, and token highlights.

*** Dimming non-matching text

Enable the backdrop to make colored matches stand out against muted surrounding text:

#+begin_src lua
require("kaleidosearch").setup({
  backdrop = { enabled = true },
})
#+end_src

The backdrop is buffer-local and applies to word highlighting, including the all-words modes. Clearing highlights, toggling off the last word, or switching to line or token colorization removes it.

~KaleidosearchBackdrop~ links to your colorscheme's ~Comment~ group by default. To choose a specific color, define the group after loading your colorscheme:

#+begin_src lua
vim.api.nvim_set_hl(0, "KaleidosearchBackdrop", { fg = "#666666" })
#+end_src

If you switch colorschemes at runtime, reapply your custom definition in a ~ColorScheme~ autocmd. Alternatively, set ~backdrop.highlight_group~ to an existing highlight group supplied by your theme.

** Development

*** Running Tests

This plugin includes unit tests using Plenary.nvim. To run the tests:

1. Use the provided script (it will install Plenary.nvim if needed):

#+begin_src bash
./scripts/run_tests.sh
#+end_src

2. Or if you're inside Neovim with Plenary installed:

#+begin_src vim
:PlenaryBustedDirectory test/ {minimal_init = 'test/minimal_init.lua'}
#+end_src

** Misc. 

- PRs welcome 😃
- Ideas / issues welcome 

** License

MIT License