# clever-tee

clever-tee extends Nvim's `f`, `F`, `t`, and `T` character motions with shared repetition, multiline search, counts, multibyte text, dot-repeat, configurable matching, and visual feedback.

## Installation

Install the complete repository root so that `plugin/`, `lua/`, and `autoload/` are on `runtimepath`. Load it at startup because it replaces core motion keys.

Example for lazy.nvim:

```lua
{
  "<owner>/clever-tee",
  lazy = false,

  init = function()
    -- Set configuration here, before plugin activation.
    vim.g.clever_tee_smart_case = true
  end,

  config = function()
    local clever_tee = require("clever_tee")

    -- Optional explicit repeat mappings.
    vim.keymap.set(
      { "n", "x", "o" },
      ";",
      clever_tee.RepeatSameDirection,
      { silent = true }
    )
    vim.keymap.set(
      { "n", "x", "o" },
      ",",
      clever_tee.RepeatOppositeDirection,
      { silent = true }
    )
  end,
}
```

Replace `<owner>/clever-tee` with the published repository identifier. For a local installation, use the repository root as the plugin manager's `dir`.

`plugin/clever_tee.lua` activates the plugin automatically. A manual runtime loader can call:

```lua
require("clever_tee").activate()
```

## Default mappings

The plugin installs these silent, non-recursive mappings in Normal, Visual, and operator-pending modes:

- `f`: find forward
- `F`: find backward
- `t`: till forward
- `T`: till backward

Counts work, for example `2fa`.

All four keys share the active FIND or TILL sequence. With the default direction policy, lower-case keys repeat the stored direction and upper-case keys use the opposite direction.

The explicit repeat functions provide semicolon and comma behavior:

- `RepeatSameDirection`
- `RepeatOppositeDirection`

## Suppressing the default mappings

Set this global before activation:

```lua
vim.g.clever_tee_not_overwrites_standard_mappings = true
```

Its presence suppresses the default mappings. Values such as `false` and `0` also suppress them. Leave the global absent to install the defaults.

Custom mappings can call these functions from `require("clever_tee")`:

- `StartFindForward`
- `StartFindBackward`
- `StartTillForward`
- `StartTillBackward`
- `RepeatSameDirection`
- `RepeatOppositeDirection`
- `Reset`

## Configuration

All regular settings use the `vim.g.clever_tee_` prefix.

Search and matching:

- `search_current_line_only`: Boolean, default `false`. The default searches toward the buffer boundary.
- `ignore_case`: Boolean, default `false`.
- `smart_case`: Boolean, default `false`. Lower-case ASCII targets ignore case; upper-case targets preserve case.
- `use_migemo`: Boolean, default `false`. UTF-8, CP932, and EUC-JP dictionaries are bundled.
- `chars_match_any_signs`: String, default `""`. Each listed trigger matches the complete supported symbol class.

Sequence behavior:

- `fix_key_direction`: Boolean, default `false`. When true, lower-case primary keys always move forward and upper-case keys always move backward.
- `repeat_timeout_ms`: Nonnegative integer, default `0`. Zero keeps repetition active without expiration.
- `repeat_last_char_inputs`: List of strings, default `{ "\r" }`. Enter reuses the last acquired target.

Input feedback:

- `show_prompt`: Boolean, default `false`.
- `mark_cursor`: Boolean, default `true`.
- `mark_cursor_color`: Highlight-group name, default target `Cursor`.
- `hide_cursor_on_cmdline`: Boolean, default `true`.
- `mark_direct`: Boolean, default `false`.
- `mark_direct_color`: Highlight-group name, default target `CleverTeeDefaultLabel`.

Persistent feedback:

- `mark_char`: Boolean, default `true`.
- `mark_char_color`: Highlight-group name, default target `CleverTeeDefaultLabel`.
- `highlight_timeout_ms`: Nonnegative integer, default `0`. Zero keeps labels until a lifecycle event clears them.
- `clean_labels_eagerly`: Boolean, default `true`.

Example:

```lua
vim.g.clever_tee_search_current_line_only = true
vim.g.clever_tee_smart_case = true
vim.g.clever_tee_mark_direct = true
vim.g.clever_tee_repeat_timeout_ms = 1500
vim.g.clever_tee_highlight_timeout_ms = 500
vim.g.clever_tee_mark_char_color = "Search"
```

Set `clean_labels_eagerly` and the mapping-suppression sentinel before activation. Setting all options before activation gives predictable highlight initialization. Most search and motion settings are sampled again for each action.

The available highlight groups are:

- `CleverTeeDefaultLabel`
- `CleverTeeCursor`
- `CleverTeeChar`
- `CleverTeeDirect`

The plugin refreshes their links after `ColorScheme`.

## Requirements

- Nvim 1.12.5
- The complete plugin repository, including the bundled Migemo assets
- A startup package or plugin manager that adds the repository root to `runtimepath`